online_migrations 0.24.0 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99170e244f0f008e8d097222c88a96555692aa5afc136087d03341866ed8412c
-  data.tar.gz: 6068a722274c73d8a0ab3c1bed4d1f2673cd99d15ca77c24f7fff5af75e77129
+  metadata.gz: cbca384d5eaf4ab575e80c60160d42326ef86f1baf21419f290663e0d9698eb0
+  data.tar.gz: b90abf4e278ee1b2ab27e60472f6bb127b124797084f53205a0929a5cc98268b
 SHA512:
-  metadata.gz: 9d2a127aee978d36676d8bdd85352487f66a14289cca28173eb1126aee65ceeea5dda067171ffb320b7c0cb2be903712ab158af12312452180b8e56da1e7b641
-  data.tar.gz: 305f89162f87a3746d91bfdfacae00b7d0f2a374f27755c846cd4386d65694442b70fc6963a7dec8845c192eca2cc625bb020c7c4aec664320a395b124bb3e71
+  metadata.gz: eea056dd2b0c5a24213543d96d6b2ca5a1c230c38aa37f475d674157bc354a8d0c1cb39e6e2c0a6e86867b184e82b51ec9ad0452eed00e1a7b7a6098b203c3ff
+  data.tar.gz: 9636d4b788d655ad04d0141cd28ae61c053b15d83f00c63b236ee181feeb438c18f2a8f34da49b26d955ff3c004c053f0d570d00ff6801e47e15c438b09f2c51

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 ## master (unreleased)
 
+## 0.26.0 (2025-04-28)
+
+- 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`
+
+  ```ruby
+  # config/initializers/online_migrations.rb
+  config.require_safety_assured_reason = true
+
+  # in migration
+  safety_assured("Table is small") do
+    add_index :users, :email, unique: true
+  end
+  ```
+
+## 0.25.0 (2025-02-03)
+
+- Track start/finish time of background data migrations
+
+    Note: Make sure to run `bin/rails generate online_migrations:upgrade` if using background migrations.
+
+- Add new state for errored background migrations
+
+    * **errored** - migration raised an error during last run
+    * **failed** - migration raises an error when running and retry attempts exceeded
+
+- Fix thread safety issue for lock retrier
+
+    Note: Lock retrier changed its API (`LockRetrier#connection` accessor was removed and
+    `LockRetrier#with_lock_retries` now accepts a connection argument). This change might be of interest
+    if you implemented a custom lock retrier class.
+
 ## 0.24.0 (2025-01-20)
 
 - Add ability to run a separate background migrations scheduler per shard

data/README.md

