online_migrations 0.17.1 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9822bc892c205f69f4dba067e5b3b096c1a2950e36a40800411aa30e23cdf95
-  data.tar.gz: 3756a3c7f274370411372ce08ffd37fde5ef7e930b0c98c57d1185e853e400af
+  metadata.gz: 57661cb5e096da3eaed31d4dbe5cda862f9f75271b59c28045412642acaf786b
+  data.tar.gz: 50ed46eaa89a4ee95ecd8b249b0fce616047006c91339dbc1069e572a96f0454
 SHA512:
-  metadata.gz: bce2d08b3126bfe68cfe85535f6d0efcdbdeea37843bdab281eb8330a5279a60df7dc63b904aa58d26c7a6c6f617103896a1478d4197127511632c151f0ed335
-  data.tar.gz: ffd7307d6e042188199991abb61efa93d53e72f8f1653349863167f6e8cd7df4d90fafe2113c76ac032bb9b32274b5f512ccda36840289c99b10ef3bab80df9a
+  metadata.gz: be91a43493896dbf0787cf9045c0ac187920a55946b98b0c653b8a50604031aee1bba3b59591fd4c22f7996af05254c71001e098289ded180eec9cdd8ae47d43
+  data.tar.gz: 840c35a008b4b949d1d686222d0722f98aa579fb31ccb14ffe3f6bd80147100bbcb323a9bdba657f230efbd3b2a97f799385e21f43218d8dbf19ab9a484d1147

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## master (unreleased)
 
+## 0.19.0 (2024-05-21)
+
+- Add ability to cancel background migrations
+
+## 0.18.0 (2024-05-07)
+
+- Fix setting `started_at`/`finished_at` for parents of sharded background schema migrations
+- Improve retrying of failed sharded background migrations
+- Fix a bug when retried background data migration can not start
+- Do not run multiple background schema migrations on the same table at the same time
+
 ## 0.17.1 (2024-04-28)
 
 - Fix raising in development when using sharding and background index creation/removal was not enqueued

data/docs/background_data_migrations.md

@@ -237,6 +237,7 @@ Background Migrations can be in various states during its execution:
   Note: In normal circumstances, this should not be used since background migrations should be run and finished by the scheduler.
 * **failed**: A migration raises an exception when running.
 * **succeeded**: A migration finished without error.
+* **cancelled**: A migration was cancelled by the user.
 
 To get the progress (assuming `#count` method on background migration class was defined):
 
@@ -247,6 +248,26 @@ migration.progress # value from 0 to 100.0
 
 **Note**: It will be easier to work with background migrations through some kind of Web UI, but until it is implemented, we can work with them only manually.
 
+## Retrying a failed migration
+
+To retry a failed migration, run:
+
+```ruby
+migration = OnlineMigrations::BackgroundMigrations::Migration.find(id)
+migration.retry # => `true` if scheduled to be retried, `false` - if not
+```
+
+The migration will be retried on the next Scheduler run.
+
+## Cancelling a migration
+
+To cancel an existing migration from future performing, run:
+
+```ruby
+migration = OnlineMigrations::BackgroundMigrations::Migration.find(id)
+migration.cancel
+```
+
 ## Configuring
 
 There are a few configurable options for the Background Migrations. Custom configurations should be placed in a `online_migrations.rb` initializer.

data/docs/background_schema_migrations.md

@@ -66,6 +66,26 @@ end
 
 You shouldn't depend on the schema until the background schema migration is finished. If having the schema migrated is a requirement, then the `ensure_background_schema_migration_succeeded` helper can be used to guarantee that the migration succeeded and the schema change applied.
 
+## Retrying a failed migration
+
+To retry a failed migration, run:
+
+```ruby
+migration = OnlineMigrations::BackgroundSchemaMigrations::Migration.find(id)
+migration.retry # => `true` if scheduled to be retried, `false` - if not
+```
+
+The migration will be retried on the next Scheduler run.
+
+## Cancelling a migration
+
+To cancel an existing migration from future performing, run:
+
+```ruby
+migration = OnlineMigrations::BackgroundSchemaMigrations::Migration.find(id)
+migration.cancel
+```
+
 ## Instrumentation
 
 Background schema migrations use the [ActiveSupport::Notifications](http://api.rubyonrails.org/classes/ActiveSupport/Notifications.html) API.
@@ -110,6 +130,7 @@ Background Schema Migrations can be in various states during its execution:
 * **running**: A migration is being performed by a migration executor.
 * **failed**: A migration raises an exception when running.
 * **succeeded**: A migration finished without error.
+* **cancelled**: A migration was cancelled by the user.
 
 ## Configuring
 

data/lib/online_migrations/background_migrations/migration.rb

@@ -15,6 +15,7 @@ module OnlineMigrations
         :finishing,   # The migration is being manually finishing inline by the user.
         :failed,      # The migration raises an exception when running.
         :succeeded,   # The migration finished without error.
+        :cancelled,   # The migration was cancelled by the user.
       ]
 
       self.table_name = :background_migrations
