Recommended Free Tools
If the business database and outbox row committed but a downstream ledger has no matching event, the local transaction likely did its job: it durably recorded both the business change and the work to publish. The missing downstream record points to the relay, broker, consumer, or processing lag—not necessarily a lost database update. The transactional outbox prevents one important dual-write failure, but it does not make delivery or downstream processing automatic or exactly once.
What “the outbox held” actually proves
In this title, “ledger” means the downstream system expected to reflect an event; it does not identify a specific ledger product. A committed outbox row proves that the service recorded a publication task in its own database transaction. It does not prove that a relay read the row, a broker accepted a message, a consumer received it, or the consumer committed its own update.
The transactional outbox addresses the dual-write gap between a service’s database and its message broker. AWS describes the pattern as resolving the inconsistency that can arise when an operation must write to a database and send an event notification (AWS Prescriptive Guidance).
Why the database can change while the event does not arrive
A database commit and a broker publish are separate operations unless they share a transaction mechanism. In a direct dual write, the service might commit the business change and then publish, or publish first and then commit the database change. A crash, timeout, or broker outage between those operations can leave one side updated and the other untouched. AWS documents both failure directions in its explanation of the pattern (AWS Prescriptive Guidance).
#1 Best Overall
With an outbox, the service instead writes its business data and an event row in the same local database transaction. If either write fails, the transaction rolls back; if it commits, both records exist together. A separate relay then publishes committed outbox entries. AWS’s EventBridge Pipes example uses this approach to save order and event information atomically before downstream publication (AWS Compute Blog).
Trace the missing event through the pipeline
- Confirm the local transaction. Check the business record and its outbox row using the same transaction or correlation identifier. If the row is absent, investigate the application path, rollback, or transaction boundary; there is no durable publication task for a relay to send.
- Check relay progress. For a polling relay, verify that it is running, selecting eligible committed rows, and not stuck on a failed record. For a CDC-based relay, inspect connector health, captured changes, offsets, and recovery state.
- Check broker acceptance and routing. Establish whether the broker accepted the event and whether it was routed to the expected destination. A relay can fail before publish, or a successful publish can still be followed by a routing or subscription issue.
- Check consumer processing. Look for consumer lag, deserialization or schema errors, retries, dead-letter handling, and failures while committing the downstream update. Distinguish “message delivered” from “ledger transaction committed.”
- Reconcile before replaying. Compare event identifiers and downstream state before retrying or republishing. A retry may be necessary, but an already-processed event can be delivered again.
Choose polling or change data capture
A polling relay reads pending rows from the outbox table and publishes them. Change data capture (CDC) reads committed changes from a database change stream or transaction log and routes the outbox event to a broker. Debezium’s Outbox Event Router is one documented CDC option (Debezium Outbox Event Router).
| Decision area | Polling an outbox table | CDC / change stream |
|---|---|---|
| Database support | Requires a transactional table and a relay that can query it. | Requires a supported change stream or transaction log and a functioning connector. |
| Operational responsibility | Operate the poller, query path, retry policy, and publish state. | Operate connectors, offsets, recovery, and schema evolution. |
| Latency | Depends on poll frequency and relay workload. | Depends on change-stream and connector processing; neither method guarantees a particular latency. |
| Ordering | Can use timestamps or sequence numbers to preserve required notification order; AWS identifies these as useful ordering aids. | Must preserve and validate the required ordering through capture, routing, and consumption; CDC alone does not define domain ordering. |
| Duplicates and retries | Retries may republish a row when the relay cannot know whether a prior publish succeeded. | Recovery and redelivery can also produce repeated events; consumer behavior must match the delivery semantics. |
| Retention and cleanup | Define when published rows can be deleted or archived without removing work needed for recovery. | Manage outbox retention as well as connector offsets and the database log’s retention constraints. |
| Monitoring and recovery | Monitor oldest pending row, backlog, publish errors, and relay progress; retry or inspect stuck entries. | Monitor connector status, offsets, lag, schema errors, and recovery progress. |
Polling is a direct fit when the database supports the required transaction and a team can operate a relay and its backlog. CDC can avoid repeated table polling, but moves responsibility to connector and change-stream operations. Neither approach removes the need to handle retries, schema changes, ordering requirements, retention, or recovery. AWS describes both table-based and change-capture approaches (AWS Prescriptive Guidance).
Design consumers for redelivery
An outbox makes the database update and event record atomic; it does not make the relay-to-broker-to-consumer path exactly once. A relay can publish successfully and fail before marking its row complete, or a broker can redeliver a message. The same event may therefore reach a consumer more than once. AWS warns that standard queue delivery can duplicate messages and recommends idempotent consumers (AWS Prescriptive Guidance).
Give each event a stable identifier and make the consumer’s effect safe to repeat. Commonly, the consumer records processed identifiers in the same local transaction as its business update, or applies an update whose repeated execution has the same result. The right technique depends on the consumer’s storage and operation; the essential requirement is that a retry must not apply the business effect twice.
Preserve order only where the domain requires it
Some events can be processed independently; others must be applied in sequence, such as successive changes to one account or order. Decide the ordering key and scope explicitly. Timestamps or sequence numbers can help a relay preserve notification order, as AWS notes, but consumers must also avoid applying later events ahead of earlier ones when the domain depends on sequence. A global ordering requirement can constrain throughput, so prefer ordering within the smallest meaningful entity or partition where that is sufficient.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Know where the outbox stops
The outbox coordinates one service’s database write with publication of that service’s event. It does not create an atomic transaction across independent service databases. If a workflow spans multiple services and their separate stores must reach a coordinated outcome, model the workflow as a saga, with steps and compensating actions or orchestration appropriate to the business process. AWS distinguishes the outbox’s local dual-write role from saga coordination across services (AWS Prescriptive Guidance).
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →
