django-pgware

PostgreSQL utilities for Django: advisory locks, GUC management, and logging suppression.

What it is

A small, dependency-light toolkit of three independent PostgreSQL utilities for Django. Each is a context manager (and, where it makes sense, a decorator) that borrows Django's database connection, performs a session-scoped action, and reliably undoes it on exit: advisory locks (sync + async), GUC setting (pg_set / atomic_set), and logging suppression (hush, for keeping sensitive query parameters out of the logs).

See ARCHITECTURE.md for the internals and invariants, and THEORY.md for the design rationale.

Status

Beta (1.0.x). The public API is stable; see CHANGELOG.md for recent changes.

Installation

pip install django-pgware

You'll also need a PostgreSQL database adapter — either psycopg2 or psycopg (v3):

pip install django-pgware[psycopg2]
# or
pip install django-pgware[psycopg3]

Advisory Locks

Context managers for PostgreSQL advisory locks — synchronous and asynchronous.

from django_pg_utils import advisory_lock

# Exclusive lock (blocks until acquired):
with advisory_lock("my-task") as acquired:
    assert acquired is True
    do_exclusive_work()

# Shared lock:
with advisory_lock("my-task", shared=True):
    do_shared_work()

# Non-blocking:
with advisory_lock("my-task", wait=False) as acquired:
    if acquired:
        do_work()

Async

from django_pg_utils import async_advisory_lock

async with async_advisory_lock("my-task") as acquired:
    await do_work()

Lock ID Types

Parameters

GUC Management

Temporarily SET PostgreSQL GUCs within a scope, with automatic cleanup.

pg_set — session-level SET / RESET

from django_pg_utils import pg_set

with pg_set("work_mem", "256MB"):
    MyModel.objects.complex_query()

# Multiple GUCs:
with pg_set([("work_mem", "256MB"), ("statement_timeout", "30s")]):
    ...

# As a decorator:
@pg_set("work_mem", "256MB")
def my_view(request):
    ...

atomic_set — transaction-level SET LOCAL

from django_pg_utils import atomic_set

with atomic_set("work_mem", "256MB"):
    MyModel.objects.complex_query()

Wraps the scope in atomic() and uses SET LOCAL — settings revert automatically when the transaction ends.

When to use which

Logging Suppression (hush)

Suppress PostgreSQL server logging and Django query logging within a scope — useful for protecting sensitive data (PCI cardholder data, credentials, tokens).

from django_pg_utils import hush

# Context manager:
with hush() as result:
    cursor.execute("SELECT decrypt_card(%s)", [card_token])

# Decorator:
@hush
def process_payment(card_token):
    ...

# Parameterized:
@hush(strict=True, database="payments")
def process_payment(card_token):
    ...

Parameters

hush() targets only the default connection unless you pass an explicit alias or database="*". (Earlier behavior suppressed on every configured connection by default, which would dial replicas/analytics DBs as a side effect.)

Django Settings

Running the tests

The project uses uv. Tests require a live PostgreSQL — there is no sqlite fallback.

uv sync                # install the dev environment
docker compose up -d   # throwaway PostgreSQL on localhost:5432
uv run pytest          # run the suite

PG_VERSION selects the PostgreSQL image (default 17); POSTGRES_HOST/PORT/USER/PASSWORD/DB override the connection. Lint and types: uv run ruff check && uv run ruff format --check && uv run mypy.

Requirements

• Python 3.10+
• Django 4.2+
• PostgreSQL 14+ with psycopg2 or psycopg3

License

PostgreSQL License. See LICENSE for details.