online_migrations 0.18.0 → 0.19.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31bbf9d9c3a619e7a878717b8d4bcffae2e71e819bd4d2ea140495fdbb951452
-  data.tar.gz: f9a92ef118577b4bd2e837c95687d19a6d69fba988e61625f51bf2807a855e62
+  metadata.gz: 259343358d51032a296c3745f92aa0e7ab5fc8f2d5dc6cd124873876e523d525
+  data.tar.gz: d07240d06faac048145ae8f54da1a947d197f9ff40bb2adf276625eb76bcafb5
 SHA512:
-  metadata.gz: b786ffdeb3d57f72d2582a222915b21c2c09f2755b049d99b9faf68fd1fe5a0655a577b37bb427473af9e24c564b5db825051da86a87e82787c29122c7e5053a
-  data.tar.gz: 33ec438be94ff7b69dee15770a730e6d946b2e1ccf0fb71a3be8819690701b7057d4ba4d5f4b297810265be83225f78b5b7e990b91e5affc35d5961a807ffc93
+  metadata.gz: c67adbf061095fdcbb5fcaa5305f671d81cf434dc182bfe9e43d66dae41f87d24cf5a79bb4aca160a955c74dff20de5e217b20731fe022df1dece6246e0239c0
+  data.tar.gz: 705397632e3afe3628776e854f74ff0ee70ada9d73d0d9e84c113289623d6240fc79b7823ca0dc05d3dab8dfd90c421c667b60ee394dbfb03c49afabd31ddc95

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## master (unreleased)
 
+## 0.19.1 (2024-05-24)
+
+- Fix `add_index_in_background` to be idempotent
+
+## 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_helpers.rb

@@ -6,14 +6,24 @@ module OnlineMigrations
       def add_index_in_background(table_name, column_name, **options)
         migration_options = options.extract!(:max_attempts, :statement_timeout, :connection_class_name)
 
+        options[:algorithm] = :concurrently
+        index, algorithm, if_not_exists = add_index_options(table_name, column_name, **options)
+
+        # Need to check this first, because `index_exists?` does not check for `:where`s.
+        if index_name_exists?(table_name, index.name)
+          Utils.raise_or_say(<<~MSG)
+            Index creation was not enqueued because the index with name '#{index.name}' already exists.
+            This can be due to an aborted migration or you need to explicitly provide another name
+            via `:name` option.
+          MSG
+          return
+        end
+
         if index_exists?(table_name, column_name, **options)
           Utils.raise_or_say("Index creation was not enqueued because the index already exists.")
           return
         end
 
-        options[:algorithm] = :concurrently
-        index, algorithm, if_not_exists = add_index_options(table_name, column_name, **options)
-
         create_index = ActiveRecord::ConnectionAdapters::CreateIndexDefinition.new(index, algorithm, if_not_exists)
         schema_creation = ActiveRecord::ConnectionAdapters::PostgreSQL::SchemaCreation.new(self)
         definition = schema_creation.accept(create_index)
@@ -77,22 +87,21 @@ module OnlineMigrations
       # @private
       def create_background_schema_migration(migration_name, table_name, **options)
         options.assert_valid_keys(:definition, :max_attempts, :statement_timeout, :connection_class_name)
-        migration = Migration.new(migration_name: migration_name, table_name: table_name, **options)
-
-        shards = Utils.shard_names(migration.connection_class)
-        if shards.size > 1
-          migration.children = shards.map do |shard|
-            child = migration.dup
-            child.shard = shard
-            child
-          end
 
-          migration.composite = true
-        end
+        Migration.find_or_create_by!(migration_name: migration_name, shard: nil) do |migration|
+          migration.assign_attributes(**options, table_name: table_name)
 
-        # This will save all the records using a transaction.
-        migration.save!
-        migration
+          shards = Utils.shard_names(migration.connection_class)
+          if shards.size > 1
+            migration.children = shards.map do |shard|
+              child = migration.dup
+              child.shard = shard
+              child
+            end
+
+            migration.composite = true
+          end
+        end
       end
     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? || migration.succeeded?
+
         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.1"
 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.1
 platform: ruby
 authors:
 - fatkodima
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-05-07 00:00:00.000000000 Z
+date: 2024-05-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord