dekiru-data_migration 1.1.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df1675b37a0388bddd1b67330d5a1b17c4557fe799de88589ab9f0eea8384a4e
-  data.tar.gz: ec25183013962b62b2bd7c15ae3eae1961dd8c4866c48081f8715b9733f8c6ce
+  metadata.gz: b46a5373c84760557f19d957cdc79d285e1c11812090007b4ccc2dfd7d81cb82
+  data.tar.gz: a3ba1a45dc98df3ba559adefcfbda99ccab9cc76e64ea83cd94f3f815d5541df
 SHA512:
-  metadata.gz: ce709a7039fd0fb49fb03dc2a325a9e947849bfa5ca5406c9ced48c15d1a586d7d81a2452389cbbd7d3b98754bcb6d45a762054489112496b28d69f1163e1f94
-  data.tar.gz: df6853cd129775bdc22d9f045f2b38b3bc7fd9da7135aaac9f8a9747d8dd0c782fd137d346310d613ee338e42eef5a1e1b4772c70ca6e210fc340d87f2474bb3
+  metadata.gz: 3febccaa7208f1375ef412fcb77c48450d613733900130b6f388e4ae5e099aa0dc4787ab6877cc13769d442cf21ceb21ed058e364423e6a862d49ec3ecc151c9
+  data.tar.gz: 6e39a7f6148affaa5e50461e32cf546cde57dcda1e6409a705c6ff617904116c70689d5e71df6233f8fd73e4a430074efbcdfe2c4875b3b8d8adfbaf681633ca

data/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "cSpell.words": [
+    "demodulize"
+  ]
+}

data/README.md

