with_advisory_lock 7.0.2 → 7.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a82d92e5b44f2cf65a9af5ac2d00baacab6d47b3b47be9fc2db82bd5677e4c7
-  data.tar.gz: 4a9b77cd24fad228812b9eff2f65079e6be7b95130a8e8d628d71525045ef902
+  metadata.gz: b73961f538d06e085eda202c9acac95b86e248dfc368cefa5267947ed8f988a2
+  data.tar.gz: c6b025af1bc1f16ea12b104da20fcfbd6586347eb23b72de47eafd09b8c4e9f0
 SHA512:
-  metadata.gz: 77996aa445351903666828d916b8bd02ad4357496c2240ac847f937f7b3adff7af83993b10d6af8bcdb33825992dc6391cc211f97428c36b2bd102e65e5c26b2
-  data.tar.gz: 94ec70a26f7c336f9dba44a384bc16d9d680d7495e43cb0c9fc22fee2380317f5d5263f36d3998837ca21f3e05424c7fc0fdb37ed75daf441ce534f0b4d67339
+  metadata.gz: b11f600e41ed75fe00f7314d2cc090547e941ef4a9562c98e4573e892a15d3429b6609a1475f170a20f2d5197aba6dac153596e58181d6092db0d05c0adcc4fc
+  data.tar.gz: 24e45f293e0d2d653cc58e772b11f70d8d9691aac66a4d4be64cc81d67f322e6e00520e83d23613c0a176b74ca7137d60c5de8036b837a1b67b39eab3cad221e

data/.github/workflows/ci.yml

@@ -36,16 +36,38 @@ jobs:
           MYSQL_PASSWORD: with_advisory_pass
           MYSQL_DATABASE: with_advisory_lock_test
           MYSQL_ROOT_HOST: '%'
+      mariadb:
+        image: mariadb:12
+        ports:
+          - 3306
+        env:
+          MARIADB_ROOT_PASSWORD: root
+          MARIADB_DATABASE: with_advisory_lock_trilogy_test
+          MARIADB_USER: with_advisory
+          MARIADB_PASSWORD: with_advisory_pass
+          MARIADB_ROOT_HOST: '%'
+        options: >-
+          --health-cmd "healthcheck.sh --su-mysql --connect --innodb_initialized"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
     strategy:
       fail-fast: false
       matrix:
         ruby:
           - '3.3'
           - '3.4'
+          - '4.0'
           - 'truffleruby'
         rails:
           - 7.2
           - "8.0"
+          - "8.1"
+          - "edge"
+        exclude:
+          # TruffleRuby doesn't support Rails edge yet
+          - ruby: 'truffleruby'
+            rails: "edge"
     env:
       ACTIVERECORD_VERSION: ${{ matrix.rails }}
       RAILS_ENV: test
@@ -60,10 +82,14 @@ jobs:
           bundler-cache: true
           rubygems: latest
 
+
       - name: Setup test databases
+        timeout-minutes: 5
         env:
           DATABASE_URL_PG: postgres://with_advisory:with_advisory_pass@localhost:${{ job.services.postgres.ports[5432] }}/with_advisory_lock_test
           DATABASE_URL_MYSQL: mysql2://with_advisory:with_advisory_pass@127.0.0.1:${{ job.services.mysql.ports[3306] }}/with_advisory_lock_test
+          # Trilogy doesn't support TruffleRuby
+          DATABASE_URL_TRILOGY: ${{ matrix.ruby != 'truffleruby' && format('trilogy://with_advisory:with_advisory_pass@127.0.0.1:{0}/with_advisory_lock_trilogy_test', job.services.mariadb.ports[3306]) || '' }}
         run: |
           cd test/dummy
           bundle exec rake db:test:prepare
@@ -72,5 +98,7 @@ jobs:
         env:
           DATABASE_URL_PG: postgres://with_advisory:with_advisory_pass@localhost:${{ job.services.postgres.ports[5432] }}/with_advisory_lock_test
           DATABASE_URL_MYSQL: mysql2://with_advisory:with_advisory_pass@127.0.0.1:${{ job.services.mysql.ports[3306] }}/with_advisory_lock_test
