active-record-deadlock-handler 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5eb27e3dc7a6c988d2878216e63b5de755cc42233e9630a13a5817d999ad10bb
+  data.tar.gz: 7b6a3266f459b1ceb434071c782d54f17262c270781ffb3b562766d361988662
+SHA512:
+  metadata.gz: 33a0a288d9bc1f644c07bf798b4939ecc2871a5b4458c8450364301e1e47b0d9aad9174add38141296c32adeabef7fa81207beeb0bea8f3aa7d2b7d477332ec8
+  data.tar.gz: 24e7b8b19e9a7956c11cb57f6decf690290b6ce24c43826e79dacc359c84ab0a26943919c7de4be7616934ac2c605765f4e21d858d25b1f8c687aada64df9b8c

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 afshmini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,111 @@
+# ActiveRecordDeadlockHandler
+
+A Ruby gem that automatically retries ActiveRecord transactions on deadlock errors with exponential backoff and jitter.
+
+Handles:
+- `ActiveRecord::Deadlocked`
+- `PG::TRDeadlockDetected`
+- Any database deadlock that raises through ActiveRecord's exception hierarchy
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "active_record_deadlock_handler"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### Rails (automatic)
+
+The gem hooks into Rails via a Railtie and automatically patches `ActiveRecord::Base.transaction`. No code changes required — all transactions are retried on deadlock by default.
+
+Create an initializer to customize behavior:
+
+```ruby
+# config/initializers/active_record_deadlock_handler.rb
+ActiveRecordDeadlockHandler.configure do |config|
+  config.max_retries   = 3      # number of retries after the first attempt
+  config.base_delay    = 0.1    # seconds before first retry
+  config.max_delay     = 5.0    # upper cap on delay
+  config.jitter_factor = 0.25   # randomness fraction to avoid thundering herd
+  config.log_level     = :warn  # :debug, :info, :warn, :error
+  config.auto_patch    = true   # set false to disable automatic patching
+  config.reraise_after_exhaustion = true  # re-raise after all retries fail
+end
+```
+
+### Manual wrapper (without Rails or auto-patch)
+
+```ruby
+ActiveRecordDeadlockHandler.with_retry do
+  User.find_or_create_by!(email: params[:email])
+end
+```
+
+### Callbacks (e.g. error tracking)
+
+```ruby
+ActiveRecordDeadlockHandler.on_deadlock do |exception:, attempt:, **|
+  Sentry.capture_exception(exception, extra: { retry_attempt: attempt })
+end
+```
+
+Multiple callbacks can be registered and are all invoked on each deadlock detection.
+
+## Configuration
+
+| Option | Default | Description |
+|---|---|---|
+| `max_retries` | `3` | Number of retries after the initial attempt |
+| `base_delay` | `0.1` | Base sleep duration in seconds before first retry |
+| `max_delay` | `5.0` | Maximum sleep duration in seconds |
+| `jitter_factor` | `0.25` | Random jitter as a fraction of the computed delay (0–1) |
+| `backoff_multiplier` | `2.0` | Exponential growth factor per retry |
+| `logger` | `nil` | Custom logger; falls back to `ActiveRecord::Base.logger` |
+| `log_level` | `:warn` | Log level for deadlock messages |
+| `auto_patch` | `true` | Automatically patch `DatabaseStatements#transaction` |
+| `reraise_after_exhaustion` | `true` | Re-raise the error after all retries are exhausted |
+
+### Backoff formula
+
+```
+delay = min(base_delay * backoff_multiplier^(attempt - 1), max_delay)
+      + delay * jitter_factor * rand
+```
+
+Example with defaults — sleep durations before each retry:
+
+| Retry | Base delay | With jitter (approx) |
+|---|---|---|
+| 1st | 0.1s | 0.10–0.125s |
+| 2nd | 0.2s | 0.20–0.250s |
+| 3rd | 0.4s | 0.40–0.500s |
+
+## How it works
+
+The gem `prepend`s a module into `ActiveRecord::ConnectionAdapters::DatabaseStatements`, wrapping the `#transaction` method with retry logic. Only the **outermost** transaction is wrapped — nested transactions (savepoints) pass through untouched, because a deadlock always invalidates the entire outer transaction. Retrying a savepoint inside a dead transaction would corrupt state.
+
+```
+User.transaction do           # ← retry loop installed here
+  account.transaction do      # ← savepoint, passes through
+    account.update!(balance: 0)
+  end
+end
+# If deadlock fires: entire outer block is re-executed
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Contributing
+
+Bug reports and pull requests are welcome at https://github.com/afshmini/deadlock-handler.

data/lib/active_record_deadlock_handler/backoff.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ActiveRecordDeadlockHandler
+  module Backoff
+    # Computes sleep duration for a given retry attempt using exponential backoff with jitter.
+    #
+    # Formula: min(base_delay * multiplier^(attempt-1), max_delay) + jitter
+    # Jitter is a random fraction of the computed exponential delay to reduce thundering herd.
+    #
+    # @param attempt [Integer] 1-indexed retry attempt number
+    # @param config [Configuration]
+    # @return [Float] seconds to sleep
+    def self.compute(attempt:, config:)
+      exponential = [config.base_delay * (config.backoff_multiplier**(attempt - 1)), config.max_delay].min
+      jitter = exponential * config.jitter_factor * rand
+      exponential + jitter
+    end
+  end
+end

data/lib/active_record_deadlock_handler/callbacks.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ActiveRecordDeadlockHandler
+  module Callbacks
+    LOCK = Mutex.new
+    private_constant :LOCK
+
+    @handlers = []
+
+    class << self
+      # Register a callback to be invoked on each deadlock detection.
+      #
+      # @yieldparam exception [ActiveRecord::Deadlocked] the deadlock error
+      # @yieldparam attempt [Integer] which retry attempt triggered this (1-indexed)
+      # @yieldparam config [Configuration]
+      def register(&block)
+        raise ArgumentError, "block required" unless block
+
+        LOCK.synchronize { @handlers << block }
+      end
+
+      def clear
+        LOCK.synchronize { @handlers.clear }
+      end
+
+      # Invokes all registered callbacks with deadlock context.
+      # Runs outside the lock so slow callbacks don't block registration.
+      def run(exception:, attempt:, config:)
+        handlers = LOCK.synchronize { @handlers.dup }
+        handlers.each do |handler|
+          handler.call(exception: exception, attempt: attempt, config: config)
+        rescue StandardError => e
+          warn "[ActiveRecordDeadlockHandler] Callback raised an error: #{e.class}: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/active_record_deadlock_handler/configuration.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ActiveRecordDeadlockHandler
+  class Configuration
+    DEFAULTS = {
+      max_retries:             3,
+      base_delay:              0.1,
+      max_delay:               5.0,
+      jitter_factor:           0.25,
+      backoff_multiplier:      2.0,
+      logger:                  nil,
+      log_level:               :warn,
+      auto_patch:              true,
+      reraise_after_exhaustion: true
+    }.freeze
+
+    attr_accessor(*DEFAULTS.keys)
+
+    def initialize
+      DEFAULTS.each { |k, v| public_send(:"#{k}=", v) }
+    end
+
+    def validate!
+      raise ArgumentError, "max_retries must be >= 0" unless max_retries >= 0
+      raise ArgumentError, "base_delay must be > 0"   unless base_delay > 0
+      raise ArgumentError, "max_delay must be >= base_delay" unless max_delay >= base_delay
+      raise ArgumentError, "jitter_factor must be between 0 and 1" unless (0.0..1.0).cover?(jitter_factor)
+      raise ArgumentError, "backoff_multiplier must be >= 1" unless backoff_multiplier >= 1
+      raise ArgumentError, "log_level must be a symbol" unless log_level.is_a?(Symbol)
+    end
+  end
+end

data/lib/active_record_deadlock_handler/connection_adapter_patch.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ActiveRecordDeadlockHandler
+  # Prepended into ActiveRecord::ConnectionAdapters::DatabaseStatements to wrap
+  # every top-level transaction with deadlock retry logic.
+  module ConnectionAdapterPatch
+    # Wraps transaction with retry logic only at the outermost transaction level.
+    #
+    # Nested transactions (savepoints) are NOT wrapped individually — when a deadlock
+    # kills a transaction, the entire outer transaction is invalidated. Retrying only
+    # a savepoint inside a dead transaction would corrupt state. The outer retry loop
+    # handles the full re-execution.
+    def transaction(**options, &block)
+      # open_transactions > 0 means we're already inside a real transaction.
+      # Let it pass through; the outermost call's retry loop covers everything.
+      return super(**options, &block) if open_transactions > 0
+
+      RetryExecutor.run(config: ActiveRecordDeadlockHandler.configuration) do
+        super(**options, &block)
+      end
+    end
+  end
+end

data/lib/active_record_deadlock_handler/logging.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ActiveRecordDeadlockHandler
+  module Logging
+    def self.log(message, exception:, attempt:, config:)
+      logger = resolve_logger(config)
+      return unless logger
+
+      error_summary = exception.message.lines.first&.strip
+      full_message  = "[ActiveRecordDeadlockHandler] #{message} " \
+                      "(attempt=#{attempt}, error=#{exception.class}: #{error_summary})"
+
+      logger.public_send(config.log_level, full_message)
+    end
+
+    def self.resolve_logger(config)
+      config.logger || (defined?(ActiveRecord::Base) && ActiveRecord::Base.logger)
+    end
+    private_class_method :resolve_logger
+  end
+end

data/lib/active_record_deadlock_handler/railtie.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module ActiveRecordDeadlockHandler
+  class Railtie < Rails::Railtie
+    initializer "active_record_deadlock_handler.configure_active_record" do
+      # Wait until ActiveRecord is fully loaded before patching.
+      ActiveSupport.on_load(:active_record) do
+        if ActiveRecordDeadlockHandler.configuration.auto_patch
+          ActiveRecord::ConnectionAdapters::DatabaseStatements.prepend(
+            ActiveRecordDeadlockHandler::ConnectionAdapterPatch
+          )
+        end
+      end
+    end
+  end
+end

data/lib/active_record_deadlock_handler/retry_executor.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module ActiveRecordDeadlockHandler
+  module RetryExecutor
+    RETRYABLE_ERRORS = [ActiveRecord::Deadlocked].freeze
+
+    # Executes the given block, retrying on deadlock errors with exponential backoff.
+    #
+    # Thread-safe: all state (attempt counter, delay) is local to the call stack.
+    #
+    # @param config [Configuration]
+    # @yieldreturn [Object] the return value of the block on success
+    # @raise [ActiveRecord::Deadlocked] if max_retries is exhausted and reraise_after_exhaustion is true
+    def self.run(config: ActiveRecordDeadlockHandler.configuration, &block)
+      attempt = 0
+
+      begin
+        attempt += 1
+        yield
+      rescue *RETRYABLE_ERRORS => e
+        Callbacks.run(exception: e, attempt: attempt, config: config)
+
+        if attempt <= config.max_retries
+          Logging.log("Deadlock detected, retrying...", exception: e, attempt: attempt, config: config)
+          delay = Backoff.compute(attempt: attempt, config: config)
+          sleep(delay)
+          retry
+        else
+          Logging.log(
+            "Deadlock detected, max retries (#{config.max_retries}) exhausted.",
+            exception: e,
+            attempt: attempt,
+            config: config
+          )
+          raise if config.reraise_after_exhaustion
+        end
+      end
+    end
+  end
+end

data/lib/active_record_deadlock_handler/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ActiveRecordDeadlockHandler
+  VERSION = "0.1.0"
+end

data/lib/active_record_deadlock_handler.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "active_record"
+require_relative "active_record_deadlock_handler/version"
+require_relative "active_record_deadlock_handler/configuration"
+require_relative "active_record_deadlock_handler/backoff"
+require_relative "active_record_deadlock_handler/callbacks"
+require_relative "active_record_deadlock_handler/logging"
+require_relative "active_record_deadlock_handler/retry_executor"
+require_relative "active_record_deadlock_handler/connection_adapter_patch"
+require_relative "active_record_deadlock_handler/railtie" if defined?(Rails::Railtie)
+
+module ActiveRecordDeadlockHandler
+  class Error < StandardError; end
+
+  @configuration       = Configuration.new
+  @configuration_mutex = Mutex.new
+
+  class << self
+    # Configure the gem. Should be called once from an initializer.
+    #
+    # @example
+    #   ActiveRecordDeadlockHandler.configure do |config|
+    #     config.max_retries   = 5
+    #     config.base_delay    = 0.05
+    #     config.log_level     = :warn
+    #   end
+    def configure
+      @configuration_mutex.synchronize do
+        yield @configuration
+        @configuration.validate!
+      end
+    end
+
+    def configuration
+      @configuration
+    end
+
+    # Register a callback invoked on every deadlock detection.
+    #
+    # @example
+    #   ActiveRecordDeadlockHandler.on_deadlock do |exception:, attempt:, **|
+    #     Sentry.capture_exception(exception, extra: { retry_attempt: attempt })
+    #   end
+    def on_deadlock(&block)
+      Callbacks.register(&block)
+    end
+
+    # Opt-in wrapper for use without Rails or when auto_patch is disabled.
+    #
+    # @example
+    #   ActiveRecordDeadlockHandler.with_retry { User.find_or_create_by!(email: email) }
+    def with_retry(config: configuration, &block)
+      RetryExecutor.run(config: config, &block)
+    end
+
+    # Resets configuration to defaults. Primarily useful in tests.
+    def reset_configuration!
+      @configuration_mutex.synchronize do
+        @configuration = Configuration.new
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: active-record-deadlock-handler
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- afshmini
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-03-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+description: |
+  Transparently retries ActiveRecord transactions on ActiveRecord::Deadlocked errors
+  (including PG::TRDeadlockDetected) with configurable exponential backoff and jitter.
+  Provides hooks for custom callbacks, structured logging, and Rails initializer support.
+email:
+- afshmini@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/active_record_deadlock_handler.rb
+- lib/active_record_deadlock_handler/backoff.rb
+- lib/active_record_deadlock_handler/callbacks.rb
+- lib/active_record_deadlock_handler/configuration.rb
+- lib/active_record_deadlock_handler/connection_adapter_patch.rb
+- lib/active_record_deadlock_handler/logging.rb
+- lib/active_record_deadlock_handler/railtie.rb
+- lib/active_record_deadlock_handler/retry_executor.rb
+- lib/active_record_deadlock_handler/version.rb
+homepage: https://github.com/afshmini/active-record-deadlock-handler
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.20
+signing_key: 
+specification_version: 4
+summary: Automatic deadlock retry with exponential backoff for ActiveRecord
+test_files: []