ScriptTracker

A Ruby gem that provides a migration-like system for managing one-off scripts in Rails applications with execution tracking, transaction support, and built-in logging.

• Execution Tracking - Automatically tracks which scripts have been run and their status
• Transaction Support - Wraps script execution in database transactions
• Status Management - Track scripts as success, failed, running, or skipped
• Built-in Logging - Convenient logging methods with timestamps
• Batch Processing - Helper methods for processing large datasets efficiently
• Timeout Support - Configure custom timeouts for long-running scripts

Add to your Gemfile:

gem 'script_tracker'

Then run:

bundle install
rails generate script_tracker:install
rails db:migrate

rake scripts:create["update user preferences"]

This creates a timestamped script file in lib/scripts/ :

module Scripts
  class UpdateUserPreferences < ScriptTracker::Base
    def self.execute
      log "Starting script"
      
      User.find_each do |user|
        user.update!(preferences: { theme: 'dark' })
      end
      
      log "Script completed"
    end
  end
end

rake scripts:run        # Run all pending scripts
rake scripts:status     # View script status
rake scripts:rollback[filename]  # Rollback a script
rake scripts:cleanup    # Cleanup stale scripts

def self.execute
  skip! "No users need updating" if User.where(needs_update: true).count.zero?
  # Your logic here
end

def self.timeout
  3600 # 1 hour in seconds
end

def self.execute
  users = User.where(processed: false)
  process_in_batches(users, batch_size: 1000) do |user|
    user.update!(processed: true)
  end
end

def self.execute
  total = User.count
  processed = 0
  
  User.find_each do |user|
    # Process user
    processed += 1
    log_progress(processed, total) if (processed % 100).zero?
  end
end

Class Methods:

• execute - Implement with your script logic (required)
• timeout - Override to set custom timeout (default: 300 seconds)
• skip!(reason) - Skip script execution
• log(message, level: :info) - Log a message
• log_progress(current, total) - Log progress percentage
• process_in_batches(relation, batch_size: 1000, &block) - Process in batches

Scopes: successful , failed , running , skipped , completed , ordered , recent_first

Class Methods:

• executed?(filename) - Check if script has been executed
• cleanup_stale_running_scripts(older_than: 1.hour.ago) - Clean up stale scripts

• rake scripts:create[description] - Create a new script
• rake scripts:run - Run all pending scripts
• rake scripts:status - Show status of all scripts
• rake scripts:rollback[filename] - Rollback a script
• rake scripts:cleanup - Cleanup stale running scripts

1. Go to Actions → Release workflow
2. Click Run workflow
3. Enter version number (e.g., 0.1.3)

Or push a tag:

git tag -a v0.1.3 -m "Release version 0.1.3"
git push origin v0.1.3

Required: Set RUBYGEMS_AUTH_TOKEN in GitHub repository secrets.

bin/release 0.1.3

Choosing the right tool for your data migration needs depends on your use case. Here's how ScriptTracker compares to other popular solutions:

data_migrate runs data migrations alongside schema migrations using a db/data directory.

When to choose data_migrate: You want data migrations to run automatically with schema migrations in your deployment pipeline.

When to choose ScriptTracker: You need more control over one-off scripts with detailed tracking, rollback capabilities, and don't want them tied to your schema migration workflow.

maintenance_tasks is a Rails engine providing a web UI for queueing and managing long-running data migrations.

When to choose maintenance_tasks: You need a robust UI for non-technical users, want tasks to survive deploys/restarts, or need advanced features like throttling.

When to choose ScriptTracker: You prefer simplicity, want CLI-based workflow, or don't need the overhead of a web UI and Active Job.

after_party automates post-deploy tasks that run once per environment.

When to choose after_party: You want tasks to run automatically after each deployment with minimal configuration.

When to choose ScriptTracker: You need more visibility, control, and features like rollback, status tracking, and skip logic.

Choose ScriptTracker if you want:

• Rich execution tracking with detailed status
• Built-in logging, batch processing, and progress tracking
• Rollback capabilities for one-off scripts
• CLI-based workflow without web UI overhead
• Transaction support with automatic rollback on failure

Choose data_migrate if you want:

• Data migrations that run with schema migrations
• Integration with existing Rails migration workflow
• Automatic execution during deployments

Choose maintenance_tasks if you want:

• Web UI for managing tasks
• Tasks that survive deploys and restarts
• Advanced features (throttling, CSV processing)
• Production-grade task management for large teams

Choose after_party if you want:

• Simple post-deploy automation
• Fire-and-forget task execution
• Minimal configuration and setup

Bug reports and pull requests welcome at https://github.com/a-abdellatif98/script_tracker.

MIT License - see LICENSE file for details.