online_migrations 0.29.2 → 0.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f0f48b03f81c0a92af100d5d547eefc241806204f0cc0a475eb528fed026037
-  data.tar.gz: 74f9246907e52d527c46f832e66ab4b4b74c89e0ea9492612a303a1d65f006c7
+  metadata.gz: 428fd65e363b915608f720370a2cd91ec14749cd17933ec4e26351bb4745084a
+  data.tar.gz: ae292bba4cd1b557694f78240a7da761c8d890aa691cc6b485ddd9f71fd339c5
 SHA512:
-  metadata.gz: d55296987b866078354a39a06f431c360a18935803b852a5768549b3ae9f18bf8d27a3b0608086b1bf9c20ecaa006ea782ed7f128bd45c57d32bce50e8cc67e3
-  data.tar.gz: b57ae5030819e74eb891565fd87c77a1762ed1e3aa8f74ec4fba570f286150f6da500279f7bbea95cf7e0fb360dcf3acd491ee05e1ce8e635889549211d55bf8
+  metadata.gz: 59c0573c24d75488c849fa746d6346c31e439d66032725264ce724e97ab8ffbd16cebb03a57ad75071e2b29bf884be0b47696abdcadc72d974effaafd73fe8b4
+  data.tar.gz: 73de95254d001d4d285a48ad4d3adb60726ab6bf0bb86b085dde8466b6e1e85fbb668738f09121c38718504ad253615afb3da5e24f56bc48bd01ce9d369cdd4c

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## master (unreleased)
 
+## 0.30.0 (2025-10-17)
+
+- Fix `remove_check_constraint` when using `:if_exists`
+- Add schema statement to lock retrier
+
+## 0.29.3 (2025-08-19)
+
+- Fix an edge case where a background index might not be added
+
 ## 0.29.2 (2025-07-21)
 
 - Fix analyzing tables when indexes are added

data/docs/configuring.md

