The transactional outbox: consistent events without distributed transactions
Event-driven services must do two things atomically: change their own state and tell the rest of the system about it. Doing both directly – write the row, then publish the message – fails in ways that are rare in testing and certain in production. The transactional outbox makes the change and the announcement a single local commit.
Tämä sisältö on toistaiseksi saatavilla vain englanniksi.
The dual-write problem
Consider a service that creates an order and publishes OrderCreated. If it commits the database transaction first and then publishes, a crash between the two steps leaves an order that no other service knows about. If it publishes first and then commits, a failed commit leaves an event describing an order that does not exist. Retrying the publish after a timeout may produce duplicates. None of these failures show up in a happy-path test.
Two-phase commit across the database and the broker would solve this in theory, but most brokers do not support it, it couples availability of both systems, and it adds latency to every write. The outbox pattern accepts a weaker but sufficient guarantee: the event is published eventually and at least once if and only if the state change committed.
How the outbox works
The service adds an outbox table to its own database. In the same transaction that changes business state, it inserts a row describing the event: an ID, the aggregate type and key, the event type, a payload and a timestamp. Because both writes are in one local transaction, they commit or roll back together.
A separate relay reads committed outbox rows and publishes them to the broker. There are two common relay designs:
- Polling publisher: a worker selects unpublished rows in order, publishes them and marks them as sent. It is simple and works with any database, at the cost of polling load and some latency.
- Change data capture (CDC): a connector reads the database’s transaction log and turns inserted outbox rows into broker messages. Debezium’s outbox event router is a widely used implementation. CDC adds infrastructure but gives low latency and no polling queries.
Ordering and partitioning
Consumers usually need events for the same entity in order: OrderCreated before OrderPaid before OrderShipped. Global ordering is expensive and rarely needed. Instead, partition broker topics by aggregate key – the order ID – so that all events for one order land in the same partition and are consumed in commit order.
The relay must preserve that order. A polling publisher should process rows for the same aggregate sequentially; a CDC connector follows the transaction log, which is already ordered. Parallelism comes from many aggregates, not from reordering events of one aggregate.
If a consumer receives an event whose aggregate version is not the next one it expects, it should neither apply it blindly nor drop it silently. Parking the event and retrying after a short delay, or fetching the current state from the producer, keeps projections correct when redeliveries and rebalances shuffle timing.
Idempotent consumers
The outbox guarantees that no committed event is lost, but a relay that crashes after publishing and before marking a row as sent will publish it again. Brokers themselves redeliver after consumer failures. Every consumer must therefore tolerate duplicates.
The standard technique is an inbox or processed-messages table in the consumer’s database: record the event ID in the same transaction as the consumer’s state change, and skip events whose ID is already present. Where the effect is naturally idempotent – setting a status to a value, upserting a projection – the table may be unnecessary, but it is cheap insurance.
Operating the pattern
Outbox tables grow. Delete or archive published rows on a schedule, keeping enough history to replay recent events if a downstream projection must be rebuilt. Monitor the age of the oldest unpublished row: it is the single best indicator that the relay is stuck. Monitor consumer lag per partition and route events that repeatedly fail to a dead-letter topic with enough context to investigate.
Event schemas are public contracts. Version them, evolve them in backward-compatible ways – add optional fields, never change meaning – and test consumers against producer schemas in CI so that a change cannot be deployed if it breaks a known consumer.
Event design that survives change
An outbox only moves events reliably; it cannot make badly designed events useful. Two styles dominate. Notification events carry an identifier and a type – “order 123 changed” – and consumers call back to fetch details. They keep payloads small but create read traffic and temporal coupling. State-carrying events include the relevant data, so consumers can act without calling back. They make the producer’s schema a public contract but scale much better.
Whichever style you choose, include an event ID, the aggregate ID and version, the event type with an explicit schema version, an occurrence timestamp and a correlation ID that links the event to the originating request. The aggregate version lets consumers detect gaps and out-of-order delivery; the correlation ID makes distributed traces readable.
Avoid publishing the internal database row as the event. Tables change for storage reasons that consumers should never see. A deliberate event payload, mapped from the domain model inside the same transaction, keeps the freedom to refactor storage without breaking every downstream team.
Finally, decide early how long events are retained in the broker and whether consumers may rebuild their state by replaying the topic from the beginning. If they may, the retention and compaction settings become part of the contract.
Esimerkki: Order service with CDC relay
An order service on PostgreSQL inserts into orders and outbox in one transaction. Debezium reads the write-ahead log and routes outbox rows to the topic orders.events, using the order ID as the message key so that all events of one order share a partition. The payment and notification services keep a processed_events table keyed by event ID. During a broker outage the outbox accumulates rows and the alert on “oldest unpublished event older than 60 seconds” fires; when the broker recovers, the connector resumes from its stored log position and consumers ignore the few duplicates delivered around the restart. No order was lost or announced twice in effect.
Yleiset sudenkuopat
- Publishing to the broker inside the database transaction and assuming a rollback also un-publishes.
- Using a random partition key, which destroys per-entity ordering.
- Consumers without deduplication, so redeliveries apply effects twice.
- Letting the outbox table grow without archiving.
- Changing the meaning of an existing event field instead of adding a new version.
Kysymyksiä ja vastauksia
Is the outbox only for microservices?
No. Any system that must update its own data and notify another system – including a monolith feeding a search index or a partner integration – benefits from the same guarantee.
Polling or change data capture?
Start with polling if volumes are modest and operations should stay simple. Move to CDC when latency or database load from polling becomes a problem, or when you already operate a CDC platform.
Does this give exactly-once delivery?
It gives at-least-once delivery with exactly-once effects when consumers are idempotent. That combination is what most systems actually need.
Tarkistuslista
- Identify every place that writes state and publishes an event.
- Add an outbox table and write events in the same transaction.
- Choose a relay: polling publisher or CDC.
- Partition topics by aggregate key and preserve per-key order.
- Make every consumer idempotent with an inbox table or natural idempotency.
- Alert on outbox age, consumer lag and dead-letter volume.
- Version event schemas and test consumers against them in CI.
Ensisijaiset lähteet
- Richardson, C., Microservices Patterns, Manning, 2018 – “Transactional outbox” and “Idempotent consumer” patterns
- Debezium documentation – Outbox Event Router
- Kleppmann, M., Designing Data-Intensive Applications, O’Reilly, 2017 – chapter 11, Stream Processing
- PostgreSQL documentation – Write-Ahead Logging and logical decoding