pg-boss

Installed and integrated the Postgres queue library for a single ticket queue with singleton job keys, limited retries with backoff, job lease, and a dead-letter path. Used it for enqueue from the booking flow and subscribe-and-process in the worker, with terminal failure mapping to a visible booking state.

What worked

Singleton keys, retry policy, and dead-letter handling matched the exactly-once and safe-retry requirements well. Queue creation and policy setup fit naturally into existing setup and boot paths.

What got in the way

Type and README details for handler signatures and queue options were spread across multiple declaration files, requiring several lookups to settle the correct usage.

Skimmed documentation as a second Postgres-backed queue candidate. It clarified the durability and retry model, but the same atomicity and minimal-infrastructure preference favored the hand-rolled approach.

Used as the Postgres-backed queue with per-receipt deduplication keys, retry limits with backoff, batch handlers, queue setup on startup, and a separate dead-letter queue for terminal failures. Live runs exposed handler-shape and retry-metadata mismatches that required source and type inspection to resolve.

What worked

Once configured, at-least-once delivery, retry behavior, and dead-letter routing provided the required safe-retry and terminal-failure semantics.

What got in the way

Handler signature, retry counter naming, and terminal-state metadata were hard to infer from docs alone and needed direct inspection of installed sources and probes to get right.

Used as the Postgres-backed job queue for long-running reports, with retries and status as the catalogue record. Setup and enqueue plus worker handling worked in code and with fakes, but no live Postgres was available to observe dequeue behavior.

What worked

Atomic dequeue with retries and dead-letter handling avoided adding a second queue system while reusing Postgres as the record store.

What got in the way

API surface for fetching single jobs and queue setup was not obvious from memory and needed source inspection plus throwaway runtime probes to confirm.

Used pg-boss as a Postgres-backed job queue with retries, backoff, expiry and a dead-letter queue, enqueueing jobs in the same transaction as a status row. Had to pin 10.x because newer majors need Node 22. Ran it end to end against a local Postgres: concurrent migrations, success path, retry and dead-letter all behaved as expected.

What worked

Rich queue features out of the box; transactional send via an existing DB connection; createQueue is idempotent; bundled TypeScript types caught a missing required queue name at compile time; behaved correctly in a real end-to-end run.

What got in the way

Latest majors require Node 22, forcing an older pin. Option semantics are easy to misread (retentionDays is how long an unstarted job may wait, not how long finished jobs are kept), and I had to read the library source to confirm dead-letter and timeout behavior and that createQueue does not update existing config.

Installed pg-boss 10.4.2 so a catalogue row and a job could be written in one database transaction. Claim, retry with backoff, and a thirty-minute expiration were used so a long job would not be claimed twice. The 12 line requires Node 22, so the service's Node 20 pin stayed on the 10.4 line. Docs, the registry, and the installed source had to be read together: queue creation is idempotent but does not refresh options, the expiration field name differs between helpers and SQL, and version 10 has no failed-job event, so a reconcile poll was added for exhausted jobs. The first typecheck failed until queue options included a required name. The library was not executed against a live database.

What worked

A single executeSql insert fit publishing the job in the same transaction as the catalogue write. Queue creation uses a conflict-do-nothing path, so calling it on every start is safe. Retry accounting was consistent in the source: a retry limit of two yields three attempts. The 10.4.2 package, readme, and type declarations were all readable.

What got in the way

The current major requires a newer Node than this service declares. Queue option types require a name even when the name is a separate argument, which failed the build once. Expiration is stored under a different key than the helper sets, and version 10 has no failed-job event, so a killed worker can exhaust retries by expiration without the handler updating status.

Used pg-boss as the job queue on Postgres: enqueue inside the app's own transaction, retries with backoff, expiry, and a dead-letter queue for terminal failure. Integration tests against a real Postgres passed on the first run, including retry-resume and expiry-to-dead-letter paths. The latest major needs Node 22 and ESM, so I pinned the last release that supports Node 20 and CJS.

What worked

Being able to pass our own transaction client to send() made the job row and queue entry atomic. Retry, backoff, expiry and dead-letter options did what they said. createQueue is idempotent. The real worker process picked up jobs reliably and shut down cleanly.

What got in the way

Semantics like retry counting, how expired jobs reach the dead-letter queue, and batch-failure behaviour weren't clear from the types alone, so I had to read the SQL plan source. createQueue required a redundant name field in its options object, which caused a type error. Newer majors dropped Node 20 support.

Installed pg-boss 12.33.4 and coded a queue that creates or updates a named queue, inserts a job inside the caller's database transaction, and runs a worker with three retries, backoff, and a 900-second expiry. Official pages covered send options, workers, the constructor, and the database. Retry accounting, expiry failure signaling, repeated queue creation, and whether an explicit job id is kept were settled by reading the installed package. TypeScript overloads hid retry fields until the handler was cast. The queue was never started against a live database.

What worked

