online_migrations 0.18.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31bbf9d9c3a619e7a878717b8d4bcffae2e71e819bd4d2ea140495fdbb951452
-  data.tar.gz: f9a92ef118577b4bd2e837c95687d19a6d69fba988e61625f51bf2807a855e62
+  metadata.gz: 57661cb5e096da3eaed31d4dbe5cda862f9f75271b59c28045412642acaf786b
+  data.tar.gz: 50ed46eaa89a4ee95ecd8b249b0fce616047006c91339dbc1069e572a96f0454
 SHA512:
-  metadata.gz: b786ffdeb3d57f72d2582a222915b21c2c09f2755b049d99b9faf68fd1fe5a0655a577b37bb427473af9e24c564b5db825051da86a87e82787c29122c7e5053a
-  data.tar.gz: 33ec438be94ff7b69dee15770a730e6d946b2e1ccf0fb71a3be8819690701b7057d4ba4d5f4b297810265be83225f78b5b7e990b91e5affc35d5961a807ffc93
+  metadata.gz: be91a43493896dbf0787cf9045c0ac187920a55946b98b0c653b8a50604031aee1bba3b59591fd4c22f7996af05254c71001e098289ded180eec9cdd8ae47d43
+  data.tar.gz: 840c35a008b4b949d1d686222d0722f98aa579fb31ccb14ffe3f6bd80147100bbcb323a9bdba657f230efbd3b2a97f799385e21f43218d8dbf19ab9a484d1147

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## 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

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):
 
@@ -258,6 +259,15 @@ 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

@@ -77,6 +77,15 @@ 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.
@@ -121,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
@@ -98,6 +99,17 @@ module OnlineMigrations
         end
       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!
+
       def last_job
         migration_jobs.order(:max_value).last
       end

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

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,15 +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 -> 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/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
@@ -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

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?

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

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: online_migrations
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.19.0
 platform: ruby
 authors:
 - fatkodima
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-05-07 00:00:00.000000000 Z
+date: 2024-05-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord