online_migrations 0.33.2 → 0.35.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54cc719e4b9c6d22226c4393fa81362cec973f1f368553c2797bc5a7e0b3720b
-  data.tar.gz: f8dba7a97c0e4bbb744d552f783ad9407aa65aec16d1020933becaf83a9779a4
+  metadata.gz: 5a84bdeb495a3d25432c6ae97d4c46777517ae3bbcf01359020d400ad8f16f30
+  data.tar.gz: 935d3b38b096fcdb222a89065d7c10023a8b85a6009065d73a1df9bb92c2b0f8
 SHA512:
-  metadata.gz: bd3a4195693d1f48a585c96ec66a0ae5775f585a2ce66c2e226a1148847cc63292e64a9704268a7a40e84a094c50e6a1990b91009fc22527db4ba004ef8aae95
-  data.tar.gz: 8f8cf24be5a12a4e68dadaeae47373a05ed2426bcc61f7bbe325e3e714c884ee353c48afd7696b7da3bd0393a2c88e11993afa081b99a63bedf839fb88e8eec4
+  metadata.gz: f2c578a25081bb86cafc2851cb818c40e819363d40bdac2a6f4cde634f71a8dc3a90909e4dbf10bf0fb6df61e1d979f4d581982650eec3834715baa8e5888832
+  data.tar.gz: 01377b6bcdbe0b601a45b53a52a99746e443d60c5ca513e2312322c81718e4a995fde32ee78a45554fe155878391f6a885fdef50bdea4d4619a4e10799bab295

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 ## master (unreleased)
 
+## 0.35.0 (2026-07-01)
+
+- Drop support for Ruby < 3.3
+- Defer `tick_total` calculation to the background data migration starting time instead of enqueueing time
+- Make "replacing an index" check independent of the live database state
+
+## 0.34.0 (2026-05-29)
+
+- Drop support for Rails < 7.2
+
+- Do not schedule background data migrations with non existent data migration classes
+
+    This prevents a situation when the background data migration was enqueued and started running
+    before the deploy completes and the data migration class is available.
+
+- Add ability to enqueue background migrations for specific shards (if using sharding)
+
+  ```ruby
+  add_index_in_background(:users, :name, connection_class_name: "ApplicationRecord", shard: :shard_one)
+  enqueue_background_data_migration("MyMigration", shard: :shard_one)
+  ```
+
+- Fix validating foreign key in `add_reference_concurrently` when multiple foreign keys target the same table
+
 ## 0.33.2 (2026-03-16)
 
 - Fix message for adding to `ignored_columns` when renaming a column
@@ -22,7 +46,7 @@
 - Add ability to create delayed background migrations
 
   ```ruby
-  add_index_in_background(:users, :name, delay: true)
+  add_index_in_background(:users, :name, connection_class_name: "ApplicationRecord", delay: true)
   enqueue_background_data_migration("MyMigration", delay: true)
   ```
 

data/README.md

@@ -16,8 +16,8 @@ See [comparison to `strong_migrations`](#comparison-to-strong_migrations)
 
 ## Requirements
 
-- Ruby 3.1+
-- Rails 7.1+
+- Ruby 3.3+
+- Rails 7.2+
 - PostgreSQL 12+
 
 For older Ruby and Rails versions you can use older versions of this gem.

data/lib/generators/online_migrations/upgrade_generator.rb

@@ -48,7 +48,7 @@ module OnlineMigrations
         end
 
         iteration_pause_column = connection.columns(:background_data_migrations).find { |c| c.name == "iteration_pause" }
-        if iteration_pause_column && iteration_pause_column.default
+        if iteration_pause_column&.default
           migrations << "background_data_migrations_remove_iteration_pause_default"
         end
 

data/lib/online_migrations/background_data_migrations/migration.rb

@@ -123,7 +123,13 @@ module OnlineMigrations
       # @private
       def start
         if enqueued?
-          update!(status: :running, started_at: Time.current)
+          # Defer `tick_total` calculation to the migration starting time
+          # instead of the enqueueing time to avoid failed deploys.
+          self.tick_total ||= safely_calculate_tick_total
+          self.status = :running
+          self.started_at = Time.current
+          save!
+
           data_migration.after_start
           true
         else
@@ -309,11 +315,20 @@ module OnlineMigrations
         def set_defaults
           config = ::OnlineMigrations.config.background_data_migrations
           self.max_attempts ||= config.max_attempts
-          self.tick_total ||= on_shard_if_present do
+          self.iteration_pause ||= config.iteration_pause
+        end
+
+        def safely_calculate_tick_total
+          on_shard_if_present do
             data_migration.count
           end
+        rescue ActiveRecord::QueryCanceled => e
+          OnlineMigrations.config.background_data_migrations.error_handler.call(e, self)
 
-          self.iteration_pause ||= config.iteration_pause
+          # `tick_total` is not required and is used only for progress tracking.
+          # Probably the `count` method was implemented in a non-efficient way.
+          # Better to not track progress than have a failing migration.
+          nil
         end
 
         def instrument_status_change

data/lib/online_migrations/background_data_migrations/migration_helpers.rb

@@ -339,6 +339,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.
+      # @param shard [String, Symbol] Specific shard this migration will be enqueued for. Defaults to all shards.
       # @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
       #
@@ -369,7 +370,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, delay: false, **options)
+      def enqueue_background_data_migration(migration_name, *arguments, delay: false, shard: nil, **options)
         options.assert_valid_keys(:max_attempts, :iteration_pause, :connection_class_name)
 
         migration_name = migration_name.name if migration_name.is_a?(Class)
@@ -380,8 +381,16 @@ module OnlineMigrations
         end
 
         connection_class = options[:connection_class_name].constantize
-        shards = Utils.shard_names(connection_class)
-        shards = [nil] if shards.size == 1
+        shards = Utils.shard_names(connection_class).map(&:to_s)
+        if shards.size == 1
+          shards = [nil]
+        elsif shard
+          shard = shard.to_s
+          raise "Unknown shard: #{shard}" if !shards.include?(shard)
+
+          shards = [shard]
+        end
+
         status = delay ? :delayed : :pending
 
         shards.each do |shard|

data/lib/online_migrations/background_data_migrations/scheduler.rb

@@ -37,7 +37,7 @@ module OnlineMigrations
 
         with_lock do
           stuck_migrations, active_migrations = relation.running.partition(&:stuck?)
-          runnable_migrations = relation.pending + stuck_migrations
+          runnable_migrations = migrations_with_existing_classes(relation.pending) + stuck_migrations
 
           # Ensure no more than 'concurrency' migrations are running at the same time.
           remaining_to_enqueue = concurrency - active_migrations.count
@@ -71,6 +71,17 @@ module OnlineMigrations
           end
         end
 
+        def migrations_with_existing_classes(migrations)
+          migrations.select do |migration|
+            # Detect if the data migration class exists.
+            # It may not yet exist if the data migration was enqueued before the deploy finished.
+            migration.data_migration
+            true
+          rescue DataMigration::NotFoundError
+            false
+          end
+        end
+
         def enqueue_migration(migration)
           job = OnlineMigrations.config.background_data_migrations.job
           job_class = job.constantize

data/lib/online_migrations/background_schema_migrations/migration.rb

@@ -208,12 +208,8 @@ module OnlineMigrations
 
         # Extension point, do not remove this method.
         def with_connection(&block)
-          if Utils.ar_version >= 7.2
-            # https://github.com/rails/rails/pull/51083
-            connection_class.with_connection(&block)
-          else
-            yield connection_class.connection
-          end
+          # https://github.com/rails/rails/pull/51083
+          connection_class.with_connection(&block)
         end
 
         def with_statement_timeout(connection, timeout)

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, :delay)
+        migration_options = options.extract!(:max_attempts, :statement_timeout, :connection_class_name, :delay, :shard)
 
         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, :delay)
+        migration_options = options.extract!(:max_attempts, :statement_timeout, :connection_class_name, :delay, :shard)
 
         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, :delay)
+        migration_options = options.extract!(:max_attempts, :statement_timeout, :connection_class_name, :delay, :shard)
 
         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, delay: false, **options)
+      def enqueue_background_schema_migration(migration_name, table_name, connection_class_name: nil, delay: false, shard: nil, **options)
         options.assert_valid_keys(:definition, :max_attempts, :statement_timeout)
 
         if Utils.multiple_databases? && !connection_class_name
@@ -104,8 +104,15 @@ module OnlineMigrations
         # Normalize to the real connection class name.
         connection_class_name = connection_class.name
 
