PALs makes it easy to use PostgreSQL advisory locks for distributed, application-level locking.
Do not confuse this type of locking with table or row locking in PostgreSQL. Distributed application-level locking can also be implemented with Redis, Memcache, ZeroMQ, and other services. For applications already using PostgreSQL, PALs avoids setting up and managing another service.
Install with:
pip install PALsThen use a Locker as a lock factory:
import datetime as dt
import pals
locker = pals.Locker('my-app-name', 'postgresql://user:pass@server/dbname')
lock1 = locker.lock('my-lock')
lock2 = locker.lock('my-lock')
assert lock1.acquire() is True
assert lock2.acquire(blocking=False) is False
start = dt.datetime.now()
acquired = lock2.acquire(acquire_timeout=300)
waited_ms = (dt.datetime.now() - start).total_seconds() * 1000
assert acquired is False
assert 300 <= waited_ms < 350
lock1.release()
if lock1.acquire(blocking=False):
try:
# Do your work here.
pass
finally:
lock1.release()
try:
with lock1:
# Do your work here.
pass
except pals.AcquireFailure:
# The acquire timeout was reached before the lock was acquired.
passUnlike locking systems backed by cache services, PostgreSQL advisory locks do not expire. If a client holds a lock and then sleeps or hangs, no other client can acquire the lock until it is released.
PALs helps prevent accidental lock retention in several ways:
- Locks work as context managers, which guarantees release when the context exits.
- Locks release their connection when garbage collected.
- By default, PALs calls
pg_advisory_unlock_all()whenever a connection returns to its dedicated SQLAlchemy pool.
PostgreSQL also invokes pg_advisory_unlock_all() when a session ends, including an
ungraceful client disconnect. The extra pool check-in call has a cost and can be disabled
with unlock_all_on_checkin=False for high-frequency workloads. Applications that disable
it should monitor locks and recycle connections regularly.
The project structure and tooling derive from Coppy. To set up and test the project:
- Install the Coppy host dependencies, including Mise and uv.
- Start PostgreSQL with
docker compose up -d. - Set
PALS_DB_URL=postgresql://postgres:password@localhost:54321/postgres. - Run
uv syncandprek install. - Run
noxto test Python 3.12 through 3.14 and execute the project checks.
Use mise run version show to show the current version and mise run version -- --help
for the version-management commands. See Updating a Coppy project before applying
template updates.
The implementation and tests are intentionally compact. See changelog.rst for release history.