| single |
# 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
```bash
pip install django-pgware
```
You'll also need a PostgreSQL database adapter — either `psycopg2` or
`psycopg` (v3):
```bash
pip install django-pgware[psycopg2]
# or
pip install django-pgware[psycopg3]
```
## Advisory Locks
Context managers for PostgreSQL advisory locks — synchronous and
asynchronous.
```python
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
```python
from django_pg_utils import async_advisory_lock
async with async_advisory_lock("my-task") as acquired:
await do_work()
```
### Lock ID Types
| Type | Example | Notes |
|------|---------|-------|
| `str` | `"my-lock"` | Hashed to 64-bit via SHA-256 |
| `int` | `12345` | Used directly as bigint |
| `tuple[int, int]` | `(5, 9)` | Two-argument advisory lock |
### Parameters
| Parameter | Default | Description |
|-----------|---------|-------------|
| `lock_id` | required | String, int, or (int, int) tuple |
| `shared` | `False` | Shared lock (vs exclusive) |
| `wait` | `True` | Block until acquired |
| `comment` | `None` | Toggle the auto-generated `file:line` SQL comment.
If `None`, resolves to `settings.ADVISORY_LOCK_COMMENT` if set, else
`settings.DEBUG` |
| `using` | `None` | Django database alias |
## GUC Management
Temporarily SET PostgreSQL GUCs within a scope, with automatic cleanup.
### `pg_set` — session-level SET / RESET
```python
from django_pg_utils import pg_set
with pg_set("work_mem", "256MB"):
|