~/notes/transactional-outbox

Transactional Outbox

The Transactional Outbox pattern writes the business state change and an outbox message in the same local database transaction.

Aug 20, 2026

diagram
ConsumerMessage BrokerOutbox RelayBusiness Database and OutboxApplicationloop[Publish pending outboxrows]Consumers remain idempotentBegin local transactionWrite business stateWrite outbox messageCommit both atomicallyRead pending messagesOutbox batchPublish eventACKMark message publishedDeliver event
ConsumerMessage BrokerOutbox RelayBusiness Database and OutboxApplicationloop[Publish pending outboxrows]Consumers remain idempotentBegin local transactionWrite business stateWrite outbox messageCommit both atomicallyRead pending messagesOutbox batchPublish eventACKMark message publishedDeliver event

Pros

  • Records a business change and the plan to publish its event in a single, atomic action.
  • Keeps committed publication work safe, even if the broker goes down.
  • Allows the relay to retry on its own, separate from the original request transaction.

Drawbacks

  • Needs a relay, outbox cleanup, lag monitoring, and a way to recover from failures.
  • At-least-once publication might create duplicates, so consumers need to be idempotent.
  • Maintaining order across transactions, aggregates, or partitions requires careful planning.