@@ -38,9 +39,9 @@ module OnlineMigrations
         enum status: STATUSES.index_with(&:to_s)
       end
 
-      belongs_to :parent, class_name: name, optional: true
-      has_many :children, class_name: name, foreign_key: :parent_id, dependent: :delete_all
-      has_many :migration_jobs, dependent: :delete_all
+      belongs_to :parent, class_name: name, optional: true, inverse_of: :children
+      has_many :children, class_name: name, foreign_key: :parent_id, dependent: :delete_all, inverse_of: :parent
+      has_many :migration_jobs, dependent: :delete_all, inverse_of: :migration
 
       validates :migration_name, :batch_column_name, presence: true
 
@@ -98,12 +99,19 @@ module OnlineMigrations
         end
       end
 
-      def last_job
-        migration_jobs.order(:max_value).last
+      # Overwrite enum's generated method to correctly work for composite migrations.
+      def cancelled!
+        return super if !composite?
+
+        transaction do
+          super
+          children.each { |child| child.cancelled! if !child.succeeded? }
+        end
       end
+      alias cancel cancelled!
 
-      def last_completed_job
-        migration_jobs.completed.order(:finished_at).last
+      def last_job
+        migration_jobs.order(:max_value).last
       end
 
       # Returns the progress of the background migration.
@@ -115,10 +123,13 @@ module OnlineMigrations
       def progress
         if succeeded?
           100.0
+        elsif enqueued?
+          0.0
         elsif composite?
           rows_counts = children.to_a.pluck(:rows_count)
           if rows_counts.none?(nil)
             total_rows_count = rows_counts.sum
+            return 100.0 if total_rows_count == 0
 
             progresses = children.map do |child|
               child.progress * child.rows_count / total_rows_count # weighted progress
@@ -126,11 +137,15 @@ module OnlineMigrations
 
             progresses.sum.round(2)
           end
-        elsif rows_count && rows_count > 0
-          jobs_rows_count = migration_jobs.succeeded.sum(:batch_size)
-          # The last migration job may need to process the amount of rows
-          # less than the batch size, so we can get a value > 1.0.
-          ([jobs_rows_count.to_f / rows_count, 1.0].min * 100).round(2)
+        elsif rows_count
+          if rows_count > 0
+            jobs_rows_count = migration_jobs.succeeded.sum(:batch_size)
+            # The last migration job may need to process the amount of rows
+            # less than the batch size, so we can get a value > 1.0.
+            ([jobs_rows_count.to_f / rows_count, 1.0].min * 100).round(2)
+          else
+            0.0
+          end
         end
       end
 
@@ -154,31 +169,34 @@ module OnlineMigrations
       # @return [Boolean]
       #
       def interval_elapsed?
-        last_active_job = migration_jobs.active.order(:updated_at).last
+        last_job = migration_jobs.order(:updated_at).last
+        return true if last_job.nil?
 
-        if last_active_job && !last_active_job.stuck?
-          false
-        elsif batch_pause > 0 && (job = last_completed_job)
-          job.finished_at + batch_pause <= Time.current
-        else
-          true
-        end
+        last_job.enqueued? || (last_job.updated_at + batch_pause <= Time.current)
       end
 
-      # Manually retry failed jobs.
+      # Mark this migration as ready to be processed again.
       #
       # This method marks failed jobs as ready to be processed again, and
       # they will be picked up on the next Scheduler run.
       #
-      def retry_failed_jobs
-        iterator = BatchIterator.new(migration_jobs.failed)
-        iterator.each_batch(of: 100) do |batch|
-          transaction do
+      def retry
+        if composite? && failed?
+          children.failed.each(&:retry)
+          running!
+          true
+        elsif failed?
+          iterator = BatchIterator.new(migration_jobs.failed)
+          iterator.each_batch(of: 100) do |batch|
             batch.each(&:retry)
-            enqueued!
           end
+          running!
+          true
+        else
+          false
         end
       end
+      alias retry_failed_jobs retry
 
       # Returns the time this migration started running.
       def started_at

data/lib/online_migrations/background_migrations/migration_job.rb

@@ -8,6 +8,7 @@ module OnlineMigrations
         :running,
         :failed,
         :succeeded,
+        :cancelled,
       ]
 
       self.table_name = :background_migration_jobs
@@ -47,7 +48,7 @@ module OnlineMigrations
       delegate :migration_name, :migration_class, :migration_object, :migration_relation, :batch_column_name,
         :arguments, :batch_pause, to: :migration
 
