online_migrations 0.31.2 → 0.33.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4afb5d9ab9916861d263de3c38a2436d2ee131ae9988edf282866145a274356d
-  data.tar.gz: 761d30f417479db296429af0668bf62e47581aa4a73fce1d9ba72bd62c66173f
+  metadata.gz: 7f092b18d7bc864ba2232a41727e136bb86469279bdc3ad4c04a49a49628fb95
+  data.tar.gz: b7349d9b1c818ed4fefd078f7262bb380bb22a34109be13d2ead3191f338dbc9
 SHA512:
-  metadata.gz: 9e6930e8069732e7988b731d826a9e82b023c8f4bbebd5827a31efa10747ada86af64e7e75553df5a8d2e318688002e9c194cdf07e9124ef4231986197d885e7
-  data.tar.gz: fe46acbfd31436293ead08b37258c877ca4eddf3bb6c41e462a74c89153d4f632e244c2fa5b98b0887fbfe024a3ab8a9ada8ad101fffb9bebfd10dbbd9f5c9bc
+  metadata.gz: 4a52e29b327dbecae7f1c31fa4020fa5b428c5f830ea34215695bfd827c787c90146dda6dd12045a5c7f4cc2136741bb1a08b76b2a3ad7273f69c028d192a764
+  data.tar.gz: 6175ee34939fbdc6c21605320c36cfdeca971458381e1d6e465e7b464b302914f87f69c7bbcfc50c3b150fc9b9d6d8d34e0d0a1fd2a0573940aa1efa36e983a5

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 ## master (unreleased)
 
+## 0.33.0 (2026-02-04)
+
+- Change background migrations default status to "pending"
+
+    Note: Run `bin/rails generate online_migrations:upgrade` if using background migrations.
+
+- Fix copying partial indexes when changing column type
+
+## 0.32.0 (2026-01-07)
+
+- Add ability to create delayed background migrations
+
+  ```ruby
+  add_index_in_background(:users, :name, delay: true)
+  enqueue_background_data_migration("MyMigration", delay: true)
+  ```
+
+  They will start only after approval from the user.
+
+- Fix enqueueing background data migrations with the same name on different tables
+
+    Note: Run `bin/rails generate online_migrations:upgrade` if using background schema migrations.
+
 ## 0.31.2 (2025-11-13)
 
 - Fix running background data migrations inline

data/docs/background_data_migrations.md

@@ -300,7 +300,8 @@ end
 
 Data Migrations can be in various states during its execution:
 
-* **enqueued**: A migration has been enqueued by the user.
+* **pending**: A migration has been created by the user.
+* **enqueued**: A migration has been enqueued by the scheduler.
 * **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.
@@ -312,7 +313,8 @@ Data Migrations can be in various states during its execution:
   migration.pause
   ```
 
-* **failed**: A migration raises an exception when running.
+* **errored**: A migration raised an error during last run.
+* **failed**: A migration raises an error when running and retry attempts exceeded.
 * **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.
@@ -324,6 +326,14 @@ Data Migrations can be in various states during its execution:
   migration.cancel
   ```
 
