river

River is a background job processing library for Go that uses Postgres as its job queue. It is designed so that application data and job queue share the same database, allowing jobs to be enqueued transactionally alongside other database changes. Jobs are guaranteed to be enqueued if their transaction commits, removed if it rolls back, and are not visible for work until commit. Jobs are defined as struct pairs: a JobArgs implementation with json annotations and a stable "kind" string, plus a Worker implementation exposing a Work function. Workers are registered on startup so River can map job kinds to workers. A Client is created with a database pool, a driver, and a config containing a Workers bundle and queue settings. Clients can be started and stopped, with graceful shutdown via context cancellation or an explicit Stop call. Insert-only clients can insert jobs without working them. Features include batch job insertion using Postgres COPY FROM, cancelling jobs from inside a work function, error and panic handling, multiple queues for throughput and isolation, periodic and cron jobs, scheduled jobs, snoozing jobs, subscriptions to queue activity and statistics for telemetry, test helpers, transactional job completion, unique jobs by args/period/queue/state, a web UI for inspecting jobs and queues, and simplified work functions. River also supports inserting jobs from Python and Ruby for cross-language enqueueing, with Go workers processing them. The project is inspired by background job libraries such as Oban, Que, Sidekiq, Delayed::Job, GoodJob, and Hangfire. Documentation, godoc, a River UI, and a live demo are referenced in the README.