-      belongs_to :migration
+      belongs_to :migration, inverse_of: :migration_jobs
 
       validates :min_value, :max_value, presence: true, numericality: { greater_than: 0 }
       validate :values_in_migration_range, if: :min_value?
@@ -69,15 +70,23 @@ module OnlineMigrations
       # This is used when retrying failed jobs.
       #
       def retry
-        update!(
-          status: self.class.statuses[:enqueued],
-          attempts: 0,
-          started_at: nil,
-          finished_at: nil,
-          error_class: nil,
-          error_message: nil,
-          backtrace: nil
-        )
+        if failed?
+          transaction do
+            update!(
+              status: self.class.statuses[:enqueued],
+              attempts: 0,
+              started_at: nil,
+              finished_at: nil,
+              error_class: nil,
+              error_message: nil,
+              backtrace: nil
+            )
+            migration.running! if migration.failed?
+          end
+          true
+        else
+          false
+        end
       end
 
       private

data/lib/online_migrations/background_migrations/migration_job_status_validator.rb

@@ -5,9 +5,9 @@ module OnlineMigrations
     # @private
     class MigrationJobStatusValidator < ActiveModel::Validator
       VALID_STATUS_TRANSITIONS = {
-        "enqueued" => ["running"],
-        "running" => ["succeeded", "failed"],
-        "failed" => ["enqueued", "running"],
+        "enqueued" => ["running", "cancelled"],
+        "running" => ["succeeded", "failed", "cancelled"],
+        "failed" => ["enqueued", "running", "cancelled"],
       }
 
       def validate(record)

data/lib/online_migrations/background_migrations/migration_runner.rb

@@ -13,6 +13,7 @@ module OnlineMigrations
       # Runs one background migration job.
       def run_migration_job
         raise "Should not be called on a composite (with sharding) migration" if migration.composite?
+        return if migration.cancelled?
 
         mark_as_running if migration.enqueued?
         migration_payload = notifications_payload(migration)
@@ -56,7 +57,7 @@ module OnlineMigrations
           raise "This method is not intended for use in production environments"
         end
 
-        return if migration.completed?
+        return if migration.completed? || migration.cancelled?
 
         mark_as_running
 
@@ -77,7 +78,7 @@ module OnlineMigrations
       # Keep running until the migration is finished.
       #
       def finish
-        return if migration.completed?
+        return if migration.completed? || migration.cancelled?
 
         if migration.composite?
           migration.children.each do |child_migration|

data/lib/online_migrations/background_migrations/migration_status_validator.rb

@@ -7,7 +7,7 @@ module OnlineMigrations
       VALID_STATUS_TRANSITIONS = {
         # enqueued -> running occurs when the migration starts performing.
         # enqueued -> paused occurs when the migration is paused before starting.
-        "enqueued" => ["running", "paused"],
+        "enqueued" => ["running", "paused", "cancelled"],
         # running -> paused occurs when a user pauses the migration as
         #   it's performing.
         # running -> finishing occurs when a user manually finishes the migration.
@@ -18,14 +18,16 @@ module OnlineMigrations
           "finishing",
           "succeeded",
           "failed",
+          "cancelled",
         ],
         # finishing -> succeeded occurs when the migration completes successfully.
         # finishing -> failed occurs when the migration raises an exception when running.
-        "finishing" => ["succeeded", "failed"],
+        "finishing" => ["succeeded", "failed", "cancelled"],
         # paused -> running occurs when the migration is resumed after being paused.
-        "paused" => ["running"],
+        "paused" => ["running", "cancelled"],
         # failed -> enqueued occurs when the failed migration jobs are retried after being failed.
-        "failed" => ["enqueued"],
+        # failed -> running occurs when the failed migration is retried.
+        "failed" => ["enqueued", "running", "cancelled"],
       }
 
       def validate(record)

data/lib/online_migrations/background_schema_migrations/migration.rb

@@ -13,6 +13,7 @@ module OnlineMigrations
         :running,     # The migration is being performed by a migration executor.
         :failed,      # The migration raises an exception when running.
         :succeeded,   # The migration finished without error.
+        :cancelled,   # The migration was cancelled by the user.
       ]
 
       MAX_IDENTIFIER_LENGTH = 63
@@ -55,8 +56,8 @@ module OnlineMigrations
         enum status: STATUSES.index_with(&:to_s)
       end
 
-      belongs_to :parent, class_name: name, optional: true
-      has_many :children, class_name: name, foreign_key: :parent_id
+      belongs_to :parent, class_name: name, optional: true, inverse_of: :children
+      has_many :children, class_name: name, foreign_key: :parent_id, inverse_of: :parent
 
       validates :table_name, presence: true, length: { maximum: MAX_IDENTIFIER_LENGTH }
       validates :definition, presence: true
