online_migrations 0.15.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b1b826df875fae97622c702205853da01d67153172ef73fbb0edf28a2f7ff60
-  data.tar.gz: 18ae161255543e7ab7c266efc94f1ca166a344aa18b92dd4ab2f37209fb42547
+  metadata.gz: 48ddbce66257c9010d8ab7361d8860cd898854207b5a1f4c6aa2b6b797aec2e1
+  data.tar.gz: c21fbb5f535f788e13068e339eebe77f05a378c68c00244c4522a10d50a28a0d
 SHA512:
-  metadata.gz: 705e4ce816bd8b4fcbcb78871589274bdf37acca01fbdf031883e87403a403782d28990ebed10acdf57adcbf3fb4e30e1dbf187123029bf6b1b7d31f26ccd3ca
-  data.tar.gz: 60ea354440b96645c5c03345d60793a66ba61d8aa1b946737098bc1449ba67e0b24caeb4581c525b3b014c5dd44b0ac28e0c539c8e3454ad67a3a1610cffdd79
+  metadata.gz: a5bbff2a8cca45e5fce79d653db3246bc41a4ab9d314f44131bbf74f2659d610fdaf3e87ac5e22baf7928d0cdb481e19eacaa1ed8945e4ee32f1afac3223273f
+  data.tar.gz: 6e3861f420327e0bccec7ab8e7c0a508e7cf224312c366297834091467d7cdb5e4fac8a305dbb59f7c0650d199d9a17062ab0408fd180b6fbaa05946bfd27545

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## 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

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
@@ -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
 
