Advisory locking for ActiveRecord
Adds advisory locking (mutexes) to ActiveRecord 7.2+, with ruby 3.3+, jruby or truffleruby, when used with
MySQL
or
PostgreSQL.
Note: SQLite support has been removed. For single-node SQLite deployments,
consider using a Ruby mutex instead. Support for MySQL 5.7 has also been
dropped; please use MySQL 8 or PostgreSQL.
An advisory lock is a mutex
used to ensure no two processes run some process at the same time. When the
advisory lock is powered by your database server,
your mutex spans hosts.
This gem automatically includes the WithAdvisoryLock
module in all of your
ActiveRecord models. Here’s an example of how to use it where User
is an
ActiveRecord model, and lock_name
is some string:
User.with_advisory_lock(lock_name) do
do_something_that_needs_locking
end
with_advisory_lock
takes an options hash as the second parameter. Thetimeout_seconds
option defaults to nil
, which means wait indefinitely for
the lock.
A value of zero will try the lock only once. If the lock is acquired, the block
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 returnfalse
, whilewith_advisory_lock!
will raise aWithAdvisoryLock::FailedToAcquireLock
error.
For backwards compatability, the timeout value can be specified directly as the
second parameter.
The shared
option defaults to false
which means an exclusive lock will be
obtained. Setting shared
to true
will allow locks to be obtained by multiple
actors as long as they are all shared locks.
Note: MySQL does not support shared locks.
PostgreSQL supports transaction-level locks which remain held until the
transaction completes. You can enable this by setting the transaction
option
to true
.
Note: transaction-level locks will not be reflected by .current_advisory_lock
when the block has returned.
The return value of with_advisory_lock_result
is a WithAdvisoryLock::Result
instance, which has a lock_was_acquired?
method and a result
accessor
method, which is the returned value of the given block. If your block may
validly return false, you should use this method.
The return value of with_advisory_lock
will be the result of the yielded
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.
If you needed to check if the advisory lock is currently being held, you can
call Tag.advisory_lock_exists?("foo")
, but realize the lock can be acquired
between the time you test for the lock, and the time you try to acquire the
lock.
If you want to see if the current Thread is holding a lock, you can callTag.current_advisory_lock
which will return the name of the current lock. If
no lock is currently held, .current_advisory_lock
returns nil
.
You can optionally pass disable_query_cache: true
to the options hash ofwith_advisory_lock
in order to disable ActiveRecord’s query cache. This can
prevent problems when you query the database from within the lock and it returns
stale results. More info on why this can be a problem can be
found here
Add this line to your application’s Gemfile:
gem 'with_advisory_lock'
And then execute:
$ bundle
First off, know that there are lots of different kinds of locks available to
you. Pick the finest-grain lock that ensures correctness. If you choose a
lock that is too coarse, you are unnecessarily blocking other processes.
These are named mutexes that are inherently “application level”—it is up to the
application to acquire, run a critical code section, and release the advisory
lock.
Whether optimistic
or pessimistic,
row-level locks prevent concurrent modification to a given model.
If you’re building a
CRUD
application, this will be 2.4, 2.5 and your most commonly used lock.
Provided through something like the
monogamy gem, these prevent
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.
Advisory locks with MySQL and PostgreSQL ignore database transaction boundaries.
You will want to wrap your block within a transaction to ensure consistency.