OOmnistu

Blog / Engineering Playbooks

Engineering Playbooks

Transactional outbox: when a saved order never reaches the next service

Understand the database-and-message dual-write gap, why an outbox relay can send duplicates, and which crash-recovery tests belong in your acceptance plan.

OOmnistu
Reviewed 2026-11-17 · 7 min read

Your application saves an order, then tells another service to reserve stock. The database commit succeeds. Before the notification is sent, the application crashes. The order exists, but the next service knows nothing about it.

Changing the sequence does not remove the problem. If you notify first and the database transaction later rolls back, the next service can act on an order that was never committed. These are two separate writes with a failure gap between them.

A transactional outbox addresses that gap by recording the business change and its outgoing event in the same database transaction. A separate relay publishes committed events. This article explains that boundary and its limits. It is an architectural guide with a hypothetical order example, not a claim about an existing Omnistu implementation.

What the outbox commits together

In a relational implementation, the transaction writes the order and an outbox row describing the event to publish. If either write fails, the transaction should roll back both. If it commits, both records exist for subsequent processing.

PostgreSQL's transaction tutorial explains the all-or-nothing behavior of a database transaction. That local guarantee does not automatically include a remote message broker or inventory API.

AWS's transactional-outbox guidance and Chris Richardson's pattern description describe moving the outgoing message into the same transaction as the business update. The application records a durable intent to notify; it does not claim that the downstream action has already finished.

For the hypothetical order, distinguish three states in the design:

  1. The order and outgoing event are committed.
  2. The event is accepted by the broker.
  3. The inventory service has processed it and recorded the reservation outcome.

A customer-facing message should not collapse all three into "stock reserved" unless the system has evidence for that result.

Give each event a stable identity

The event needs an identifier that remains the same when the relay retries it. It also needs enough context to identify the business record and interpret the event's meaning.

A proposed event record might include an event ID, order ID, event type, schema version and the information the consumer actually needs. The event ID and order ID serve different purposes: one identifies this occurrence; the other identifies the order whose events may need consistent processing.

Debezium's outbox event router makes a similar distinction between its unique event ID and aggregate ID. It documents using the event ID for duplicate handling and the aggregate ID as an event key important for Kafka partition ordering. Those are product-specific configuration details, not a rule that every queue uses identical columns.

Keep credentials, payment secrets and unnecessary personal data out of event payloads and logs. Decide which information must represent the original business event and which can safely be retrieved later. Fetching today's order state is not always equivalent to reading what happened when the event was recorded.

Expect the relay to repeat itself

A relay can poll committed outbox rows or use an appropriate database change-capture mechanism. Either approach needs monitoring and recovery ownership; adding a table alone does not deliver messages.

Consider this failure sequence:

  1. The relay publishes event E1 successfully.
  2. It crashes before recording that publication completed.
  3. After restarting, it finds E1 still pending.
  4. It publishes E1 again.

Richardson's pattern explicitly identifies this duplicate-publication window. Marking the event complete before sending it merely creates the opposite risk: a crash can leave an event recorded as sent when nothing reached the broker.

The design therefore needs a duplicate-aware consumer. A stable event ID should survive relay retries. If every attempt creates a new identity, the receiver may be unable to recognize the repeated event.

Make the consumer's effect safe too

For a consumer whose entire effect is inside one transactional database, one design is to record the processed event ID in the same transaction as the business update. Enforce uniqueness so concurrent attempts cannot both apply the effect. If the transaction rolls back, neither the effect nor the completion record should remain committed.

This is a design recommendation, not drop-in implementation code. Isolation, constraints, error handling and transaction boundaries must be checked against the actual database and application.

The boundary changes when the consumer calls an external service. A database row saying "email sent" cannot by itself make a remote email send atomic. Nor does a local processed-event record automatically prevent a payment provider from executing a request twice after an uncertain network result.

For external effects, investigate the provider's idempotency and reconciliation contract, retain the identity needed to recover the outcome, and distinguish pending from confirmed completion. Omnistu's API retry guide explains why a header alone is not duplicate protection. Its Stripe webhook checklist covers the separate task of receiving and reconciling payment events. An outbox does not replace either boundary.

Ordering requires a defined scope

An order-created event followed by an order-cancelled event may require different handling from two independent orders. Specify where order matters: per order, account, inventory item or another business key. Do not assume one global sequence is necessary or that timestamps alone enforce it across multiple publishers and consumers.

The AWS and Richardson guides both discuss preserving the order of related updates. Debezium documents event keys for partition ordering. The full design must also address concurrent updates, relay selection, broker behavior and consumer processing.

Agree what happens when a consumer receives a duplicate, an older event or a gap. Possible responses depend on the business operation: rejecting a stale state transition and fetching authoritative state are not interchangeable in every workflow.

A queue's delivery feature is not proof of one business effect

Read the precise scope of a broker's guarantee. For example, Amazon SQS documents FIFO send deduplication within a five-minute interval. Its visibility-timeout guidance also explains that an unprocessed, undeleted message becomes visible again after the timeout.

Neither statement proves that your database update, email, inventory reservation and payment operation form one indivisible action. Describe the guarantee at each boundary instead of advertising the entire workflow as "exactly once."

Test the crash boundaries before acceptance

A happy-path demonstration proves little about the failures the outbox is intended to handle. Use an appropriate test environment and inspect actual records and downstream effects for these cases:

Define an operator's view of pending work, oldest unpublished event, repeated failures and recovery actions. Decide retention and cleanup from recovery needs rather than deleting every event immediately after a successful test. Do not silently discard an event that cannot be processed; record the failure and assign a review path.

When not to add the machinery

Not every application needs a broker, change-data-capture pipeline and multiple services. First identify the actual consistency problem. If the required work fits within one local transaction, an outbox may add operating cost without solving a real cross-system boundary.

Where asynchronous work is justified, request a diagram of the commit, relay and consumer boundaries, then ask the team to demonstrate the failure tests. The deliverable is evidence that committed work can be recovered without unintended duplicate effects, not merely a screenshot of a queue dashboard.

Sources and scope

Reviewed 17 November 2026. This AI-drafted synthesis was checked against the linked primary documentation and independent pattern reference. The order example and acceptance tests are illustrative recommendations. No benchmark, loss-prevention guarantee, provider endorsement or claim of an already-deployed Omnistu system is made.

All storiesAPI retry guide