-        shards = Utils.shard_names(connection_class)
-        shards = [nil] if shards.size == 1
+        shards = Utils.shard_names(connection_class).map(&:to_s)
+        if shards.size == 1
+          shards = [nil]
+        elsif shard
+          shard = shard.to_s
+          raise "Unknown shard: #{shard}" if !shards.include?(shard)
+
+          shards = [shard]
+        end
 
         status = delay ? :delayed : :pending
 

data/lib/online_migrations/change_column_type_helpers.rb

@@ -212,7 +212,14 @@ module OnlineMigrations
       conversions = column_names.map do |column_name|
         tmp_column = __change_type_column(column_name)
 
-        old_value = Arel::Table.new(table_name)[column_name]
+        old_value = begin
+          # Delete after supporting only ActiveRecord >= 8.2
+          Arel::Table.new(table_name)[column_name]
+        rescue ArgumentError
+          # https://github.com/rails/rails/commit/b1650993b02497ae7d0d8b984d40bc036e62c681
+          Arel::Table.new(name: table_name)[column_name]
+        end
+
         if (type_cast_function = type_cast_functions.with_indifferent_access[column_name])
           old_value =
             case type_cast_function
@@ -393,10 +400,8 @@ module OnlineMigrations
       def __options_from_column(column, options)
         result = {}
         options.each do |option|
-          if column.respond_to?(option)
-            value = column.public_send(option)
-            result[option] = value if !value.nil?
-          end
+          value = column.public_send(option)
+          result[option] = value if !value.nil?
         end
         result
       end

data/lib/online_migrations/command_checker.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "erb"
-require "set"
 
 module OnlineMigrations
   # @private
@@ -46,7 +45,7 @@ module OnlineMigrations
 
       true
     end
-    ruby2_keywords(:check) if respond_to?(:ruby2_keywords, true)
+    ruby2_keywords(:check)
 
     def version_safe?
       version && version <= OnlineMigrations.config.start_after
@@ -574,13 +573,21 @@ module OnlineMigrations
             Array(index.columns).map(&:to_s) == Array(options[:column]).map(&:to_s)
         end
 
-        if index_def
-          existing_options = [:name, :columns, :unique, :where, :type, :using, :opclasses].filter_map do |option|
-            [option, index_def.public_send(option)] if index_def.respond_to?(option)
-          end.to_h
+        # IndexDefinition expects "columns", but "remove_index" API uses "column".
+        options[:columns] = options[:column]
 
-          @removed_indexes << IndexDefinition.new(table: table_name, **existing_options)
-        end
+        # Fall back to the declared options when the index isn't present in the database,
+        # so an index remove → add is still recorded and caught.
+        existing_options =
+          [:name, :columns, :unique, :where, :type, :using, :opclasses].index_with do |option|
+            if index_def
+              index_def.public_send(option)
+            else
+              options[option]
+            end
+          end.compact
+
+        @removed_indexes << IndexDefinition.new(table: table_name, **existing_options)
       end
 
       def add_foreign_key(from_table, to_table, **options)
@@ -844,8 +851,8 @@ module OnlineMigrations
 
       def index_include_column?(index, column)
         index.columns.include?(column) ||
-          (index.include && index.include.include?(column)) ||
-          (index.where && index.where.include?(column))
+          index.include&.include?(column) ||
+          index.where&.include?(column)
       end
 
       def run_custom_checks(method, args)

data/lib/online_migrations/command_recorder.rb

@@ -48,7 +48,7 @@ module OnlineMigrations
           record(:"#{method}", args, &block)  #   record(:create_table, args, &block)
         end                                   # end
       RUBY
-      ruby2_keywords(method) if respond_to?(:ruby2_keywords, true)
+      ruby2_keywords(method)
     end
 
     private

data/lib/online_migrations/data_migration.rb

@@ -16,6 +16,7 @@ module OnlineMigrations
       # @return [DataMigration] the Data Migration with the given name.
       #
       # @raise [NotFoundError] if a Data Migration with the given name does not exist.
+      # @raise [ArgumentError] if a Data Migration with the given name is not a subclass of DataMigration.
       #
       def named(name)
         namespace = OnlineMigrations.config.background_data_migrations.migrations_module.constantize
