ADR-0005: river over asynq for background jobs¶
- Status: Accepted
- Date: 2026-04-13 (backfill)
- Deciders: @lusoris
- Tags: jobs, db
Context¶
Apps need durable background jobs (emails, exports, webhooks). The two contenders for Postgres-backed Go job queues:
- riverqueue/river — Postgres-only, uses LISTEN/NOTIFY +
SELECT ... FOR UPDATE SKIP LOCKED, typed args via generics. - hibiken/asynq — Redis-only, mature web UI, scheduled tasks.
Apps already use Postgres (per ADR-0001 wiring + db/pgx); adding Redis just for jobs doubles operational surface. The framework also wants the transactional outbox pattern — write job alongside domain rows in the same pgx.Tx so partial failures are impossible. That requires the job queue to live in the same DB.
Decision¶
We will use github.com/riverqueue/river as the background job system. The framework provides jobs/ (river client + workers registry as fx modules) and outbox/ (transactional outbox → river dispatcher).
Alternatives considered¶
| Option | Pros | Cons | Why not chosen |
|---|---|---|---|
hibiken/asynq |
Mature, web UI, multi-queue priorities | Redis adds an operational dep; loses transactional consistency with Postgres rows | Doubles infrastructure for marginal gain. |
gocraft/work |
Simple, Redis-based | Unmaintained since 2021 | Dead. |
Hand-rolled pgq (LISTEN/NOTIFY + a table) |
Total control | River already does this correctly with retries, dead letters, periodic jobs | Reinventing river badly. |
temporal.io |
Workflow engine, not just jobs | Server install, learning curve, overkill for "send email" | Right tool for orchestration, wrong tool for fire-and-forget. |
Consequences¶
- Positive: One database to operate.
outbox.Add(ctx, tx, ...)in the same transaction as domain writes guarantees exactly-once enqueue. Typed args via generics catch arg/worker mismatches at compile time. River's web UI (jobs/ui/) opt-in. - Negative: Postgres-bound — apps that move jobs off Postgres (e.g. to SQS) must also rewrite the outbox dispatcher. Job throughput capped by Postgres write rate (acceptable for our target workloads — saturated at ~10k jobs/s on commodity hardware per river benchmarks).
- Follow-ups:
outbox/shipped as a separate module (per ADR-0006) so only the leader replica drains. Periodic jobs handled byjobs/cron/wrapping river'sPeriodicJob.
References¶
- The decision evaluated river v0.34.0. The maintained current pin is recorded in
docs/upstream/river/. outbox/AGENTS.md— dispatcher contract.jobs/AGENTS.md— worker registration patterns.