online_migrations 0.33.1 → 0.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ea2552d8a879bacf5a5f8360a13aeafa9b36bec50943b359eb2d0501532ceb0
-  data.tar.gz: 251b3bee148c70f37d86892ce985a93ee664a2623111de38b9fcff47b6be4baa
+  metadata.gz: b7f1dd28a4540742f77c2a33d7336f4f6f2b12a4f267a1cc556975f7b7122ba4
+  data.tar.gz: db448dca841dc39418cd92e5d86108ee0b59b69b72eeda391b0a81a30aa7ce71
 SHA512:
-  metadata.gz: 295c89b41757157ce16b7b2585d3516cd2900b1ba0291523c2e689991002669e08ba3928fc23b1047a92dbd0f225436f0b2f8ed9c7b6803fee8a4e56c4ef4239
-  data.tar.gz: 16c0ada6d9a4e07271eae3a1a509f23a4756a5af3eebf172ca4971680b1c799f148c2f7bbeeffdcfce2e600cf24095e1663f03d6de00dd692af803ccdad22f62
+  metadata.gz: b423580e44eefc2f1ff71b2ebdcd15e4ff449f869231aaebe38c4598dc364d817eb3b484a82b7a0cc493727f94d956610ced75ac409092227c2e5cc727935eee
+  data.tar.gz: 3287e23ec07a09a1026790ab4747427eafbc70f675fd2cbf7382f302a86f748c3fde45f5a7546b3e66848cd1e12eb86f073ff3e5461471bb35ba79f5b0a160ec

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 ## master (unreleased)
 
+## 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
+- Schedule background data migration jobs only after committing the database transaction
+
 ## 0.33.1 (2026-02-05)
 
 - Allow "running" to "enqueued" state transition for stuck background data migrations
@@ -17,7 +40,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)
   ```
 
@@ -94,7 +117,7 @@
 - Drop support for Ruby < 3.1 and Rails < 7.1
 - Add check for `change_column` for columns with check constraints
 
-- Allow to require safety reason explanation when calling `safery_assured`
+- Allow to require safety reason explanation when calling `safety_assured`
 
   ```ruby
   # config/initializers/online_migrations.rb

data/README.md