@@ -26,7 +27,7 @@ module OnlineMigrations
 
         raise NotFoundError.new("Data Migration #{name} not found", name) if migration.nil?
         if !(migration.is_a?(Class) && migration < self)
-          raise NotFoundError.new("#{name} is not a Data Migration", name)
+          raise ArgumentError, "#{name} is not a Data Migration"
         end
 
         migration

data/lib/online_migrations/index_definition.rb

@@ -3,10 +3,11 @@
 module OnlineMigrations
   # @private
   class IndexDefinition
-    attr_reader :table, :columns, :unique, :opclasses, :where, :type, :using
+    attr_reader :table, :name, :columns, :unique, :opclasses, :where, :type, :using
 
     def initialize(**options)
-      @table = options[:table]
+      @table = options[:table]&.to_s
+      @name = options[:name]&.to_s
       @columns = Array(options[:columns]).map(&:to_s)
       @unique = options[:unique]
       @opclasses = options[:opclass] || {}
@@ -20,7 +21,7 @@ module OnlineMigrations
       # For ActiveRecord::ConnectionAdapters::IndexDefinition is for expression indexes,
       # `columns` is a string
       table == other.table &&
-        columns.intersect?(Array(other.columns))
+        ((name && name == other.name) || columns.intersect?(Array(other.columns)))
     end
 
     # @param other [OnlineMigrations::IndexDefinition, ActiveRecord::ConnectionAdapters::IndexDefinition]
@@ -28,7 +29,7 @@ module OnlineMigrations
       return false if type != other.type
       return false if using != other.using
       return false if where != other.where
-      return false if other.respond_to?(:opclasses) && opclasses != other.opclasses
+      return false if opclasses != other.opclasses
 
       if unique && !other.unique
         false

data/lib/online_migrations/migration.rb

@@ -29,7 +29,7 @@ module OnlineMigrations
         end
       end
     end
-    ruby2_keywords(:method_missing) if respond_to?(:ruby2_keywords, true)
+    ruby2_keywords(:method_missing)
 
     # @private
     def revert(*args)

data/lib/online_migrations/schema_cache.rb

@@ -3,83 +3,6 @@
 module OnlineMigrations
   # @private
   module SchemaCache
-    def primary_keys(connection, table_name)
-      if (renamed_table = renamed_table?(connection, table_name))
-        super(connection, renamed_table)
-      elsif renamed_column?(connection, table_name)
-        super(connection, column_rename_table(table_name))
-      else
-        super
-      end
-    end
-
-    def columns(connection, table_name)
-      if (renamed_table = renamed_table?(connection, table_name))
-        super(connection, renamed_table)
-      elsif renamed_column?(connection, table_name)
-        columns = super(connection, column_rename_table(table_name))
-        OnlineMigrations.config.column_renames[table_name].each do |old_column_name, new_column_name|
-          duplicate_column(old_column_name, new_column_name, columns)
-        end
-        columns
-      else
-        super.reject { |column| column.name.end_with?("_for_type_change") }
-      end
-    end
-
-    def indexes(connection, table_name)
-      if (renamed_table = renamed_table?(connection, table_name))
-        super(connection, renamed_table)
-      elsif renamed_column?(connection, table_name)
-        super(connection, column_rename_table(table_name))
-      else
-        super
-      end
-    end
-
-    def clear_data_source_cache!(connection, name)
-      if (renamed_table = renamed_table?(connection, name))
-        super(connection, renamed_table)
-      end
-
-      if renamed_column?(connection, name)
-        super(connection, column_rename_table(name))
-      end
-
-      super
-    end
-
-    private
-      def renamed_table?(connection, table_name)
-        table_renames = OnlineMigrations.config.table_renames
-        if table_renames.key?(table_name) && connection.view_exists?(table_name)
-          table_renames[table_name]
-        end
-      end
-
-      def renamed_column?(connection, table_name)
-        column_renames = OnlineMigrations.config.column_renames
-        column_renames.key?(table_name) && connection.view_exists?(table_name)
-      end
-
-      def column_rename_table(table_name)
-        "#{table_name}_column_rename"
-      end
-
-      def duplicate_column(old_column_name, new_column_name, columns)
-        old_column = columns.find { |column| column.name == old_column_name }
-        new_column = old_column.dup
-        # Active Record defines only reader for :name
-        new_column.instance_variable_set(:@name, new_column_name)
-        # Correspond to the Active Record freezing of each column
-        columns << new_column.freeze
-      end
-  end
-
-  # @private
-  module SchemaCache72
-    # Active Record >= 7.2 changed signature of the methods,
-    # see https://github.com/rails/rails/pull/48716.
     def primary_keys(pool, table_name)
       if (renamed_table = renamed_table?(pool, table_name))
         super(pool, renamed_table)

