Architecture decision record

# ADR-007: PostgreSQL job queue

Illustrative example · all scenario-specific names, dates, figures, and thresholds are fictional · status: Accepted · date: 2026-03-14 · ADR steward: platform lead · decision authority: platform team · supersedes: none · superseded by: none

## Context

The service needs delayed jobs and retries at roughly 50 jobs per minute. The team already operates PostgreSQL but has no production experience with Redis or RabbitMQ. Adding a dedicated queue now would add on-call work before the workload proves that it needs one. A job record must commit in the same PostgreSQL transaction as the application change that requires it.

## Options considered

We considered a PostgreSQL-backed queue, managed Redis, RabbitMQ, and synchronous processing. At the current volume, PostgreSQL is preferred because it commits the job record with the application data and the team already operates it. A dedicated queue could provide more isolation and throughput, but would add a production service before those benefits are demonstrated.

## Decision

We will use a PostgreSQL-backed job queue with a small worker library. It is a deliberate fit for the current volume and operating capability, not a claim that PostgreSQL is the best queue for every workload.

The design has three non-negotiable boundaries:

- Application code commits each job with the application data that requires it. A worker claims work in a short transaction, commits before handler work, and treats a lost or expired claim as stale.
- Every external operation has a durable logical-effect key and immutable payload fingerprint. A timeout or late worker is `unknown` until reconciliation; it never creates a fresh effect by guesswork.
- Order-sensitive effects are allowed only when the recipient enforces a monotonic fence or a durable no-effect tombstone. Local leases coordinate workers but cannot prove that a late network call did not happen.

The implementation record defines `SKIP LOCKED` claiming, lease expiry measured with the database clock (`clock_timestamp()`, not transaction-fixed `now()`), retry limits, idempotent effects, recipient ordering, recovery, and monitoring. Follow the [reliable event processing reference](/design/rfc/reliable-event-processing/) for those details.

## Consequences

This decision favours current operational simplicity over potential future throughput and workload isolation.

### Easier now

- We operate one fewer production system.
- Job enqueueing is atomic with the related application write.
- The team can use its existing PostgreSQL access controls, monitoring, backup process, and operational knowledge.

### Harder now

- Queue traffic shares database capacity with application traffic and adds table-maintenance work.
- The team must maintain and support the worker library.
- The queue is at-least-once, so handlers need durable effect records and idempotent downstream contracts.

## Confirmation or review trigger

Before production use, test atomic enqueueing, concurrent claims, crash recovery, duplicate delivery, unknown downstream results, and the late-worker ordering boundary. The implementation must show one intended effect or a reconciled unknown outcome; it must not silently retry ambiguity.

Review triggers:

- Sustained volume reaches 500 jobs per minute; reassess queue latency and database impact.
- Queue table bloat, lock contention, or job latency degrades normal database work.
- The workload needs more throughput or isolation than the current PostgreSQL design can provide without degrading normal database work.

If any trigger persists for seven days, or causes material impact sooner, propose a successor ADR. Keep this accepted decision text and reasoning unchanged. After an accepted successor replaces it, set this predecessor’s `Status: Superseded` and `Superseded by: ADR-XXX`; in the same coordinated update, set the successor’s `Supersedes: ADR-007`.