+          # Trilogy doesn't support TruffleRuby
+          DATABASE_URL_TRILOGY: ${{ matrix.ruby != 'truffleruby' && format('trilogy://with_advisory:with_advisory_pass@127.0.0.1:{0}/with_advisory_lock_trilogy_test', job.services.mariadb.ports[3306]) || '' }}
           WITH_ADVISORY_LOCK_PREFIX: ${{ github.run_id }}
         run: bin/rails test

data/.release-please-manifest.json

@@ -1 +1 @@
-{".":"7.0.2"}
+{".":"7.6.0"}

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 ## Changelog
 
+## [7.6.0](https://github.com/ClosureTree/with_advisory_lock/compare/with_advisory_lock/v7.5.0...with_advisory_lock/v7.6.0) (2026-08-05)
+
+
+### Features
+
+* honor timeout_seconds with blocking: true on PostgreSQL ([88abf06](https://github.com/ClosureTree/with_advisory_lock/commit/88abf0689b2ac7045c1617fe5fcac0bedff61adf)), closes [#147](https://github.com/ClosureTree/with_advisory_lock/issues/147)
+
+
+### Bug Fixes
+
+* Remove ruby-version files ([#145](https://github.com/ClosureTree/with_advisory_lock/issues/145)) ([681fd66](https://github.com/ClosureTree/with_advisory_lock/commit/681fd66f1d45800897f2d77ac8905474910a90ff))
+* scope advisory lock stack per connection ([8c39439](https://github.com/ClosureTree/with_advisory_lock/commit/8c394392872f0d9d6ab6b83d1185eeb291de2409))
+
+## [7.5.0](https://github.com/ClosureTree/with_advisory_lock/compare/with_advisory_lock/v7.0.2...with_advisory_lock/v7.5.0) (2026-01-21)
+
+
+### Features
+
+* add blocking advisory locks with deadlock detection for PostgreSQL ([#140](https://github.com/ClosureTree/with_advisory_lock/issues/140)) ([f7f9aff](https://github.com/ClosureTree/with_advisory_lock/commit/f7f9aff545381107a632a25511e8fc08654a28b6))
+* Add Trilogy adapter support with MariaDB 12.0+ ([#134](https://github.com/ClosureTree/with_advisory_lock/issues/134)) ([b7764cd](https://github.com/ClosureTree/with_advisory_lock/commit/b7764cd9432b25b37c6da9160f980da29a5cdaa6))
+* bump version for new features ([9a8c4be](https://github.com/ClosureTree/with_advisory_lock/commit/9a8c4be5cf51147e60df7e5733360e3dfd8d009e))
+
+
+### Bug Fixes
+
+* Use monotonic clock so postgres timeouts are unaffected by system clock changes ([#141](https://github.com/ClosureTree/with_advisory_lock/issues/141)) ([929e010](https://github.com/ClosureTree/with_advisory_lock/commit/929e0103e5ffc4c66f9088942441f764de1bc650))
+
 ## [7.0.2](https://github.com/ClosureTree/with_advisory_lock/compare/with_advisory_lock/v7.0.1...with_advisory_lock/v7.0.2) (2025-09-20)
 
 
@@ -58,7 +85,7 @@
 
 ### Features
 
-* use current connnection instead of the one in ActiveRecord::Base ([#90](https://github.com/ClosureTree/with_advisory_lock/issues/90)) ([c28a172](https://github.com/ClosureTree/with_advisory_lock/commit/c28a172a5a64594448b6090501fc0b8cbace06f6))
+* use current connection instead of the one in ActiveRecord::Base ([#90](https://github.com/ClosureTree/with_advisory_lock/issues/90)) ([c28a172](https://github.com/ClosureTree/with_advisory_lock/commit/c28a172a5a64594448b6090501fc0b8cbace06f6))
 
 
 ### Bug Fixes

data/Gemfile

@@ -11,12 +11,17 @@ gem 'benchmark'
 gem 'logger'
 gem 'ostruct'
 
-activerecord_version = ENV.fetch('ACTIVERECORD_VERSION', '7.2')
-
-gem 'activerecord', "~> #{activerecord_version}.0"
+activerecord_version = ENV.fetch('ACTIVERECORD_VERSION', '8.1')
+
+if activerecord_version == 'edge'
+  gem 'activerecord', github: 'rails/rails', branch: 'main'
+  gem 'railties', github: 'rails/rails', branch: 'main'
+else
+  gem 'activerecord', "~> #{activerecord_version}.0"
+  gem 'railties'
+end
 
 gem 'dotenv'
-gem 'railties'
 
 platforms :ruby do
   gem 'mysql2'

data/README.md

@@ -48,11 +48,11 @@ will be yielded to. If the lock is currently being held, the block will not be
 called.
 
 > **Note**
-> 
+>
 > If a non-nil value is provided for `timeout_seconds`, the block will
 *not* be invoked if the lock cannot be acquired within that time-frame. In this case, `with_advisory_lock` will return `false`, while `with_advisory_lock!` will raise a `WithAdvisoryLock::FailedToAcquireLock` error.
 
-For backwards compatability, the timeout value can be specified directly as the
+For backwards compatibility, the timeout value can be specified directly as the
 second parameter.
 
 ### Shared locks
@@ -72,6 +72,54 @@ to `true`.
 Note: transaction-level locks will not be reflected by `.current_advisory_lock`
 when the block has returned.
 
+### Blocking locks (PostgreSQL only)
+
+By default, PostgreSQL advisory locks use a polling strategy with Ruby-level
+retries and sleeps. Setting `blocking: true` switches to database-level blocking
+locks that enable PostgreSQL's deadlock detection:
+
+```ruby
+User.with_advisory_lock("lock_name", blocking: true, transaction: true) do
+  # PostgreSQL will detect circular lock waits and raise an error
+  # instead of sleeping forever
+end
+```
+
+**Benefits:**
+- **Deadlock detection**: PostgreSQL detects circular waits and raises `PG::TRDeadlockDetected` after ~1 second (configurable via `deadlock_timeout`)
+- **No polling overhead**: The database handles the wait queue instead of Ruby sleep/retry loops
+- **Clean failure**: Returns `false` on deadlock instead of infinite retries
+
+**When to use:**
+- When acquiring multiple locks in your application (risk of deadlock)
+- When you need PostgreSQL to detect and break circular lock dependencies
+- When you want to avoid Ruby-level polling overhead
+
+**Combining with a timeout:** `blocking: true` together with `timeout_seconds`
+bounds the database-level wait using a transaction-scoped
+`SET LOCAL lock_timeout`, returning `false` if the lock cannot be acquired in
+time. The setting never leaks to the session, and a timeout inside an enclosing
+transaction rolls back to a savepoint instead of aborting your transaction.
+A `timeout_seconds` of `0` degrades to the non-blocking try path.
+
+```ruby
+User.with_advisory_lock("lock_name", blocking: true, timeout_seconds: 5) do
+  # waits up to 5 seconds at the database level, no Ruby polling
+end
+```
+
+**Note:** MySQL ignores this option since `GET_LOCK` already provides native
+timeout and deadlock detection via the MDL subsystem.
+
+### Connection poolers (PgBouncer)
+
+Session-level advisory locks bind to the PostgreSQL backend connection, so they
+are incompatible with PgBouncer in *transaction pooling* mode: statements
+outside a transaction may run on different backends, stranding or leaking
+locks. Under transaction pooling, use `transaction: true` locks, which stay
+pinned to one backend for the duration of the transaction. Session pooling and
+direct connections are unaffected.
+
 ### Return values
 
 The return value of `with_advisory_lock_result` is a `WithAdvisoryLock::Result`
@@ -84,7 +132,7 @@ block, if the lock was able to be acquired and the block yielded, or `false`, if
 you provided a timeout_seconds value and the lock was not able to be acquired in
 time.
 
-`with_advisory_lock!` is similar to `with_advisory_lock`, but raises a `WithAdvisoryLock::FailedToAcquireLock` error if the lock was not able to be acquired in time. 
+`with_advisory_lock!` is similar to `with_advisory_lock`, but raises a `WithAdvisoryLock::FailedToAcquireLock` error if the lock was not able to be acquired in time.
 
 ### Testing for the current lock status
 
@@ -147,6 +195,16 @@ concurrent access to **any instance of a model**. Their coarseness means they
 aren't going to be commonly applicable, and they can be a source of
 [deadlocks](http://en.wikipedia.org/wiki/Deadlock).
 
+## Running Tests
+
+To setup the project and run the whole test suite:
+
+1. Have Docker running
+2. `echo -e "DB_USER=with_advisory\nDB_PASSWORD=with_advisory_pass\nDB_NAME=with_advisory_lock_test\nDATABASE_URL_PG=postgres://\$DB_USER:\$DB_PASSWORD@localhost:5433/\$DB_NAME\nDATABASE_URL_MYSQL=mysql2://\$DB_USER:\$DB_PASSWORD@127.0.0.1:3366/\$DB_NAME" > .env`
+3. `make`
+
+Alternatively to `make`, run `bin/rails test` to skip database and dependency setup.
+
 ## FAQ
 
 ### Transactions and Advisory Locks
@@ -158,4 +216,3 @@ You will want to wrap your block within a transaction to ensure consistency.
 ### Is clustered MySQL supported?
 
 [No.](https://github.com/ClosureTree/with_advisory_lock/issues/16)
-

data/bin/setup_test_db

@@ -3,6 +3,8 @@
 
 require 'bundler/setup'
 require 'active_record'
+require 'dotenv'
+Dotenv.load
 
 # Setup PostgreSQL database
 puts 'Setting up PostgreSQL test database...'
@@ -10,9 +12,9 @@ ActiveRecord::Base.establish_connection(
   adapter: 'postgresql',
   host: 'localhost',
   port: 5433,
-  database: 'with_advisory_lock_test',
-  username: 'with_advisory',
-  password: 'with_advisory_pass'
+  database: ENV['DB_NAME'],
+  username: ENV['DB_USER'],
+  password: ENV['DB_PASSWORD']
 )
 
 ActiveRecord::Schema.define(version: 1) do
@@ -36,9 +38,9 @@ ActiveRecord::Base.establish_connection(
   adapter: 'mysql2',
   host: '127.0.0.1',
   port: 3366,
-  database: 'with_advisory_lock_test',
-  username: 'with_advisory',
-  password: 'with_advisory_pass'
+  database: ENV['DB_NAME'],
+  username: ENV['DB_USER'],
+  password: ENV['DB_PASSWORD']
 )
 
 ActiveRecord::Schema.define(version: 1) do

data/docker-compose.yml

@@ -17,3 +17,13 @@ services:
       MYSQL_ROOT_HOST: '%'
     ports:
       - "3366:3306"
+  mariadb:
+    image: mariadb:12
+    environment:
+      MARIADB_USER: with_advisory
+      MARIADB_PASSWORD: with_advisory_pass
+      MARIADB_DATABASE: with_advisory_lock_trilogy_test
+      MARIADB_RANDOM_ROOT_PASSWORD: "yes"
+      MARIADB_ROOT_HOST: '%'
+    ports:
+      - "3368:3306"

data/lib/with_advisory_lock/concern.rb

@@ -24,22 +24,22 @@ module WithAdvisoryLock
         end
       end
 
-      def advisory_lock_exists?(lock_name)
+      def advisory_lock_exists?(lock_name, shared: false)
         with_connection do |conn|
           lock_str = "#{ENV.fetch(CoreAdvisory::LOCK_PREFIX_ENV, nil)}#{lock_name}"
-          lock_stack_item = LockStackItem.new(lock_str, false)
+          lock_stack_item = LockStackItem.new(lock_str, shared)
 
           if conn.advisory_lock_stack.include?(lock_stack_item)
             true
           else
-            # For PostgreSQL, try non-blocking query first to avoid race conditions
+            # Prefer the adapter's non-blocking existence check
             if conn.respond_to?(:advisory_lock_exists_for?)
-              query_result = conn.advisory_lock_exists_for?(lock_name)
+              query_result = conn.advisory_lock_exists_for?(lock_name, shared: shared)
               return query_result unless query_result.nil?
             end
 
             # Fall back to the original implementation
-            result = conn.with_advisory_lock_if_needed(lock_name, { timeout_seconds: 0 })
+            result = conn.with_advisory_lock_if_needed(lock_name, { timeout_seconds: 0, shared: shared })
             !result.lock_was_acquired?
           end
         end

data/lib/with_advisory_lock/core_advisory.rb

@@ -8,14 +8,14 @@ module WithAdvisoryLock
 
     LOCK_PREFIX_ENV = 'WITH_ADVISORY_LOCK_PREFIX'
 
-    # Thread-local lock stack management
+    # Per-connection lock stack management
     def advisory_lock_stack
-      Thread.current[:with_advisory_lock_stack] ||= []
+      @advisory_lock_stack ||= []
     end
 
     def with_advisory_lock_if_needed(lock_name, options = {}, &block)
       options = { timeout_seconds: options } unless options.respond_to?(:fetch)
-      options.assert_valid_keys :timeout_seconds, :shared, :transaction, :disable_query_cache
+      options.assert_valid_keys :timeout_seconds, :shared, :transaction, :disable_query_cache, :blocking
 
       # Validate transaction-level locks are used within a transaction
       if options.fetch(:transaction, false) && !transaction_open?
@@ -56,12 +56,16 @@ module WithAdvisoryLock
       timeout_seconds = options.fetch(:timeout_seconds, nil)
       shared = options.fetch(:shared, false)
       transaction = options.fetch(:transaction, false)
+      blocking = options.fetch(:blocking, false)
+      # An explicit zero timeout means try-once, so blocking degrades to the try path
+      blocking = false if timeout_seconds&.zero?
 
       lock_keys = lock_keys_for(lock_name)
 
       # MySQL supports database-level timeout in GET_LOCK, skip Ruby-level polling
-      if supports_database_timeout? || timeout_seconds&.zero?
-        yield_with_lock(lock_keys, lock_name, lock_str, lock_stack_item, shared, transaction, timeout_seconds, &)
+      # PostgreSQL blocking locks also skip polling and let the database handle waiting
+      if supports_database_timeout? || timeout_seconds&.zero? || blocking
+        yield_with_lock(lock_keys, lock_name, lock_str, lock_stack_item, shared, transaction, timeout_seconds, blocking, &)
       else
         yield_with_lock_and_timeout(lock_keys, lock_name, lock_str, lock_stack_item, shared, transaction,
                                     timeout_seconds, &)
@@ -70,9 +74,9 @@ module WithAdvisoryLock
 
     def yield_with_lock_and_timeout(lock_keys, lock_name, lock_str, lock_stack_item, shared, transaction,
                                     timeout_seconds, &)
-      give_up_at = timeout_seconds ? Time.now + timeout_seconds : nil
-      while give_up_at.nil? || Time.now < give_up_at
-        r = yield_with_lock(lock_keys, lock_name, lock_str, lock_stack_item, shared, transaction, 0, &)
+      give_up_at = timeout_seconds ? Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout_seconds : nil
+      while give_up_at.nil? || Process.clock_gettime(Process::CLOCK_MONOTONIC) < give_up_at
+        r = yield_with_lock(lock_keys, lock_name, lock_str, lock_stack_item, shared, transaction, 0, false, &)
         return r if r.lock_was_acquired?
 
         # Randomizing sleep time may help reduce contention.
@@ -81,9 +85,9 @@ module WithAdvisoryLock
       Result.new(lock_was_acquired: false)
     end
 
-    def yield_with_lock(lock_keys, lock_name, _lock_str, lock_stack_item, shared, transaction, timeout_seconds = nil)
+    def yield_with_lock(lock_keys, lock_name, _lock_str, lock_stack_item, shared, transaction, timeout_seconds = nil, blocking = false)
       if try_advisory_lock(lock_keys, lock_name: lock_name, shared: shared, transaction: transaction,
-                                      timeout_seconds: timeout_seconds)
+                                      timeout_seconds: timeout_seconds, blocking: blocking)
         begin
           advisory_lock_stack.push(lock_stack_item)
           result = block_given? ? yield : nil

data/lib/with_advisory_lock/mysql_advisory.rb

@@ -6,18 +6,23 @@ module WithAdvisoryLock
   module MySQLAdvisory
     extend ActiveSupport::Concern
 
-    LOCK_PREFIX_ENV = 'WITH_ADVISORY_LOCK_PREFIX'
-
-    def try_advisory_lock(lock_keys, lock_name:, shared:, transaction:, timeout_seconds: nil)
+    def try_advisory_lock(lock_keys, lock_name:, shared:, transaction:, timeout_seconds: nil, blocking: false)
       raise ArgumentError, 'shared locks are not supported on MySQL' if shared
       raise ArgumentError, 'transaction level locks are not supported on MySQL' if transaction
 
-      # MySQL GET_LOCK supports native timeout:
-      # - timeout_seconds = nil: wait indefinitely (-1)
+      # Note: blocking parameter is accepted for API compatibility but ignored for MySQL
+      # MySQL's GET_LOCK already provides native timeout support, making the blocking
+      # parameter redundant. MySQL doesn't have separate try/blocking functions like PostgreSQL.
+
+      # MySQL/MariaDB GET_LOCK supports native timeout:
+      # - timeout_seconds = nil: wait indefinitely
       # - timeout_seconds = 0: try once, no wait (0)
       # - timeout_seconds > 0: wait up to timeout_seconds
+      #
+      # Note: MySQL accepts -1 for infinite wait, but MariaDB does not.
+      # Using a large value (1 year) for cross-compatibility.
       mysql_timeout = case timeout_seconds
-                      when nil then -1
+                      when nil then 31_536_000 # 1 year in seconds
                       when 0 then 0
                       else timeout_seconds.to_i
                       end
@@ -39,22 +44,11 @@ module WithAdvisoryLock
     rescue ActiveRecord::StatementInvalid => e
       # If the connection is broken, the lock is automatically released by MySQL
       # No need to fail the release operation
-      connection_lost = case e.cause
-                        when defined?(Mysql2::Error::ConnectionError) && Mysql2::Error::ConnectionError
-                          true
-                        when defined?(Trilogy::ConnectionError) && Trilogy::ConnectionError
-                          true
-                        else
-                          e.message =~ /Lost connection|MySQL server has gone away|Connection refused/i
-                        end
-
-      return if connection_lost
-
-      raise
+      raise unless connection_lost_error?(e)
     end
 
     def lock_keys_for(lock_name)
-      lock_str = "#{ENV.fetch(LOCK_PREFIX_ENV, nil)}#{lock_name}"
+      lock_str = "#{ENV.fetch(CoreAdvisory::LOCK_PREFIX_ENV, nil)}#{lock_name}"
       [lock_str]
     end
 
@@ -62,8 +56,26 @@ module WithAdvisoryLock
       true
     end
 
+    # Non-blocking check via IS_USED_LOCK, no lock is acquired as a side effect
+    def advisory_lock_exists_for?(lock_name, shared: false)
+      raise ArgumentError, 'shared locks are not supported on MySQL' if shared
+
+      lock_keys = lock_keys_for(lock_name)
+      !query_value("SELECT IS_USED_LOCK(#{quote(lock_keys.first)})").nil?
+    rescue ActiveRecord::StatementInvalid
+      nil
+    end
+
     private
 
+    def connection_lost_error?(error)
+      cause = error.cause
+      return true if defined?(Mysql2::Error::ConnectionError) && cause.is_a?(Mysql2::Error::ConnectionError)
+      return true if defined?(Trilogy::ConnectionError) && cause.is_a?(Trilogy::ConnectionError)
+
+      error.message.match?(/Lost connection|MySQL server has gone away|Connection refused/i)
+    end
+
     def execute_successful?(mysql_function)
       query_value("SELECT #{mysql_function}") == 1
     end

data/lib/with_advisory_lock/postgresql_advisory.rb

@@ -6,49 +6,72 @@ module WithAdvisoryLock
   module PostgreSQLAdvisory
     extend ActiveSupport::Concern
 
-    LOCK_PREFIX_ENV = 'WITH_ADVISORY_LOCK_PREFIX'
     LOCK_RESULT_VALUES = ['t', true].freeze
     ERROR_MESSAGE_REGEX = / ERROR: +current transaction is aborted,/
 
-    def try_advisory_lock(lock_keys, lock_name:, shared:, transaction:, timeout_seconds: nil)
-      # timeout_seconds is accepted for compatibility but ignored - PostgreSQL doesn't support
-      # native timeouts with pg_try_advisory_lock, requiring Ruby-level polling instead
-      function = advisory_try_lock_function(transaction, shared)
-      execute_advisory(function, lock_keys, lock_name)
-    end
+    def try_advisory_lock(lock_keys, lock_name:, shared:, transaction:, timeout_seconds: nil, blocking: false)
+      function = if blocking
+                   advisory_lock_function(transaction, shared)
+                 else
+                   advisory_try_lock_function(transaction, shared)
+                 end
 
-    def release_advisory_lock(*args)
-      # Handle both signatures - ActiveRecord's built-in and ours
-      if args.length == 1 && args[0].is_a?(Integer)
-        # ActiveRecord's built-in signature: release_advisory_lock(lock_id)
-        super
+      if blocking && timeout_seconds&.positive?
+        blocking_lock_with_timeout(function, lock_keys, lock_name, timeout_seconds)
       else
-        # Our signature: release_advisory_lock(lock_keys, lock_name:, shared:, transaction:)
-        lock_keys, options = args
-        return if options[:transaction]
-
-        function = advisory_unlock_function(options[:shared])
-        execute_advisory(function, lock_keys, options[:lock_name])
+        execute_advisory(function, lock_keys, lock_name, blocking: blocking)
       end
+    rescue ActiveRecord::Deadlocked
+      # Rails 8.2+ raises ActiveRecord::Deadlocked directly for PostgreSQL deadlocks
+      # When using blocking locks, treat deadlocks as lock acquisition failure
+      return false if blocking
+
+      raise
     rescue ActiveRecord::StatementInvalid => e
-      # If the connection is broken, the lock is automatically released by PostgreSQL
-      # No need to fail the release operation
-      return if e.cause.is_a?(PG::ConnectionBad) || e.message =~ /PG::ConnectionBad/
+      # PostgreSQL deadlock detection raises PG::TRDeadlockDetected (SQLSTATE 40P01)
+      # When using blocking locks, treat deadlocks as lock acquisition failure.
+      # Rails 8.2+ may also retry after deadlock and get "current transaction is aborted"
+      # when the transaction was rolled back by PostgreSQL's deadlock detection.
+      if blocking && (e.cause.is_a?(PG::TRDeadlockDetected) ||
+                      e.message.include?('deadlock detected') ||
+                      e.message =~ ERROR_MESSAGE_REGEX)
+        false
+      else
+        raise
+      end
+    end
+
+    def release_advisory_lock(*args)
+      # ActiveRecord's built-in signature: release_advisory_lock(lock_id)
+      return super if args.length == 1 && args[0].is_a?(Integer)
 
-      raise unless e.message =~ ERROR_MESSAGE_REGEX
+      # Our signature: release_advisory_lock(lock_keys, lock_name:, shared:, transaction:)
+      lock_keys, options = args
+      return if options[:transaction]
 
+      function = advisory_unlock_function(options[:shared])
       begin
-        rollback_db_transaction
         execute_advisory(function, lock_keys, options[:lock_name])
-      ensure
-        begin_db_transaction
+      rescue ActiveRecord::StatementInvalid => e
+        # If the connection is broken, the lock is automatically released by PostgreSQL
+        # No need to fail the release operation
+        return if e.cause.is_a?(PG::ConnectionBad) || e.message =~ /PG::ConnectionBad/
+
+        raise unless e.message =~ ERROR_MESSAGE_REGEX
+
+        begin
+          rollback_db_transaction
+          execute_advisory(function, lock_keys, options[:lock_name])
+        ensure
+          begin_db_transaction
+        end
       end
     end
 
     def lock_keys_for(lock_name)
       [
         stable_hashcode(lock_name),
-        ENV.fetch(LOCK_PREFIX_ENV, nil)
+        ENV.fetch(CoreAdvisory::LOCK_PREFIX_ENV, nil)
       ].map { |ea| ea.to_i & 0x7fffffff }
     end
 
@@ -68,6 +91,7 @@ module WithAdvisoryLock
           AND classid = #{lock_keys.first}
           AND objid = #{lock_keys.last}
           AND mode = '#{shared ? 'ShareLock' : 'ExclusiveLock'}'
+          AND granted
         LIMIT 1
       SQL
 
@@ -79,6 +103,23 @@ module WithAdvisoryLock
 
     private
 
+    # Bounded blocking acquisition via SET LOCAL lock_timeout. The setting is
+    # transaction-scoped so it never leaks to the session (pooler-safe), and
+    # the savepoint keeps a timeout from aborting an enclosing transaction.
+    # Session-level locks acquired here survive the wrapping COMMIT.
+    def blocking_lock_with_timeout(function, lock_keys, lock_name, timeout_seconds)
+      transaction(requires_new: true) do
+        previous_timeout = query_value('SHOW lock_timeout')
+        execute("SET LOCAL lock_timeout = '#{(timeout_seconds * 1000).to_i}ms'")
+        execute_advisory(function, lock_keys, lock_name, blocking: true)
+        # SET LOCAL survives a released savepoint, so restore the outer value
+        execute("SET LOCAL lock_timeout = #{quote(previous_timeout)}")
+        true
+      end
+    rescue ActiveRecord::LockWaitTimeout
+      false
+    end
+
     def advisory_try_lock_function(transaction_scope, shared)
       [
         'pg_try_advisory',
@@ -88,6 +129,15 @@ module WithAdvisoryLock
       ].compact.join
     end
 
+    def advisory_lock_function(transaction_scope, shared)
+      [
+        'pg_advisory',
+        transaction_scope ? '_xact' : nil,
+        '_lock',
+        shared ? '_shared' : nil
+      ].compact.join
+    end
+
     def advisory_unlock_function(shared)
       [
         'pg_advisory_unlock',
@@ -95,9 +145,26 @@ module WithAdvisoryLock
       ].compact.join
     end
 
-    def execute_advisory(function, lock_keys, lock_name)
-      result = query_value(prepare_sql(function, lock_keys, lock_name))
-      LOCK_RESULT_VALUES.include?(result)
+    def execute_advisory(function, lock_keys, lock_name, blocking: false)
+      sql = prepare_sql(function, lock_keys, lock_name)
+      if blocking
+        # Blocking locks return void - if the query executes successfully, the lock was acquired.
+        # Rails 8.2+ uses lazy transaction materialization. We must use materialize_transactions: true
+        # to ensure the transaction is started on the database before acquiring the lock,
+        # otherwise the lock won't actually block other connections.
+        if respond_to?(:internal_exec_query, true)
+          # Rails < 8.2
+          query_value(sql)
+        else
+          # Rails 8.2+ - use query_all with materialize_transactions: true
+          send(:query_all, sql, 'AdvisoryLock', materialize_transactions: true)
+        end
+        true
+      else
+        # Non-blocking try locks return boolean
+        result = query_value(sql)
+        LOCK_RESULT_VALUES.include?(result)
+      end
     end
 
     def prepare_sql(function, lock_keys, lock_name)

data/lib/with_advisory_lock/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module WithAdvisoryLock
-  VERSION = Gem::Version.new('7.0.2')
+  VERSION = Gem::Version.new('7.6.0')
 end

data/test/dummy/app/models/trilogy_label.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class TrilogyLabel < TrilogyRecord
+  self.table_name = 'trilogy_labels'
+end

data/test/dummy/app/models/trilogy_record.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class TrilogyRecord < ActiveRecord::Base
+  self.abstract_class = true
+  establish_connection :trilogy
+end