online_migrations 0.14.1 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 330d5ed7f11aae3b85e7fb5aab5a1ea66d809da704cf193420b6d4206f72d82b
-  data.tar.gz: 36d47a6f2a1cae3de33331a4ec9e6b21fc7b3b8b09a7d5e9c34d1be6c92e5d35
+  metadata.gz: 48ddbce66257c9010d8ab7361d8860cd898854207b5a1f4c6aa2b6b797aec2e1
+  data.tar.gz: c21fbb5f535f788e13068e339eebe77f05a378c68c00244c4522a10d50a28a0d
 SHA512:
-  metadata.gz: e07937136867b4b6bc2d0dfb2e5ccb8471faf6ce0339a247bc0c63d591cc163e084da731e86fc01ba839c7744a51e9c63e99ce632452e471f9eed98a95b9dd02
-  data.tar.gz: f1a33636d5fbd01f25a0cee32af0d74e377c804eaef0feee2c778c5318a93bbe8942dc03e8ea2bad0a610d0046a8d4e42b505d0991c7d215cc9842a24d5e5065
+  metadata.gz: a5bbff2a8cca45e5fce79d653db3246bc41a4ab9d314f44131bbf74f2659d610fdaf3e87ac5e22baf7928d0cdb481e19eacaa1ed8945e4ee32f1afac3223273f
+  data.tar.gz: 6e3861f420327e0bccec7ab8e7c0a508e7cf224312c366297834091467d7cdb5e4fac8a305dbb59f7c0650d199d9a17062ab0408fd180b6fbaa05946bfd27545

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 ## master (unreleased)
 
+## 0.16.0 (2024-03-28)
+
+- Add support for asynchronous creation/removal of indexes
+
+    See `docs/background_schema_migrations.md` for the feature description.
+
+## 0.15.0 (2024-03-19)
+
+- Reraise errors when running background migrations inline
+- Add `remove_background_migration` migration helper
+- Allow adding bigint foreign keys referencing integer primary keys
+- Fix `add_reference_concurrently` to check for mismatched key types
+
 ## 0.14.1 (2024-02-21)
 
 - Fix `MigrationRunner` to consider `run_background_migrations_inline` proc

data/README.md

@@ -40,11 +40,11 @@ $ bin/rails generate online_migrations:install
 $ bin/rails db:migrate
 ```
 
-**Note**: If you do not have plans on using [background migrations](docs/background_migrations.md) feature, then you can delete the generated migration and regenerate it later, if needed.
+**Note**: If you do not have plans on using [background data migrations](docs/background_data_migrations.md) or [background schema migrations](docs/background_schema_migrations.md) features, then you can delete the generated migration and regenerate it later, if needed.
 
 ### Upgrading
 
-If you're already using [background migrations](docs/background_migrations.md), your background migrations tables may require additional columns. After every upgrade run:
+If you're already using [background data migrations](docs/background_data_migrations.md) or [background schema migrations](docs/background_schema_migrations.md), your background migrations tables may require additional columns. After every upgrade run:
 
 ```sh
 $ bin/rails generate online_migrations:upgrade
@@ -191,7 +191,7 @@ end
 
    ```ruby
    class User < ApplicationRecord
-     self.ignored_columns = ["name"]
+     self.ignored_columns += ["name"]
    end
    ```
 
@@ -285,7 +285,7 @@ end
 ```
 
 **Note**: If you forget `disable_ddl_transaction!`, the migration will fail.
-**Note**: You may consider [background migrations](#background-migrations) to run data changes on large tables.
+**Note**: You may consider [background data migrations](#background-data-migrations) or [background schema migrations](#background-schema-migrations) to run data changes on large tables.
 
 ### Changing the type of a column
 
@@ -488,7 +488,7 @@ It will use a combination of a VIEW and column aliasing to work with both column
 
    ```ruby
    class User < ApplicationRecord
-     self.ignored_columns = ["name"]
+     self.ignored_columns += ["name"]
    end
    ```
 
@@ -1172,7 +1172,7 @@ A safer approach is to:
 
    ```ruby
    class User < ApplicationRecord
