online_migrations 0.32.0 → 0.33.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52861ed084d1bd3fd77bc08ea3f1b6aae8c26b58f1fc5ef08f181c18feb8d390
-  data.tar.gz: 92b111ad1679c421cbe97e206b18b2e3126cfb2c2fe4247de70e793a49ac112a
+  metadata.gz: 7f092b18d7bc864ba2232a41727e136bb86469279bdc3ad4c04a49a49628fb95
+  data.tar.gz: b7349d9b1c818ed4fefd078f7262bb380bb22a34109be13d2ead3191f338dbc9
 SHA512:
-  metadata.gz: 0eeeae19aec88ff880a076e3f82c60a99fb210b62ac3aeb881fb601ea14d34de8139ad9b42f839ffc29a83ffa65f6e787f36d9940ec06d2602982e562cda6e13
-  data.tar.gz: 82d54ab9eff606c039e96f8f158c4991ffd861456237fcfcef9578e63cc212e8db3a9abc1be0ec92d40e51e2ac37c8748e2396db560a7737d680bb01357b4519
+  metadata.gz: 4a52e29b327dbecae7f1c31fa4020fa5b428c5f830ea34215695bfd827c787c90146dda6dd12045a5c7f4cc2136741bb1a08b76b2a3ad7273f69c028d192a764
+  data.tar.gz: 6175ee34939fbdc6c21605320c36cfdeca971458381e1d6e465e7b464b302914f87f69c7bbcfc50c3b150fc9b9d6d8d34e0d0a1fd2a0573940aa1efa36e983a5

data/CHANGELOG.md

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

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.

data/docs/background_schema_migrations.md

@@ -132,7 +132,7 @@ 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.

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/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
@@ -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

data/lib/generators/online_migrations/upgrade_generator.rb

@@ -52,6 +52,11 @@ module OnlineMigrations
           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,11 +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.
+        "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.
@@ -25,8 +27,10 @@ module OnlineMigrations
       COMPLETED_STATUSES = ["succeeded", "failed", "cancelled"]
 
       ACTIVE_STATUSES = [
+        "pending",
         "enqueued",
         "running",
+        "failed",
         "pausing",
         "paused",
         "cancelling",
@@ -87,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.
       #
@@ -107,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
@@ -137,7 +137,7 @@ module OnlineMigrations
       #
       def enqueue
         if delayed?
-          enqueued!
+          pending!
           true
         else
           false
@@ -153,7 +153,7 @@ module OnlineMigrations
 
         if paused? || delayed? || stuck?
           update!(status: :cancelled, finished_at: Time.current)
-        elsif enqueued?
+        elsif pending? || enqueued? || errored?
           cancelled!
         else
           cancelling!
@@ -169,7 +169,7 @@ module OnlineMigrations
       def pause
         return false if completed?
 
-        if enqueued? || delayed? || stuck?
+        if pending? || enqueued? || delayed? || stuck? || errored?
           paused!
         else
           pausing!
@@ -184,7 +184,7 @@ module OnlineMigrations
       #
       def resume
         if paused?
-          enqueued!
+          pending!
           true
         else
           false
@@ -235,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,
@@ -290,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

@@ -382,7 +382,7 @@ module OnlineMigrations
         connection_class = options[:connection_class_name].constantize
         shards = Utils.shard_names(connection_class)
         shards = [nil] if shards.size == 1
-        status = delay ? :delayed : :enqueued
+        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`.

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

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,22 +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"],
-        # delayed -> enqueued occurs when the delayed migration was approved by the user to start running.
+        "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" => ["enqueued", "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,7 +11,7 @@ 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.
@@ -25,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
 
@@ -59,12 +59,12 @@ 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
 
       # Returns whether this migration is pausable.
@@ -98,7 +98,7 @@ module OnlineMigrations
       def retry
         if failed?
           update!(
-            status: :enqueued,
+            status: :pending,
             attempts: 0,
             started_at: nil,
             finished_at: nil,
@@ -119,7 +119,7 @@ module OnlineMigrations
       #
       def enqueue
         if delayed?
-          enqueued!
+          pending!
           true
         else
           false
@@ -133,7 +133,7 @@ module OnlineMigrations
       def cancel
         if completed?
           false
-        elsif enqueued? || errored? || delayed? || stuck?
+        elsif pending? || errored? || delayed? || stuck?
           cancelled!
           true
         end

data/lib/online_migrations/background_schema_migrations/migration_helpers.rb

@@ -107,7 +107,7 @@ module OnlineMigrations
         shards = Utils.shard_names(connection_class)
         shards = [nil] if shards.size == 1
 
-        status = delay ? :delayed : :enqueued
+        status = delay ? :delayed : :pending
 
         shards.each do |shard|
           migration = Migration.create_with(**options, status: status)
@@ -115,7 +115,7 @@ module OnlineMigrations
 
           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,12 +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"],
-        # delayed -> enqueued occurs when the delayed migration was approved by the user to start running.
+        "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" => ["enqueued", "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/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: online_migrations
 version: !ruby/object:Gem::Version
-  version: 0.32.0
+  version: 0.33.0
 platform: ruby
 authors:
 - fatkodima
 bindir: bin
 cert_chain: []
-date: 2026-01-07 00:00:00.000000000 Z
+date: 2026-02-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -42,6 +42,7 @@ files:
 - 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