Outbox Pattern
Write the business change and an outbox row in one local transaction, then relay outbox rows to the broker — solving the dual-write problem reliably.
By Ratish Jain · Updated
Definition
The outbox pattern ensures a database update and a message publish happen reliably together. Within a single local transaction, the service writes both its business change and an event row into an outbox table. A separate relay process later reads unpublished outbox rows and delivers them to the message broker.
Because both writes share one ACID transaction, they either both commit or both roll back — no lost or phantom events.
The Problem It Solves
The dual-write problem: a service that must update its database *and* publish an event to a broker has no atomic way to do both across two systems. If the DB commit succeeds but the publish fails (or vice versa), state and events diverge — a downstream consumer never learns about a committed order.
Distributed transactions (2PC) across a DB and a broker are impractical, so the outbox moves the event into the DB transaction itself.
How It Works
- 1The service begins a local DB transaction.
- 2It writes the business state change (e.g. insert the order).
- 3In the same transaction, it inserts an event row into the
outboxtable. - 4The transaction commits atomically — both rows persist or neither does.
- 5A relay polls the outbox (or reads the DB change log via CDC) for new rows.
- 6The relay publishes each event to the broker and marks the row as sent.
Expect at-least-once delivery
The relay may crash after publishing but before marking a row sent, causing redelivery. Consumers must be idempotent. Log-based CDC (e.g. Debezium reading the WAL) avoids polling overhead and captures every commit.
Tradeoffs
- Atomic state change + event via one local transaction.
- Eliminates the dual-write inconsistency.
- No distributed transaction across DB and broker.
- Works with polling or log-based CDC relays.
- Adds an outbox table and a relay component to operate.
- At-least-once delivery → consumers must be idempotent.
- Polling adds latency and DB load (CDC mitigates).
- Outbox table needs cleanup/retention management.
Interview Questions
That is the dual-write problem: the process can crash between the DB commit and the publish, so the state change persists but the event is lost. There's no atomicity across two independent systems. The outbox folds the event into the DB transaction to make it atomic.
CDC (log-based, e.g. Debezium reading the transaction log) captures every commit with low latency and no query load, and it's the preferred approach. Polling is simpler to build but adds latency and repeated queries against the outbox table.
- →Write business change + outbox row in one local transaction.
- →A relay publishes outbox rows to the broker afterward.
- →Solves the dual-write problem without 2PC.
- →Delivery is at-least-once → consumers must be idempotent.
- →Relay via polling or (preferably) log-based CDC.
Related
Everything on Archprimer is connected — follow the graph.