@@ -17,7 +17,7 @@ See [comparison to `strong_migrations`](#comparison-to-strong_migrations)
 ## Requirements
 
 - Ruby 3.1+
-- Rails 7.1+
+- Rails 7.2+
 - PostgreSQL 12+
 
 For older Ruby and Rails versions you can use older versions of this gem.
@@ -441,8 +441,9 @@ It will use a combination of a VIEW and column aliasing to work with both column
    ```
 
 4. Replace usages of the old column with a new column in the codebase
-5. If you enabled Active Record `enumerate_columns_in_select_statements` setting in your application
-   (is disabled by default in Active Record >= 7), then you need to ignore old column:
+5. If the model has `ignored_columns` set, or you enabled Active Record
+   `enumerate_columns_in_select_statements` setting (is disabled by default in Active Record >= 7),
+   then you need to ignore the old column:
 
    ```ruby
    class User < ApplicationRecord

data/docs/configuring.md

@@ -40,7 +40,7 @@ Check the [source code](https://github.com/fatkodima/online_migrations/blob/mast
 
 ## Requiring safety_assured reason
 
-To require safety reason explanation when calling `safery_assured` (disabled by default):
+To require safety reason explanation when calling `safety_assured` (disabled by default):
 
 ```ruby
 config.require_safety_assured_reason = true

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

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

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

@@ -12,7 +12,7 @@ OnlineMigrations.configure do |config|
   # Set the version of the production database so the right checks are run in development.
   # config.target_version = 17
 
-  # Configure whether to require safety reason explanation when calling #safery_assured.
+  # Configure whether to require safety reason explanation when calling #safety_assured.
   config.require_safety_assured_reason = false
 
   # Configure whether to perform checks when migrating down.

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

@@ -33,20 +33,27 @@ module OnlineMigrations
         relation = Migration.queue_order
         relation = relation.where(shard: shard) if shard
 
+        migrations_to_enqueue = []
+
         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
           if remaining_to_enqueue > 0
-            migrations_to_enqueue = runnable_migrations.take(remaining_to_enqueue)
-            migrations_to_enqueue.each do |migration|
-              enqueue_migration(migration)
+            runnable_migrations.take(remaining_to_enqueue).each do |migration|
+              migration.update!(status: :enqueued)
+
+              migrations_to_enqueue << migration
             end
           end
         end
 
+        migrations_to_enqueue.each do |migration|
+          enqueue_migration(migration)
+        end
+
         true
       end
 
@@ -64,10 +71,20 @@ 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
-          migration.update!(status: :enqueued)
 
           jid = job_class.perform_async(migration.id)
           if jid

data/lib/online_migrations/background_schema_migrations/migration.rb

@@ -151,28 +151,28 @@ module OnlineMigrations
       # @private
       def run
         on_shard_if_present do
-          connection = connection_class.connection
-
-          connection.with_lock_retries do
-            statement_timeout = self.statement_timeout || OnlineMigrations.config.statement_timeout
-
-            with_statement_timeout(connection, statement_timeout) do
-              if index_addition?
-                index = connection.indexes(table_name).find { |i| name.match?(/\b#{i.name}\b/) }
-                if index
-                  if index.valid?
-                    return
-                  else
-                    connection.remove_index(table_name, name: index.name, algorithm: :concurrently)
+          with_connection do |connection|
+            connection.with_lock_retries do
+              statement_timeout = self.statement_timeout || OnlineMigrations.config.statement_timeout
+
+              with_statement_timeout(connection, statement_timeout) do
+                if index_addition?
+                  index = connection.indexes(table_name).find { |i| name.match?(/\b#{i.name}\b/) }
+                  if index
+                    if index.valid?
+                      return
+                    else
+                      connection.remove_index(table_name, name: index.name, algorithm: :concurrently)
+                    end
                   end
                 end
-              end
 
-              connection.execute(definition)
+                connection.execute(definition)
 
-              # Outdated statistics + a new index can hurt performance of existing queries.
-              if OnlineMigrations.config.auto_analyze
-                connection.execute("ANALYZE #{table_name}")
+                # Outdated statistics + a new index can hurt performance of existing queries.
+                if OnlineMigrations.config.auto_analyze
+                  connection.execute("ANALYZE #{table_name}")
+                end
               end
             end
           end
@@ -206,6 +206,12 @@ module OnlineMigrations
           indexes_in_progress.include?(name)
         end
 
+        # Extension point, do not remove this method.
+        def with_connection(&block)
+          # https://github.com/rails/rails/pull/51083
+          connection_class.with_connection(&block)
+        end
+
         def with_statement_timeout(connection, timeout)
           return yield if timeout.nil?
 

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/config.rb

@@ -73,7 +73,7 @@ module OnlineMigrations
       end
     end
 
-    # Whether to require safety reason explanation when calling #safery_assured
+    # Whether to require safety reason explanation when calling #safety_assured
     #
     # Disabled by default
     # @return [Boolean]

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/error_messages.rb

@@ -148,14 +148,14 @@ It will use a combination of a VIEW and column aliasing to work with both column
   end
 
 4. Replace usages of the old column with a new column in the codebase
-<% if ActiveRecord::Base.enumerate_columns_in_select_statements %>
-5. Ignore old column
+5. If the model has `ignored_columns` set, or you enabled
+  `enumerate_columns_in_select_statements`, ignore the old column:
 
   self.ignored_columns += [:<%= column_name %>]
 
 6. Deploy
 7. Remove the column rename config from step 1
-8. Remove the column ignore from step 5
+8. Remove the column ignore from step 5, if added
 9. Remove the VIEW created in step 3 and finally rename the column:
 
   class Finalize<%= migration_name %> < <%= migration_parent %>
@@ -165,19 +165,7 @@ It will use a combination of a VIEW and column aliasing to work with both column
   end
 
 10. Deploy
-<% else %>
-5. Deploy
-6. Remove the column rename config from step 1
-7. Remove the VIEW created in step 3 and finally rename the column:
-
-  class Finalize<%= migration_name %> < <%= migration_parent %>
-    def change
-      finalize_column_rename :<%= table_name %>, :<%= column_name %>, :<%= new_column %>
-    end
-  end
-
-8. Deploy
-<% end %>",
+",
 
       change_column_with_not_null:
 "Changing the type is safe, but setting NOT NULL is not.",

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

@@ -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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OnlineMigrations
-  VERSION = "0.33.1"
+  VERSION = "0.34.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.1
+  version: 0.34.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: []
@@ -115,7 +115,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Catch unsafe PostgreSQL migrations in development and run them easier in
   production