-     self.ignored_columns = ["type"]
+     self.ignored_columns += ["type"]
    end
    ```
 
@@ -1228,9 +1228,13 @@ Certain methods like `execute` and `change_table` cannot be inspected and are pr
 
 Read [configuring.md](docs/configuring.md).
 
-## Background Migrations
+## Background Data Migrations
 
-Read [background_migrations.md](docs/background_migrations.md) on how to perform data migrations on large tables.
+Read [background_data_migrations.md](docs/background_data_migrations.md) on how to perform data migrations on large tables.
+
+## Background Schema Migrations
+
+Read [background_schema_migrations.md](docs/background_schema_migrations.md) on how to perform background schema migrations on large tables.
 
 ## Credits
 
@@ -1295,7 +1299,7 @@ The main differences are:
      * adding different types of constraints
      * and others
 
-2. This gem has a [powerful internal framework](https://github.com/fatkodima/online_migrations/blob/master/docs/background_migrations.md) for running data migrations on very large tables using background migrations.
+2. This gem has a powerful internal framework for running [data migrations](docs/background_data_migrations.md) and [schema migrations](docs/background_schema_migrations.md) on very large tables in background.
 
    For example, you can use background migrations to migrate data that’s stored in a single JSON column to a separate table instead; backfill values from one column to another (as one of the steps when changing column type); or backfill some column’s value from an API.
 

data/docs/{background_migrations.md → background_data_migrations.md}

@@ -1,4 +1,4 @@
-# Background Migrations
+# Background Data Migrations
 
 When a project grows, your database starts to be heavy and changing the data through the deployment process can be very painful.
 
@@ -18,7 +18,7 @@ Start a background migrations scheduler. For example, to run it on cron using [w
 
 ```ruby
 every 1.minute do
-  runner "OnlineMigrations.run_background_migrations"
+  runner "OnlineMigrations.run_background_data_migrations"
 end
 ```
 
@@ -30,7 +30,8 @@ A generator is provided to create background migrations. Generate a new backgrou
 $ bin/rails generate online_migrations:background_migration backfill_project_issues_count
 ```
 
-This creates the background migration file `lib/online_migrations/background_migrations/backfill_project_issues_count.rb`.
+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.
 
 The generated class is a subclass of `OnlineMigrations::BackgroundMigration` that implements:
 
@@ -76,12 +77,16 @@ end
 You can enqueue your background migration to be run by the scheduler via:
 
 ```ruby
-# db/migrate/xxxxxxxxxxxxxx_backfill_project_issues_count.rb
-# ...
-def up
-  enqueue_background_migration("BackfillProjectIssuesCount")
+# db/migrate/xxxxxxxxxxxxxx_enqueue_backfill_project_issues_count.rb
+class EnqueueBackfillProjectIssuesCount < ActiveRecord::Migration[7.1]
+  def up
+    enqueue_background_migration("BackfillProjectIssuesCount")
+  end
+
+  def down
+    remove_background_migration("BackfillProjectIssuesCount")
+  end
 end
-# ...
 ```
 
 `enqueue_background_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.
@@ -106,7 +111,17 @@ end
 And pass them when enqueuing:
 
 ```ruby
-enqueue_background_migration("MyMigrationWithArgs", arg1, arg2, ...)
+def up
+  enqueue_background_migration("MyMigrationWithArgs", arg1, arg2, ...)
+end
+```
+
+Make sure to also pass the arguments inside the `down` method of the migration:
+
+```ruby
+def down
+  remove_background_migration("MyMigrationWithArgs", arg1, arg2, ...)
+end
 ```
 
 ## Considerations when writing Background Migrations
@@ -246,20 +261,6 @@ migration.update!(
 )
 ```
 
-### Throttling
-
-Background Migrations often modify a lot of data and can be taxing on your database. There is a throttling mechanism that can be used to throttle a background migration when a given condition is met. If a migration is throttled, it will be interrupted and retried on the next Scheduler cycle run.
-
-Specify the throttle condition as a block:
-
-```ruby
-# config/initializers/online_migrations.rb
-
-config.background_migrations.throttler = -> { DatabaseStatus.unhealthy? }
-```
-
-Note that it's up to you to define a throttling condition that makes sense for your app. For example, you can check various PostgreSQL metrics such as replication lag, DB threads, whether DB writes are available, etc.
-
 ### Customizing the error handler
 
 Exceptions raised while a Background Migration is performing are rescued and information about the error is persisted in the database.
@@ -306,21 +307,6 @@ config.background_migrations.migrations_module = "BackgroundMigrationsModule"
 
 If no value is specified, it will default to `"OnlineMigrations::BackgroundMigrations"`.
 
