The Transactional Outbox Pattern
Learn how the transactional outbox pattern reliably bridges a database transaction and Kafka publishing, avoiding dual-write inconsistencies in Spring Boot.
The Transactional Outbox Pattern is a free Advanced Spring Boot 4: Event-Driven Architecture (Kafka) lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Advanced Spring Boot 4: Event-Driven Architecture (Kafka) learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
The Dual-Write Problem
A common bug: a service updates its database and publishes a Kafka event in two separate operations. If one succeeds and the other fails, the system becomes inconsistent.
The transactional outbox pattern eliminates this risk.
Core Idea
Instead of publishing directly, write the event into an outbox table within the same database transaction as your business change.
A separate process then reads the outbox and publishes to Kafka.
The Outbox Table
The outbox table stores serialized events plus metadata.
CREATE TABLE outbox (
id UUID PRIMARY KEY,
aggregate_type VARCHAR(255),
aggregate_id VARCHAR(255),
event_type VARCHAR(255),
payload JSONB,
created_at TIMESTAMP DEFAULT now(),
published BOOLEAN DEFAULT false
);Writing in One Transaction
Both the domain entity and the outbox row are saved inside one @Transactional method, so they commit or roll back together.
@Transactional
public void placeOrder(Order order) {
orderRepository.save(order);
outboxRepository.save(OutboxEvent.from(order));
}Atomicity Guarantee
Because both writes share the database transaction, there is no window where the order exists without its event recorded. This is the key correctness property.
The Relay Process
A background relay polls unpublished outbox rows and sends them to Kafka, marking them published on success.
@Scheduled(fixedDelay = 500)
public void relay() {
for (OutboxEvent e : outboxRepository.findUnpublished()) {
kafkaTemplate.send(e.getTopic(), e.getPayload());
e.markPublished();
}
}At-Least-Once Publishing
If the relay crashes after sending but before marking published, the event is sent again. Consumers must therefore be idempotent, often using the event id as a dedup key.
Change Data Capture Alternative
Instead of polling, tools like Debezium tail the database transaction log and stream outbox inserts to Kafka automatically — lower latency and no polling load.
Cleaning Up the Outbox
Periodically delete or archive published rows to keep the table small and queries fast.
DELETE FROM outbox WHERE published = true AND created_at < now() - INTERVAL '7 days';When to Use It
Use the outbox when you must keep a database state change and an event publication consistent. It is simpler and more portable than spanning a Kafka transaction across an external database.
Putting It Together
The outbox pattern turns two unreliable writes into one atomic database commit plus a reliable relay. Combine it with idempotent consumers for end-to-end consistency.
Quick Check
Test your understanding of the outbox pattern.
Recap
You learned the transactional outbox pattern.
- Avoids dual-write inconsistency by using one DB transaction.
- An outbox table stores pending events.
- A relay (polling or CDC) publishes to Kafka.
- Consumers must be idempotent due to at-least-once delivery.
Frequently asked questions
Is the “The Transactional Outbox Pattern” lesson free?
Yes — the full text of “The Transactional Outbox Pattern” is free to read here on the web, and the Advanced Spring Boot 4: Event-Driven Architecture (Kafka) course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Advanced Spring Boot 4: Event-Driven Architecture (Kafka) course, upgrade to CoddyKit PRO.
What will I learn in “The Transactional Outbox Pattern”?
Learn how the transactional outbox pattern reliably bridges a database transaction and Kafka publishing, avoiding dual-write inconsistencies in Spring Boot. You practise Advanced Spring Boot 4: Event-Driven Architecture (Kafka) with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Advanced Spring Boot 4: Event-Driven Architecture (Kafka)?
No prior experience is required. Advanced Spring Boot 4: Event-Driven Architecture (Kafka) on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “The Transactional Outbox Pattern” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Advanced Spring Boot 4: Event-Driven Architecture (Kafka) lesson?
Yes. Every Advanced Spring Boot 4: Event-Driven Architecture (Kafka) lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Understanding Kafka Transactions
- Implementing Transactional Producers
- Exactly-Once Processing Semantics
- The Transactional Outbox Pattern