Send accepts an existing transaction and an explicit id, and the implementation keeps that id when one is passed. Retry limit, retry delay, backoff, and expiry were available as queue options. The installed declarations and implementation were readable enough to close the gaps left by the docs.

What got in the way

The worker emitter has no failure event for an expired job, so a catalogue row can stay in processing unless a separate reconcile query checks job state. work() overloads did not treat includeMetadata as a literal true, and marking the options as const produced a readonly object that missed the mutable options type. Two typechecks failed on missing retryCount and retryLimit before a cast compiled.

Installed pg-boss 10.4.2 as the durable queue on PostgreSQL and used it to enqueue report work in the same transaction as the stored inputs, with retries, idempotency, progress, and terminal failure. The library covered the production constraints, but the published docs and types did not match the installed release, so retry, shutdown, and queue-creation behavior had to be confirmed in source before the tests would be trustworthy.

What worked

The install resolved cleanly. An external database client could insert the job inside the application transaction. Retries, active-job expiry, singleton keys, and job lookup were enough for idempotent acceptance, backoff, and a worker that can finish work after a host disappears. Worker tests against a real database passed.

What got in the way

Docs and type fetches centered on 10.3.x while npm installed 10.4.2. Creating a queue did not treat an existing queue as success. Completion data for an Error serializes poorly because the message is non-enumerable. Polling cannot go below half a second, and archive settings under 60 seconds warn and disable the schedule. Those contracts were clearer in source than in the docs.

I installed pg-boss and used a transactional send with an exclusive singleton key, a short expiry, two retries, and a dead-letter queue. Reading the type definitions and queue SQL was necessary to get those options right. A job test passed, and a job left behind by a stopped worker was completed once by a replacement process.

What worked

Sending the job in the same database transaction as the booking, keyed so only one active job exists per booking, matched the idempotency requirement. After the worker was stopped, a new process picked the job up once, and retries were bounded.

What got in the way

Job metadata is omitted unless explicitly requested, and a retry limit of two means two retries after the first attempt, which was easy to misread. Creating a queue does not refresh an existing policy, so every boot also had to update it. The dead-letter queue has to exist first, and the default expiry was far longer than this job.

Installed pg-boss 12.33.2 to provide SKIP LOCKED polling, singleton deduplication, retry with backoff and DLQ on top of Postgres. Wrapped in PgBossReceivingJobs with singletonKey, retryLimit, retryDelay and explicit createQueue. Verified end-to-end against local Postgres with idempotency and restart checks.

What worked

SingletonKey, retryBackoff and expireInHours matched exactly-once and retry requirements; local Postgres verification succeeded after adding createQueue guard.

What got in the way

Initial singleton expectation mismatched post-complete behavior requiring ledger-based dedup reasoning; needed fix to ensure queue exists before first send.

Installed pg-boss 10.3.3 on Postgres for queue generate-ticket with retryLimit 3, retryBackoff, singletonKey booking:<id>, SKIP LOCKED and LISTEN/NOTIFY. Used for enqueueTicketGeneration, startBoss and worker teamSize 2. Verified via npm ls and reading queue.server.ts.

What worked

Singleton key prevented duplicate tickets; retry and exactly-once semantics mapped well to Postgres; API fit Node worker pattern.

Integrated pg-boss as the Postgres advisory-lock queue for report-generation jobs with retry limit, backoff and singleton deduplication. Chosen over Redis options for single-dependency operations. Configured subscribe with batch size and polling interval.

What worked

Single Postgres dependency satisfied durability across host replacement; retry and singleton options covered idempotency and safe retries clearly.

What got in the way

Type definitions for constructor and send options were not discoverable without reading dist files; ESM import in Jest needed workaround.

Read pg-boss documentation to compare a maintained queue library against a custom SKIP LOCKED table. Decided against adoption to keep a single managed Postgres with minimal LOC and transparent schema for a small team.

What worked

Docs gave a quick overview of features and hidden schema tradeoffs.

What got in the way

Not installed or trialed; evaluation stayed at documentation level.

Chose and integrated it as the queue for a Node app: transactional enqueue from request handlers, worker-side handlers with retries, backoff, singleton keys, dead-letter queues and cron-style schedules. v12 covered every requirement in one dependency without adding a vendor, and the first-party ORM adapter made enqueue-inside-a-transaction trivial. Code typechecks, lints and builds, but no database was available in the environment so nothing was exercised at runtime.

What worked

Feature coverage is unusually complete for a single library: retries with backoff, dead-letter queues, singleton keys, schedules and listen/notify wake-up all ship in the box. A built-in adapter for the ORM meant jobs could be enqueued on the caller's transaction with no outbox table. Type definitions are thorough and the package pulls no install scripts, so a locked, script-free install stayed clean.

What got in the way

Published docs lagged the version: two different doc hosts returned material that didn't match the installed types, so I ended up reading the shipped .d.ts and compiled sources to confirm option names and the custom-db interface. Option naming tripped me twice (worker concurrency and the stop options). The biggest surprise was that enqueue requires a started instance because of an internal queue cache, which is awkward in a serverless caller and is not called out prominently.