@@ -82,6 +83,17 @@ module OnlineMigrations
         succeeded? || failed?
       end
 
+      # Overwrite enum's generated method to correctly work for composite migrations.
+      def cancelled!
+        return super if !composite?
+
+        transaction do
+          super
+          children.each { |child| child.cancelled! if !child.succeeded? }
+        end
+      end
+      alias cancel cancelled!
+
       # Returns the progress of the background schema migration.
       #
       # @return [Float] value in range from 0.0 to 100.0
@@ -109,8 +121,13 @@ module OnlineMigrations
       # This is used to manually retrying failed migrations.
       #
       def retry
-        if composite?
+        if composite? && failed?
           children.failed.each(&:retry)
+          update!(
+            status: self.class.statuses[:running],
+            finished_at: nil
+          )
+          true
         elsif failed?
           update!(
             status: self.class.statuses[:enqueued],
@@ -121,6 +138,9 @@ module OnlineMigrations
             error_message: nil,
             backtrace: nil
           )
+          true
+        else
+          false
         end
       end
 

data/lib/online_migrations/background_schema_migrations/migration_runner.rb

@@ -11,6 +11,8 @@ module OnlineMigrations
       end
 
       def run
+        return if migration.cancelled?
+
         mark_as_running if migration.enqueued? || migration.failed?
 
         if migration.composite?
@@ -27,7 +29,14 @@ module OnlineMigrations
         def mark_as_running
           Migration.transaction do
             migration.running!
-            migration.parent.running! if migration.parent
+
+            if (parent = migration.parent)
+              if parent.started_at
+                parent.update!(status: :running, finished_at: nil)
+              else
+                parent.update!(status: :running, started_at: Time.current, finished_at: nil)
+              end
+            end
           end
         end
 
@@ -90,10 +99,10 @@ module OnlineMigrations
           parent.with_lock do
             children = parent.children.select(:status)
             if children.all?(&:succeeded?)
-              parent.succeeded!
+              parent.update!(status: :succeeded, finished_at: Time.current)
               completed = true
             elsif children.any?(&:failed?)
-              parent.failed!
+              parent.update!(status: :failed, finished_at: Time.current)
               completed = true
             end
           end

data/lib/online_migrations/background_schema_migrations/migration_status_validator.rb

@@ -6,13 +6,13 @@ module OnlineMigrations
     class MigrationStatusValidator < ActiveModel::Validator
       VALID_STATUS_TRANSITIONS = {
         # enqueued -> running occurs when the migration starts performing.
-        "enqueued" => ["running"],
+        "enqueued" => ["running", "cancelled"],
         # running -> succeeded occurs when the migration completes successfully.
         # running -> failed occurs when the migration raises an exception when running and retry attempts exceeded.
-        "running" => ["succeeded", "failed"],
+        "running" => ["succeeded", "failed", "cancelled"],
         # failed -> enqueued occurs when the failed migration is enqueued to be retried.
         # failed -> running occurs when the failed migration is retried.
-        "failed" => ["enqueued", "running"],
+        "failed" => ["enqueued", "running", "cancelled"],
       }
 
       def validate(record)

data/lib/online_migrations/background_schema_migrations/scheduler.rb

@@ -3,7 +3,8 @@
 module OnlineMigrations
   module BackgroundSchemaMigrations
     # Class responsible for scheduling background schema migrations.
-    # It selects a single migration and runs it if there is no currently running migration.
+    # It selects a single migration and runs it if there is no currently
+    # running migration on the same table.
     #
     # Scheduler should be configured to run periodically, for example, via cron.
     # @example Run via whenever
@@ -19,12 +20,25 @@ module OnlineMigrations
 
       # Runs Scheduler
       def run
-        migration = Migration.runnable.enqueued.queue_order.first || Migration.retriable.queue_order.first
+        migration = find_migration
         if migration
           runner = MigrationRunner.new(migration)
           runner.run
         end
       end
+
+      private
+        def find_migration
+          active_migrations = Migration.running.select(:table_name, :shard).to_a
+          runnable_migrations = Migration.runnable.enqueued.queue_order.to_a + Migration.retriable.queue_order.to_a
+
+          runnable_migrations.find do |runnable_migration|
+            active_migrations.none? do |active_migration|
+              active_migration.shard == runnable_migration.shard &&
+                active_migration.table_name == runnable_migration.table_name
+            end
+          end
+        end
     end
   end
 end

data/lib/online_migrations/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: online_migrations
 version: !ruby/object:Gem::Version
-  version: 0.17.1
+  version: 0.19.0
 platform: ruby
 authors:
 - fatkodima
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-04-28 00:00:00.000000000 Z
+date: 2024-05-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -113,7 +113,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.4
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
 summary: Catch unsafe PostgreSQL migrations in development and run them easier in