Guides
Background jobs
A Postgres queue by default, workers and brokers when you need them.
export const sendReceipt = defineJob({
name: 'billing.send_receipt',
schema: z.object({ orderId: z.string() }),
run: async ({ orderId }, { db, mailer }) => { /* … */ },
});
await enqueue(tx, sendReceipt, { orderId }); // commits with the transactionAdd the job to modules/jobs/registry.ts. Jobs retry with backoff, so run must be safe to repeat. Payloads are stored in plain text: never put a token or secret in one. Recurring work goes in SCHEDULES.
Scaling
| Level | Setting | When |
|---|---|---|
| Inside the API | default | Almost always |
| Dedicated workers | WORKER_INLINE=false, run node dist/worker.js | Heavy jobs |
| A broker | QUEUE_DRIVER=rabbitmq, kafka or pubsub | You already run one, or volume outgrows polling |
With a broker, Postgres stays the record: the broker carries only the job's id.