What happens if your database successfully commits a transaction, but your Message Broker becomes unavailable at exactly the same moment ?
Imagine a user places an order in an online store, and the order is successfully stored in the database:
Order #123 → Created
A few milliseconds later, your service tries to send an OrderCreated event to Kafka or RabbitMQ, and suddenly:
- The network goes down.
- The Broker becomes unavailable.
- The application crashes.
- A timeout occurs.
So what happens ?
The database says:
The order has been created.
But the other services say:
We have no idea about this order!
This is one of the classic problems in distributed systems and Microservices architecture: the Dual Write Problem.
This is where the Outbox Pattern comes in.
The Core Idea Behind the Outbox Pattern
The idea behind the Outbox Pattern is surprisingly simple.
Instead of writing to the database and Message Broker at the same time, we store the business data change and the corresponding message/event in the same database transaction.
We then delegate message publishing to a separate process.
This small change in architecture can make a significant difference to system reliability.
What Is the Outbox Pattern ?
The Outbox Pattern, or more precisely the Transactional Outbox Pattern, is a design pattern for reliably sending messages and events in distributed systems.
Instead of having the application directly publish an event to a Message Broker after modifying the database, the application first stores the event in an Outbox Table in the same database.
The most important point is this:
The business data change and the event stored in the Outbox must happen within the same database transaction.
A separate process then reads events from the Outbox and sends them to the Message Broker.
At a high level:
Application
│
│ Transaction
▼
┌───────────────────────┐
│ Database │
│ │
│ Orders │
│ Outbox Events │
└───────────┬───────────┘
│
│ Async
▼
Outbox Publisher
│
▼
Message Broker
│
┌────┴────┐
▼ ▼
Service A Service B
Why Do We Need the Outbox Pattern ?
To understand the Outbox Pattern, we first need to understand the problem it solves.
Suppose we have an Order Service that needs to perform two operations:
- Store the order in the database.
- Send the
OrderCreatedevent to Kafka.
Our code might initially look like this:
BEGIN TRANSACTION
INSERT INTO orders (...)
COMMIT
publish(OrderCreated)
At first glance, this seems reasonable.
But there is a dangerous gap between COMMIT and publish().
What happens if the database commits successfully but the application crashes before publishing the event ?
Database
│
└── Order Created ✅
Message Broker
│
└── OrderCreated ❌
Now the system is in an inconsistent state:
- The internal business state has changed.
- The corresponding event was never published.
AWS also describes Transactional Outbox as a solution to the Dual Write problem: a situation where one logical operation needs to modify both a database and a messaging system, while failure in one of them can leave the systems inconsistent.
What Is the Dual Write Problem ?
A Dual Write occurs when one logical operation needs to be writtern into two independent systems.
For example:
Database
+
Kafka
Or:
Database
+
RabbitMQ
Or even:
Database
+
External API
The problem is that we usually don't have a shared transaction between these two systems.
For example:
1. UPDATE database ✅
2. SEND message ❌
Or the opposite:
1. SEND message ✅
2. UPDATE database ❌
In the first case, the event is lost.
In the second case, an event has been published even though the corresponding business state does not actually exist.
Why Isn't a Normal Database Transaction Enough ?
You might say:
Why don't we simply put message publishing inside the transaction ?
The problem is that the database and Message Broker are two independent resources. To make the entire operation atomic, we would need some form of distributed transaction.
One classic approach is Two-Phase Commit, or 2PC.
In 2PC, a coordinator asks all participants:
Are you ready to commit your changes ?
Only when all participants agree, the coordinator instruct them to perform the final commit.
If one participant has a problem, the entire operation can be stopped.
This approach is theoretically attractive, but modern distributed architectures can introduce problems such as:
- Complexity
- Latency
- Coupling
- Failure handling
In addition, not every database or Message Broker supports distributed transactions in the same way.
The Outbox Pattern asks a different question:
Do we really need the database and Broker to participate in one transaction ?
The answer is:
No.
Instead, we can reliably record the critical operation in a local database transaction and defer message publishing until afterward.
How Does the Outbox Pattern Solve the Dual Write Problem ?
Instead of:
Database → Commit
Broker → Publish
we use:
Database
├── Business Data
└── Outbox Event
For example:
BEGIN;
INSERT INTO orders (id, customer_id, status) VALUES (123, 456, 'CREATED');
INSERT INTO outbox (id, aggregate_type, aggregate_id, event_type, payload) VALUES ('event-789', 'Order', 123, 'OrderCreated', '{...}');
COMMIT;
If the transaction succeeds:
Order ✅
Outbox Event ✅
If the transaction fails:
Order ❌
Outbox Event ❌
The database guarantees that both changes are committed or rolled back together.
This is the key idea behind the Outbox Pattern.
What Is an Outbox Table ?
An Outbox is usually just a normal database table.
For example:
CREATE TABLE outbox (
id UUID PRIMARY KEY,
aggregate_type VARCHAR(100),
aggregate_id VARCHAR(100),
event_type VARCHAR(200),
payload JSONB,
created_at TIMESTAMP,
processed_at TIMESTAMP NULL
);
The actual schema can vary depending on your system's requirements.
Common fields include:
1. id
A unique identifier for the event.
This ID is extremely important for Deduplication and Idempotency.
2. aggregate_id
For example:
order_id = 123
This field can be important for maintaining event ordering in many architectures.
3. event_type
For example:
OrderCreated
OrderPaid
OrderCancelled
4. payload
The actual event data:
{
"orderId": 123,
"customerId": 456,
"totalAmount": 250
}
5. created_at
The time at which the event was created.
6. processed_at
With a polling-based implementation, this field can be used to identify events that have already been processed.
How Does the Complete Outbox Flow Work ?
Let's look at the complete flow:
Client
│
▼
Order Service
│
│ BEGIN TRANSACTION
├────────────────────────┐
│ │
▼ ▼
Orders Table Outbox Table
│ │
└──────────┬─────────────┘
│
COMMIT
│
▼
Outbox Publisher
│
▼
Message Broker
│
┌──────┴──────┐
▼ ▼
Inventory Notification
Service Service
Step by step:
- The Client sends a request to create an Order.
- The Order Service starts a Transaction.
- The Order is stored in the database.
- The corresponding Event is stored in the Outbox.
- The Transaction is committed.
- An Outbox Publisher reads the event from the Outbox.
- The Event is sent to the Message Broker.
- Different Consumers receive the Event.
- After successful publishing, the Outbox Event is cleaned up or marked as processed.
An important detail is that the application does not need to wait for the Broker for the original request to succeed.
This means event publishing can happen asynchronously.
A Real-World Example: Creating an Order
Suppose a user creates order 1001.
Step 1: Create the Order
POST /orders
The application starts a transaction.
Step 2: Store the Order
orders
id: 1001
status: CREATED
Step 3: Store the Event
Inside the same transaction:
outbox
id: event-abc
event_type: OrderCreated
aggregate_id: 1001
Step 4: Commit
If the commit succeeds:
Order → persisted
Event → persisted
Now, even if the application crashes immediately afterward, the event has not been lost.
Step 5: Publish the Event
The Publisher eventually sends:
Kafka → OrderCreated
Step 6: Consumers Process the Event
For example:
Inventory Service:
OrderCreated
↓
Reserve Stock
Notification Service:
OrderCreated
↓
Send Confirmation Email
Analytics Service:
OrderCreated
↓
Record Conversion
This is where the Outbox Pattern becomes especially useful for Event-Driven Architecture.
Does the Outbox Pattern Prevent Duplicate Messages ?
No.
This is one of the most important things to understand about the Outbox Pattern.
The Outbox Pattern can ensure that an event is not lost, but it does not necessarily guarantee that the event will be published exactly once.
Consider this sequence:
- The Publisher reads the event.
- The Publisher sends the event to Kafka.
- Kafka successfully receives the message.
- The Publisher crashes before marking the event as processed.
After the Publisher restarts:
Publisher
↓
"This event is still unprocessed"
↓
Publish Again
As a result, OrderCreated may reach the Consumer twice.
This behavior is normal and is associated with At-Least-Once Delivery.
AWS's Transactional Outbox guidance also discusses duplicate messages and the need for idempotent Consumers.
Idempotency: The Other Half of the Story
If you use the Outbox Pattern, you need to ask:
What happens if the same event reaches a Consumer twice ?
For example:
PaymentCompleted
Suppose the Consumer processes the event twice and each time performs:
$100 → Charge Customer
The customer could potentially be charged twice.
The Consumer therefore needs a way to detect duplicate events.
One common approach is to maintain a table such as:
processed_events
event_id
--------
event-123
event-456
Before processing:
Does event-123 exist ?
If it exists:
Ignore
If it doesn't:
Process
Insert event_id
Ideally, these operations should also happen inside a transaction.
This makes the Outbox Pattern and the Idempotent Consumer Pattern complementary solutions.
Does Outbox Mean Exactly-Once Delivery ?
This is where terminology matters.
You sometimes hear:
The Outbox Pattern provides Exactly-Once Delivery.
That statement is an oversimplification.
The Outbox Pattern by itself does not provide an exactly-once guarantee.
A more realistic architecture looks like this:
Producer
↓
Outbox
↓
At-Least-Once Publish
↓
Idempotent Consumer
This combination can provide much more reliable behavior in terms of the final business state.
However, if the Consumer calls an external API, guaranteeing exactly-once behavior across the entire chain becomes much more complicated.
The important point is:
Exactly-once is not simply a property of one component; it is an end-to-end property.
How Is an Outbox Event Published to the Broker ?
There are two common approaches:
Approach 1: Polling Publisher
With polling, a worker periodically queries the Outbox table.
For example:
SELECT * FROM outbox WHERE processed_at IS NULL ORDER BY created_at LIMIT 100;
The workflow is:
Read
↓
Publish
↓
Mark as processed
The biggest advantage of polling is simplicity.
You don't need your system to work directly with the database's Transaction Log. Almost any database that supports queries can be used to build this type of architecture.
However, polling has a latency trade-off.
For example, if you poll every five seconds, an event created immediately after a polling cycle might have to wait almost five seconds before being detected.
If you poll more frequently:
100ms
50ms
10ms
you increase the load on the database.
So you have a trade-off:
Polling Frequency
↕
Latency
↕
Database Load
Approach 2: Change Data Capture (CDC)
With Change Data Capture (CDC), instead of repeatedly querying the Outbox table, we track changes in the database's Transaction Log.
For example:
Application
↓
Database
↓
Transaction Log
↓
CDC Connector
↓
Message Broker
Different databases may use transaction logs such as:
WAL
Binlog
Redo Log
Tools such as Debezium can capture changes to an Outbox Table from the Transaction Log and transform them into events.
Debezium also provides a dedicated Outbox Event Router for this scenario.
Advantages of CDC
- Lower latency
- Less continuous polling
- Suitable for high throughput
- Better alignment with Transaction Log changes
Disadvantages of CDC
- More architectural complexity
- More infrastructure and monitoring requirements
- Dependency on database capabilities
- Higher operational complexity
Therefore, CDC is not necessarily better than polling. It is simply more appropriate for certain scales and latency requirements.
Polling or CDC: Which Should You Choose ?
If your system is still relatively new, polling can be a straightforward approach.
If event volume is high and low latency is particularly important, CDC can become a more suitable option.
The choice ultimately depends on factors such as:
- Event volume
- Latency requirements
- Database capabilities
- Operational complexity
- Infrastructure maturity
Does the Outbox Pattern Preserve Event Ordering ?
Not automatically, and not in every architecture.
Suppose we have:
OrderCreated
OrderPaid
OrderShipped
A Consumer may need to receive these events in exactly this order.
If it receives:
OrderShipped
OrderCreated
OrderPaid
the business logic could behave incorrectly.
Therefore, ordering needs to be designed intentionally.
For example:
aggregate_id = order-123
You can then route events belonging to the same Aggregate to the same Partition in the Message Broker.
With Kafka, a Partition Key can help ensure that events for a particular Aggregate are placed in the same Partition and processed in order within that Partition.
The important distinction is:
The Outbox Pattern and Message Ordering are related, but they are separate problems.
What Happens to the Outbox Table Over Time ?
Suppose your system generates:
1,000 events / second
That's approximately:
86,400,000 events / day
If you never delete or archive processed events, the Outbox table will grow rapidly.
This can lead to:
- Increased database size
- Larger database indexes
- Heavier backups
- Slower queries
- Higher storage costs
Therefore, an Outbox needs a Lifecycle Strategy.
For example:
Pending
↓
Published
↓
Retention Period
↓
Delete / Archive
Three Common Strategies
1. Delete
Delete events after they have been successfully published.
This is simple and inexpensive, but it makes historical replay more difficult.
2. Archive
Move events to another storage system after a certain period.
This can be more useful for:
- Auditing
- Debugging
- Historical analysis
3. Partitioning
Partition the table based on time.
For example:
outbox_2026_09_18
outbox_2026_09_19
outbox_2026_09_20
Old partitions can then be deleted or archived efficiently.
Advantages of the Outbox Pattern
1. Preventing Lost Events
The most important advantage of the Outbox Pattern is that when the Business Transaction commits, the Event is also stored.
Therefore, if the Publisher crashes immediately after the commit, the Event is not lost.
2. No Need for 2PC
The database and Broker do not need to participate in a shared Distributed Transaction.
3. Separation of Business Operations and Message Publishing
The Business Request does not need to wait for the Broker.
4. Suitable for Event-Driven Architecture
The Outbox Pattern is particularly useful for communication between Microservices.
5. Easier Retries
If the Broker is temporarily unavailable:
Outbox
↓
Retry
↓
Retry
↓
Success
The Event remains safely stored in the database.
Disadvantages of the Outbox Pattern
The Outbox Pattern solves one class of reliability problems, but it also introduces additional responsibilities.
1. Increased Complexity
Instead of having only a database, you may now have:
Database
+
Outbox
+
Publisher
+
Broker
+
Retry
+
Monitoring
+
Cleanup
2. Duplicate Events
The Publisher may send an Event more than once.
Therefore, Consumers should be designed to be idempotent.
3. Eventual Consistency
An Event does not necessarily reach every service immediately after the database transaction commits.
For a short period, you might have:
Order Service → CREATED
Inventory Service → still knows nothing
This delay needs to be acceptable from a business perspective.
4. Outbox Growth
Without a proper lifecycle strategy, the Outbox can become a very large table.
5. New Failure Modes
You now need to handle problems such as:
Publisher Crash
Broker Down
Database Down
Poison Message
Retry Storm
Duplicate Event
Outbox Backlog
The Outbox Pattern therefore does not eliminate reliability problems.
Instead, it changes the types of failures your system needs to handle.
Outbox Pattern vs. 2PC
The Outbox Pattern takes a fundamentally different approach from distributed transactions.
Instead of trying to create one global transaction, it keeps the transaction within the boundaries of a single database.
Database Transaction
├── Business Data
└── Outbox Event
Message publishing happens afterward.
The goal is not to make the database and Message Broker participate in the same transaction, but to make the database operation itself reliable and then handle message delivery separately.
Outbox vs. Direct Event Publishing
The simple approach is:
UPDATE DB
↓
PUBLISH EVENT
Advantages
- Simple
- Low cost
- Low latency
Disadvantages
- Dual Write
- Potential Lost Event
- Failure Window
The Outbox approach is:
UPDATE DB
+
INSERT OUTBOX
↓
COMMIT
↓
PUBLISH ASYNC
Advantages
- Higher reliability
- Easier retries
- No Lost Event in common failures between Commit and Publish
Costs
- Increased complexity
- Eventual Consistency
- Duplicate handling
- Operational overhead
Therefore, if an Event is not actually critical, the Outbox Pattern is not necessarily required.
For example, if Events are used only for non-critical analytics and losing a small percentage of them is acceptable, keeping the architecture simple may be more valuable.
Is the Outbox Pattern Only for Microservices ?
No.
A common misconception is that the Outbox Pattern is exclusively a Microservices pattern.
Even in a Monolithic Architecture, you may need to perform an external operation after changing the database.
For example:
Order Created
↓
Call a Webhook
Or:
User Registered
↓
Send Email
If the Email Provider is temporarily unavailable, you may not want to fail the user's registration.
Instead, you can store:
User
+
Email Event
inside the same transaction and send the email asynchronously afterward.
So the Outbox Pattern is better understood as a reliable solution for Asynchronous Messaging rather than something limited to Microservices.
When Is the Outbox Pattern Worth Using ?
The Outbox Pattern is particularly valuable when:
- The Event is important to the business.
- Losing an Event is unacceptable.
- The database and Broker are independent systems.
- The architecture is Event-Driven.
- Services communicate asynchronously.
- Retry and reliability are important.
- Immediate consistency between services is not required.
When Isn't the Outbox Pattern Necessary ?
If an Event is completely non-critical, adding an Outbox may introduce unnecessary complexity.
For example:
User clicked button
Suppose this Event is used only for approximate analytics.
If losing some Events is acceptable, direct publishing—or even an independent analytics system—may be a simpler solution.
The right architecture depends on the business consequences of failure.
Technical Considerations When Implementing Outbox
1. Use a Unique Event ID
Every Event should have a stable identifier:
event_id = UUID
This ID is essential for Deduplication.
2. Design Consumers to Be Idempotent
Suppose:
OrderPaid
is delivered twice.
The result should not be:
Payment = Payment × 2
The Consumer needs to recognize that the Event has already been processed.
3. Index the Outbox
If you use polling, queries such as:
WHERE processed_at IS NULL ORDER BY created_at
should be supported by appropriate indexes based on your workload and access patterns.
4. Consider Batch Processing
Instead of:
1 Event → 1 Query
you may be better off processing:
100 Events → 1 Batch
The AWS Batch Processing guidance provides useful background on batch processing.
However, very large batches can also increase:
- Lock duration
- Memory usage
- Retry costs
So the batch size should be chosen carefully.
5. Use Retry with Backoff
If the Broker is unavailable, you should not continuously retry every few milliseconds.
For example:
1s
2s
4s
8s
16s
...
Use exponential backoff together with appropriate retry limits and policies.
6. Don't Forget Dead-Letter Handling
Sometimes an Event will consistently fail.
If you retry indefinitely:
Event
↓
Fail
↓
Retry
↓
Fail
↓
Retry
↓
...
you can create a Retry Storm.
A problematic Event therefore needs an explicit failure-handling strategy, such as a Dead Letter mechanism.
An Important Note About Monitoring
One of the most useful Outbox metrics is the number of Events waiting to be published.
For example:
Outbox Pending Events = 12
might be completely normal.
But:
Outbox Pending Events = 2,000,000
could indicate that the Publisher has fallen significantly behind.
Useful metrics can include:
Outbox Backlog
Publish Latency
Publish Failure Rate
Retry Count
Oldest Unprocessed Event Age
Consumer Lag
Dead Letter Count
One particularly valuable metric is:
Oldest Unprocessed Event Age
For example:
Age = 45 minutes
Even if the total number of pending Events is relatively small, an old unprocessed Event could indicate an operational problem.
The Outbox Pattern and Eventual Consistency
The Outbox Pattern forces us to accept an important reality of distributed systems:
Not everything needs to be immediately consistent.
For example:
T0:
Order Created
T0 + 20ms:
Outbox Published
T0 + 50ms:
Inventory Updated
T0 + 100ms:
Notification Sent
For a short period, the system might look like this:
Order Service → CREATED
Inventory Service → Previous State
This is not necessarily a bug.
If your business requirements allow this delay, Eventual Consistency can be a perfectly reasonable trade-off.
In Event-Driven Architectures, this is one of the fundamental design considerations.
Duplication, ordering, and idempotency all need to be deliberately designed.
Final Thoughts
The Outbox Pattern is a solution to one of the classic problems in distributed systems: the Dual Write Problem.
Instead of having an application simultaneously modify:
Database
+
Message Broker
we store the business state change and its corresponding Event in a single local database transaction:
Database
├── Business Data
└── Outbox Event
A separate process then transfers the Event to the Message Broker.
The main benefit is straightforward:
If the original transaction commits, the corresponding Event is also persisted and can be retried later.
But the Outbox Pattern is not the end of the story.
You still need to deal with:
- Duplicate messages
- Idempotency
- Ordering
- Eventual Consistency
- Retries
- Outbox Growth
- Monitoring
- Cleanup
In other words, the Outbox Pattern does not eliminate distributed-system complexity.
It moves that complexity into areas where it can be managed more explicitly.
A Question for Discussion
If losing an Event is unacceptable for your system, but a few seconds of Eventual Consistency is tolerable, would you introduce the additional complexity of the Outbox Pattern, retries, and idempotency ?
And at what point would you decide that architectural simplicity is more valuable than higher messaging reliability ?
Top comments (0)