@@ -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
 ```
 
@@ -261,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.
@@ -321,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
@@ -345,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

@@ -216,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.
 
@@ -227,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/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

@@ -47,5 +47,29 @@ class InstallOnlineMigrations < <%= migration_parent %>
       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

data/lib/generators/online_migrations/upgrade_generator.rb

@@ -23,6 +23,11 @@ module OnlineMigrations
 
         migrations = []
         migrations << "add_sharding_to_online_migrations" if !columns.include?("shard")
+
+        if !connection.table_exists?(BackgroundSchemaMigrations::Migration.table_name)
+          migrations << "create_background_schema_migrations"
+        end
+
         migrations
       end
 

data/lib/online_migrations/application_record.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module OnlineMigrations
+  # Base class for all records used by this gem.
+  #
+  # Can be extended to setup different database where all tables related to
+  # online_migrations will live.
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/lib/online_migrations/background_migrations/config.rb

@@ -39,17 +39,13 @@ module OnlineMigrations
       #
       attr_accessor :batch_max_attempts
 
-      # Allows to throttle background migrations based on external signal (e.g. database health)
-      #
-      # It will be called before each batch run.
-      # If throttled, the current run will be retried next time.
-      #
-      # @return [Proc]
-      #
-      # @example
-      #   OnlineMigrations.config.background_migrations.throttler = -> { DatabaseStatus.unhealthy? }
-      #
-      attr_reader :throttler
+      def throttler
+        OnlineMigrations.deprecator.warn(<<~MSG)
+          `config.background_migrations.throttler` is deprecated and will be removed.
+          Use `config.throttler` instead.
+        MSG
+        OnlineMigrations.config.throttler
+      end
 
       # The number of seconds that must pass before the running job is considered stuck
       #
@@ -57,13 +53,21 @@ module OnlineMigrations
       #
       attr_accessor :stuck_jobs_timeout
 
-      # The Active Support backtrace cleaner that will be used to clean the
-      # backtrace of a migration job that errors.
-      #
-      # @return [ActiveSupport::BacktraceCleaner, nil] the backtrace cleaner to
-      #   use when cleaning a job's backtrace. Defaults to `Rails.backtrace_cleaner`
-      #
-      attr_accessor :backtrace_cleaner
+      def backtrace_cleaner
+        OnlineMigrations.deprecator.warn(<<~MSG)
+          `config.background_migrations.backtrace_cleaner` is deprecated and will be removed.
+          Use `config.backtrace_cleaner` instead.
+        MSG
+        OnlineMigrations.config.backtrace_cleaner
+      end
+
+      def backtrace_cleaner=(value)
+        OnlineMigrations.deprecator.warn(<<~MSG)
+          `config.background_migrations.backtrace_cleaner=` is deprecated and will be removed.
+          Use `config.backtrace_cleaner=` instead.
+        MSG
+        OnlineMigrations.config.backtrace_cleaner = value
+      end
 
       # The callback to perform when an error occurs in the migration job.
       #
@@ -86,17 +90,16 @@ module OnlineMigrations
         @batch_pause = 0.seconds
         @sub_batch_pause_ms = 100
         @batch_max_attempts = 5
-        @throttler = -> { false }
         @stuck_jobs_timeout = 1.hour
         @error_handler = ->(error, errored_job) {}
       end
 
       def throttler=(value)
-        if !value.respond_to?(:call)
-          raise ArgumentError, "background_migrations throttler must be a callable."
-        end
-
-        @throttler = value
+        OnlineMigrations.deprecator.warn(<<~MSG)
+          `config.background_migrations.throttler=` is deprecated and will be removed.
+          Use `config.throttler=` instead.
+        MSG
+        OnlineMigrations.config.throttler = value
       end
     end
   end

data/lib/online_migrations/background_migrations/migration.rb

@@ -181,7 +181,7 @@ module OnlineMigrations
 
       # @private
       def on_shard(&block)
-        abstract_class = find_abstract_class(migration_model)
+        abstract_class = Utils.find_connection_class(migration_model)
 
         shard = (self.shard || abstract_class.default_shard).to_sym
         abstract_class.connected_to(shard: shard, role: :writing, &block)
@@ -290,13 +290,6 @@ module OnlineMigrations
             min_value
           end
         end
-
-        def find_abstract_class(model)
-          model.ancestors.find do |parent|
-            parent == ActiveRecord::Base ||
-              (parent.is_a?(Class) && parent.abstract_class?)
-          end
-        end
     end
   end
 end

data/lib/online_migrations/background_migrations/migration_job_runner.rb

@@ -35,7 +35,7 @@ module OnlineMigrations
 
         migration_job.update!(status: :succeeded, finished_at: Time.current)
       rescue Exception => e # rubocop:disable Lint/RescueException
-        backtrace_cleaner = ::OnlineMigrations.config.background_migrations.backtrace_cleaner
+        backtrace_cleaner = ::OnlineMigrations.config.backtrace_cleaner
 
         migration_job.update!(
           status: :failed,

data/lib/online_migrations/background_migrations/migration_runner.rb

@@ -105,7 +105,7 @@ module OnlineMigrations
         end
 
         def should_throttle?
-          ::OnlineMigrations.config.background_migrations.throttler.call
+          ::OnlineMigrations.config.throttler.call
         end
 
         def find_or_create_next_migration_job

data/lib/online_migrations/background_schema_migrations/config.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module OnlineMigrations
+  module BackgroundSchemaMigrations
+    # Class representing configuration options for background schema migrations.
+    class Config
+      # Maximum number of run attempts
+      #
+      # When attempts are exhausted, the migration is marked as failed.
+      # @return [Integer] defaults to 5
+      #
+      attr_accessor :max_attempts
+
+      # Statement timeout value used when running background schema migration.
+      #
+      # @return [Integer] defaults to 1 hour
+      #
+      attr_accessor :statement_timeout
+
+      # The callback to perform when an error occurs in the migration.
+      #
+      # @example
+      #   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
+      #
+      # @return [Proc] the callback to perform when an error occurs in the migration
+      #
+      attr_accessor :error_handler
+
+      def initialize
+        @max_attempts = 5
+        @statement_timeout = 1.hour
+        @error_handler = ->(error, errored_migration) {}
+      end
+    end
+  end
+end