-### Customizing the backtrace cleaner
-
-`config.background_migrations.backtrace_cleaner` can be configured to specify a backtrace cleaner to use when a Background Migration errors and the backtrace is cleaned and persisted. An `ActiveSupport::BacktraceCleaner` should be used.
-
-```ruby
-# config/initializers/online_migrations.rb
-
-cleaner = ActiveSupport::BacktraceCleaner.new
-cleaner.add_silencer { |line| line =~ /ignore_this_dir/ }
-
-config.background_migrations.backtrace_cleaner = cleaner
-```
-
-If none is specified, the default `Rails.backtrace_cleaner` will be used to clean backtraces.
-
 ### Multiple databases and sharding
 
 If you have multiple databases or sharding, you may need to configure where background migrations related tables live
@@ -330,10 +316,10 @@ by configuring the parent model:
 # config/initializers/online_migrations.rb
 
 # Referring to one of the databases
-OnlineMigrations::BackgroundMigrations::ApplicationRecord.connects_to database: { writing: :animals }
+OnlineMigrations::ApplicationRecord.connects_to database: { writing: :animals }
 
 # Referring to one of the shards (via `:database` option)
-OnlineMigrations::BackgroundMigrations::ApplicationRecord.connects_to database: { writing: :shard_one }
+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`.

data/docs/background_schema_migrations.md

@@ -0,0 +1,163 @@
+# Background Schema Migrations
+
+When a project grows, your database starts to be heavy and performing schema changes through the deployment process can be very painful.
+
+E.g., for very large tables, index creation can be a challenge to manage. While adding indexes `CONCURRENTLY` creates indexes in a way that does not block ordinary traffic, it can still be problematic when index creation runs for many hours. Necessary database operations like autovacuum cannot run, and the deployment process is usually blocked waiting for index creation to finish.
+
+**Note**: You probably don't need to use this feature for smaller projects, since performing schema changes directly on smaller databases will be perfectly fine and will not block the deployment too much.
+
+## Installation
+
+Make sure you have migration files generated when installed this gem:
+
+```sh
+$ 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:
+
+```ruby
+every 1.minute do
+  runner "OnlineMigrations.run_background_schema_migrations"
+end
+```
+
+or run it manually when the deployment is finished, from the rails console:
+
+```rb
+[production] (main)> OnlineMigrations.run_background_schema_migrations
+```
+
+**Note**: Scheduler will perform only one migration at a time, to not load the database too much. If you enqueued multiple migrations or a migration for multiple shards, you need to call this method a few times.
+
+**Note**: Make sure that the process that runs the scheduler does not die until the migration is finished.
+
+## Enqueueing a Background Schema Migration
+
+Currently, only helpers for adding/removing indexes are provided.
+
+Background schema migrations should be performed in 2 steps:
+
+1. Create a PR that schedules the index to be created/removed
+2. Verify that the PR was deployed and that the index was actually created/removed on production.
+  Create a follow-up PR with a regular migration that creates/removes an index synchronously (will be a no op when run on production) and commit the schema changes for `schema.rb`/`structure.sql`
+
+To schedule an index creation:
+
+```ruby
+# db/migrate/xxxxxxxxxxxxxx_add_index_to_users_email_in_background.rb
+def up
+  add_index_in_background(:users, :email, unique: true)
+end
+```
+
+To schedule an index removal:
+
+```ruby
+# db/migrate/xxxxxxxxxxxxxx_remove_index_from_users_email_in_background.rb
+def up
+  remove_index_in_background(:users, name: "index_users_on_email")
+end
+```
+
+`add_index_in_background`/`remove_index_in_background` accept additional configuration options which controls how the background schema migration is run. Check the [source code](https://github.com/fatkodima/online_migrations/blob/master/lib/online_migrations/background_schema_migrations/migration_helpers.rb) for the list of all available configuration options.
+
+## Instrumentation
+
+Background schema migrations use the [ActiveSupport::Notifications](http://api.rubyonrails.org/classes/ActiveSupport/Notifications.html) API.
+
+You can subscribe to `background_schema_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_schema_migrations` namespace. E.g. for retries use:
+
+```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]
+
+  # Your code here
+end
+```
+
+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]
+
+  # Your code here
+end
+```
+
+Available events:
+
+* `started.background_schema_migrations`
+* `run.background_schema_migrations`
+* `completed.background_schema_migrations`
+* `retried.background_schema_migrations`
+* `throttled.background_schema_migrations`
+
+## Monitoring Background Schema Migrations
+
+Background Schema 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.
+* **failed**: A migration raises an exception when running.
+* **succeeded**: A migration finished without error.
+
+## Configuring
+
+There are a few configurable options for the Background Schema 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_schema_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::BackgroundSchemaMigrations::Migration.find(id)
+migration.update!(
+  statement_timeout: 2.hours,  # The statement timeout value used when running the migration
+  max_attempts: 10             # The # of attempts the failing migration will be retried
+)
+```
+
+### Customizing the error handler
+
+Exceptions raised while a Background Schema 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
+
+OnlineMigrations.config.background_schema_migrations.error_handler = ->(error, errored_migration) do
+  Bugsnag.notify(error) do |notification|
+    notification.add_metadata(:background_schema_migration, { name: errored_migration.name })
+  end
+end
+```
+
+The error handler should be a lambda that accepts 2 arguments:
+
+* `error`: The exception that was raised.
+* `errored_migration`: An `OnlineMigrations::BackgroundSchemaMigrations::Migration` object that represents a failed migration.
+
+### Multiple databases and sharding
+
+If you have multiple databases or sharding, you may need to configure where background migrations related tables live
+by configuring the parent model:
+
+```ruby
+# config/initializers/online_migrations.rb
+
+# Referring to one of the databases
+OnlineMigrations::ApplicationRecord.connects_to database: { writing: :animals }
+
+# Referring to one of the shards (via `:database` option)
+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.

data/docs/configuring.md

@@ -101,13 +101,15 @@ config.lock_retrier = OnlineMigrations::ExponentialLockRetrier.new(
 )
 ```
 
-When statement within transaction fails - the whole transaction is retried.
+When a statement within transaction fails - the whole transaction is retried. If any statement fails when running outside a transaction (e.g. using `disable_ddl_transaction!`) then only that statement is retried.
 
-To permanently disable lock retries, you can set `lock_retrier` to `nil`.
+**Note**: Statements are retried by default, unless lock retries are disabled. It is possible to implement more sophisticated lock retriers. See [source code](https://github.com/fatkodima/online_migrations/blob/master/lib/online_migrations/lock_retrier.rb) for the examples.
 
 To temporarily disable lock retries while running migrations, set `DISABLE_LOCK_RETRIES` env variable. This is useful when you are deploying a hotfix and do not want to wait too long while the lock retrier safely tries to acquire the lock, but try to acquire the lock immediately with the default configured lock timeout value.
 
-**Note**: Statements are retried by default, unless lock retries are disabled. It is possible to implement more sophisticated lock retriers. See [source code](https://github.com/fatkodima/online_migrations/blob/master/lib/online_migrations/lock_retrier.rb) for the examples.
+To permanently disable lock retries, you can set `lock_retrier` to `nil`.
+
+Finally, if your lock retrier implementation does not have an explicit `lock_timeout` value configured, then the timeout behavior will fallback to the database configuration (`config/database.yml`) or the PostgreSQL server config value ([off by default](https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-LOCK-TIMEOUT)). Take care configuring this value, as this fallback may result in your migrations running without a lock timeout!
 
 ## Existing Migrations
 
@@ -214,7 +216,7 @@ Add to an initializer file:
 config.auto_analyze = true
 ```
 
-### Running background migrations inline
+## Running background migrations inline
 
 `config.run_background_migrations_inline` can be configured with a proc to decide whether background migrations should be run inline. For convenience defaults to true for development and test environments.
 
@@ -225,6 +227,35 @@ config.run_background_migrations_inline = -> { Rails.env.local? }
 
 Set to `nil` to avoid running background migrations inline.
 
+## Throttling
+
+Background data and schema migrations can be taxing on your database. There is a throttling mechanism that can be used to throttle a background migration when a given condition is met. If a migration is throttled, it will be interrupted and retried on the next Scheduler cycle run.
+
+Specify the throttle condition as a block:
+
+```ruby
+# config/initializers/online_migrations.rb
+
+OnlineMigrations.config.throttler = -> { DatabaseStatus.unhealthy? }
+```
+
+**Note**: It's up to you to define a throttling condition that makes sense for your app. For example, you can check various PostgreSQL metrics such as replication lag, DB threads, whether DB writes are available, etc.
+
+## Customizing the backtrace cleaner
+
+`OnlineMigrations.config.backtrace_cleaner` can be configured to specify a backtrace cleaner to use when a background data or schema migration errors and the backtrace is cleaned and persisted. An `ActiveSupport::BacktraceCleaner` should be used.
+
+```ruby
+# config/initializers/online_migrations.rb
+
+cleaner = ActiveSupport::BacktraceCleaner.new
+cleaner.add_silencer { |line| line =~ /ignore_this_dir/ }
+
+OnlineMigrations.config.backtrace_cleaner = cleaner
+```
+
+If none is specified, the default `Rails.backtrace_cleaner` will be used to clean backtraces.
+
 ## Schema Sanity
 
 Columns can flip order in `db/schema.rb` when you have multiple developers. One way to prevent this is to [alphabetize them](https://www.pgrs.net/2008/03/12/alphabetize-schema-rb-columns/).

data/lib/generators/online_migrations/background_migration_generator.rb

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
 require "rails/generators"
+require "rails/generators/active_record/migration"
 
 module OnlineMigrations
   # @private
   class BackgroundMigrationGenerator < Rails::Generators::NamedBase
+    include ActiveRecord::Generators::Migration
+
     source_root File.expand_path("templates", __dir__)
-    desc "This generator creates a background migration file."
+    desc "This generator creates a background migration related files."
 
     def create_background_migration_file
       migrations_module_file_path = migrations_module.underscore
@@ -20,6 +23,10 @@ module OnlineMigrations
       template("background_migration.rb", template_file)
     end
 
+    def create_migration_file
+      migration_template("migration.rb", File.join(db_migrate_path, "enqueue_#{file_name}.rb"))
+    end
+
     private
       def migrations_module
         config.migrations_module
@@ -28,5 +35,9 @@ module OnlineMigrations
       def config
         OnlineMigrations.config.background_migrations
       end
+
+      def migration_parent
+        "ActiveRecord::Migration[#{Utils.ar_version}]"
+      end
   end
 end

data/lib/generators/online_migrations/install_generator.rb

@@ -15,7 +15,7 @@ module OnlineMigrations
     end
 
     def create_migration_file
-      migration_template("migration.rb", File.join(db_migrate_path, "install_online_migrations.rb"))
+      migration_template("install_migration.rb", File.join(db_migrate_path, "install_online_migrations.rb"))
     end
 
     private

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

@@ -0,0 +1,29 @@
+class CreateBackgroundSchemaMigrations < <%= migration_parent %>
+  def change
+    # You can remove this migration for now and regenerate it later if you do not have plans
+    # to use background schema migrations, like adding indexes in the background.
+    create_table :background_schema_migrations do |t|
+      t.bigint :parent_id
+      t.string :migration_name, null: false
+      t.string :table_name, null: false
+      t.string :definition, null: false
+      t.string :status, default: "enqueued", null: false
+      t.string :shard
+      t.boolean :composite, default: false, null: false
+      t.integer :statement_timeout
+      t.datetime :started_at
+      t.datetime :finished_at
+      t.integer :max_attempts, null: false
+      t.integer :attempts, default: 0, null: false
+      t.string :error_class
+      t.string :error_message
+      t.string :backtrace, array: true
+      t.string :connection_class_name
+      t.timestamps
+
+      t.foreign_key :background_schema_migrations, column: :parent_id, on_delete: :cascade
+
+      t.index [:migration_name, :shard], unique: true, name: :index_background_schema_migrations_on_unique_configuration
+    end
+  end
+end

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

@@ -77,12 +77,20 @@ OnlineMigrations.configure do |config|
   #   end
   # end
 
-  # Decide whether background migrations should be run inline.
+  # Decide whether background data and schema migrations should be run inline.
   # Convenient for development and test environments.
   config.run_background_migrations_inline = -> { Rails.env.local? }
 
-  # ==> Background migrations configuration
+  # Configure custom throttler for background data and schema migrations.
+  # It will be called before each run.
+  # If throttled, the current run will be retried next time.
+  # config.throttler = -> { DatabaseStatus.unhealthy? }
+
+  # The Active Support backtrace cleaner that will be used to clean the
+  # backtrace of a background data or schema migration that errors.
+  config.backtrace_cleaner = Rails.backtrace_cleaner
 
+  # ==> Background data migrations configuration
   # The path where generated background migrations will be placed.
   # config.background_migrations.migrations_path = "lib"
 
@@ -105,22 +113,27 @@ OnlineMigrations.configure do |config|
   # When attempts are exhausted, the individual batch is marked as failed.
   # config.background_migrations.batch_max_attempts = 5
 
-  # Configure custom throttler for background migrations.
-  # It will be called before each batch run.
-  # If throttled, the current run will be retried next time.
-  # config.background_migrations.throttler = -> { DatabaseStatus.unhealthy? }
-
   # The number of seconds that must pass before the running job is considered stuck.
   # config.background_migrations.stuck_jobs_timeout = 1.hour
 
-  # The Active Support backtrace cleaner that will be used to clean the
-  # backtrace of a migration job that errors.
-  config.background_migrations.backtrace_cleaner = Rails.backtrace_cleaner
-
   # The callback to perform when an error occurs in the migration job.
   # config.background_migrations.error_handler = ->(error, errored_job) do
   #   Bugsnag.notify(error) do |notification|
   #     notification.add_metadata(:background_migration, { name: errored_job.migration_name })
   #   end
   # end
+
+  # ==> Background schema migrations configuration
+  # When attempts are exhausted, the failing migration stops to be retried.
+  # config.background_schema_migrations.max_attempts = 5
+
+  # Statement timeout value used when running background schema migration.
+  # config.background_schema_migrations.statement_timeout = 1.hour
+
+  # The callback to perform when an error occurs during the background schema migration.
+  # config.background_schema_migrations.error_handler = ->(error, errored_migration) do
+  #   Bugsnag.notify(error) do |notification|
+  #     notification.add_metadata(:background_schema_migration, { name: errored_migration.name })
+  #   end
+  # end
 end

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

@@ -0,0 +1,75 @@
+class InstallOnlineMigrations < <%= migration_parent %>
+  def change
+    create_table :background_migrations do |t|
+      t.bigint :parent_id
+      t.string :migration_name, null: false
+      t.jsonb :arguments, default: [], null: false
+      t.string :batch_column_name, null: false
+      t.bigint :min_value, null: false
+      t.bigint :max_value, null: false
+      t.bigint :rows_count
+      t.integer :batch_size, null: false
+      t.integer :sub_batch_size, null: false
+      t.integer :batch_pause, null: false
+      t.integer :sub_batch_pause_ms, null: false
+      t.integer :batch_max_attempts, null: false
+      t.string :status, default: "enqueued", null: false
+      t.string :shard
+      t.boolean :composite, default: false, null: false
+      t.timestamps
+
+      t.foreign_key :background_migrations, column: :parent_id, on_delete: :cascade
+
+      t.index [:migration_name, :arguments, :shard],
+        unique: true, name: :index_background_migrations_on_unique_configuration
+    end
+
+    create_table :background_migration_jobs do |t|
+      t.bigint :migration_id, null: false
+      t.bigint :min_value, null: false
+      t.bigint :max_value, null: false
+      t.integer :batch_size, null: false
+      t.integer :sub_batch_size, null: false
+      t.integer :pause_ms, null: false
+      t.datetime :started_at
+      t.datetime :finished_at
+      t.string :status, default: "enqueued", null: false
+      t.integer :max_attempts, null: false
+      t.integer :attempts, default: 0, null: false
+      t.string :error_class
+      t.string :error_message
+      t.string :backtrace, array: true
+      t.timestamps
+
+      t.foreign_key :background_migrations, column: :migration_id, on_delete: :cascade
+
+      t.index [:migration_id, :max_value], name: :index_background_migration_jobs_on_max_value
+      t.index [:migration_id, :status, :updated_at], name: :index_background_migration_jobs_on_updated_at
+      t.index [:migration_id, :finished_at], name: :index_background_migration_jobs_on_finished_at
+    end
+
+    create_table :background_schema_migrations do |t|
+      t.bigint :parent_id
+      t.string :migration_name, null: false
+      t.string :table_name, null: false
+      t.string :definition, null: false
+      t.string :status, default: "enqueued", null: false
+      t.string :shard
+      t.boolean :composite, default: false, null: false
+      t.integer :statement_timeout
+      t.datetime :started_at
+      t.datetime :finished_at
+      t.integer :max_attempts, null: false
+      t.integer :attempts, default: 0, null: false
+      t.string :error_class
+      t.string :error_message
+      t.string :backtrace, array: true
+      t.string :connection_class_name
+      t.timestamps
+
+      t.foreign_key :background_schema_migrations, column: :parent_id, on_delete: :cascade
+
+      t.index [:migration_name, :shard], unique: true, name: :index_background_schema_migrations_on_unique_configuration
+    end
+  end
+end