PALs 0.1.0

Introduction

PALs makes it easy to use PostgreSQL Advisory Locks to do distributed application level locking.

Do not confuse this type of locking with table or row locking in PostgreSQL. It’s not the same thing.

Distributed application level locking can be implemented by using Redis, Memcache, ZeroMQ and others. But for those who are already using PostgreSQL, setup & management of another service is unnecessary.

Usage

# Think of the Locker instance as a Lock factory.
locker = pals.Locker('my-app-name', 'postgresql://user:pass@server/dbname')

lock1 = locker.lock('my-lock')
lock2 = locker.lock('my-lock')

# The first aquire works
assert lock1.aquire() is True

# Non blocking version should fail immediately
assert lock2.aquire(blocking=False) is False

# Blocking version will retry and eventually fail
aquired, retries = lock2.aquire(return_retries=True)
assert aquired is False
assert retries > 4

# You can set the retry parameters yourself if you don't like our defaults.
lock2.aquire(retry_delay=100, retry_timeout=300)

# They can also be set on the lock instance
lock3 = locker.lock('my-lock', retry_delay=100, retry_timeout=300)

# Release the lock
lock1.release()

# Recommended usage pattern:
if not lock1.aquire():
    # Remember to check to make sure you got your lock
    return
try:
    # do my work here
finally:
    lock1.release()

# But more recommended and easier is to use the lock as a context manager:
with lock1:
    assert lock2.aquire() is False

# Outside the context manager the lock should have been released and we can get it now
assert lock2.aquire()

# The context manager version will throw an exception if it fails to aquire the lock.  This
# pattern was chosen because it feels symantically wrong to have to check to see if the lock
# was actually aquired inside the context manager.  If the code inside is ran, the lock was
# aquired.
try:
    with lock1:
        # We won't get here because lock2 aquires the lock just above
        pass
except pals.AquireFailure:
    pass

Running Tests Locally

$ docker-compose up -d
$ export PALS_DB_URL=postgresql://postgres:password@localhost:54321/postgres

$ tox

$ pipenv install --dev
$ pipenv shell
$ pytest pals/tests.py

See Also

• https://vladmihalcea.com/how-do-postgresql-advisory-locks-work/

• https://github.com/binded/advisory-lock

• https://github.com/vaidik/sherlock

• https://github.com/Xof/django-pglocks

Changelog

0.1.0 released 2019-02-22

• Use lock_timeout setting to expire blocking calls (d0216ce)

• fix tox (1b0ffe2)

• rename to PALs (95d5a3c)

• improve readme (e8dd6f2)

• move tests file to better location (a153af5)

• add flake8 dep (3909c95)

• fix tests so they work locally too (7102294)

• get circleci working (28f16d2)

• suppress exceptions in Lock __del__ (e29c1ce)

• Add hang.py script (3372ef0)

• fix packaging stuff, update readme (cebd976)

• initial commit (871b877)