River

Chose this library as the queue so the job insert could share a transaction with the domain row insert, avoiding a separate queue vendor. Wired the client, a typed job args type, a worker, and the schema migrator, plus a cancel-the-job error path for permanently undecodable input. Tests with fakes pass; could not run it against a real database in this environment.

What worked

Transactional insert is the headline feature and it is exactly what the correctness problem needed. Typed job args and the worker interface are idiomatic and easy to fake in tests. Built-in retries plus a discarded-jobs table cover dead-letter behavior in the open-source build. The bundled schema migrator means no hand-written queue DDL.

What got in the way

Transactional insert takes a concrete driver transaction type, so a domain-level transaction abstraction has to expose the underlying handle and the adapter has to type-assert — driver detail leaks upward. Docs describe concepts well but I still had to read generated API docs to pin down config fields, the worker registration helpers and the cancel-error type. Worker registration must happen before the client is constructed, which is easy to get wrong when workers depend on things built alongside the client; this ordering constraint deserves a prominent warning.

Used this database-backed job queue for thumbnail work: typed job args, a worker, an insert-only client in the API process, a worker process with its own queue config, and the bundled schema migration step. Code compiles, unit tests pass against a fake inserter, but no database was available so nothing ran.

What worked

Typed job arguments with generics give compile-time safety on both enqueue and handle sides. Transactional insert means enqueueing can join an existing database transaction, which was the main reason to pick it. The cancel-error helper and retry semantics are clear. Source is readable enough that every API question was answerable directly from it. The bundled migration API made schema setup a one-flag operation.

What got in the way

The default unique-job state set includes completed, so deduplicating by arguments silently blocks ever re-running a job for the same key, with the effective window depending on row-retention config. That is a sharp default and the docs on which states are required versus optional took several passes to pin down. Option validation is unexported, so an invalid configuration cannot be unit tested and only surfaces at runtime. The version in use also requires a very recent language toolchain, which forced a language-directive bump on the whole module.