← All patterns
Data consistency · Architecture pattern

Transactional outbox

Commit a business change and its event record in one database transaction.

The problem

An order commits, then its event publish fails. Other services never learn that the order exists.

When it fits

A local database change must eventually cause a message, and the producer can persist an outbox record in the same transaction.

The whole architecture

Architecture diagram

Business state and an outbox record commit locally; a relay publishes retained events to a broker.

Blue arrows are writes; purple arrows are committed-event handoffs.

100%

Scroll to pan. Select a component for its role.

transactional outbox architectureBusiness state and an outbox record commit locally; a relay publishes retained events to a broker. Blue arrows are writes; purple arrows are committed-event handoffs.One local SQL transactionConsumer transaction domainproducer → business: state writeproducer → outbox: event recordoutbox → relay: committed entriesrelay → broker: publishbroker → consumer: deliverconsumer → consumer-sql: commit effect + IDstate writeevent recordcommitted entriespublishdelivercommit effect + IDThe producer commits its state and event record in one SQL transaction.Producer APIBusiness operationThese tables share the transaction boundary with the outbox.Business tablesAuthoritative stateOnly committed outbox entries are eligible for publication.Outbox tableStable event identityA crash after publish can cause the same event to be sent again.Outbox relayPoll or committed feedPublication acknowledgment is distinct from a consumer effect.Message brokerRetained event deliveryThe handler must handle duplicate event delivery.ConsumerIdempotent handlerPersist the effect and deduplication record atomically where that local contract is supported.Consumer SQLEffect + processed ID

Select a component, or focus it and press Enter, to read its role.

Walk through the design

Follow one operation

Select a step to highlight its participants. This conceptual walkthrough is separate from challenge scoring.

Arrows show the conceptual relationships used by this walkthrough.

AppActive in this stepSQL + outboxActive in this stepRelayWaitingBrokerWaiting
Step 1 of 3

Write one local transaction

App writes the order and its event record in the same SQL transaction.

Trade-offs to make explicit

  • The atomic boundary covers business state and the outbox record, not the later broker publish.
  • A relay adds delivery lag, cleanup and monitoring. Consumers still need duplicate handling and ordering rules.

Failure modes to plan for

  • A relay crash after publishing but before marking delivery can publish the same event again.
  • An unmonitored relay can leave committed events waiting indefinitely. Track oldest undelivered age.
Before you build

Explain your decision

How would a consumer deduplicate an event without losing its effect if it crashes midway?

Use Plan & estimate inside practice to record your assumptions and trade-offs.

Connect concept to practice

Related challenges

Browse challenges →

These links open the original challenges. Existing round unlocks, completions and points apply.

Rebuild search while writes continue

Related practice in committed change capture and replay. It models CDC recovery, not a complete transactional-outbox protocol.

Open challenge →

One transfer, two attempts

Practice stable identities and atomic deduplication within one SQL domain.

Open challenge →

Further reading

AWS · Transactional outbox ↗

Original PractiseGrid explanations and conceptual diagrams, with primary references for further study. Dedicated scored exercises can be added as coverage grows.