online_migrations 0.26.0 → 0.27.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cbca384d5eaf4ab575e80c60160d42326ef86f1baf21419f290663e0d9698eb0
-  data.tar.gz: b90abf4e278ee1b2ab27e60472f6bb127b124797084f53205a0929a5cc98268b
+  metadata.gz: 8a3658cc979ead6b8dea71140f3ba95b0f7a4a4c26a27891f49a5b6925c94e59
+  data.tar.gz: 7d3ab5e09422e28078543ac67fa0ecae1a7afe9d8e29f67e55d6b772fb708e50
 SHA512:
-  metadata.gz: eea056dd2b0c5a24213543d96d6b2ca5a1c230c38aa37f475d674157bc354a8d0c1cb39e6e2c0a6e86867b184e82b51ec9ad0452eed00e1a7b7a6098b203c3ff
-  data.tar.gz: 9636d4b788d655ad04d0141cd28ae61c053b15d83f00c63b236ee181feeb438c18f2a8f34da49b26d955ff3c004c053f0d570d00ff6801e47e15c438b09f2c51
+  metadata.gz: 43ae3f3ebffa5491d4ac9b99b987b048702b9142e9a4ae49182b705b9c81a562acbea6dc1580ef76e49a9124adf2d662723451b6d03003f10f05c1d39ff4a33e
+  data.tar.gz: 5793df9ffd71454f2edb251d079439c5dfb0cfe212a30360654cbb5622c23fcd47a63e2a8cdd6b8d4df2bd7d3b39ec4d29eede4a99519264075e65956bdd1b55

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## master (unreleased)
 
+## 0.27.1 (2025-05-08)
+
+- Fix background data migrations to enumerate using the correct shard
+
+## 0.27.0 (2025-05-01)
+
+- **WARNING**: This release has breaking changes! See `docs/0.27-upgrade.md` for release notes
+
+- Add ability to run background data migrations in parallel
+
+    ```ruby
+    # Run 2 data migrations in parallel.
+    OnlineMigrations.run_background_data_migrations(concurrency: 2)
+    ```
+
+- Retry deadlocks by lock retrier
+- Fix copying check constraints on columns with similar names when changing column type
+
 ## 0.26.0 (2025-04-28)
 
 - Drop support for Ruby < 3.1 and Rails < 7.1

data/docs/0.27-upgrade.md

