Deploying the Outbox
What the outbox needs in production: PostgreSQL 17, two role settings, the queue and cron the deploy creates, and its connection budget.
The deploy creates the outbox's queue (outbox) and cron trigger (*/5 * * * *) with the rest of the Worker (Deploy to Production). These are the extra checks.
PostgreSQL 17 or Newer
The outbox bounds every settlement with transaction_timeout, which PostgreSQL added in 17. vp run deploy checks the server first and stops before anything migrates if it's older:
deploy: the outbox needs PostgreSQL 17 or newer; DATABASE_URL's server is 16.4. Nothing was deployed.Upgrade the database (or create a 17+ one), then deploy again.
Two Role Settings
Run once, as the database owner, for the role DATABASE_URL connects as (the app role; the outbox uses the same one):
-- ends a session left inside an open transaction (a Worker killed mid-job), releasing its locksALTER ROLE app_role SET idle_in_transaction_session_timeout = '60s';-- a statement waiting on a lock fails instead of queueing behind itALTER ROLE app_role SET lock_timeout = '5s';Replace app_role with your role (SELECT current_user;). The first is required: without it, a transaction orphaned by a dead isolate can hold row locks until its connection closes, which a pooled connection may never do. Both apply to new sessions only: Hyperdrive's existing connections pick them up as they're recycled. Normal app transactions finish well inside both limits. lock_timeout applies to everything the role runs, void deploy's migrations included: a migration that waits more than 5 seconds for a lock fails instead of stalling the app behind it; rerun it at a quieter moment. Set them on the role, never with SET in code: Hyperdrive pools sessions, and a session SET leaks to the next client.
Connection Budget
Each running queue consumer holds one Postgres connection while it works; each sweep or schedule tick holds one more. Void can't cap how many consumers Cloudflare runs at once, so a burst of jobs can use more connections than usual. Hyperdrive pools them near your database, but keep your plan's connection limit well above your app's own traffic. If you hit it, spread enqueues out (delayMs).
Lost Messages
Void's queues have no dead-letter queue: a message that exhausts its retries is dropped. That's safe here, because the job row is the record and the sweep runs it within 5 minutes.
Gradual Rollouts
The Worker gets its version metadata (CF_VERSION_METADATA, set in void.config.ts), so during a gradual rollout an older version skips jobs a newer one enqueued, whose payload it may not understand. Change payloads additively anyway (Jobs).
Upgrading the Package
@makerkit/workers-outbox owns the outbox.job and outbox.attempt tables. After bumping it:
pnpm --filter web exec void db generate, and review the SQL:outbox.jobis written by every enqueue, so prefer migrations that don't lock it for long.pnpm test:unit:apps/web/db/__tests__/outbox.test.tschecks the migrated schema matches the package's own definition, column by column and index by index.- Commit the migration with the bump.
After the First Deploy
Two things only a real deploy shows. Check them once:
- The cron runs: in the dashboard, Worker → Settings → Triggers lists
*/5 * * * *, and the Worker's Logs show a scheduled invocation every 5 minutes with nooutbox phase_failedoroutbox infra_errorentries (those mean the sweep can't reach the database). - Jobs run through Hyperdrive: enqueue one (any action that does) and see its row reach
succeededwithin seconds.