Choose the right durable-work shape

The same Postgres mechanics can power background jobs, outbox relays, projections, CDC consumers, webhooks, and short saga steps. The table shape changes because the source of truth changes.

Pick the established pattern by asking one question first: who owns the durable fact?

Start with the owner of the fact

Inbox, transactional outbox, projections, CDC, and sagas are not interchangeable names for the same table. They answer different ownership questions: did your API create work, did your domain transaction create a publish intent, did an event log create history, or did the WAL expose a row change?

The implementation still uses durable rows, claims, leases, retries, idempotency keys, and optional ordering guards. The difference is what the row represents.

Use an inbox for one-shot service-local work

Fire-and-forget jobs inside your service: send email, resize an image, call a partner API, or process a webhook payload. The producer and consumer share Postgres, or the producer writes rows that workers read.

Use an outbox when publish intent must commit with the domain write

You cannot publish to external message infrastructure inside the same ACID transaction as your UPDATE orders. The outbox makes intent durable in the same commit. A relay worker (same Competing Consumers loop) publishes at-least-once to your chosen transport. Downstream must dedupe, whether they consume from a broker or write an inbox row.

BEGIN;
UPDATE orders SET status = 'paid' WHERE id = 9182;
INSERT INTO outbox (partition_key, event_type, payload, idempotency_key)
VALUES (
  'order:9182',
  'OrderPaid',
  '{"order_id":9182,"paid_at":"2026-07-01T12:00:00Z"}'::jsonb,
  'evt-order-9182-paid-v1'
);
COMMIT;

Use a projection when replay is part of the contract

The event store is the source of truth. Search indexes and caches are derived views. Workers catch up stream by stream with checkpoints: poll the tail or consume via outbox/inbox push.

const checkpoint = await loadCheckpoint(streamId);
const events = await eventStore.readFrom(streamId, checkpoint + 1);
for (const evt of events) {
  await applyIdempotent(evt, { key: evt.id });
  await saveCheckpoint(streamId, evt.sequence);
}

Use CDC when the write path cannot add an outbox

CDC fits legacy tables or polyglot stacks where you cannot add outbox INSERTs to every write path. It reads the WAL and turns row changes into a stream. Prefer outbox for greenfield systems; use CDC when you need to integrate existing databases.

CDC vs outbox

Use saga steps for short durable cross-service progress

Multi-step processes across services need a durable place to remember progress. Each step is a row, and each successful step enqueues the next action or a compensation. Use partition_key = saga:{instanceId} so confirm and compensate steps stay ordered. This is suitable for short idempotent choreographies; it is not a full workflow engine.

async function deliverWebhook(row) {
  const sig = sign(row.payload, WEBHOOK_SECRET);
  const res = await fetch(row.payload.url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Idempotency-Key": row.idempotency_key,
      "X-Signature": sig,
    },
    body: JSON.stringify(row.payload.body),
  });
  if (!res.ok) throw new RetryableError(res.status);
}

Use a library unless the shape needs custom control

For ordinary background jobs, start with pg-boss, Graphile Worker, or River if one fits your stack. Keep the custom Postgres implementation when the shape needs guarantees the library does not expose cleanly.

• Outbox rows in the same transaction as domain writes with identical column semantics
• Custom lease_generation fencing passed to downstream stores
• One worker loop shared across inbox, outbox relay, and projection tables
• Full control over ordering guard and bucket claim queries

Source

Use the article for explanation, then use these files when you want the complete SQL and TypeScript in one place.

• Complete SQL
• Complete TypeScript
• Shared TypeScript helper