online_migrations 0.36.0 → 0.37.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6740adaa6d20273e8d148e8e0788a6e27c6c6701187fe60e006ff3ba8e2129d2
-  data.tar.gz: 445a3ef72888dd358cc5d917ca31de7499df3368797c9c73324704e0e2d8307a
+  metadata.gz: cdad1569af01bacbaa092898b51ba64ad8f6c9746c091441af38b11921bbe2cc
+  data.tar.gz: 7f3d23f9e0d5b78fb958322e852bcc274e73ef9c035e05e2e072bec1ebcca086
 SHA512:
-  metadata.gz: 338cf3a26b64efb827b5691addc67987048e0522f467d89c5ff4a18494f6b0e3cbeb93513e419a01b04be643d9f7e7a36c1aaf1b0a9d7f5c8158ecff1eb315e7
-  data.tar.gz: 4a6b9282a87124e037b3f101a5856d4a8756e86f9fb5b8bf3a4e42e7e2790e0edbd78b7263b8e9c653bedc25700d8a3fb8ade671e2f99e1e74dbfd49780c20eb
+  metadata.gz: 2fce7817c096a2ca24fed7f8f4984a28bb12a5b4992dd395da4b6ae843ed39684f0917ad0f112c81d7b46ee178a2f3424d7ac9426d32b8ed4a1a83251398985f
+  data.tar.gz: e2cd67a8215dbb287ebdd306c574cbbbfaaafcd5c55b0fb2ec2f393f363870ad3e228dd83fedca3b44287baf148504edf2ca191103e179b63e92675636328c4b

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## master (unreleased)
 
+## 0.37.0 (2026-09-23)
+
+- Add ability to restart background migrations
+- Fix collecting referenced tables when using `foreign_key: { to_table: ... }`
+
+## 0.36.1 (2026-09-23)
+
+- Fix compatibility with future Rails 8.2
+- Fix pausing already paused background data migrations
+
 ## 0.36.0 (2026-07-20)
 
 - Serialize to JSON `cursor` value for background data migrations

data/docs/background_data_migrations.md

@@ -354,6 +354,18 @@ migration.retry # => `true` if scheduled to be retried, `false` - if not
 
 The migration will be retried on the next Scheduler run.
 
+## Restarting a migration
+
+To restart a migration, run:
+
+```ruby
+migration = OnlineMigrations::DataMigrations::Migration.find(id)
+migration.force_restart
+```
+
+It ignores any previous status and marks the migration for the restart. Can be useful if the migration is stuck or
+you need to rerun an already finished migration etc.
+
 ## Configuring
 
 There are a few configurable options for the data migrations. Custom configurations should be placed in a `online_migrations.rb` initializer.

data/docs/background_schema_migrations.md

@@ -77,7 +77,7 @@ You shouldn't depend on the schema until the background schema migration is fini
 To retry a failed migration, run:
 
 ```ruby
-migration = OnlineMigrations::BackgroundSchemaMigrations::Migration.find(id)
+migration = OnlineMigrations::SchemaMigrations::Migration.find(id)
 migration.retry # => `true` if scheduled to be retried, `false` - if not
 ```
 
@@ -88,10 +88,22 @@ The migration will be retried on the next Scheduler run.
 To cancel an existing migration from future performing, run:
 
 ```ruby
-migration = OnlineMigrations::BackgroundSchemaMigrations::Migration.find(id)
+migration = OnlineMigrations::SchemaMigrations::Migration.find(id)
 migration.cancel
 ```
 
+## Restarting a migration
+
+To restart a migration, run:
+
+```ruby
+migration = OnlineMigrations::SchemaMigrations::Migration.find(id)
+migration.force_restart
+```
+
+It ignores any previous status and marks the migration for the restart. Can be useful if the migration is stuck or
+you need to rerun a cancelled migration.
+
 ## Instrumentation
 
 Background schema migrations use the [ActiveSupport::Notifications](http://api.rubyonrails.org/classes/ActiveSupport/Notifications.html) API.
@@ -156,7 +168,7 @@ Check the [source code](https://github.com/fatkodima/online_migrations/blob/mast
 **Note**: You can dynamically change certain migration parameters while the migration is run.
 For example,
 ```ruby
-migration = OnlineMigrations::BackgroundSchemaMigrations::Migration.find(id)
+migration = OnlineMigrations::SchemaMigrations::Migration.find(id)
 migration.update!(
   statement_timeout: 2.hours,  # The statement timeout value used when running the migration
   max_attempts: 10             # The # of attempts the failing migration will be retried
@@ -182,7 +194,7 @@ end
 The error handler should be a lambda that accepts 2 arguments:
 
 * `error`: The exception that was raised.
-* `errored_migration`: An `OnlineMigrations::BackgroundSchemaMigrations::Migration` object that represents a failed migration.
+* `errored_migration`: An `OnlineMigrations::SchemaMigrations::Migration` object that represents a failed migration.
 
 ### Multiple databases and sharding
 

data/lib/online_migrations/background_data_migrations/migration.rb

@@ -177,12 +177,12 @@ module OnlineMigrations
         true
       end
 
-      # Pause this data migration. No-op if migration is completed.
+      # Pause this data migration. No-op if migration is completed or already paused.
       #
       # @return [Boolean] whether this data migration was paused.
       #
       def pause
-        return false if completed?
+        return false if paused? || completed?
 
         if pending? || enqueued? || delayed? || stuck? || errored?
           paused!
@@ -240,6 +240,24 @@ module OnlineMigrations
         true
       end
 
+      # Force restart this data migration.
+      #
+      def force_restart
+        update_columns(
+          status: :pending,
+          cursor: nil,
+          jid: nil,
+          started_at: nil,
+          finished_at: nil,
+          tick_total: nil,
+          tick_count: 0,
+          time_running: 0.0,
+          error_class: nil,
+          error_message: nil,
+          backtrace: nil
+        )
+      end
+
       # @private
       def persist_progress(cursor, number_of_ticks, duration)
         update!(

data/lib/online_migrations/background_schema_migrations/migration.rb

@@ -135,6 +135,20 @@ module OnlineMigrations
         end
       end
 
+      # Force restart this schema migration.
+      #
+      def force_restart
+        update_columns(
+          status: :pending,
+          started_at: nil,
+          finished_at: nil,
+          attempts: 0,
+          error_class: nil,
+          error_message: nil,
+          backtrace: nil
+        )
+      end
+
       def index_addition?
         definition.match?(/create (unique )?index/i)
       end

data/lib/online_migrations/command_checker.rb

@@ -490,9 +490,10 @@ module OnlineMigrations
         bad_index = index && !concurrently_set
 
         foreign_key = options.fetch(:foreign_key, false)
+        foreign_key_options = foreign_key.is_a?(Hash) ? foreign_key : {}
 
         if foreign_key
-          foreign_table_name = Utils.foreign_table_name(ref_name, options)
+          foreign_table_name = Utils.foreign_table_name(ref_name, foreign_key_options)
           @foreign_key_tables << foreign_table_name.to_s
         end
 
@@ -519,9 +520,10 @@ module OnlineMigrations
 
       def add_reference_concurrently(table_name, ref_name, **options)
         foreign_key = options.fetch(:foreign_key, false)
+        foreign_key_options = foreign_key.is_a?(Hash) ? foreign_key : {}
 
         if foreign_key
-          foreign_table_name = Utils.foreign_table_name(ref_name, options)
+          foreign_table_name = Utils.foreign_table_name(ref_name, foreign_key_options)
           @foreign_key_tables << foreign_table_name.to_s
         end
 
@@ -529,7 +531,6 @@ module OnlineMigrations
           type = (options[:type] || :bigint).to_sym
           column_name = "#{ref_name}_id"
 
-          foreign_key_options = foreign_key.is_a?(Hash) ? foreign_key : {}
           check_mismatched_foreign_key_type(table_name, column_name, type, **foreign_key_options)
         end
       end

data/lib/online_migrations/command_recorder.rb

@@ -153,4 +153,157 @@ module OnlineMigrations
         [:add_text_limit_constraint, args]
       end
   end
+
+  # @private
+  # New format was introduced in https://github.com/rails/rails/pull/58239.
+  module CommandRecorder82
+    REVERSIBLE_AND_IRREVERSIBLE_METHODS = [
+      :update_column_in_batches,
+      :initialize_column_rename,
+      :initialize_columns_rename,
+      :revert_initialize_column_rename,
+      :revert_initialize_columns_rename,
+      :finalize_column_rename,
+      :finalize_columns_rename,
+      :revert_finalize_column_rename,
+      :revert_finalize_columns_rename,
+      :initialize_table_rename,
+      :revert_initialize_table_rename,
+      :finalize_table_rename,
+      :revert_finalize_table_rename,
+      :swap_column_names,
+      :add_column_with_default,
+      :add_not_null_constraint,
+      :remove_not_null_constraint,
+      :add_text_limit_constraint,
+      :remove_text_limit_constraint,
+      :add_reference_concurrently,
+      :change_column_type_in_background,
+      :enqueue_background_data_migration,
+      :remove_background_data_migration,
+
+      # column type change helpers
+      :initialize_column_type_change,
+      :initialize_columns_type_change,
+      :revert_initialize_column_type_change,
+      :revert_initialize_columns_type_change,
+      :backfill_column_for_type_change,
+      :backfill_columns_for_type_change,
+      :finalize_column_type_change,
+      :finalize_columns_type_change,
+      :revert_finalize_column_type_change,
+      :cleanup_column_type_change,
+      :cleanup_columns_type_change,
+    ]
+
+    REVERSIBLE_AND_IRREVERSIBLE_METHODS.each do |method|
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{method}(*args, **kwargs, &block)          # def create_table(*args, **kwargs, &block)
+          record(:"#{method}", args, kwargs, &block)    #   record(:create_table, args, kwargs, &block)
+        end                                             # end
+      RUBY
+    end
+
+    private
+      module StraightReversions
+        {
+          initialize_column_rename:           :revert_initialize_column_rename,
+          initialize_columns_rename:          :revert_initialize_columns_rename,
+          finalize_column_rename:             :revert_finalize_column_rename,
+          finalize_columns_rename:            :revert_finalize_columns_rename,
+          initialize_table_rename:            :revert_initialize_table_rename,
+          finalize_table_rename:              :revert_finalize_table_rename,
+          add_not_null_constraint:            :remove_not_null_constraint,
+          initialize_column_type_change:      :revert_initialize_column_type_change,
+          initialize_columns_type_change:     :revert_initialize_columns_type_change,
+          finalize_column_type_change:        :revert_finalize_column_type_change,
+          finalize_columns_type_change:       :revert_finalize_columns_type_change,
+        }.each do |cmd, inv|
+          [[inv, cmd], [cmd, inv]].each do |method, inverse|
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              def invert_#{method}(args, kwargs, &block)    # def invert_create_table(args, kwargs, &block)
+                [:#{inverse}, args, kwargs, block]          #   [:drop_table, args, kwargs, block]
+              end                                           # end
+            RUBY
+          end
+        end
+      end
+
+      include StraightReversions
+
+      def invert_add_reference_concurrently(args, kwargs)
+        [:remove_reference, args, kwargs]
+      end
+
+      def invert_swap_column_names(args, kwargs)
+        table_name, column1, column2 = args
+        [:swap_column_names, [table_name, column2, column1], kwargs]
+      end
+
+      def invert_add_column_with_default(args, kwargs)
+        table_name, column_name, = args
+        [:remove_column, [table_name, column_name], kwargs]
+      end
+
+      def invert_revert_initialize_column_rename(args, kwargs)
+        _table, column, new_column = args
+        if !column || !new_column
+          raise ActiveRecord::IrreversibleMigration,
+            "revert_initialize_column_rename is only reversible if given a column and new_column."
+        end
+        [:initialize_column_rename, args, kwargs]
+      end
+
+      def invert_revert_initialize_columns_rename(args, kwargs)
+        _table, old_new_column_hash = args
+        if !old_new_column_hash
+          raise ActiveRecord::IrreversibleMigration,
+            "revert_initialize_columns_rename is only reversible if given a hash of old and new columns."
+        end
+        [:initialize_columns_rename, args, kwargs]
+      end
+
+      def invert_finalize_table_rename(args, kwargs)
+        _table_name, new_name = args
+        if !new_name
+          raise ActiveRecord::IrreversibleMigration,
+            "finalize_table_rename is only reversible if given a new_name."
+        end
+        [:revert_finalize_table_rename, args, kwargs]
+      end
+
+      def invert_revert_initialize_column_type_change(args, kwargs)
+        if !args[2]
+          raise ActiveRecord::IrreversibleMigration,
+            "revert_initialize_column_type_change is only reversible if given a new_type."
+        end
+        super
+      end
+
+      def invert_revert_initialize_columns_type_change(args, kwargs)
+        if args[1].empty?
+          raise ActiveRecord::IrreversibleMigration,
+            "revert_initialize_columns_type_change is only reversible if given a columns_and_types."
+        end
+        super
+      end
+
+      def invert_add_not_null_constraint(args, kwargs)
+        kwargs.delete(:validate)
+        [:remove_not_null_constraint, args, kwargs]
+      end
+
+      def invert_add_text_limit_constraint(args, kwargs)
+        kwargs.delete(:validate)
+        [:remove_text_limit_constraint, args, kwargs]
+      end
+
+      def invert_remove_text_limit_constraint(args, kwargs)
+        if !args[2]
+          raise ActiveRecord::IrreversibleMigration, "remove_text_limit_constraint is only reversible if given a limit."
+        end
+
+        [:add_text_limit_constraint, args, kwargs]
+      end
+  end
 end

data/lib/online_migrations/foreign_keys_collector.rb

@@ -18,9 +18,12 @@ module OnlineMigrations
     end
 
     def references(*ref_names, **options)
-      if options[:foreign_key]
+      foreign_key = options[:foreign_key]
+
+      if foreign_key
+        foreign_key_options = foreign_key.is_a?(Hash) ? foreign_key : {}
         ref_names.each do |ref_name|
-          @referenced_tables << Utils.foreign_table_name(ref_name, options)
+          @referenced_tables << Utils.foreign_table_name(ref_name, foreign_key_options)
         end
       end
     end

data/lib/online_migrations/schema_cache.rb

@@ -79,6 +79,14 @@ module OnlineMigrations
         new_column = old_column.dup
         # Active Record defines only reader for :name
         new_column.instance_variable_set(:@name, new_column_name)
+
+        # https://github.com/rails/rails/commit/0c5b92705960ceff44324e69a921e760f1646503
+        # New in Active Record 8.2+.
+        if new_column.respond_to?(:slot)
+          max_slot = columns.map(&:slot).max
+          new_column.instance_variable_set(:@slot, max_slot + 1)
+        end
+
         # Correspond to the Active Record freezing of each column
         columns << new_column.freeze
       end

data/lib/online_migrations/schema_dumper.rb

@@ -15,7 +15,13 @@ module OnlineMigrations
 
   class WrappedConnection < SimpleDelegator
     def columns(table_name)
-      super.sort_by(&:name)
+      columns = super
+
+      if Utils.ar_version >= 8.2 && columns.is_a?(Hash)
+        columns.transform_values { |v| v.sort_by(&:name) }
+      else
+        columns.sort_by(&:name)
+      end
     end
   end
 end

data/lib/online_migrations/version.rb

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

data/lib/online_migrations.rb

@@ -119,7 +119,12 @@ module OnlineMigrations
       ActiveRecord::ConnectionAdapters::SchemaCache.prepend(OnlineMigrations::SchemaCache)
 
       ActiveRecord::Tasks::DatabaseTasks.singleton_class.prepend(OnlineMigrations::DatabaseTasks)
-      ActiveRecord::Migration::CommandRecorder.include(OnlineMigrations::CommandRecorder)
+
+      if Utils.ar_version >= 8.2
+        ActiveRecord::Migration::CommandRecorder.include(OnlineMigrations::CommandRecorder82)
+      else
+        ActiveRecord::Migration::CommandRecorder.include(OnlineMigrations::CommandRecorder)
+      end
 
       if !ActiveRecord::Batches::BatchEnumerator.method_defined?(:use_ranges)
         ActiveRecord::Batches::BatchEnumerator.include(OnlineMigrations::ActiveRecordBatchEnumerator)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: online_migrations
 version: !ruby/object:Gem::Version
-  version: 0.36.0
+  version: 0.37.0
 platform: ruby
 authors:
 - fatkodima
@@ -116,7 +116,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.14
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Catch unsafe PostgreSQL migrations in development and run them easier in
   production