The dual-write failure window
An application often needs to update its database and notify another system. If it commits the database first and message publication fails, downstream work may never learn about the change. If it publishes first and the database rolls back, downstream work may act on an event that should not exist.
The transactional outbox pattern records the business change and an event intent within the same local database transaction. A separate publisher later delivers the recorded intent. AWS's pattern guidance describes this dual-write problem and warns that consumers still need to handle duplicate delivery. The pattern is not a universal distributed exactly-once guarantee.
Setup: define the event and ownership
Specify the event identity, aggregate or business key, payload version and required ordering. Identify the publisher's polling or change-stream mechanism, retry policy and terminal-failure owner. Keep the payload limited to the information downstream consumers need; avoid copying secrets into a broadly accessible event history.
Create the outbox record in the same supported transaction as the business write. A separate database call made afterward recreates the failure window. Document how publication state is recorded and how operators can distinguish pending, attempted and confirmed work without manually editing business records.
Illustrative incident: the order exists, the warehouse never hears
An illustrative order service commits a synthetic order and then loses connectivity to its message broker. Without a durable publication intent, a restart leaves no clear list of missing notifications. With an outbox, the pending event remains available for recovery. This is a teaching scenario, not a customer architecture or measured result.
Test the boundary by stopping the publisher after the database commit. Correlate business operation identity, outbox identity and delivery attempts. A log entry saying publish requested is not equivalent to a durable event record.
Troubleshooting: inspect recovery evidence
| Observation | Evidence | Investigation |
|---|---|---|
| Business change has no event intent | Transaction boundaries and write paths | Did an alternate path bypass the outbox? |
| Pending age grows | Publisher health and broker responses | Is delivery blocked or under-capacity? |
| Consumer sees duplicates | Publish acknowledgment window and event identity | Does repeated delivery converge safely? |
| Events arrive out of business order | Partitioning and per-key sequence | Is ordering preserved where required? |
Do not delete old pending rows merely to make backlog charts improve. They may represent accepted business changes whose notification has never been delivered. Establish reconciliation before cleanup.
Corrective action and publisher lifecycle
Make the local transaction boundary explicit and ensure every relevant write path uses it. Bound publisher concurrency and retries, and prevent multiple workers from losing ownership of the same work. Retain a durable event identity so a repeated publish can be recognized downstream.
Design consumers to record completed event identities or another appropriate business deduplication mechanism. A publisher can fail after the broker accepts a message but before local confirmation is stored. Recovery may therefore publish again. Keep schema evolution and ordering rules explicit so old retained events remain interpretable during replay.
Verification, propagation SLO and SOP
Test rollback of the business transaction, broker outage, publisher restart, duplicate delivery and a consumer failure after its own durable effect. Confirm that committed eligible changes eventually produce the intended downstream result and rolled-back changes do not. Inspect final business state, not only message counts.
An internal propagation SLO can measure age from committed event intent to accepted downstream outcome. Broker uptime and publisher throughput are supporting indicators. A commercial SLA requires separate terms. The SOP should name replay authority, ordering constraints, retention, terminal failures and reconciliation evidence. Avoid claiming that adding an outbox removes every consistency problem from a distributed workflow.
See custom application development and DevOps automation.
Technical reference
AWS transactional outbox pattern, reviewed 19 October 2026. Follow documentation matching the installed product version.