+* **delayed**: A migration was created, but waiting approval from the user to start running.
+
+  To create a delayed migration, you can pass a `delayed: true` option:
+
+  ```ruby
+  enqueue_background_data_migration("MyMigration", delay: true)
+  ```
+
 To get the progress (assuming `#count` method on data migration class was defined):
 
 ```ruby

data/docs/background_schema_migrations.md

@@ -132,13 +132,21 @@ Available events:
 
 Background Schema Migrations can be in various states during its execution:
 
-* **enqueued**: A migration has been enqueued by the user.
+* **pending**: A migration has been created by the user.
 * **running**: A migration is being performed by a migration executor.
 * **errored**: A migration raised an error during last run.
 * **failed**: A migration raises an error when running and retry attempts exceeded.
 * **succeeded**: A migration finished without error.
 * **cancelled**: A migration was cancelled by the user.
 
+* **delayed**: A migration was created, but waiting approval from the user to start running.
+
+  To create a delayed migration, you can pass a `delayed: true` option:
+
+  ```ruby
+  add_index_in_background(:users, :name, delay: true)
+  ```
+
 ## Configuring
 
 There are a few configurable options for the Background Schema Migrations. Custom configurations should be placed in a `online_migrations.rb` initializer.

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

@@ -0,0 +1,7 @@
+class BackgroundDataMigrationsRemoveIterationPauseDefault < <%= migration_parent %>
+  def change
+    safety_assured("Table is small") do
+      change_column_default :background_data_migrations, :iteration_pause, nil
+    end
+  end
+end

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

@@ -0,0 +1,8 @@
+class BackgroundDataMigrationsChangeStatusDefault < <%= migration_parent %>
+  def change
+    safety_assured do
+      change_column_default :background_data_migrations, :status, from: "enqueued", to: "pending"
+      change_column_default :background_schema_migrations, :status, from: "enqueued", to: "pending"
+    end
+  end
+end

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

@@ -2,7 +2,7 @@ class BackgroundSchemaMigrationsChangeUniqueIndex < <%= migration_parent %>
   def change
     safety_assured("Table is small") do
       remove_index :background_schema_migrations, name: :index_background_schema_migrations_on_unique_configuration
-      add_index :background_schema_migrations, [:migration_name, :shard, :connection_class_name], unique: true,
+      add_index :background_schema_migrations, [:migration_name, :table_name, :shard, :connection_class_name], unique: true,
         name: :index_background_schema_migrations_on_unique_configuration
     end
   end

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

@@ -3,7 +3,7 @@ class InstallOnlineMigrations < <%= migration_parent %>
     create_table :background_data_migrations do |t|
       t.string :migration_name, null: false
       t.jsonb :arguments, default: [], null: false
-      t.string :status, default: "enqueued", null: false
+      t.string :status, default: "pending", null: false
       t.string :shard
       t.string :cursor
       t.string :jid
@@ -13,7 +13,7 @@ class InstallOnlineMigrations < <%= migration_parent %>
       t.bigint :tick_count, default: 0, null: false
       t.float :time_running, default: 0.0, null: false
       t.integer :max_attempts, null: false
-      t.float :iteration_pause, default: 0.0, null: false
+      t.float :iteration_pause, null: false
       t.string :error_class
       t.string :error_message
       t.string :backtrace, array: true
@@ -28,7 +28,7 @@ class InstallOnlineMigrations < <%= migration_parent %>
       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 :status, default: "pending", null: false
       t.string :shard
       t.integer :statement_timeout
       t.datetime :started_at
@@ -41,7 +41,7 @@ class InstallOnlineMigrations < <%= migration_parent %>
       t.string :connection_class_name
       t.timestamps
 
-      t.index [:migration_name, :shard, :connection_class_name], unique: true,
+      t.index [:migration_name, :table_name, :shard, :connection_class_name], unique: true,
         name: :index_background_schema_migrations_on_unique_configuration
     end
   end

data/lib/generators/online_migrations/upgrade_generator.rb

@@ -30,7 +30,7 @@ module OnlineMigrations
         end
 
         indexes = connection.indexes(:background_schema_migrations)
-        unique_index = indexes.find { |i| i.unique && i.columns.sort == ["connection_class_name", "migration_name", "shard"] }
+        unique_index = indexes.find { |i| i.unique && i.columns.sort == ["connection_class_name", "migration_name", "shard", "table_name"] }
         if !unique_index
           migrations << "background_schema_migrations_change_unique_index"
         end
@@ -47,6 +47,16 @@ module OnlineMigrations
           migrations << "background_data_migrations_add_iteration_pause"
         end
 
+        iteration_pause_column = connection.columns(:background_data_migrations).find { |c| c.name == "iteration_pause" }
+        if iteration_pause_column && iteration_pause_column.default
+          migrations << "background_data_migrations_remove_iteration_pause_default"
+        end
+
+        status_column = connection.columns(:background_data_migrations).find { |c| c.name == "status" }
+        if status_column.default == "enqueued"
+          migrations << "background_migrations_change_status_default"
+        end
+
         migrations
       end
 

data/lib/online_migrations/background_data_migrations/migration.rb

@@ -11,21 +11,26 @@ module OnlineMigrations
       include ShardAware
 
       STATUSES = [
-        "enqueued",    # The migration has been enqueued by the user.
+        "pending",     # The migration has been created by the user.
+        "enqueued",    # The migration has been enqueued by the scheduler.
         "running",     # The migration is being performed by a migration executor.
         "pausing",     # The migration has been told to pause but is finishing work.
         "paused",      # The migration was paused in the middle of the run by the user.
-        "failed",      # The migration raises an exception when running.
+        "errored",     # The migration raised an error during last run.
+        "failed",      # The migration raises an error when running and retry attempts exceeded.
         "succeeded",   # The migration finished without error.
         "cancelling",  # The migration has been told to cancel but is finishing work.
         "cancelled",   # The migration was cancelled by the user.
+        "delayed",     # The migration was created, but waiting approval from the user to start running.
       ]
 
       COMPLETED_STATUSES = ["succeeded", "failed", "cancelled"]
 
       ACTIVE_STATUSES = [
+        "pending",
         "enqueued",
         "running",
+        "failed",
         "pausing",
         "paused",
         "cancelling",
@@ -86,7 +91,7 @@ module OnlineMigrations
       end
 
       # Returns whether the migration is active, which is defined as
-      # having a status of enqueued, running, pausing, paused, or cancelling.
+      # having a status of pending, enqueued, running, pausing, paused, or cancelling.
       #
       # @return [Boolean] whether the migration is active.
       #
@@ -106,22 +111,18 @@ module OnlineMigrations
       end
 
       # Returns whether a migration is stuck, which is defined as having a status of
-      # cancelling or pausing, and not having been updated in the last 5 minutes.
+      # running, cancelling or pausing, and not having been updated in the last 5 minutes.
       #
       # @return [Boolean] whether the migration is stuck.
       #
       def stuck?
         stuck_timeout = OnlineMigrations.config.background_data_migrations.stuck_timeout
-        (cancelling? || pausing?) && updated_at <= stuck_timeout.ago
+        (running? || cancelling? || pausing?) && updated_at <= stuck_timeout.ago
       end
 
       # @private
       def start
-        if running? && !started?
-          update!(started_at: Time.current)
-          data_migration.after_start
-          true
-        elsif enqueued?
+        if enqueued?
           update!(status: :running, started_at: Time.current)
           data_migration.after_start
           true
@@ -130,6 +131,19 @@ module OnlineMigrations
         end
       end
 
+      # Enqueue this data migration. No-op if migration is not delayed.
+      #
+      # @return [Boolean] whether this data migration was enqueued.
+      #
+      def enqueue
+        if delayed?
+          pending!
+          true
+        else
+          false
+        end
+      end
+
       # Cancel this data migration. No-op if migration is completed.
       #
       # @return [Boolean] whether this data migration was cancelled.
@@ -137,9 +151,9 @@ module OnlineMigrations
       def cancel
         return false if completed?
 
-        if paused? || stuck?
+        if paused? || delayed? || stuck?
           update!(status: :cancelled, finished_at: Time.current)
-        elsif enqueued?
+        elsif pending? || enqueued? || errored?
           cancelled!
         else
           cancelling!
@@ -155,7 +169,7 @@ module OnlineMigrations
       def pause
         return false if completed?
 
-        if enqueued? || stuck?
+        if pending? || enqueued? || delayed? || stuck? || errored?
           paused!
         else
           pausing!
@@ -170,7 +184,7 @@ module OnlineMigrations
       #
       def resume
         if paused?
-          enqueued!
+          pending!
           true
         else
           false
@@ -221,13 +235,14 @@ module OnlineMigrations
       end
 
       # @private
-      def persist_error(error)
+      def persist_error(error, attempt)
         backtrace = error.backtrace
         backtrace_cleaner = OnlineMigrations.config.backtrace_cleaner
         backtrace = backtrace_cleaner.clean(backtrace) if backtrace_cleaner
+        status = attempt >= max_attempts ? :failed : :errored
 
         update!(
-          status: :failed,
+          status: status,
           finished_at: Time.current,
           error_class: error.class.name,
           error_message: error.message,
@@ -276,7 +291,7 @@ module OnlineMigrations
       def retry
         if failed?
           update!(
-            status: :enqueued,
+            status: :pending,
             started_at: nil,
             finished_at: nil,
             error_class: nil,

data/lib/online_migrations/background_data_migrations/migration_helpers.rb

@@ -338,6 +338,7 @@ module OnlineMigrations
       #
       # @param migration_name [String, Class] Background migration class name
       # @param arguments [Array] Extra arguments to pass to the migration instance when the migration runs
+      # @param delay [Boolean] Whether this migration should be delayed and approved by the user to start running.
       # @option options [Integer] :max_attempts (5) Maximum number of batch run attempts
       # @option options [String, nil] :connection_class_name Class name to use to get connections
       #
@@ -368,7 +369,7 @@ module OnlineMigrations
       # @note For convenience, the enqueued background data migration is run inline
       #     in development and test environments
       #
-      def enqueue_background_data_migration(migration_name, *arguments, **options)
+      def enqueue_background_data_migration(migration_name, *arguments, delay: false, **options)
         options.assert_valid_keys(:max_attempts, :iteration_pause, :connection_class_name)
 
         migration_name = migration_name.name if migration_name.is_a?(Class)
@@ -381,13 +382,15 @@ module OnlineMigrations
         connection_class = options[:connection_class_name].constantize
         shards = Utils.shard_names(connection_class)
         shards = [nil] if shards.size == 1
+        status = delay ? :delayed : :pending
 
         shards.each do |shard|
           # Can't use `find_or_create_by` or hash syntax here, because it does not correctly work with json `arguments`.
           migration = Migration.where(migration_name: migration_name, shard: shard).where("arguments = ?", arguments.to_json).first
-          migration ||= Migration.create!(**options, migration_name: migration_name, arguments: arguments, shard: shard)
+          migration ||= Migration.create!(**options, status: status, migration_name: migration_name, arguments: arguments, shard: shard)
 
           if Utils.run_background_migrations_inline? && !migration.succeeded?
+            migration.update_column(:status, :enqueued) if !migration.enqueued?
             job = OnlineMigrations.config.background_data_migrations.job
             job.constantize.perform_inline(migration.id)
           end

data/lib/online_migrations/background_data_migrations/migration_job.rb

@@ -8,23 +8,17 @@ module OnlineMigrations
 
       sidekiq_options backtrace: true
 
-      sidekiq_retry_in do |count, _exception, jobhash|
+      sidekiq_retry_in do |count, exception, jobhash|
         migration_id = jobhash["args"].fetch(0)
         migration = Migration.find(migration_id)
+        migration.persist_error(exception, count + 1)
+        OnlineMigrations.config.background_data_migrations.error_handler.call(exception, migration)
 
         if count + 1 >= migration.max_attempts
           :kill
         end
       end
 
-      sidekiq_retries_exhausted do |jobhash, exception|
-        migration_id = jobhash["args"].fetch(0)
-        migration = Migration.find(migration_id)
-        migration.persist_error(exception)
-
-        OnlineMigrations.config.background_data_migrations.error_handler.call(exception, migration)
-      end
-
       TICKER_INTERVAL = 5 # seconds
 
       def initialize
@@ -57,6 +51,15 @@ module OnlineMigrations
       end
 
       def on_resume
+        if @migration.errored? # the job was retried
+          @migration.update!(
+            status: :running,
+            error_class: nil,
+            error_message: nil,
+            backtrace: nil
+          )
+        end
+
         @data_migration.after_resume
       end
 
@@ -126,7 +129,7 @@ module OnlineMigrations
       end
 
       def each_iteration(item, _migration_id)
-        if @migration.cancelling? || @migration.pausing? || @migration.paused?
+        if @migration.cancelling? || @migration.cancelled? || @migration.pausing? || @migration.paused?
           # Finish this exact sidekiq job. When the migration is paused
           # and will be resumed, a new job will be enqueued.
           finished = true
@@ -140,7 +143,7 @@ module OnlineMigrations
             @migration.data_migration.process(item)
 
             # Migration is refreshed regularly by ticker.
-            pause = @migration.iteration_pause
+            pause = @migration.iteration_pause.to_f
             sleep(pause) if pause > 0
           end
           @ticker.tick

data/lib/online_migrations/background_data_migrations/migration_status_validator.rb

@@ -6,6 +6,7 @@ module OnlineMigrations
     class MigrationStatusValidator < ActiveModel::Validator
       # Valid status transitions a Migration can make.
       VALID_STATUS_TRANSITIONS = {
+        "pending" => ["enqueued", "paused", "cancelled"],
         # enqueued -> running occurs when the migration starts performing.
         # enqueued -> paused occurs when the migration is paused before starting.
         # enqueued -> cancelled occurs when the migration is cancelled before starting.
@@ -15,11 +16,13 @@ module OnlineMigrations
         # running -> succeeded occurs when the migration completes successfully.
         # running -> pausing occurs when a user pauses the migration as it's performing.
         # running -> cancelling occurs when a user cancels the migration as it's performing.
-        # running -> failed occurs when the job raises an exception when running.
+        # running -> errored occurs when the migration raised an error during the last run.
+        # running -> failed occurs when the migration raises an error when running and retry attempts exceeded.
         "running" => [
           "succeeded",
           "pausing",
           "cancelling",
+          "errored",
           "failed",
         ],
         # pausing -> paused occurs when the migration actually halts performing and
@@ -32,19 +35,23 @@ module OnlineMigrations
         #   nothing in its collection to process.
         # pausing -> failed occurs when the job raises an exception after the
         #   user has paused it.
-        "pausing" => ["paused", "cancelling", "succeeded", "failed"],
-        # paused -> enqueued occurs when the migration is resumed after being paused.
+        "pausing" => ["paused", "cancelling", "succeeded", "errored", "failed"],
+        # paused -> pending occurs when the migration is resumed after being paused.
         # paused -> cancelled when the user cancels the migration after it is paused.
-        "paused" => ["enqueued", "cancelled"],
-        # failed -> enqueued occurs when the migration is retried after encounting an error.
-        "failed" => ["enqueued"],
+        "paused" => ["pending", "cancelled"],
+        "errored" => ["running", "failed", "cancelled", "paused"],
+        # failed -> pending occurs when the migration is retried after encounting an error.
+        "failed" => ["pending"],
         # cancelling -> cancelled occurs when the migration actually halts performing
         #   and occupies a status of cancelled.
         # cancelling -> succeeded occurs when the migration completes immediately after
         #   being cancelled. See description for pausing -> succeeded.
         # cancelling -> failed occurs when the job raises an exception after the
         #   user has cancelled it.
-        "cancelling" => ["cancelled", "succeeded", "failed"],
+        "cancelling" => ["cancelled", "succeeded", "errored", "failed"],
+        # delayed -> pending occurs when the delayed migration was approved by the user to start running.
+        # delayed -> cancelled occurs when the delayed migration was cancelled.
+        "delayed" => ["pending", "cancelled"],
       }
 
       def validate(record)

data/lib/online_migrations/background_data_migrations/scheduler.rb

@@ -34,13 +34,13 @@ module OnlineMigrations
         relation = relation.where(shard: shard) if shard
 
         with_lock do
-          running = relation.running
-          enqueued = relation.enqueued
+          stuck_migrations, active_migrations = relation.running.partition(&:stuck?)
+          runnable_migrations = relation.pending + stuck_migrations
 
           # Ensure no more than 'concurrency' migrations are running at the same time.
-          remaining_to_enqueue = concurrency - running.count
+          remaining_to_enqueue = concurrency - active_migrations.count
           if remaining_to_enqueue > 0
-            migrations_to_enqueue = enqueued.limit(remaining_to_enqueue)
+            migrations_to_enqueue = runnable_migrations.take(remaining_to_enqueue)
             migrations_to_enqueue.each do |migration|
               enqueue_migration(migration)
             end
@@ -67,10 +67,11 @@ module OnlineMigrations
         def enqueue_migration(migration)
           job = OnlineMigrations.config.background_data_migrations.job
           job_class = job.constantize
+          migration.update!(status: :enqueued)
 
           jid = job_class.perform_async(migration.id)
           if jid
-            migration.update!(status: :running, jid: jid)
+            migration.update!(jid: jid)
           end
         end
     end

data/lib/online_migrations/background_schema_migrations/migration.rb

@@ -11,12 +11,13 @@ module OnlineMigrations
       include ShardAware
 
       STATUSES = [
-        "enqueued",    # The migration has been enqueued by the user.
+        "pending",     # The migration has been created by the user.
         "running",     # The migration is being performed by a migration executor.
         "errored",     # The migration raised an error during last run.
         "failed",      # The migration raises an error when running and retry attempts exceeded.
         "succeeded",   # The migration finished without error.
         "cancelled",   # The migration was cancelled by the user.
+        "delayed",     # The migration was created, but waiting approval from the user to start running.
       ]
 
       MAX_IDENTIFIER_LENGTH = 63
@@ -24,7 +25,7 @@ module OnlineMigrations
       self.table_name = :background_schema_migrations
 
       scope :queue_order, -> { order(created_at: :asc) }
-      scope :active, -> { where(status: [:enqueued, :running, :errored]) }
+      scope :active, -> { where(status: [:pending, :running, :errored]) }
 
       alias_attribute :name, :migration_name
 
@@ -33,7 +34,7 @@ module OnlineMigrations
       validates :table_name, presence: true, length: { maximum: MAX_IDENTIFIER_LENGTH }
       validates :definition, presence: true
       validates :migration_name, presence: true, uniqueness: {
-        scope: [:connection_class_name, :shard],
+        scope: [:table_name, :connection_class_name, :shard],
         message: ->(object, data) do
           message = "(#{data[:value]}) has already been taken."
           if object.index_addition?
@@ -58,16 +59,14 @@ module OnlineMigrations
       end
 
       # Returns whether the migration is active, which is defined as
-      # having a status of enqueued, or running.
+      # having a status of pending, or running.
       #
       # @return [Boolean] whether the migration is active.
       #
       def active?
-        enqueued? || running?
+        pending? || running?
       end
 
-      alias cancel cancelled!
-
       # Returns whether this migration is pausable.
       #
       def pausable?
@@ -99,7 +98,7 @@ module OnlineMigrations
       def retry
         if failed?
           update!(
-            status: :enqueued,
+            status: :pending,
             attempts: 0,
             started_at: nil,
             finished_at: nil,
@@ -114,6 +113,32 @@ module OnlineMigrations
         end
       end
 
+      # Enqueue this data migration. No-op if migration is not delayed.
+      #
+      # @return [Boolean] whether this data migration was enqueued.
+      #
+      def enqueue
+        if delayed?
+          pending!
+          true
+        else
+          false
+        end
+      end
+
+      # Cancel this schema migration. No-op if migration is completed.
+      #
+      # @return [Boolean] whether this schema migration was cancelled.
+      #
+      def cancel
+        if completed?
+          false
+        elsif pending? || errored? || delayed? || stuck?
+          cancelled!
+          true
+        end
+      end
+
       def index_addition?
         definition.match?(/create (unique )?index/i)
       end

data/lib/online_migrations/background_schema_migrations/migration_helpers.rb

@@ -4,7 +4,7 @@ module OnlineMigrations
   module BackgroundSchemaMigrations
     module MigrationHelpers
       def add_index_in_background(table_name, column_name, **options)
-        migration_options = options.extract!(:max_attempts, :statement_timeout, :connection_class_name)
+        migration_options = options.extract!(:max_attempts, :statement_timeout, :connection_class_name, :delay)
 
         options[:algorithm] = :concurrently
         index, algorithm, if_not_exists = add_index_options(table_name, column_name, **options)
@@ -34,7 +34,7 @@ module OnlineMigrations
       def remove_index_in_background(table_name, column_name = nil, name:, **options)
         raise ArgumentError, "Index name must be specified" if name.blank?
 
-        migration_options = options.extract!(:max_attempts, :statement_timeout, :connection_class_name)
+        migration_options = options.extract!(:max_attempts, :statement_timeout, :connection_class_name, :delay)
 
         if !index_exists?(table_name, column_name, **options, name: name)
           Utils.raise_or_say("Index deletion was not enqueued because the index does not exist.")
@@ -46,7 +46,7 @@ module OnlineMigrations
       end
 
       def validate_foreign_key_in_background(from_table, to_table = nil, **options)
-        migration_options = options.extract!(:max_attempts, :statement_timeout, :connection_class_name)
+        migration_options = options.extract!(:max_attempts, :statement_timeout, :connection_class_name, :delay)
 
         if !foreign_key_exists?(from_table, to_table, **options)
           Utils.raise_or_say("Foreign key validation was not enqueued because the foreign key does not exist.")
@@ -87,7 +87,7 @@ module OnlineMigrations
         end
       end
 
-      def enqueue_background_schema_migration(migration_name, table_name, connection_class_name: nil, **options)
+      def enqueue_background_schema_migration(migration_name, table_name, connection_class_name: nil, delay: false, **options)
         options.assert_valid_keys(:definition, :max_attempts, :statement_timeout)
 
         if Utils.multiple_databases? && !connection_class_name
@@ -107,13 +107,15 @@ module OnlineMigrations
         shards = Utils.shard_names(connection_class)
         shards = [nil] if shards.size == 1
 
+        status = delay ? :delayed : :pending
+
         shards.each do |shard|
-          migration = Migration.create_with(**options, table_name: table_name)
-                               .find_or_create_by!(migration_name: migration_name, shard: shard, connection_class_name: connection_class_name)
+          migration = Migration.create_with(**options, status: status)
+                               .find_or_create_by!(migration_name: migration_name, table_name: table_name, shard: shard, connection_class_name: connection_class_name)
 
           if Utils.run_background_migrations_inline?
             # Run migration again in development.
-            migration.update_column(:status, :enqueued) if !migration.enqueued?
+            migration.update_column(:status, :pending) if !migration.pending?
 
             runner = MigrationRunner.new(migration)
             runner.run

data/lib/online_migrations/background_schema_migrations/migration_runner.rb

@@ -13,7 +13,7 @@ module OnlineMigrations
       def run
         return if migration.cancelled? || migration.succeeded?
 
-        migration.running! if migration.enqueued? || migration.errored?
+        migration.running! if migration.pending? || migration.errored?
         migration_payload = { migration: migration }
 
         if migration.attempts == 0

data/lib/online_migrations/background_schema_migrations/migration_status_validator.rb

@@ -5,8 +5,8 @@ module OnlineMigrations
     # @private
     class MigrationStatusValidator < ActiveModel::Validator
       VALID_STATUS_TRANSITIONS = {
-        # enqueued -> running occurs when the migration starts performing.
-        "enqueued" => ["running", "cancelled"],
+        # pending -> running occurs when the migration starts performing.
+        "pending" => ["running", "cancelled"],
         # running -> succeeded occurs when the migration completes successfully.
         # running -> errored occurs when the migration raised an error during the last run.
         # running -> failed occurs when the migration raises an error when running and retry attempts exceeded.
@@ -14,9 +14,12 @@ module OnlineMigrations
         # errored -> running occurs when previously errored migration starts running
         # errored -> failed occurs when the migration raises an error when running and retry attempts exceeded.
         "errored" => ["running", "failed", "cancelled"],
-        # failed -> enqueued occurs when the failed migration is enqueued to be retried.
+        # failed -> pending occurs when the failed migration is enqueued to be retried.
         # failed -> running occurs when the failed migration is retried.
-        "failed" => ["enqueued", "running", "cancelled"],
+        "failed" => ["pending", "running", "cancelled"],
+        # delayed -> pending occurs when the delayed migration was approved by the user to start running.
+        # delayed -> cancelled occurs when the delayed migration was cancelled.
+        "delayed" => ["pending", "cancelled"],
       }
 
       def validate(record)

data/lib/online_migrations/background_schema_migrations/scheduler.rb

@@ -36,7 +36,7 @@ module OnlineMigrations
       private
         def find_migration(**options)
           stuck_migrations, active_migrations = Migration.running.partition(&:stuck?)
-          runnable_migrations = (Migration.enqueued + Migration.errored + stuck_migrations).sort_by(&:created_at)
+          runnable_migrations = (Migration.pending + Migration.errored + stuck_migrations).sort_by(&:created_at)
 
           if options.key?(:shard)
             runnable_migrations = runnable_migrations.select { |migration| migration.shard.to_s == options[:shard].to_s }

data/lib/online_migrations/change_column_type_helpers.rb

@@ -436,7 +436,10 @@ module OnlineMigrations
           }
 
           options[:using] = index.using if index.using
-          options[:where] = index.where if index.where
+
+          if index.where
+            options[:where] = index.where.gsub(/\b#{from_column}\b/, to_column)
+          end
 
           if index.opclasses.present?
             opclasses = index.opclasses.dup

data/lib/online_migrations/command_checker.rb

@@ -426,7 +426,7 @@ module OnlineMigrations
               validate_constraint_code: command_str(:validate_not_null_constraint, table_name, column_name, name: constraint_name),
               table_name: table_name,
               column_name: column_name,
-              default: default,
+              default_value: default,
               remove_constraint_code: command_str(:remove_check_constraint, table_name, name: constraint_name),
               change_column_null_code: command_str(:change_column_null, table_name, column_name, false),
             }

data/lib/online_migrations/error_messages.rb

@@ -277,11 +277,11 @@ class <%= migration_name %> < <%= migration_parent %>
 
   def change
     <%= add_constraint_code %>
-<% unless default.nil? %>
+<% unless default_value.nil? %>
 
     # Passing a default value to change_column_null runs a single UPDATE query,
     # which can cause downtime. Instead, backfill the existing rows in batches.
-    update_column_in_batches(:<%= table_name %>, :<%= column_name %>, <%= default.inspect %>) do |relation|
+    update_column_in_batches(:<%= table_name %>, :<%= column_name %>, <%= default_value.inspect %>) do |relation|
       relation.where(<%= column_name %>: nil)
     end
 

data/lib/online_migrations/schema_statements.rb

@@ -852,6 +852,33 @@ module OnlineMigrations
     end
 
     # @private
+    # From rails 8.2 this will be used by fixtures code.
+    # https://github.com/rails/rails/commit/3415223ed2765c61ae348622dc8d2681efd910d7
+    def reset_column_sequences!(tables)
+      views = self.views
+
+      table_renames = OnlineMigrations.config.table_renames
+      renamed_tables = table_renames.slice(*views)
+
+      column_renames = OnlineMigrations.config.column_renames
+      renamed_columns = column_renames.slice(*views)
+
+      tables = tables.map do |table|
+        if renamed_tables.key?(table)
+          renamed_tables[table]
+        elsif renamed_columns.key?(table)
+          __tmp_table_name_for_column_rename(table)
+        else
+          table
+        end
+      end
+
+      super
+    end
+
+    # @private
+    # Was used by fixtures code in rails < 8.2.
+    # Delete when rails < 8.2 is no longer supported.
     def pk_and_sequence_for(table)
       views = self.views
 

data/lib/online_migrations/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OnlineMigrations
-  VERSION = "0.31.2"
+  VERSION = "0.33.0"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: online_migrations
 version: !ruby/object:Gem::Version
-  version: 0.31.2
+  version: 0.33.0
 platform: ruby
 authors:
 - fatkodima
 bindir: bin
 cert_chain: []
-date: 2025-11-12 00:00:00.000000000 Z
+date: 2026-02-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -41,6 +41,8 @@ files:
 - lib/generators/online_migrations/templates/add_sharding_to_online_migrations.rb.tt
 - lib/generators/online_migrations/templates/add_timestamps_to_background_migrations.rb.tt
 - lib/generators/online_migrations/templates/background_data_migrations_add_iteration_pause.rb.tt
+- lib/generators/online_migrations/templates/background_data_migrations_remove_iteration_pause_default.rb.tt
+- lib/generators/online_migrations/templates/background_migrations_change_status_default.rb.tt
 - lib/generators/online_migrations/templates/background_schema_migrations_change_unique_index.rb.tt
 - lib/generators/online_migrations/templates/change_background_data_migrations.rb.tt
 - lib/generators/online_migrations/templates/create_background_schema_migrations.rb.tt