River

River is a job processing library for Go that uses Postgres as its only dependency, avoiding the need for a separate broker like Redis or RabbitMQ. Jobs are inserted directly within database transactions, so they’re only enqueued if the surrounding transaction commits and are automatically discarded if it rolls back, eliminating a whole class of dual-write bugs common with external queue systems.

Beyond basic enqueue-and-work semantics, River ships with batch insertion via Postgres COPY, unique job constraints, periodic/cron jobs, job snoozing and cancellation, resumable step-based jobs, pluggable retry policies, subscriptions for real-time queue events, and a companion React-based web UI (River UI) for inspecting and managing jobs. The project is organized as a Go workspace with separate modules for its core client, database drivers (pgx and database/sql), shared internals, and test helpers, and it ships an official CLI for running migrations and other operational tasks.

What You Get

• Transactional job enqueueing that inserts jobs inside the same database transaction as the business logic that created them
• Pluggable database drivers with first-class support for pgx/v5, the standard library database/sql, and SQLite for local development
• Batch insertion using Postgres COPY FROM for efficiently enqueueing large numbers of jobs at once
• Built-in maintenance services for stuck-job rescue, retention cleanup, scheduling, and cluster-wide leader election
• A companion React-based web UI (River UI) for inspecting queues, jobs, and statistics in real time
• An official CLI (cmd/river) for running database migrations and other operational tasks

Common Use Cases

• Offloading slow work (emails, webhooks, image processing) from web request handlers
• Scheduling periodic and cron-style maintenance tasks with cluster-wide leader election so they run exactly once
• Building durable, exactly-once side effects tied to a business transaction, such as only sending a welcome email if the signup transaction commits
• Running a multi-queue worker pool with per-queue concurrency limits and the ability to pause individual queues
• Inserting jobs from a Python or Ruby service to be worked by Go consumers against the same Postgres-backed queue

Under The Hood

Architecture The project is a multi-module Go workspace (go.work) organized around a generic Client[TTx any] (client.go) that wires together an internal producer (producer.go) which pulls jobs per queue, a jobexecutor that runs work with hooks and middleware, a jobcompleter for transactional job completion, maintenance services for stuck-job rescue and retention, and a leadership package for cluster-wide leader election. All database access flows through a riverdriver.Driver interface, with concrete implementations living in separate modules (riverdriver/riverpgxv5, riverdriver/riverdatabasesql, riverdriver/riversqlite), so the core package never depends on a specific Postgres driver. Unique-job enforcement (internal/dbunique) and job listing (internal/dblist) are kept as separate concerns from the hot insert/fetch path, and a small plugin system (internal/riverplugin, rivershared/riverpilot) lets optional behavior hook into the client lifecycle without changing its core.

Tech Stack Built on Go 1.26 (toolchain 1.26.6) as a workspace of eight modules (root, cmd/river, three riverdriver submodules, rivershared, rivertype). Runtime dependencies are deliberately minimal: jackc/pgx/v5 (plus pgerrcode and puddle) for the pgx driver, robfig/cron/v3 for cron-expression scheduling, tidwall/gjson/sjson for JSON metadata patching, and golang.org/x/sync for concurrency primitives; stretchr/testify appears only in tests. Migrations are hand-written SQL under each driver’s migration/ directory rather than generated by an ORM. CI runs against a real Postgres service container across a Go/Postgres version matrix, with a dedicated benchmark job alongside the standard test suite.

Code Quality The repository carries 146 _test.go files, with stretchr/testify used across roughly a hundred of them alongside dedicated riverinternaltest, riverdbtest, and testsignal helper packages for deterministic, driver-agnostic concurrency testing. Errors are explicit, typed values rather than raw strings or swallowed failures — error.go defines sentinel types like QueueAlreadyAddedError, QueueNotFoundError, JobCancelError, and JobSnoozeError, each implementing Is for errors.Is compatibility. Linting is unusually strict: .golangci.yaml sets default: all and documents every disabled linter with a rationale, and CI enforces it on every push and pull request.

What Makes It Unique The core idea — enqueueing a job as part of the same Postgres transaction as the rest of an application’s writes, so the job is guaranteed to exist if and only if that transaction commits — removes an entire class of dual-write ambiguity that broker-backed queues (Sidekiq, BullMQ, Celery) can’t offer without extra outbox machinery. On top of that guarantee, River layers cluster-wide leader election, resumable step-based jobs that checkpoint progress mid-run and resume after a crash (resumable.go, resumable_step_tx.go), and documented cross-language interop where Python or Ruby services insert jobs directly into the same Postgres tables Go workers consume. Individually these are known patterns, but the combination is a distinctive design compared to typical Go job queues.