online_migrations 0.31.2 → 0.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4afb5d9ab9916861d263de3c38a2436d2ee131ae9988edf282866145a274356d
-  data.tar.gz: 761d30f417479db296429af0668bf62e47581aa4a73fce1d9ba72bd62c66173f
+  metadata.gz: 52861ed084d1bd3fd77bc08ea3f1b6aae8c26b58f1fc5ef08f181c18feb8d390
+  data.tar.gz: 92b111ad1679c421cbe97e206b18b2e3126cfb2c2fe4247de70e793a49ac112a
 SHA512:
-  metadata.gz: 9e6930e8069732e7988b731d826a9e82b023c8f4bbebd5827a31efa10747ada86af64e7e75553df5a8d2e318688002e9c194cdf07e9124ef4231986197d885e7
-  data.tar.gz: fe46acbfd31436293ead08b37258c877ca4eddf3bb6c41e462a74c89153d4f632e244c2fa5b98b0887fbfe024a3ab8a9ada8ad101fffb9bebfd10dbbd9f5c9bc
+  metadata.gz: 0eeeae19aec88ff880a076e3f82c60a99fb210b62ac3aeb881fb601ea14d34de8139ad9b42f839ffc29a83ffa65f6e787f36d9940ec06d2602982e562cda6e13
+  data.tar.gz: 82d54ab9eff606c039e96f8f158c4991ffd861456237fcfcef9578e63cc212e8db3a9abc1be0ec92d40e51e2ac37c8748e2396db560a7737d680bb01357b4519

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 ## master (unreleased)
 
+## 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

@@ -324,6 +324,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

@@ -139,6 +139,14 @@ Background Schema Migrations can be in various states during its execution:
 * **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_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

@@ -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
@@ -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,11 @@ 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
+
         migrations
       end
 

data/lib/online_migrations/background_data_migrations/migration.rb

@@ -19,6 +19,7 @@ module OnlineMigrations
         "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"]
@@ -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?
+          enqueued!
+          true
+        else
+          false
+        end
+      end
+
       # Cancel this data migration. No-op if migration is completed.
       #
       # @return [Boolean] whether this data migration was cancelled.
@@ -137,7 +151,7 @@ module OnlineMigrations
       def cancel
         return false if completed?
 
-        if paused? || stuck?
+        if paused? || delayed? || stuck?
           update!(status: :cancelled, finished_at: Time.current)
         elsif enqueued?
           cancelled!
@@ -155,7 +169,7 @@ module OnlineMigrations
       def pause
         return false if completed?
 
-        if enqueued? || stuck?
+        if enqueued? || delayed? || stuck?
           paused!
         else
           pausing!

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 : :enqueued
 
         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

@@ -140,7 +140,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

@@ -45,6 +45,9 @@ module OnlineMigrations
         # 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.
+        # delayed -> cancelled occurs when the delayed migration was cancelled.
+        "delayed" => ["enqueued", "cancelled"],
       }
 
       def validate(record)

data/lib/online_migrations/background_schema_migrations/migration.rb

@@ -17,6 +17,7 @@ module OnlineMigrations
         "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
@@ -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?
@@ -66,8 +67,6 @@ module OnlineMigrations
         enqueued? || running?
       end
 
-      alias cancel cancelled!
-
       # Returns whether this migration is pausable.
       #
       def pausable?
@@ -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?
+          enqueued!
+          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 enqueued? || 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,9 +107,11 @@ module OnlineMigrations
         shards = Utils.shard_names(connection_class)
         shards = [nil] if shards.size == 1
 
+        status = delay ? :delayed : :enqueued
+
         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.

data/lib/online_migrations/background_schema_migrations/migration_status_validator.rb

@@ -17,6 +17,9 @@ module OnlineMigrations
         # failed -> enqueued 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.
+        # delayed -> cancelled occurs when the delayed migration was cancelled.
+        "delayed" => ["enqueued", "cancelled"],
       }
 
       def validate(record)

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.32.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.32.0
 platform: ruby
 authors:
 - fatkodima
 bindir: bin
 cert_chain: []
-date: 2025-11-12 00:00:00.000000000 Z
+date: 2026-01-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -41,6 +41,7 @@ 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_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