@@ -113,6 +113,129 @@ When a statement within transaction fails - the whole transaction is retried. If
 
 **Note**: Statements are retried by default, unless lock retries are disabled. It is possible to implement more sophisticated lock retriers. See [source code](https://github.com/fatkodima/online_migrations/blob/master/lib/online_migrations/lock_retrier.rb) for the examples.
 
+### Command-specific lock retry configuration
+
+For migrations using `disable_ddl_transaction!`, you can implement command-specific lock retry behavior. This is useful when different DDL operations have different locking characteristics:
+
+- `add_index` with `algorithm: :concurrently` uses `ShareUpdateExclusiveLock` (less restrictive), so can use longer timeouts
+- `add_foreign_key` uses `AccessExclusiveLock` (blocks all access), so should use shorter timeouts to fail fast
+
+**Note**: Command-specific configuration only works for migrations with `disable_ddl_transaction!`. For migrations running within transactions (the default), the lock retrier wraps the entire transaction and doesn't have visibility into individual DDL commands.
+
+```ruby
+module OnlineMigrations
+  class CommandAwareLockRetrier < LockRetrier
+    # You can vary the number of attempts based on the command
+    def attempts(command = nil, arguments = [])
+      case command
+      when :add_index
+        # Concurrent index creation uses longer individual timeouts,
+        # so fewer attempts are needed to reach the same overall window
+        10
+      when :add_foreign_key
+        # Foreign keys use shorter timeouts to fail fast,
+        # so more attempts are needed to reach the same overall window
+        60
+      else
+        # Default attempts for other operations
+        30
+      end
+    end
+
+    def lock_timeout(attempt, command = nil, arguments = [])
+      case command
+      when :add_index
+        # Concurrent index creation is less restrictive, use longer timeout
+        30.seconds
+      when :add_foreign_key
+        # Foreign keys block all access, use shorter timeout to fail fast
+        5.seconds
+      else
+        # Default timeout for other operations
+        10.seconds
+      end
+    end
+
+    def delay(attempt, command = nil, arguments = [])
+      case command
+      when :add_index
+        # Longer delay for index operations since they take time anyway
+        3.seconds
+      when :add_foreign_key
+        # Shorter delay to retry faster for quick FK operations
+        1.second
+      else
+        # Default delay for other operations
+        2.seconds
+      end
+    end
+  end
+end
+
+config.lock_retrier = OnlineMigrations::CommandAwareLockRetrier.new
+```
+
+All three methods (`attempts`, `lock_timeout`, and `delay`) can receive command-specific parameters:
+- `command` - the migration method being called (e.g., `:add_index`, `:add_column`, `:add_foreign_key`), or `nil` for transaction-wrapped migrations
+- `arguments` - an array of arguments passed to the migration method
+
+Additionally, `lock_timeout` and `delay` receive:
+- `attempt` - the current retry attempt number (1-indexed)
+
+This allows you to fine-tune the retry strategy for different commands. For example, to maintain roughly the same total timeout window:
+- `add_index`: 10 attempts × (30s lock + 3s delay) = ~5.5 minute window
+- `add_foreign_key`: 60 attempts × (5s lock + 1s delay) = ~6 minute window
+
+#### Alternative: Configuration Hash Approach
+
+For simpler use cases, you can use a configuration hash instead of case statements:
+
+```ruby
+module OnlineMigrations
+  class ConfigurableLockRetrier < LockRetrier
+    COMMAND_CONFIGS = {
+      add_index: {
+        attempts: 10,
+        lock_timeout: 30.seconds,
+        delay: 3.seconds
+      },
+      add_foreign_key: {
+        attempts: 60,
+        lock_timeout: 5.seconds,
+        delay: 1.second
+      },
+      default: {
+        attempts: 30,
+        lock_timeout: 10.seconds,
+        delay: 2.seconds
+      }
+    }
+
+    def attempts(command = nil, arguments = [])
+      config_for(command)[:attempts]
+    end
+
+    def lock_timeout(attempt, command = nil, arguments = [])
+      config_for(command)[:lock_timeout]
+    end
+
+    def delay(attempt, command = nil, arguments = [])
+      config_for(command)[:delay]
+    end
+
+    private
+
+    def config_for(command)
+      COMMAND_CONFIGS[command] || COMMAND_CONFIGS[:default]
+    end
+  end
+end
+
+config.lock_retrier = OnlineMigrations::ConfigurableLockRetrier.new
+```
+
+This approach is more concise and easier to maintain when you have simple static configurations per command. The case statement approach (shown above) is better when you need conditional logic or want to use the `attempt` parameter dynamically.
+
 To temporarily disable lock retries while running migrations, set `DISABLE_LOCK_RETRIES` env variable. This is useful when you are deploying a hotfix and do not want to wait too long while the lock retrier safely tries to acquire the lock, but try to acquire the lock immediately with the default configured lock timeout value.
 
 To permanently disable lock retries, you can set `lock_retrier` to `nil`.

data/lib/online_migrations/background_schema_migrations/migration.rb

@@ -133,7 +133,7 @@ module OnlineMigrations
 
             with_statement_timeout(connection, statement_timeout) do
               if index_addition?
-                index = connection.indexes(table_name).find { |i| name.include?(i.name) }
+                index = connection.indexes(table_name).find { |i| name.match?(/\b#{i.name}\b/) }
                 if index
                   if index.valid?
                     return

data/lib/online_migrations/lock_retrier.rb

@@ -36,7 +36,7 @@ module OnlineMigrations
   #         TIMINGS.size
   #       end
   #
-  #       def lock_timeout(attempt)
+  #       def lock_timeout(attempt, command = nil, arguments = [])
   #         TIMINGS[attempt - 1][0]
   #       end
   #
@@ -48,21 +48,34 @@ module OnlineMigrations
   class LockRetrier
     # Returns the number of retrying attempts
     #
-    def attempts
+    # @param _command [Symbol, nil] the migration method being executed (e.g., :add_index, :add_column).
+    #   Will be nil when called from a transaction-wrapped migration (the default).
+    #   Only populated for migrations using `disable_ddl_transaction!`.
+    # @param _arguments [Array] the arguments passed to the migration method
+    #
+    def attempts(_command = nil, _arguments = [])
       raise NotImplementedError
     end
 
     # Returns database lock timeout value (in seconds) for specified attempt number
     #
     # @param _attempt [Integer] attempt number
+    # @param _command [Symbol, nil] the migration method being executed (e.g., :add_index, :add_column).
+    #   Will be nil when called from a transaction-wrapped migration (the default).
+    #   Only populated for migrations using `disable_ddl_transaction!`.
+    # @param _arguments [Array] the arguments passed to the migration method
     #
-    def lock_timeout(_attempt); end
+    def lock_timeout(_attempt, _command = nil, _arguments = []); end
 
     # Returns sleep time after unsuccessful lock attempt (in seconds)
     #
     # @param _attempt [Integer] attempt number
+    # @param _command [Symbol, nil] the migration method being executed (e.g., :add_index, :add_column).
+    #   Will be nil when called from a transaction-wrapped migration (the default).
+    #   Only populated for migrations using `disable_ddl_transaction!`.
+    # @param _arguments [Array] the arguments passed to the migration method
     #
-    def delay(_attempt)
+    def delay(_attempt, _command = nil, _arguments = [])
       raise NotImplementedError
     end
 
@@ -77,7 +90,7 @@ module OnlineMigrations
     #     add_column(:users, :name, :string)
     #   end
     #
-    def with_lock_retries(connection, &block)
+    def with_lock_retries(connection, command = nil, *arguments, &block)
       return yield if lock_retries_disabled?
 
       current_attempt = 0
@@ -85,15 +98,15 @@ module OnlineMigrations
       begin
         current_attempt += 1
 
-        current_lock_timeout = lock_timeout(current_attempt)
+        current_lock_timeout = lock_timeout(current_attempt, command, arguments)
         if current_lock_timeout
           with_lock_timeout(connection, current_lock_timeout.in_milliseconds, &block)
         else
           yield
         end
       rescue ActiveRecord::LockWaitTimeout, ActiveRecord::Deadlocked => e
-        if current_attempt <= attempts
-          current_delay = delay(current_attempt)
+        if current_attempt <= attempts(command, arguments)
+          current_delay = delay(current_attempt, command, arguments)
 
           problem = e.is_a?(ActiveRecord::Deadlocked) ? "Deadlock detected." : "Lock timeout."
           Utils.say("#{problem} Retrying in #{current_delay} seconds...")
@@ -130,13 +143,6 @@ module OnlineMigrations
   #   config.retrier = OnlineMigrations::ConstantLockRetrier.new(attempts: 5, delay: 2.seconds, lock_timeout: 0.05.seconds)
   #
   class ConstantLockRetrier < LockRetrier
-    # LockRetrier API implementation
-    #
-    # @return [Integer] Number of retrying attempts
-    # @see LockRetrier#attempts
-    #
-    attr_reader :attempts
-
     # Create a new ConstantLockRetrier instance
     #
     # @param attempts [Integer] Maximum number of attempts
@@ -150,12 +156,21 @@ module OnlineMigrations
       @lock_timeout = lock_timeout
     end
 
+    # LockRetrier API implementation
+    #
+    # @return [Integer] Number of retrying attempts
+    # @see LockRetrier#attempts
+    #
+    def attempts(_command = nil, _arguments = [])
+      @attempts
+    end
+
     # LockRetrier API implementation
     #
     # @return [Numeric] Database lock timeout value (in seconds)
     # @see LockRetrier#lock_timeout
     #
-    def lock_timeout(_attempt)
+    def lock_timeout(_attempt, _command = nil, _arguments = [])
       @lock_timeout
     end
 
@@ -164,7 +179,7 @@ module OnlineMigrations
     # @return [Numeric] Sleep time after unsuccessful lock attempt (in seconds)
     # @see LockRetrier#delay
     #
-    def delay(_attempt)
+    def delay(_attempt, _command = nil, _arguments = [])
       @delay
     end
   end
@@ -180,13 +195,6 @@ module OnlineMigrations
   #       base_delay: 0.01.seconds, max_delay: 1.minute, lock_timeout: 0.2.seconds)
   #
   class ExponentialLockRetrier < LockRetrier
-    # LockRetrier API implementation
-    #
-    # @return [Integer] Number of retrying attempts
-    # @see LockRetrier#attempts
-    #
-    attr_reader :attempts
-
     # Create a new ExponentialLockRetrier instance
     #
     # @param attempts [Integer] Maximum number of attempts
@@ -202,12 +210,21 @@ module OnlineMigrations
       @lock_timeout = lock_timeout
     end
 
+    # LockRetrier API implementation
+    #
+    # @return [Integer] Number of retrying attempts
+    # @see LockRetrier#attempts
+    #
+    def attempts(_command = nil, _arguments = [])
+      @attempts
+    end
+
     # LockRetrier API implementation
     #
     # @return [Numeric] Database lock timeout value (in seconds)
     # @see LockRetrier#lock_timeout
     #
-    def lock_timeout(_attempt)
+    def lock_timeout(_attempt, _command = nil, _arguments = [])
       @lock_timeout
     end
 
@@ -217,21 +234,21 @@ module OnlineMigrations
     # @see LockRetrier#delay
     # @see https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
     #
-    def delay(attempt)
+    def delay(attempt, _command = nil, _arguments = [])
       (rand * [@max_delay, @base_delay * (2**(attempt - 1))].min).ceil
     end
   end
 
   # @private
   class NullLockRetrier < LockRetrier
-    def attempts(*)
+    def attempts(_command = nil, _arguments = [])
       0
     end
 
     def lock_timeout(*)
     end
 
-    def delay(*)
+    def delay(_attempt, _command = nil, _arguments = [])
     end
 
     def with_lock_retries(_connection)

data/lib/online_migrations/migration.rb

@@ -23,9 +23,9 @@ module OnlineMigrations
         if in_transaction?
           super
         elsif method == :with_lock_retries
-          connection.with_lock_retries(*args, &block)
+          connection.with_lock_retries(method, *args, &block)
         else
-          connection.with_lock_retries { super }
+          connection.with_lock_retries(method, *args) { super }
         end
       end
     end

data/lib/online_migrations/migrator.rb

@@ -12,6 +12,11 @@ module OnlineMigrations
         end
 
       if use_transaction?(migration)
+        # Wrap the entire transaction with lock retries so that if the transaction
+        # fails to acquire any locks, the whole migration is retried.
+        # Note: at this point we don't have visibility into individual DDL commands,
+        # so command and arguments will be nil when lock_timeout is called.
+        # For command-specific retry behavior, migrations must use `disable_ddl_transaction!`
         migration.connection.with_lock_retries do
           super
         end

data/lib/online_migrations/schema_statements.rb

@@ -801,7 +801,7 @@ module OnlineMigrations
     #
     # @see https://edgeapi.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-add_check_constraint
     #
-    def add_check_constraint(table_name, expression, **options)
+    def add_check_constraint(table_name, expression, if_not_exists: false, **options)
       if check_constraint_exists?(table_name, expression: expression, **options)
         Utils.say(<<~MSG.squish)
           Check constraint was not created because it already exists (this may be due to an aborted migration or similar).
@@ -816,7 +816,7 @@ module OnlineMigrations
     #
     # @see https://edgeapi.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html#method-i-remove_check_constraint
     #
-    def remove_check_constraint(table_name, expression = nil, **options)
+    def remove_check_constraint(table_name, expression = nil, if_exists: false, **options)
       if check_constraint_exists?(table_name, expression: expression, **options)
         super
       else
@@ -862,11 +862,11 @@ module OnlineMigrations
     # Executes the block with a retry mechanism that alters the `lock_timeout`
     # and sleep time between attempts.
     #
-    def with_lock_retries(&block)
+    def with_lock_retries(command = nil, *args, &block)
       __ensure_not_in_transaction!
 
       retrier = OnlineMigrations.config.lock_retrier
-      retrier.with_lock_retries(self, &block)
+      retrier.with_lock_retries(self, command, *args, &block)
     end
 
     private

data/lib/online_migrations/version.rb

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

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: online_migrations
 version: !ruby/object:Gem::Version
-  version: 0.29.2
+  version: 0.30.0
 platform: ruby
 authors:
 - fatkodima
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-07-21 00:00:00.000000000 Z
+date: 2025-10-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -24,7 +23,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.1'
-description:
 email:
 - fatkodima123@gmail.com
 executables: []
@@ -101,7 +99,6 @@ metadata:
   homepage_uri: https://github.com/fatkodima/online_migrations
   source_code_uri: https://github.com/fatkodima/online_migrations
   changelog_uri: https://github.com/fatkodima/online_migrations/blob/master/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -116,8 +113,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Catch unsafe PostgreSQL migrations in development and run them easier in
   production