data/lib/online_migrations/schema_statements.rb

@@ -111,7 +111,7 @@ module OnlineMigrations
 
         relation.update_all(updates)
 
-        progress.call(relation) if progress
+        progress.call(relation) if progress.present?
 
         sleep(pause_ms * 0.001) if pause_ms > 0
       end
@@ -635,7 +635,7 @@ module OnlineMigrations
     # @see https://api.rubyonrails.org/v8.1/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-add_column
     #
     def add_column(table_name, column_name, type, **options)
-      if column_exists?(table_name, column_name, type, **options)
+      if column_exists?(table_name, column_name)
         Utils.say("Column was not added because it already exists (this may be due to an aborted migration " \
                   "or similar) table_name: #{table_name}, column_name: #{column_name}")
       else
@@ -705,7 +705,7 @@ module OnlineMigrations
         add_foreign_key(table_name, foreign_table_name, **foreign_key, column: column_name, validate: false)
 
         if foreign_key[:validate] != false
-          validate_foreign_key(table_name, foreign_table_name, **foreign_key)
+          validate_foreign_key(table_name, foreign_table_name, **foreign_key, column: column_name)
         end
       end
     end
@@ -992,12 +992,7 @@ module OnlineMigrations
 
       def __tmp_table_name_for_column_rename(table_name)
         suffix = "_column_rename"
-
-        # On ActiveRecord 7.1 can use table_name_length instead of max_identifier_length,
-        # see https://github.com/rails/rails/pull/45136.
-        # Also we need to account for "_pkey", because older versions does not correctly rename
-        # tables with long names. Remove when supporting newer versions only.
-        prefix_length = max_identifier_length - "_pkey".size - suffix.length
+        prefix_length = max_identifier_length - suffix.length
         table_name[0, prefix_length] + suffix
       end
   end

data/lib/online_migrations/utils.rb

@@ -145,7 +145,7 @@ module OnlineMigrations
 
       def run_background_migrations_inline?
         run_inline = OnlineMigrations.config.run_background_migrations_inline
-        run_inline && run_inline.call
+        run_inline.call if run_inline.present?
       end
     end
   end

data/lib/online_migrations/version.rb

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

data/lib/online_migrations.rb

@@ -116,16 +116,11 @@ module OnlineMigrations
       ActiveRecord::Migration.prepend(OnlineMigrations::Migration)
       ActiveRecord::Migrator.prepend(OnlineMigrations::Migrator)
       ActiveRecord::SchemaDumper.prepend(OnlineMigrations::SchemaDumper)
+      ActiveRecord::ConnectionAdapters::SchemaCache.prepend(OnlineMigrations::SchemaCache)
 
       ActiveRecord::Tasks::DatabaseTasks.singleton_class.prepend(OnlineMigrations::DatabaseTasks)
       ActiveRecord::Migration::CommandRecorder.include(OnlineMigrations::CommandRecorder)
 
-      if OnlineMigrations::Utils.ar_version >= 7.2
-        ActiveRecord::ConnectionAdapters::SchemaCache.prepend(OnlineMigrations::SchemaCache72)
-      else
-        ActiveRecord::ConnectionAdapters::SchemaCache.prepend(OnlineMigrations::SchemaCache)
-      end
-
       if !ActiveRecord::Batches::BatchEnumerator.method_defined?(:use_ranges)
         ActiveRecord::Batches::BatchEnumerator.include(OnlineMigrations::ActiveRecordBatchEnumerator)
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: online_migrations
 version: !ruby/object:Gem::Version
-  version: 0.33.2
+  version: 0.35.0
 platform: ruby
 authors:
 - fatkodima
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '7.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '7.2'
 email:
 - fatkodima123@gmail.com
 executables: []
@@ -108,14 +108,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.14
 specification_version: 4
 summary: Catch unsafe PostgreSQL migrations in development and run them easier in
   production