Django PGLock

Warnings

• breaking Version 1.8.0 dropped support for Python 3.9 and older Django/PostgreSQL versions, while adding support for newer ones (Python 3.14, Django 6.0, Postgres 18). Earlier versions also dropped support for older Python/Django versions.
  Fix: Upgrade your Python, Django, and PostgreSQL versions to match the library's requirements, or pin `django-pglock` to an older compatible version.
• gotcha Advisory locks can be either session-level or transaction-level. By default, `pglock.advisory` provides a session-level lock that persists until the database session disconnects. For transaction-level locks, which are released when the transaction terminates, you must explicitly set `xact=True`.
  Fix: For transaction-level locks, use `pglock.advisory(lock_id, xact=True)`. Understand the implications: session locks can persist longer than expected if not explicitly managed, especially in connection-pooling scenarios.
• gotcha When using `pglock.model` to lock an entire table, it must always be executed within a database transaction. The lock is held for the duration of that transaction.
  Fix: Wrap `pglock.model` calls within `django.db.transaction.atomic()` or similar transaction management. For example: `with transaction.atomic(): pglock.model('app_label.ModelName')`.
• gotcha Advisory lock IDs are global across the entire PostgreSQL database. Ensure you use unique and descriptive lock IDs (e.g., namespaced strings) to avoid unintended conflicts with other parts of your application or other applications using the same database.
  Fix: Use a consistent naming convention for lock IDs, such as `app_name.module_name.function_name` or `app_name.resource_id.operation`.
• gotcha Explicit locking, especially with `pglock.model`, can increase the likelihood of deadlocks if not managed carefully. Ensure consistent lock acquisition order across concurrent operations.
  Fix: Design your locking strategy to acquire locks in a consistent order whenever multiple resources are involved. Use `timeout` and `side_effect` arguments to handle contention gracefully, such as raising an error (`pglock.Raise`) or skipping execution (`pglock.Skip`) rather than waiting indefinitely.

Install

• pip install django-pglock Install stable version

Imports

• advisory

  from pglock import advisory

  Used for application-level advisory locks, as both a context manager and a decorator.
• model

  from pglock import model

  Used for locking entire Django models (tables).
• PGLock

  from pglock.models import PGLock

  Model for querying active PostgreSQL locks.
• BlockedPGLock

  from pglock.models import BlockedPGLock

  Model for querying locks that are currently blocking other activity.

Quickstart

Demonstrates how to use `pglock.advisory` as a context manager to ensure only one instance of a critical section runs at a time. The lock ID can be any string, which `django-pglock` hashes to a 64-bit integer for PostgreSQL.

import pglock

def my_exclusive_task():
    # Simulate a task that should only run one instance at a time
    print("Attempting to acquire lock...")
    with pglock.advisory("my_critical_section_lock") as acquired:
        if acquired:
            print("Lock acquired! Running critical section...")
            # Your critical section code here
            import time
            time.sleep(2)
            print("Critical section complete.")
        else:
            print("Could not acquire lock, another instance is running.")

if __name__ == "__main__":
    # In a real Django app, this would run within a Django context
    # For quickstart, we just call the function directly.
    # You'd typically configure Django and a database connection first.
    # To test, run this script twice rapidly.
    my_exclusive_task()