data_customs 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d7c7b4003b90a683a9ea760719dc9f3fee13c2e41d8e913904d0c25d05cfb3b
-  data.tar.gz: 23abed296ee83d222794a3467f9fba98430cbb15463505f21ce7be11ff1b4c74
+  metadata.gz: 6ac72ddffa6174ea2b67b2e5bbc9ab48a3c2d74a70d9a825da40d72fbf536620
+  data.tar.gz: 945ee937b057a9baad85f82cc8008389bea80cdcbf781e971f46f9ed2728e210
 SHA512:
-  metadata.gz: f2f015a1096f50f09f5f535dcdd7cfe5d5d2c2093763af254cc69743d542cfe21fe82f90f8d42c40d11a38951ce80046ec413c9944ec02ee5107df4207f6e4c3
-  data.tar.gz: a50e40759553bebca3718c77d3095417798ae8c946524a45216d0bf331fc3a9cf08bcaf3e74a53b015b0d7f4523dcadcbfa15c73ec3918cbce4d97b7f46a9783
+  metadata.gz: 5074c92e21ca067b24e03444007bc3ff7805ed975479e182b735dfba0b73a71729395528d08056a3f0d5ca809309ff0a8dfae893d08c6a4fe22c4bbe96a993a3
+  data.tar.gz: 0da824fb923f79dc6d5ee60e4bee9554fe2edacc6c0aae23292d594df249082c608fc1cdfe09cddaaba67c8c36774779bb4e3026904232aee772606d0933e145

data/.standard.yml

@@ -0,0 +1,2 @@
+ignore:
+  - 'spec/dummy/**/*'

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-03-04
+
+- Add `progress.report` for tracking migration progress with a visual bar that updates in place on TTY terminals
+- Add `progress eta: true` class-level macro to enable ETA display without passing it on every `report` call
+
+```ruby
+class MyMigration < DataCustoms::Migration
+  progress eta: true
+
+  def up
+    users = User.where(active: true)
+    total = users.count
+    users.find_each.with_index(1) do |user, i|
+      user.update!(name: user.name.strip)
+      progress.report(i * 100 / total)
+    end
+    progress.report(100)
+  end
+end
+```
+
+- Fix transaction to wrap `Migration.new` so database operations in `initialize` are rolled back on failure
+
 ## [0.1.0] - 2025-09-04
 
 - Initial release

data/README.md

@@ -146,6 +146,66 @@ class LongMigration < DataCustoms::Migration
 end
 ```
 
+#### Reporting progress
+
+For long-running migrations, you can use `progress.report` to display a progress
+bar:
+
+```ruby
+class BackfillUsernames < DataCustoms::Migration
+  def up
+    scope = User.where(username: nil)
+    total = scope.count
+    processed = 0
+
+    find_each(scope) do |user|
+      user.update!(username: "guest_#{user.id}")
+      processed += 1
+      progress.report(processed.to_f / total * 100)
+    end
+  end
+
+  def verify!
+    raise "Some users still have no usernames!" if User.exists?(username: nil)
+  end
+end
+```
+
+```
+🛃 Progress: ██████████░░░░░░░░░░ 50%
+🛃 Progress: ████████████████████ 100% (5s elapsed)
+🛃 Data migration ran successfully!
+```
+
+It accepts a percentage (0–100) and throttles output, so it's safe to call on
+every iteration. At 100%, it shows the total elapsed time.
+
+Use `progress eta: true` at the class level to show estimated time remaining:
+
+```ruby
+class BackfillUsernames < DataCustoms::Migration
+  progress eta: true
+
+  def up
+    scope = User.where(username: nil)
+    total = scope.count
+    processed = 0
+
+    find_each(scope) do |user|
+      user.update!(username: "guest_#{user.id}")
+      processed += 1
+      progress.report(processed.to_f / total * 100)
+    end
+  end
+
+  # ...
+end
+```
+
+```
+🛃 Progress: ██████████░░░░░░░░░░ 50% (2m 30s left)
+```
+
 ### Running a data migration in the command line
 
 These migrations don't run automatically. You need to invoke them manually.
@@ -208,8 +268,8 @@ thoughtbot are trademarks of thoughtbot, inc.
 We love open source software! See [our other projects][community]. We are
 [available for hire][hire].
 
-[community]: https://thoughtbot.com/community?utm_source=github
-[hire]: https://thoughtbot.com/hire-us?utm_source=github
+[community]: https://thoughtbot.com/community?utm_source=github&utm_medium=readme&utm_campaign=data_customs
+[hire]: https://thoughtbot.com/hire-us?utm_source=github&utm_medium=readme&utm_campaign=data_customs
 
 <!-- END /templates/footer.md -->
 

data/lib/data_customs/migration.rb

@@ -5,25 +5,45 @@ module DataCustoms
     DEFAULT_BATCH_SIZE = 1000
     DEFAULT_THROTTLE = 0.01
 
-    def self.run(...) = new(...).run
+    def self.progress(**options)
+      @progress_options = options
+    end
 
-    def up = raise NotImplementedError
+    def self.progress_options
+      @progress_options || {}
+    end
+
+    def self.run(...)
+      ActiveRecord::Base.transaction do
+        new(...).run
+      end
+    rescue => e
+      warn "🛃 Data migration failed"
+      raise e
+    end
 
+    def up = raise NotImplementedError
     def verify! = raise NotImplementedError
 
     def run
-      ActiveRecord::Base.transaction do
+      with_progress_reporter do
         up
         verify!
         puts "🛃 Data migration ran successfully!"
-      rescue => e
-        warn "🛃 Data migration failed"
-        raise e
       end
     end
 
     private
 
+    def with_progress_reporter(&block)
+      ProgressOutput.wrap do |output|
+        @_progress = ProgressReporter.new(output, **self.class.progress_options)
+        block.call
+      end
+    end
+
+    def progress = @_progress
+
     def batch(scope, batch_size: DEFAULT_BATCH_SIZE, throttle_seconds: DEFAULT_THROTTLE)
       scope.in_batches(of: batch_size) do |relation|
         yield relation

data/lib/data_customs/progress_output.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module DataCustoms
+  class ProgressOutput
+    def self.wrap
+      real_output = $stdout
+      tty = real_output.respond_to?(:tty?) && real_output.tty?
+
+      if tty
+        tui = new(real_output)
+        $stdout = tui.buffer
+        yield tui
+      else
+        yield real_output
+      end
+    ensure
+      $stdout = real_output
+      tui&.flush
+    end
+
+    attr_reader :buffer
+
+    def initialize(output)
+      @output = output
+      @buffer = StringIO.new
+      @buffer_flushed_to = 0
+      output.print "\e[H\e[2J" # Clear screen and move cursor to top-left
+    end
+
+    def puts(line)
+      @output.print "\e[H" # Move cursor to top-left
+      "#{line}\n#{@buffer.string}".each_line do |l|
+        @output.print "\e[2K#{l}" # Clear line and print new content
+      end
+      @buffer_flushed_to = @buffer.string.length
+    end
+
+    def flush
+      remaining = @buffer.string[@buffer_flushed_to..]
+      @output.write(remaining) if remaining && !remaining.empty?
+    end
+  end
+end

data/lib/data_customs/progress_reporter.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module DataCustoms
+  class ProgressReporter
+    BAR_WIDTH = 20
+    PRINT_INTERVAL = 1 # seconds
+    ETA_MIN_ELAPSED = 2 # seconds before showing ETA
+
+    def initialize(output, eta: false)
+      @output = ThrottledOutput.new(output, interval: PRINT_INTERVAL)
+      @started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      @eta = eta
+    end
+
+    def report(percentage)
+      percentage = percentage.floor.clamp(0, 100)
+      line = bar(percentage)
+
+      if percentage == 100
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @started_at
+        line += " (#{format_duration(elapsed)} elapsed)" if elapsed >= 1
+        @output.write(line, force: true)
+        return
+      end
+
+      if @eta && percentage > 0
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @started_at
+        if elapsed >= ETA_MIN_ELAPSED
+          remaining = elapsed / percentage * (100 - percentage)
+          line += " (#{format_duration(remaining)} left)"
+        else
+          line += " (estimating...)"
+        end
+      end
+
+      @output.write(line)
+    end
+
+    private
+
+    def bar(percentage)
+      filled = percentage / (100 / BAR_WIDTH)
+      empty = BAR_WIDTH - filled
+      "🛃 Progress: #{"█" * filled}#{"░" * empty} #{percentage}%"
+    end
+
+    def format_duration(seconds)
+      seconds = seconds.ceil
+      if seconds < 60
+        "#{seconds}s"
+      elsif seconds < 3600
+        "#{seconds / 60}m #{seconds % 60}s"
+      else
+        "#{seconds / 3600}h #{(seconds % 3600) / 60}m"
+      end
+    end
+  end
+end

data/lib/data_customs/tasks/data_customs.rake

@@ -1,16 +1,16 @@
 namespace :data_customs do
-  desc 'Run a single data migration from db/data_migrations'
+  desc "Run a single data migration from db/data_migrations"
   task run: :environment do
-    name = ENV['NAME']
-    abort '❌ Missing migration name (e.g. `rake data_customs:run NAME=fix_users`)' unless name
+    name = ENV["NAME"]
+    abort "❌ Missing migration name (e.g. `rake data_customs:run NAME=fix_users`)" unless name
 
-    path = Rails.root.join('db', 'data_migrations', "#{name.underscore}.rb")
+    path = Rails.root.join("db", "data_migrations", "#{name.underscore}.rb")
     abort "❌ Migration not found: #{path}" unless File.exist?(path)
 
     require path
     migration_class = name.camelize.constantize
-    if args = ENV['ARGS']
-      migration_class.run(args.split(','))
+    if (args = ENV["ARGS"])
+      migration_class.run(args.split(","))
     else
       migration_class.run
     end

data/lib/data_customs/throttled_output.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module DataCustoms
+  class ThrottledOutput
+    def initialize(output, interval:)
+      @output = output
+      @interval = interval
+      @last_printed_at = nil
+    end
+
+    def write(line, force: false)
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      return if throttled?(now) && !force
+
+      @last_printed_at = now
+      @output.puts(line)
+    end
+
+    private
+
+    def throttled?(now)
+      @last_printed_at && (now - @last_printed_at) < @interval
+    end
+  end
+end

data/lib/data_customs/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DataCustoms
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/data_customs.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
 require_relative "data_customs/migration"
+require_relative "data_customs/progress_reporter"
 require_relative "data_customs/railtie"
+require_relative "data_customs/throttled_output"
+require_relative "data_customs/progress_output"
 require_relative "data_customs/version"
 
 module DataCustoms

data/mise.toml

@@ -0,0 +1,2 @@
+[tools]
+ruby = "3.4.8"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: data_customs
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Matheus Richard
@@ -23,15 +23,17 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.1'
-description: A simple gem to help you perform data migrations in your Rails app. Define
-  the work and a verification step steps, if any of them fail, your migration will
-  be rolled back.
+description: |
+  A simple gem to help you perform data migrations in your Rails app.
+  Define the migration and a verification step; if any of them fail,
+  everything will be rolled back, so you're left with the original state.
 email:
 - matheusrichardt@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".standard.yml"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
@@ -39,11 +41,15 @@ files:
 - Rakefile
 - lib/data_customs.rb
 - lib/data_customs/migration.rb
+- lib/data_customs/progress_output.rb
+- lib/data_customs/progress_reporter.rb
 - lib/data_customs/railtie.rb
 - lib/data_customs/tasks/data_customs.rake
+- lib/data_customs/throttled_output.rb
 - lib/data_customs/version.rb
 - lib/generators/data_migration/data_migration_generator.rb
 - lib/generators/data_migration/templates/data_migration.rb.tt
+- mise.toml
 homepage: https://github.com/thoughtbot/data_customs
 licenses:
 - MIT