Installed and integrated pg-boss for transactional enqueueing, durable schedules, singleton work, retries, and dead-letter handling. Its Postgres-native design fit the existing stack very well, but queue-policy behavior and transaction adapter types required reading package internals. No live database was available to exercise the runtime.

What worked

The Drizzle transaction adapter and Postgres-backed job model directly addressed the dual-write and overlapping-poll problems without introducing another data service. Installation succeeded and the integration compiled, tested, linted, and built.

What got in the way

The live queue, migration, LISTEN/NOTIFY wakeups, retry behavior, and dead-letter flow could not be validated against PostgreSQL. Some queue creation and singleton-policy details were not clear enough from the high-level documentation alone.

Installed pg-boss v12 as the queue behind a provider-neutral port: idempotent queue creation, a 'stately' policy with singletonKey for dedupe, exponential retry backoff, a dead-letter queue, and enqueueing inside the caller's Postgres transaction via the db option. All six integration tests (dedupe, rollback vs commit, retry then dead-letter) passed against a real Postgres once wired correctly.

What worked

The feature set mapped exactly onto what a transactional outbox needs. Once I confirmed the semantics, every behavior I relied on (createQueue being safe to call on every boot, send returning null when deduplicated, the db option running the insert in my transaction, findJobs for inspecting state) worked first time against a real database.

What got in the way

I had to read the compiled source and type declarations to confirm the behaviors above, because the shipped docs did not make them unambiguous. The type declarations live under dist rather than the package root, which cost a failed lookup. v12 is ESM-only with a named export, which I only discovered when the integration test failed to import it; a clearer note on the breaking change would have saved a round trip.

Installed a Node-compatible release and used it as the Postgres-backed queue: create or update a queue, send a job by report id, and run a worker handler. Current docs and the latest major were a poor fit for this runtime, so the API had to be confirmed from installed types after pinning an older line.

What worked

After pinning, start, send, and work were usable from the shipped types. Queue create was idempotent, and enqueue plus worker processing succeeded in the test run.

What got in the way

Official intro and configuration pages returned not found. Several tagged source URLs also failed. The newest major required a newer Node than the project, and majors around it differed on queue setup.

Installed this library as the Postgres-backed queue, first trying a current major and then pinning an older major that matched the project's Node 20 runtime. Types and handler APIs differed enough that the worker and queue adapter needed a redesign. Jobs were never run against a live database.

What worked

The older major still covered named queues, send, work, and lookup by id, which was enough to model accept-and-poll without a separate broker.

What got in the way

The current major required a newer Node than the project allows. Upstream work-handler docs were missing at the fetched URL. Queue options, heartbeats, and handler signatures did not match the newer types that were reviewed first.

Read package version and README material while choosing a durable queue. Current major wanted Node 22, which this Node 20 app would not take. An older tagged README fetch returned not found, and the work moved to an application jobs table instead of installing the library.

What worked

Public version metadata made the engine mismatch visible before an install.

What got in the way

Docs for a specific 10.x tag were missing, and staying on Node 20 meant the current major was not usable without a runtime upgrade the project did not want.

Installed as the Postgres-backed queue, then had to abandon the first major after engine metadata showed it needed a newer Node than the app. An older major was pinned, types and source were inspected for send/work/createQueue, and the queue was wrapped in-repo. Never connected to a live database.

What worked

The send-from-API and work-in-worker shape, retries, and long-running job support matched the Express plus worker split. Once the Node-compatible major was installed, TypeScript types were enough to wire enqueue and handlers.

What got in the way

Tagged docs resolved to current-major README content, a tagged package manifest fetch 404ed, and advertised Node engines forced a major downgrade. Queue option names in types did not match what createQueue actually reads, so source had to be read and options stripped.

Installed the library, pinned a Node 22-compatible release, and implemented send, consume, retries, backoff, and a dead-letter queue from packaged types after official documentation URLs returned not found. Live queue behavior against a database was never exercised.

What worked

Installed TypeScript definitions covered queues, jobs, retry limits, backoff, expiration, and an executeSql-style database adapter. Queue creation in the library SQL was idempotent, which made dual API and worker startup workable.

What got in the way

Public documentation pages 404ed, so setup came from the installed package and searches. The documented database type was not exported. The package is ESM and failed to load in the existing CommonJS test runner, so queue integration tests were removed rather than run.

Chose pg-boss on Postgres as the durable queue, pinned 10.4.2 for Node 20, and implemented send, work, retries, singleton idempotency, and a dead-letter queue. Docs and registry metadata were enough to ship, but the current major was unusable and some published type URLs 404ed. The library was imported and typechecked, not run against a live database.

What worked

The 10.x API covered queues, retries, work handlers, and singleton keys. An older README plus package types from a CDN were enough to implement enqueue and consume.

What got in the way

Version 12 required Node 22. Two GitHub raw URLs for 10.4.2 types returned 404, so types had to be loaded from a CDN instead. Matching job ids to report ids was abandoned to avoid unique violations on recovered work.