@@ -74,6 +74,49 @@ end
 DemoMigration.run
 ```
 
+### Batch Processing with `migrate_batch`
+
+When you need to update or delete a large number of records efficiently, you can define `migrate_batch` instead of `migrate_record`. It processes records in batches using ActiveRecord's `in_batches`, yielding each batch as an `ActiveRecord::Relation` so you can run a single `update_all` / `delete_all` query per batch. The progress bar advances per batch rather than per record.
+
+`migrate_batch` and `migrate_record` are mutually exclusive — if you implement `migrate_batch`, the batch path is used automatically.
+
+```ruby
+# scripts/20230118_deactivate_stale_users.rb
+class DeactivateStaleUsersMigration < Dekiru::DataMigration::Migration
+  def migration_targets
+    User.where(active: true).where("last_login_at < ?", 1.year.ago)
+  end
+
+  def migrate_batch(relation)
+    relation.update_all(active: false)
+  end
+end
+
+DeactivateStaleUsersMigration.run
+```
+
+If you use the block-based `Operator` directly, pass `in_batches` to `each_with_progress`:
+
+```ruby
+# scripts/deactivate_stale_users.rb
+Dekiru::DataMigration::Operator.execute('Deactivate stale users') do
+  targets = User.where(active: true).where("last_login_at < ?", 1.year.ago)
+
+  log "Target user count: #{targets.count}"
+  each_with_progress(targets.in_batches) do |batch|
+    batch.update_all(active: false)
+  end
+end
+```
+
+#### Specifying the batch size
+
+Pass `batch_size` to `run` to control how many records are fetched per batch. It applies to both paths — `in_batches(of:)` for `migrate_batch` and `find_each(batch_size:)` for `migrate_record`. When omitted, ActiveRecord's default of 1000 is used.
+
+```ruby
+DeactivateStaleUsersMigration.run(batch_size: 500)
+```
+
 ### Testing Migration Classes
 
 The class-based approach makes it easy to write unit tests:
@@ -286,7 +329,7 @@ Available options:
 Outputs log messages. Properly handled even during progress bar display.
 
 ### `find_each_with_progress(scope, options = {}, &block)`
-Executes `find_each` with a progress bar for ActiveRecord scopes.
+Executes `find_each` with a progress bar for ActiveRecord scopes. Pass `batch_size:` in `options` to control how many records are fetched per batch (forwarded to `find_each(batch_size:)`).
 
 ### `each_with_progress(enum, options = {}, &block)`
 Executes processing with a progress bar for any Enumerable objects.

data/lib/dekiru/data_migration/migration.rb

@@ -4,10 +4,15 @@ module Dekiru
   module DataMigration
     # Base class for data migration with testable method separation
     class Migration
+      attr_accessor :batch_size
+
       def self.run(options = {})
         migration = new
         title = migration.title
 
+        options = options.dup
+        migration.batch_size = options.delete(:batch_size)
+
         Operator.execute(title, options) do
           migration.instance_variable_set(:@operator_context, self)
           migration.migrate
@@ -24,8 +29,10 @@ module Dekiru
         log "Target count: #{targets.count}"
         confirm?
 
-        find_each_with_progress(targets) do |record|
-          migrate_record(record)
+        if migrate_batch_overridden?
+          migrate_in_batches(targets)
+        else
+          migrate_each_record(targets)
         end
 
         log "Migration completed"
@@ -39,8 +46,30 @@ module Dekiru
         raise NotImplementedError, "#{self.class}#migrate_record must be implemented"
       end
 
+      def migrate_batch(relation)
+        raise NotImplementedError, "#{self.class}#migrate_batch must be implemented"
+      end
+
       private
 
+      def migrate_in_batches(targets)
+        batches = batch_size ? targets.in_batches(of: batch_size) : targets.in_batches
+        each_with_progress(batches) do |batch|
+          migrate_batch(batch)
+        end
+      end
+
+      def migrate_each_record(targets)
+        options = batch_size ? { batch_size: batch_size } : {}
+        find_each_with_progress(targets, options) do |record|
+          migrate_record(record)
+        end
+      end
+
+      def migrate_batch_overridden?
+        self.class.instance_method(:migrate_batch).owner != Dekiru::DataMigration::Migration
+      end
+
       def confirm?
         if @operator_context
           @operator_context.send(:confirm?)

data/lib/dekiru/data_migration/operator.rb

@@ -82,7 +82,10 @@ module Dekiru
       def find_each_with_progress(target_scope, options = {}, &block)
         # `LocalJumpError: no block given (yield)` が出る場合、 find_each メソッドが enumerator を返していない可能性があります
         # 直接 each_with_progress を使うか、 find_each が enumerator を返すように修正してください
-        each_with_progress(target_scope.find_each, options, &block)
+        options = options.dup
+        batch_size = options.delete(:batch_size)
+        scope = batch_size ? target_scope.find_each(batch_size: batch_size) : target_scope.find_each
+        each_with_progress(scope, options, &block)
       end
 
       private

data/lib/dekiru/data_migration/version.rb

@@ -2,6 +2,6 @@
 
 module Dekiru
   module DataMigration
-    VERSION = "1.1.1"
+    VERSION = "1.3.0"
   end
 end

data/skills/data-migration-script/SKILL.md

@@ -29,7 +29,7 @@ bin/rails generate maintenance_script <PascalCaseName>
 
 ### 2. Edit the generated file
 
-Implement `migration_targets` and `migrate_record` in the generated file.
+Implement `migration_targets` and `migrate_record` (or `migrate_batch` instead, for bulk-processing a large number of records) in the generated file.
 
 ### Common Operation Patterns
 
@@ -66,6 +66,21 @@ def migrate_record(record)
 end
 ```
 
+**Bulk update/delete a large number of records (batch processing)**:
+
+Implement `migrate_batch` instead of `migrate_record` to receive each batch as an `ActiveRecord::Relation` via `in_batches`, allowing you to run `update_all` / `delete_all` in a single query. Use this to process a large number of records efficiently.
+```ruby
+def migration_targets
+  User.where(active: true).where("last_login_at < ?", 1.year.ago)
+end
+
+def migrate_batch(relation)
+  relation.update_all(active: false)  # one query per batch
+end
+```
+
+Pass `batch_size` to `run` to change the batch size (default 1000). It applies to both `migrate_batch` (`in_batches`) and `migrate_record` (`find_each`): `MyMigration.run(batch_size: 500)`.
+
 ## Execution and Verification Commands
 
 ```bash
@@ -83,4 +98,5 @@ bin/rails runner "p TargetModel.where(...).count"
 
 - `purge` deletes synchronously (immediately removes from storage). Use `purge_later` for async deletion
 - `migration_targets` must return an ActiveRecord relation (processed in batches via `find_each`)
+- `migrate_batch`'s `update_all` / `delete_all` issue SQL directly without running callbacks or validations. `updated_at` is not auto-updated either, so include it explicitly if needed
 - Always verify the target record count before running in production

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dekiru-data_migration
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.3.0
 platform: ruby
 authors:
 - SonicGarden
@@ -48,6 +48,7 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - ".rubocop.yml"
+- ".vscode/settings.json"
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md