@@ -16,8 +16,8 @@ See [comparison to `strong_migrations`](#comparison-to-strong_migrations)
 
 ## Requirements
 
-- Ruby 3.0+
-- Rails 7.0+
+- Ruby 3.1+
+- Rails 7.1+
 - PostgreSQL 12+
 
 For older Ruby and Rails versions you can use older versions of this gem.
@@ -64,76 +64,32 @@ An operation is classified as dangerous if it either:
 
 ## Example
 
-Consider the following migration:
-
-```ruby
-class AddAdminToUsers < ActiveRecord::Migration[8.0]
-  def change
-    add_column :users, :admin, :boolean, default: false, null: false
-  end
-end
-```
-
-If the `users` table is large, running this migration on a live PostgreSQL < 11 database will likely cause downtime.
-
-A safer approach would be to run something like the following:
-
-```ruby
-class AddAdminToUsers < ActiveRecord::Migration[8.0]
-  # Do not wrap the migration in a transaction so that locks are held for a shorter time.
-  disable_ddl_transaction!
-
-  def up
-    # Lower PostgreSQL's lock timeout to avoid statement queueing.
-    execute "SET lock_timeout TO '5s'" # The lock_timeout duration is customizable.
-
-    # Add the column without the default value and the not-null constraint.
-    add_column :users, :admin, :boolean
-
-    # Set the column's default value.
-    change_column_default :users, :admin, false
-
-    # Backfill the column in batches.
-    User.in_batches.update_all(admin: false)
-
-    # Add the not-null constraint. Beforehand, set a short statement timeout so that
-    # Postgres does not spend too much time performing the full table scan to verify
-    # the column contains no nulls.
-    execute "SET statement_timeout TO '5s'"
-    change_column_null :users, :admin, false
-  end
-
-  def down
-    remove_column :users, :admin
-  end
-end
-```
-
-When you actually run the original migration, you will get an error message:
+When you run a migration that's potentially dangerous, you'll see an error message like:
 
 ```txt
 ⚠️  [online_migrations] Dangerous operation detected ⚠️
 
-Adding a column with a non-null default blocks reads and writes while the entire table is rewritten.
-
+Active Record caches database columns at runtime, so if you drop a column, it can cause exceptions until your app reboots.
 A safer approach is to:
-1. add the column without a default value
-2. change the column default
-3. backfill existing rows with the new value
-4. add the NOT NULL constraint
 
-add_column_with_default takes care of all this steps:
+1. Ignore the column:
 
-class AddAdminToUsers < ActiveRecord::Migration[8.0]
-  disable_ddl_transaction!
+  class User < ApplicationRecord
+    self.ignored_columns += ["name"]
+  end
 
-  def change
-    add_column_with_default :users, :admin, :boolean, default: false, null: false
+2. Deploy
+3. Wrap column removing in a safety_assured { ... } block
+
+  class RemoveColumn < ActiveRecord::Migration[8.0]
+    def change
+      safety_assured { remove_column :users, :name }
+    end
   end
-end
-```
 
-It suggests how to safely implement a migration, which essentially runs the steps similar to described in the previous example.
+4. Remove column ignoring from step 1
+5. Deploy
+```
 
 ## Checks
 
@@ -1278,17 +1234,6 @@ Interesting reads:
 - [Stop worrying about PostgreSQL locks in your Rails migrations](https://medium.com/doctolib/stop-worrying-about-postgresql-locks-in-your-rails-migrations-3426027e9cc9)
 - [Avoiding integer overflows with zero downtime](https://buildkite.com/blog/avoiding-integer-overflows-with-zero-downtime)
 
-## Maybe TODO
-
-- support MySQL
-- support other ORMs
-
-Background migrations:
-
-- extract as a separate gem
-- add UI
-- support batching over non-integer and multiple columns
-
 ## Comparison to `strong_migrations`
 
 This gem was heavily inspired by the `strong_migrations` and GitLab's approaches to database migrations. This gem is a superset of `strong_migrations`, feature-wise, and has the same APIs.

data/docs/background_schema_migrations.md

@@ -134,7 +134,8 @@ Background Schema Migrations can be in various states during its execution:
 
 * **enqueued**: A migration has been enqueued by the user.
 * **running**: A migration is being performed by a migration executor.
-* **failed**: A migration raises an exception when running.
+* **errored**: A migration raised an error during last run.
+* **failed**: A migration raises an error when running and retry attempts exceeded.
 * **succeeded**: A migration finished without error.
 * **cancelled**: A migration was cancelled by the user.
 

data/docs/configuring.md

@@ -38,6 +38,14 @@ config.disable_check(:remove_index)
 
 Check the [source code](https://github.com/fatkodima/online_migrations/blob/master/lib/online_migrations/error_messages.rb) for the list of keys.
 
+## Requiring safety_assured reason
+
+To require safety reason explanation when calling `safery_assured` (disabled by default):
+
+```ruby
+config.require_safety_assured_reason = true
+```
+
 ## Down Migrations / Rollbacks
 
 By default, checks are disabled when migrating down. Enable them with:

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

@@ -1,6 +1,6 @@
 class AddShardingToOnlineMigrations < <%= migration_parent %>
   def change
-    safety_assured do
+    safety_assured("Table is small") do
       remove_index :background_migrations, [:migration_name, :arguments], unique: true
 
       change_table :background_migrations do |t|

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

@@ -0,0 +1,31 @@
+class AddTimestampsToBackgroundMigrations < <%= migration_parent %>
+  def change
+    safety_assured("Table is small") do
+      add_column :background_migrations, :started_at, :datetime
+      add_column :background_migrations, :finished_at, :datetime
+
+      up_only do
+        # Set started_at.
+        execute(<<~SQL)
+          UPDATE background_migrations
+          SET started_at = (
+            SELECT min(started_at)
+            FROM background_migration_jobs
+            WHERE background_migration_jobs.migration_id = background_migrations.id
+          )
+        SQL
+
+        # Set finished_at.
+        execute(<<~SQL)
+          UPDATE background_migrations
+          SET finished_at = (
+            SELECT max(finished_at)
+            FROM background_migration_jobs
+            WHERE background_migration_jobs.migration_id = background_migrations.id
+          )
+          WHERE status IN ('failed', 'succeeded')
+        SQL
+      end
+    end
+  end
+end

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

@@ -1,6 +1,6 @@
 class BackgroundSchemaMigrationsChangeUniqueIndex < <%= migration_parent %>
   def change
-    safety_assured do
+    safety_assured("Table is small") do
       remove_index :background_schema_migrations, name: :index_background_schema_migrations_on_unique_configuration
       add_index :background_schema_migrations, [:migration_name, :shard, :connection_class_name], unique: true,
         name: :index_background_schema_migrations_on_unique_configuration

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

@@ -12,6 +12,9 @@ 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.
+  config.require_safety_assured_reason = false
+
   # Configure whether to perform checks when migrating down.
   config.check_down = false
 

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

@@ -16,6 +16,8 @@ class InstallOnlineMigrations < <%= migration_parent %>
       t.string :status, default: "enqueued", null: false
       t.string :shard
       t.boolean :composite, default: false, null: false
+      t.datetime :started_at
+      t.datetime :finished_at
       t.timestamps
 
       t.foreign_key :background_migrations, column: :parent_id, on_delete: :cascade

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

@@ -1,10 +1,10 @@
 class Enqueue<%= class_name %> < <%= migration_parent %>
   def up
-    enqueue_background_data_migration("<%= class_name %>", ...args)
+    enqueue_background_data_migration("<%= class_name %>")
   end
 
   def down
     # Make sure to pass the same arguments as in the "up" method, if any.
-    remove_background_data_migration("<%= class_name %>", ...args)
+    remove_background_data_migration("<%= class_name %>")
   end
 end

data/lib/generators/online_migrations/upgrade_generator.rb

@@ -34,6 +34,10 @@ module OnlineMigrations
           migrations << "background_schema_migrations_change_unique_index"
         end
 
+        if !connection.column_exists?(BackgroundMigrations::Migration.table_name, :started_at)
+          migrations << "add_timestamps_to_background_migrations"
+        end
+
         migrations
       end
 

data/lib/online_migrations/background_migrations/migration.rb

@@ -189,15 +189,23 @@ module OnlineMigrations
       #
       def retry
         if composite? && failed?
-          children.failed.each(&:retry)
-          enqueued!
+          transaction do
+            update!(status: :enqueued, finished_at: nil)
+            children.failed.each(&:retry)
+          end
+
           true
         elsif failed?
-          iterator = BatchIterator.new(migration_jobs.failed)
-          iterator.each_batch(of: 100) do |batch|
-            batch.each(&:retry)
+          transaction do
+            parent.update!(status: :enqueued, finished_at: nil) if parent
+            update!(status: :enqueued, started_at: nil, finished_at: nil)
+
+            iterator = BatchIterator.new(migration_jobs.failed)
+            iterator.each_batch(of: 100) do |batch|
+              batch.each(&:retry)
+            end
           end
-          enqueued!
+
           true
         else
           false
@@ -205,20 +213,6 @@ module OnlineMigrations
       end
       alias retry_failed_jobs retry
 
-      # Returns the time this migration started running.
-      def started_at
-        # To be precise, we should get the minimum of `started_at` amongst the children jobs
-        # (for simple migrations) and amongst the children migrations (for composite migrations).
-        # But we do not have an appropriate index on the jobs table and using this will lead to
-        # N+1 queries if used inside some dashboard, for example.
-        created_at
-      end
-
-      # Returns the time this migration finished running.
-      def finished_at
-        updated_at if completed?
-      end
-
       # @private
       def on_shard(&block)
         abstract_class = Utils.find_connection_class(migration_model)
@@ -229,9 +223,9 @@ module OnlineMigrations
 
       # @private
       def reset_failed_jobs_attempts
-        iterator = BatchIterator.new(migration_jobs.failed.attempts_exceeded)
+        iterator = BatchIterator.new(migration_jobs.failed)
         iterator.each_batch(of: 100) do |relation|
-          relation.update_all(attempts: 0)
+          relation.update_all(status: :enqueued, attempts: 0)
         end
       end
 

data/lib/online_migrations/background_migrations/migration_job.rb

@@ -6,6 +6,7 @@ module OnlineMigrations
       STATUSES = [
         :enqueued,
         :running,
+        :errored,
         :failed,
         :succeeded,
         :cancelled,
@@ -13,7 +14,7 @@ module OnlineMigrations
 
       self.table_name = :background_migration_jobs
 
-      scope :active, -> { where(status: [:enqueued, :running]) }
+      scope :active, -> { where(status: [:enqueued, :running, :errored]) }
       scope :completed, -> { where(status: [:failed, :succeeded]) }
       scope :stuck, -> do
         timeout = OnlineMigrations.config.background_migrations.stuck_jobs_timeout
@@ -21,14 +22,11 @@ module OnlineMigrations
       end
 
       scope :retriable, -> do
-        failed_retriable = failed.where("attempts < max_attempts")
-
-        stuck_sql             = connection.unprepared_statement { stuck.to_sql }
-        failed_retriable_sql  = connection.unprepared_statement { failed_retriable.to_sql }
+        stuck_sql = connection.unprepared_statement { stuck.to_sql }
 
         from(Arel.sql(<<~SQL))
           (
-            (#{failed_retriable_sql})
+            (SELECT * FROM background_migration_jobs WHERE status = 'errored')
             UNION
             (#{stuck_sql})
           ) AS #{table_name}
@@ -36,7 +34,6 @@ module OnlineMigrations
       end
 
       scope :except_succeeded, -> { where.not(status: :succeeded) }
-      scope :attempts_exceeded, -> { where("attempts >= max_attempts") }
 
       enum :status, STATUSES.index_with(&:to_s)
 
@@ -60,6 +57,10 @@ module OnlineMigrations
         running? && updated_at <= timeout.seconds.ago
       end
 
+      def attempts_exceeded?
+        attempts >= max_attempts
+      end
+
       # Mark this job as ready to be processed again.
       #
       # This is used when retrying failed jobs.

data/lib/online_migrations/background_migrations/migration_job_runner.rb

@@ -37,8 +37,10 @@ module OnlineMigrations
       rescue Exception => e # rubocop:disable Lint/RescueException
         backtrace_cleaner = ::OnlineMigrations.config.backtrace_cleaner
 
+        status = migration_job.attempts_exceeded? ? :failed : :errored
+
         migration_job.update!(
-          status: :failed,
+          status: status,
           finished_at: Time.current,
           error_class: e.class.name,
           error_message: e.message,

data/lib/online_migrations/background_migrations/migration_job_status_validator.rb

@@ -6,7 +6,8 @@ module OnlineMigrations
     class MigrationJobStatusValidator < ActiveModel::Validator
       VALID_STATUS_TRANSITIONS = {
         "enqueued" => ["running", "cancelled"],
-        "running" => ["succeeded", "failed", "cancelled"],
+        "running" => ["succeeded", "errored", "failed", "cancelled"],
+        "errored" => ["running", "failed", "cancelled"],
         "failed" => ["enqueued", "running", "cancelled"],
       }
 

data/lib/online_migrations/background_migrations/migration_runner.rb

@@ -34,9 +34,9 @@ module OnlineMigrations
           job_runner.run
         elsif !migration.migration_jobs.active.exists?
           if migration.migration_jobs.failed.exists?
-            migration.failed!
+            migration.update!(status: :failed, finished_at: Time.current)
           else
-            migration.succeeded!
+            migration.update!(status: :succeeded, finished_at: Time.current)
           end
 
           ActiveSupport::Notifications.instrument("completed.background_migrations", migration_payload)
@@ -100,8 +100,15 @@ module OnlineMigrations
       private
         def mark_as_running
           Migration.transaction do
-            migration.running!
-            migration.parent.running! if migration.parent && migration.parent.enqueued?
+            migration.update!(status: :running, started_at: Time.current, finished_at: nil)
+
+            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
 
@@ -133,10 +140,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.rb

@@ -11,7 +11,8 @@ module OnlineMigrations
       STATUSES = [
         :enqueued,    # The migration has been enqueued by the user.
         :running,     # The migration is being performed by a migration executor.
-        :failed,      # The migration raises an exception when running.
+        :errored,     # The migration raised an error during last run.
+        :failed,      # The migration raises an error when running and retry attempts exceeded.
         :succeeded,   # The migration finished without error.
         :cancelled,   # The migration was cancelled by the user.
       ]
@@ -23,7 +24,7 @@ module OnlineMigrations
       scope :queue_order, -> { order(created_at: :asc) }
       scope :parents, -> { where(parent_id: nil) }
       scope :runnable, -> { where(composite: false) }
-      scope :active, -> { where(status: [statuses[:enqueued], statuses[:running]]) }
+      scope :active, -> { where(status: [:enqueued, :running, :errored]) }
       scope :except_succeeded, -> { where.not(status: :succeeded) }
 
       scope :stuck, -> do
@@ -33,14 +34,11 @@ module OnlineMigrations
       end
 
       scope :retriable, -> do
-        failed_retriable = runnable.failed.where("attempts < max_attempts")
-
-        stuck_sql             = connection.unprepared_statement { stuck.to_sql }
-        failed_retriable_sql  = connection.unprepared_statement { failed_retriable.to_sql }
+        stuck_sql = connection.unprepared_statement { stuck.to_sql }
 
         from(Arel.sql(<<~SQL))
           (
-            (#{failed_retriable_sql})
+            (SELECT * FROM background_schema_migrations WHERE NOT composite AND status = 'errored')
             UNION
             (#{stuck_sql})
           ) AS #{table_name}
@@ -139,22 +137,27 @@ module OnlineMigrations
       #
       def retry
         if composite? && failed?
-          children.failed.each(&:retry)
-          update!(
-            status: self.class.statuses[:enqueued],
-            finished_at: nil
-          )
+          transaction do
+            update!(status: :enqueued, finished_at: nil)
+            children.failed.each(&:retry)
+          end
+
           true
         elsif failed?
-          update!(
-            status: self.class.statuses[:enqueued],
-            attempts: 0,
-            started_at: nil,
-            finished_at: nil,
-            error_class: nil,
-            error_message: nil,
-            backtrace: nil
-          )
+          transaction do
+            parent.update!(status: :enqueued, finished_at: nil) if parent
+
+            update!(
+              status: :enqueued,
+              attempts: 0,
+              started_at: nil,
+              finished_at: nil,
+              error_class: nil,
+              error_message: nil,
+              backtrace: nil
+            )
+          end
+
           true
         else
           false
@@ -191,10 +194,7 @@ module OnlineMigrations
               if index_addition?
                 index = connection.indexes(table_name).find { |i| i.name == name }
                 if index
-                  # Use index validity from https://github.com/rails/rails/pull/45160
-                  # when switching to ActiveRecord >= 7.1.
-                  schema = connection.send(:__schema_for_table, table_name)
-                  if connection.send(:__index_valid?, name, schema: schema)
+                  if index.valid?
                     return
                   else
                     connection.remove_index(table_name, name: name, algorithm: :concurrently)
@@ -203,6 +203,11 @@ module OnlineMigrations
               end
 
               connection.execute(definition)
+
+              # 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

data/lib/online_migrations/background_schema_migrations/migration_helpers.rb

@@ -19,7 +19,7 @@ module OnlineMigrations
           return
         end
 
-        if index_exists?(table_name, column_name, **options)
+        if index_exists?(table_name, column_name, name: index.name, **options)
           Utils.raise_or_say("Index creation was not enqueued because the index already exists.")
           return
         end

data/lib/online_migrations/background_schema_migrations/migration_runner.rb

@@ -13,7 +13,7 @@ module OnlineMigrations
       def run
         return if migration.cancelled? || migration.succeeded?
 
-        mark_as_running if migration.enqueued? || migration.failed?
+        mark_as_running if migration.enqueued? || migration.errored?
 
         if migration.composite?
           migration.children.each do |child_migration|
@@ -83,14 +83,18 @@ module OnlineMigrations
         rescue Exception => e # rubocop:disable Lint/RescueException
           backtrace_cleaner = ::OnlineMigrations.config.backtrace_cleaner
 
+          status = migration.attempts_exceeded? ? :failed : :errored
+
           migration.update!(
-            status: :failed,
+            status: status,
             finished_at: Time.current,
             error_class: e.class.name,
             error_message: e.message,
             backtrace: backtrace_cleaner ? backtrace_cleaner.clean(e.backtrace) : e.backtrace
           )
 
+          complete_parent_if_needed(migration) if migration.parent.present?
+
           ::OnlineMigrations.config.background_schema_migrations.error_handler.call(e, migration)
           raise if Utils.run_background_migrations_inline?
         end

data/lib/online_migrations/background_schema_migrations/migration_status_validator.rb

@@ -8,8 +8,12 @@ module OnlineMigrations
         # enqueued -> running occurs when the migration starts performing.
         "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", "cancelled"],
+        # running -> errored occurs when the migration raised an error during the last run.
+        # running -> failed occurs when the migration raises an error when running and retry attempts exceeded.
+        "running" => ["succeeded", "errored", "failed", "cancelled"],
+        # errored -> running occurs when previously errored migration starts running
+        # errored -> failed occurs when the migration raises an error when running and retry attempts exceeded.
+        "errored" => ["running", "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", "cancelled"],