@@ -0,0 +1,24 @@
+# Upgrading to online_migrations 0.27.0
+
+In this version, background data migrations internals were significantly refactored and rewritten, that allowed to make the gem much simpler and its API more flexible and not attached to a single use case (whole table data migrations). It relies on [Sidekiq's Iteration feature](https://github.com/sidekiq/sidekiq/wiki/Iteration), so having Sidekiq 7.3.3+ is a hard requirement for background data migrations feature to work now.
+
+This is one of the preceding releases before v1.0.
+
+To upgrade:
+
+* Upgrade gem to v0.27: `gem 'online_migrations', '~> 0.27.0'`
+* Upgrade the gem's initializer in `config/online_migrations.rb` by referring to the [newest contents](https://github.com/fatkodima/online_migrations/blob/master/lib/generators/online_migrations/templates/initializer.rb.tt)
+
+If you don't use any of the [background data migrations](background_data_migrations.md) or [background schema migrations](background_schema_migrations.md), then this is probably all you need.
+
+If you use background data migrations:
+
+* Make sure all existing background data migrations completed before upgrading
+
+* Get the latest schema changes
+  ```sh
+  $ bin/rails generate online_migrations:upgrade
+  $ bin/rails db:migrate
+  ```
+
+Look at [background data migrations guide](background_data_migrations.md) to find the API changes and new features.

data/docs/background_data_migrations.md

@@ -2,10 +2,14 @@
 
 When a project grows, your database starts to be heavy and changing the data through the deployment process can be very painful.
 
-Background migrations should be used to perform data migrations on large tables or when the migration will take a lot of time. For example, you can use background migrations to migrate data that’s stored in a single JSON column to a separate table instead or backfill some column's value from an API.
+Background data migrations should be used to perform data migrations on large tables or when the migration will take a lot of time. For example, you can use background data migrations to migrate data that’s stored in a single JSON column to a separate table instead or backfill some column's value from an API.
 
 **Note**: You probably don't need to use background migrations for smaller projects, since updating data directly on smaller databases will be perfectly fine and will not block the deployment too much.
 
+## Requirements
+
+Data migrations uses [sidekiq iterable job](https://github.com/sidekiq/sidekiq/wiki/Iteration) under the hood and so requires `sidekiq` 7.3.3+ to work.
+
 ## Installation
 
 Make sure you have migration files generated when installed this gem:
@@ -14,7 +18,7 @@ Make sure you have migration files generated when installed this gem:
 $ bin/rails generate online_migrations:install
 ```
 
-Start a background migrations scheduler. For example, to run it on cron using [whenever gem](https://github.com/javan/whenever) add the following lines to its `schedule.rb` file:
+Start a background data migrations scheduler. For example, to run it on cron using [whenever gem](https://github.com/javan/whenever) add the following lines to its `schedule.rb` file:
 
 ```ruby
 every 1.minute do
@@ -22,40 +26,39 @@ every 1.minute do
 end
 ```
 
-## Creating a Background Migration
+## Creating a Data Migration
 
-A generator is provided to create background migrations. Generate a new background migration by running:
+A generator is provided to create data migrations. Generate a new data migration by running:
 
 ```bash
-$ bin/rails generate online_migrations:background_migration backfill_project_issues_count
+$ bin/rails generate online_migrations:data_migration backfill_project_issues_count
 ```
 
-This creates the background migration file `lib/online_migrations/background_migrations/backfill_project_issues_count.rb`
-and the regular migration file `db/migrate/xxxxxxxxxxxxxx_enqueue_backfill_project_issues_count.rb` where we enqueue it.
+This creates a data migration file `lib/online_migrations/data_migrations/backfill_project_issues_count.rb`
+and a regular migration file `db/migrate/xxxxxxxxxxxxxx_enqueue_backfill_project_issues_count.rb` where it is enqueued.
 
-The generated class is a subclass of `OnlineMigrations::BackgroundMigration` that implements:
+The generated class is a subclass of `OnlineMigrations::DataMigration` that implements:
 
-* `relation`: return an `ActiveRecord::Relation` to be iterated over
-* `process_batch`: do the work of your background migration on a batch (`ActiveRecord::Relation`)
-* `count`: return the number of rows that will be iterated over (optional, to be
-  able to show progress)
+* `collection`: return a collection to be processed. Can be any of `ActiveRecord::Relation`, `ActiveRecord::Batches::BatchEnumerator`, `Array`, or `Enumerator`
+* `process`: the action to be performed on each item from the `collection`
+* `count`: return total count of iterations to be performed (optional, to be able to show progress)
 
 Example:
 
 ```ruby
-# lib/online_migrations/background_migrations/backfill_project_issues_count.rb
+# lib/online_migrations/data_migrations/backfill_project_issues_count.rb
 
 module OnlineMigrations
-  module BackgroundMigrations
-    class BackfillProjectIssuesCount < OnlineMigrations::BackgroundMigration
+  module DataMigrations
+    class BackfillProjectIssuesCount < OnlineMigrations::DataMigration
       class Project < ActiveRecord::Base; end
 
-      def relation
-        Project.all
+      def collection
+        Project.in_batches(of: 100)
       end
 
-      def process_batch(projects)
-        projects.update_all(<<~SQL)
+      def process(relation)
+        relation.update_all(<<~SQL)
           issues_count = (
             SELECT COUNT(*)
             FROM issues
@@ -65,16 +68,69 @@ module OnlineMigrations
       end
 
       def count
-        relation.count
+        collection.count
+      end
+    end
+  end
+end
+```
+
+### Data Migrations with Custom Enumerators
+
+If you have a special use case requiring iteration over an unsupported collection type,
+such as external resources fetched from some API, you can implement the `build_enumerator(cursor:)`
+method in your data migration.
+
+This method should return an `Enumerator`, yielding pairs of `[item, cursor]`. Online Migrations
+takes care of persisting the current cursor position and will provide it as the `cursor` argument
+if your data migration is interrupted or resumed. The `cursor` is stored as a `String`,
+so your custom enumerator should handle serializing/deserializing the value if required.
+
+```ruby
+# lib/online_migrations/data_migrations/custom_enumerator_migration.rb
+
+module OnlineMigrations
+  module DataMigrations
+    class CustomEnumeratorMigration < OnlineMigrations::DataMigration
+      def build_enumerator(cursor:)
+        after_id = cursor&.to_i
+        PostAPI.index(after_id: after_id).map { |post| [post, post.id] }.to_enum
+      end
+
+      def process(post)
+        Post.create!(post)
       end
     end
   end
 end
 ```
 
-## Enqueueing a Background Migration
+### Customizing the Batch Size
 
-You can enqueue your background migration to be run by the scheduler via:
+When processing records from an `ActiveRecord::Relation`, records are fetched in batches internally, and then each record is passed to the `#process` method.
+The gem will query the database to fetch records in batches of 100 by default, but the batch size can be modified using the `collection_batch_size` macro:
+
+```ruby
+module OnlineMigrations
+  module DataMigrations
+    class UpdatePostsMigration < OnlineMigrations::DataMigration
+    # Fetch records in batches of 1000
+    collection_batch_size(1000)
+
+    def collection
+      Post.all
+    end
+
+    def process(post)
+      post.update!(content: "New content!")
+    end
+  end
+end
+```
+
+## Enqueueing a Data Migration
+
+You can enqueue a data migration to be run by the scheduler via:
 
 ```ruby
 # db/migrate/xxxxxxxxxxxxxx_enqueue_backfill_project_issues_count.rb
@@ -89,20 +145,20 @@ class EnqueueBackfillProjectIssuesCount < ActiveRecord::Migration[8.0]
 end
 ```
 
-`enqueue_background_data_migration` accepts additional configuration options which controls how the background migration is run. Check the [source code](https://github.com/fatkodima/online_migrations/blob/master/lib/online_migrations/background_migrations/migration_helpers.rb) for the list of all available configuration options.
+`enqueue_background_data_migration` accepts additional configuration options which controls how the data migration is run. Check the [source code](https://github.com/fatkodima/online_migrations/blob/master/lib/online_migrations/background_data_migrations/migration_helpers.rb) for the list of all available configuration options.
 
-## Custom Background Migration Arguments
+## Custom Data Migration Arguments
 
-Background migrations may need additional information, supplied via arguments, to run.
+Data migrations may need additional information to run, which can be provided via arguments.
 
 Declare that the migration class is accepting additional arguments:
 
 ```ruby
-class MyMigrationWithArgs < OnlineMigrations::BackgroundMigration
+class MyMigrationWithArgs < OnlineMigrations::DataMigration
   def initialize(arg1, arg2, ...)
     @arg1 = arg1
     @arg2 = arg2
-    ...
+    # ...
   end
   # ...
 end
@@ -124,12 +180,12 @@ def down
 end
 ```
 
-## Considerations when writing Background Migrations
+## Considerations when writing Data Migrations
 
-* **Isolation**: Background migrations should be isolated and not use application code (for example, models defined in `app/models`). Since these migrations can take a long time to run it's possible for new versions to be deployed while they are still running.
-* **Idempotence**: It should be safe to run `process_batch` multiple times for the same elements. It's important if the Background Migration errors and you run it again, because the same element that errored may be processed again. Make sure that in case that your migration job is going to be retried data integrity is guaranteed.
+* **Isolation**: Data migrations should be isolated and not use application code (for example, models defined in `app/models`). Since these migrations can take a long time to run it's possible for new versions to be deployed while they are still running.
+* **Idempotence**: It should be safe to run `process` multiple times for the same elements. It's important, because if the data migration errored and you run it again, the same element that errored may be processed again. Make sure that if your migration is going to be retried the data integrity is guaranteed.
 
-## Predefined background migrations
+## Predefined data migrations
 
 * `BackfillColumn` - backfills column(s) with scalar values (enqueue using `backfill_column_in_background`; or `backfill_column_for_type_change_in_background` if backfilling column for which type change is in progress)
 * `CopyColumn` - copies data from one column(s) to other(s) (enqueue using `copy_column_in_background`)
@@ -138,7 +194,7 @@ end
 * `PerformActionOnRelation` - performs specific action on a relation or individual records (enqueue using `perform_action_on_relation_in_background`)
 * `ResetCounters` - resets one or more counter caches to their correct value (enqueue using `reset_counters_in_background`)
 
-**Note**: These migration helpers should be run inside the migration against the database where background migrations tables are defined.
+**Note**: These migration helpers should be run inside the migration files against the database where background migrations tables are defined.
 
 ## Depending on migrated data
 
@@ -146,19 +202,19 @@ You shouldn't depend on the data until the background data migration is finished
 
 ## Testing
 
-At a minimum, it's recommended that the `#process_batch` method in your background migration is tested. You may also want to test the `#relation` and `#count` methods if they are sufficiently complex.
+At a minimum, it's recommended that the `#process` method in your data migration is tested. You may also want to test the `#collection` and `#count` methods if they are sufficiently complex.
 
 Example:
 
 ```ruby
-# test/online_migrations/background_migrations/backfill_project_issues_count_test.rb
+# test/online_migrations/data_migrations/backfill_project_issues_count_test.rb
 
 require "test_helper"
 
 module OnlineMigrations
-  module BackgroundMigrations
+  module DataMigrations
     class BackfillProjectIssuesCountTest < ActiveSupport::TestCase
-      test "#process_batch performs an iteration" do
+      test "#process backfills issues_count" do
         rails = Project.create!(name: "Ruby on Rails")
         postgres = Project.create!(name: "PostgreSQL")
 
@@ -166,7 +222,9 @@ module OnlineMigrations
         postgres.issues.create!
 
         migration = BackfillProjectIssuesCount.new
-        migration.process_batch(migration.relation)
+        migration.collection.each do |relation|
+          migration.process(relation)
+        end
 
         assert_equal 2, rails.reload.issues_count
         assert_equal 1, postgres.reload.issues_count
@@ -178,27 +236,27 @@ end
 
 ## Instrumentation
 
-Background migrations use the [ActiveSupport::Notifications](http://api.rubyonrails.org/classes/ActiveSupport/Notifications.html) API.
+Data migrations use the [ActiveSupport::Notifications](http://api.rubyonrails.org/classes/ActiveSupport/Notifications.html) API.
 
-You can subscribe to `background_migrations` events and log it, graph it, etc.
+You can subscribe to `background_data_migrations` events and log it, graph it, etc.
 
-To get notified about specific type of events, subscribe to the event name followed by the `background_migrations` namespace. E.g. for retries use:
+To get notified about specific type of events, subscribe to the event name followed by the `background_data_migrations` namespace.
 
 ```ruby
 # config/initializers/online_migrations.rb
-ActiveSupport::Notifications.subscribe("retried.background_migrations") do |name, start, finish, id, payload|
-  # background migration job object is available in payload[:background_migration_job]
+ActiveSupport::Notifications.subscribe("started.background_data_migrations") do |name, start, finish, id, payload|
+  # background data migration object is available in payload[:migration]
 
   # Your code here
 end
 ```
 
-If you want to subscribe to every `background_migrations` event, use:
+If you want to subscribe to every `background_data_migrations` event, use:
 
 ```ruby
 # config/initializers/online_migrations.rb
-ActiveSupport::Notifications.subscribe(/background_migrations/) do |name, start, finish, id, payload|
-  # background migration job object is available in payload[:background_migration_job]
+ActiveSupport::Notifications.subscribe(/background_data_migrations/) do |name, start, finish, id, payload|
+  # background data migration object is available in payload[:migration]
 
   # Your code here
 end
@@ -206,43 +264,70 @@ end
 
 Available events:
 
-* `started.background_migrations`
-* `process_batch.background_migrations`
-* `completed.background_migrations`
-* `retried.background_migrations`
-* `throttled.background_migrations`
+* `started.background_data_migrations`
+* `completed.background_data_migrations`
+* `throttled.background_data_migrations`
+
+### Using Data Migration Callbacks
+
+The data migrations provides callbacks that hook into its life cycle.
 
-## Monitoring Background Migrations
+Available callbacks are:
 
-Background Migrations can be in various states during its execution:
+* `after_start`
+* `around_process`
+* `after_resume`
+* `after_stop`
+* `after_complete`
+* `after_pause`
+* `after_cancel`
+
+```ruby
+module OnlineMigrations
+  module DataMigrations
+    class BackfillProjectIssuesCount < OnlineMigrations::DataMigration
+      def after_start
+        NotifyJob.perform_later(self.class.name)
+      end
+
+      # ...
+    end
+  end
+end
+```
+
+## Monitoring Data Migrations
+
+Data Migrations can be in various states during its execution:
 
 * **enqueued**: A migration has been enqueued by the user.
 * **running**: A migration is being performed by a migration executor.
+* **pausing**: A migration has been told to pause but is finishing work.
 * **paused**: A migration was paused in the middle of the run by the user.
 
   To manually pause a migration, you can run:
 
   ```ruby
-  migration = OnlineMigrations::BackgroundMigrations::Migration.find(id)
-  migration.paused!
+  migration = OnlineMigrations::DataMigrations::Migration.find(id)
+  migration.pause
   ```
-* **finishing**: A migration is being manually finishing inline by the user.
-  For example, if you need to manually perform a background migration until it is finished, you can run:
 
-  ```ruby
-  migration = OnlineMigrations::BackgroundMigrations::Migration.find(id)
-  runner = OnlineMigrations::BackgroundMigrations::MigrationRunner.new(migration)
-  runner.finish
-  ```
-  Note: In normal circumstances, this should not be used since background migrations should be run and finished by the scheduler.
 * **failed**: A migration raises an exception when running.
 * **succeeded**: A migration finished without error.
+* **cancelling**: A migration has been told to cancel but is finishing work.
 * **cancelled**: A migration was cancelled by the user.
 
-To get the progress (assuming `#count` method on background migration class was defined):
+  To manually cancel a migration, you can run:
+
+  ```ruby
+  migration = OnlineMigrations::DataMigrations::Migration.find(id)
+  migration.cancel
+  ```
+
+To get the progress (assuming `#count` method on data migration class was defined):
 
 ```ruby
-migration = OnlineMigrations::BackgroundMigrations::Migration.find(id)
+migration = OnlineMigrations::DataMigrations::Migration.find(id)
 migration.progress # value from 0 to 100.0
 ```
 
@@ -253,51 +338,30 @@ migration.progress # value from 0 to 100.0
 To retry a failed migration, run:
 
 ```ruby
-migration = OnlineMigrations::BackgroundMigrations::Migration.find(id)
+migration = OnlineMigrations::DataMigrations::Migration.find(id)
 migration.retry # => `true` if scheduled to be retried, `false` - if not
 ```
 
 The migration will be retried on the next Scheduler run.
 
-## Cancelling a migration
-
-To cancel an existing migration from future performing, run:
-
-```ruby
-migration = OnlineMigrations::BackgroundMigrations::Migration.find(id)
-migration.cancel
-```
-
 ## Configuring
 
-There are a few configurable options for the Background Migrations. Custom configurations should be placed in a `online_migrations.rb` initializer.
+There are a few configurable options for the data migrations. Custom configurations should be placed in a `online_migrations.rb` initializer.
 
-Check the [source code](https://github.com/fatkodima/online_migrations/blob/master/lib/online_migrations/background_migrations/config.rb) for the list of all available configuration options.
-
-**Note**: You can dynamically change certain migration parameters while the migration is run.
-For example,
-```ruby
-migration = OnlineMigrations::BackgroundMigrations::Migration.find(id)
-migration.update!(
-  batch_size: 50_000,      # The # of records migration will update per run
-  sub_batch_size: 10_000,  # The # of records migration will update via single `UPDATE`
-  batch_pause: 1.second,   # Minimum time (in seconds) between successive migration runs
-  sub_batch_pause_ms: 20   # Minimum time (in ms) between successive migration `UPDATE`s
-)
-```
+Check the [source code](https://github.com/fatkodima/online_migrations/blob/master/lib/online_migrations/background_data_migrations/config.rb) for the list of all available configuration options.
 
 ### Customizing the error handler
 
-Exceptions raised while a Background Migration is performing are rescued and information about the error is persisted in the database.
+Exceptions raised while a data migration is performing are rescued and information about the error is persisted in the database.
 
 If you want to integrate with an exception monitoring service (e.g. Bugsnag), you can define an error handler:
 
 ```ruby
 # config/initializers/online_migrations.rb
 
-config.background_migrations.error_handler = ->(error, errored_job) do
+config.background_data_migrations.error_handler = ->(error, errored_migration) do
   Bugsnag.notify(error) do |notification|
-    notification.add_metadata(:background_migration, { name: errored_job.migration_name })
+    notification.add_metadata(:background_data_migration, { name: errored_migration.name })
   end
 end
 ```
@@ -305,32 +369,52 @@ end
 The error handler should be a lambda that accepts 2 arguments:
 
 * `error`: The exception that was raised.
-* `errored_job`: An `OnlineMigrations::BackgroundMigrations::MigrationJob` object that represents a failed batch.
+* `errored_migration`: An `OnlineMigrations::BackgroundDataMigrations::Migration` object that represents a migration.
 
-### Customizing the background migrations path
+### Customizing the data migrations path
 
-`OnlineMigrations.config.background_migrations.migrations_path` can be configured to define where generated background migrations will be placed.
+`OnlineMigrations.config.background_data_migrations.migrations_path` can be configured to define where generated data migrations will be placed.
 
 ```ruby
 # config/initializers/online_migrations.rb
 
-config.background_migrations.migrations_path = "app/lib"
+config.background_data_migrations.migrations_path = "app/lib"
 ```
 
 If no value is specified, it will default to `"lib"`.
 
-### Customizing the background migrations module
+### Customizing the data migrations module
+
+`config.background_data_migrations.migrations_module` can be configured to define the module in which
+data migrations will be placed.
+
+```ruby
+# config/initializers/online_migrations.rb
+
+config.background_data_migrations.migrations_module = "DataMigrationsModule"
+```
+
+If no value is specified, it will default to `"OnlineMigrations::DataMigrations"`.
+
+### Customizing the underlying sidekiq job class
 
-`config.background_migrations.migrations_module` can be configured to define the module in which
-background migrations will be placed.
+A custom sidekiq job class can be configured to define a job class for your data migrations to use.
 
 ```ruby
 # config/initializers/online_migrations.rb
 
-config.background_migrations.migrations_module = "BackgroundMigrationsModule"
+config.background_data_migrations.job = "CustomMigrationJob"
+```
+
+```ruby
+# app/jobs/custom_migration_job.rb
+
+class CustomMigrationJob < OnlineMigrations::DataMigrations::MigrationJob
+  sidekiq_options queue: "low"
+end
 ```
 
-If no value is specified, it will default to `"OnlineMigrations::BackgroundMigrations"`.
+The job class **must inherit** from `OnlineMigrations::DataMigrations::MigrationJob`.
 
 ### Multiple databases and sharding
 
@@ -350,7 +434,9 @@ OnlineMigrations::ApplicationRecord.connects_to database: { writing: :shard_one
 By default, ActiveRecord uses the database config named `:primary` (if exists) under the environment section from the `database.yml`.
 Otherwise, the first config under the environment section is used.
 
-By default, the scheduler works on a single shard on each run. To run a separate scheduler per shard:
+#### Parallelize processing by shards
+
+By default, only a single data migration at a time is processed. To process a single data migration at a time *per shard*:
 
 ```ruby
 [:shard_one, :shard_two, :shard_three].each do |shard|
@@ -359,3 +445,16 @@ By default, the scheduler works on a single shard on each run. To run a separate
   end
 end
 ```
+
+#### Change processing concurrency
+
+By default, only a *single* data migration at a time is processed. To change the concurrency:
+
+```ruby
+every 1.minute do
+  # Run 2 data migrations in parallel.
+  runner "OnlineMigrations.run_background_data_migrations(concurrency: 2)"
+end
+```
+
+**Note**: This configuration works perfectly well in combination with the `:shard` configuration from the previous section.

data/docs/background_schema_migrations.md

@@ -103,7 +103,7 @@ To get notified about specific type of events, subscribe to the event name follo
 ```ruby
 # config/initializers/online_migrations.rb
 ActiveSupport::Notifications.subscribe("retried.background_schema_migrations") do |name, start, finish, id, payload|
-  # background schema migration object is available in payload[:background_schema_migration]
+  # background schema migration object is available in payload[:migration]
 
   # Your code here
 end
@@ -114,7 +114,7 @@ If you want to subscribe to every `background_schema_migrations` event, use:
 ```ruby
 # config/initializers/online_migrations.rb
 ActiveSupport::Notifications.subscribe(/background_schema_migrations/) do |name, start, finish, id, payload|
-  # background schema migration object is available in payload[:background_schema_migration]
+  # background schema migration object is available in payload[:migration]
 
   # Your code here
 end

data/lib/generators/online_migrations/{background_migration_generator.rb → data_migration_generator.rb}

@@ -5,11 +5,11 @@ require "rails/generators/active_record/migration"
 
 module OnlineMigrations
   # @private
-  class BackgroundMigrationGenerator < Rails::Generators::NamedBase
+  class DataMigrationGenerator < Rails::Generators::NamedBase
     include ActiveRecord::Generators::Migration
 
     source_root File.expand_path("templates", __dir__)
-    desc "This generator creates a background migration related files."
+    desc "This generator creates a background data migration related files."
 
     def create_background_data_migration_file
       migrations_module_file_path = migrations_module.underscore
@@ -20,7 +20,7 @@ module OnlineMigrations
         class_path,
         "#{file_name}.rb"
       )
-      template("background_data_migration.rb", template_file)
+      template("data_migration.rb", template_file)
     end
 
     def create_migration_file
@@ -33,7 +33,7 @@ module OnlineMigrations
       end
 
       def config
-        OnlineMigrations.config.background_migrations
+        OnlineMigrations.config.background_data_migrations
       end
 
       def migration_parent

data/lib/generators/online_migrations/templates/change_background_data_migrations.rb.tt

@@ -0,0 +1,34 @@
+class ChangeBackgroundDataMigrations < <%= migration_parent %>
+  def change
+    safety_assured do
+      change_table :background_migrations do |t|
+        t.string :cursor
+        t.string :jid
+        t.bigint :tick_total
+        t.bigint :tick_count, default: 0, null: false
+        t.float :time_running, default: 0.0, null: false
+        t.string :error_class
+        t.string :error_message
+        t.string :backtrace, array: true
+        t.string :connection_class_name
+      end
+
+      rename_column :background_migrations, :batch_max_attempts, :max_attempts
+
+      [
+        "batch_column_name",
+        "min_value",
+        "max_value",
+        "batch_size",
+        "sub_batch_size",
+        "batch_pause",
+        "sub_batch_pause_ms",
+        "composite",
+      ].each do |column|
+        change_column_null :background_migrations, column, true
+      end
+
+      rename_table :background_migrations, :background_data_migrations
+    end
+  end
+end