The Outbox Pattern — Reliable Event Publishing in Microservices

Introduction

In a microservice that owns both a database and a Kafka topic, every interesting operation looks the same: change a row, publish an event. The obvious implementation — save() then kafkaTemplate.send() — is wrong. It is a textbook dual-write, and dual writes always eventually fail in production. The row is committed, the broker is unreachable, and downstream services never learn that anything happened.

The Outbox pattern is the standard fix. It moves the event into the database as a regular row, written in the same local transaction as the business change. A separate relay reads from the outbox table and republishes the events to Kafka. There is exactly one source of truth (the database) and at-least-once delivery to consumers.

This tutorial walks through a production implementation in Spring Boot with PostgreSQL and Kafka, covering both the polling-relay and Debezium-CDC variants, idempotent consumers, retention, and operational concerns.

The dual-write problem

Consider this naive code:

@Transactional
public void place(Order order) {
  orderRepo.save(order);
  kafka.send("orders.events", new OrderPlaced(order.getId()));
}

What happens if the application crashes between save and send? The order exists in the database but no downstream service knows. What about the reverse — send succeeds, save fails? Now consumers act on an order that does not exist.

You cannot fix this with retries inside the method. There is no atomic transaction that spans PostgreSQL and Kafka. Any solution must persist the *intent to publish* in a place that *is* transactional with the business write.

The Outbox solution

Write the event to an outbox table in the same database transaction as the business change. A separate process (the relay) reads new rows and publishes them to Kafka. Once Kafka has acknowledged, mark the row as sent (or delete it).

The key invariant: if the business row is committed, the outbox row is committed. If the relay restarts ten times before publishing, the event is still in the table waiting. The system can only fail by *delivering more than once*, which is solved on the consumer side with idempotency keys.

Real-world use cases

• Order, payment and inventory services that must publish state changes to other services without losing events.
• Audit logs where every write must produce a tamper-evident record.
• CDC pipelines feeding analytics warehouses (BigQuery, Snowflake) from operational databases.
• CQRS projections (see our CQRS tutorial) where the projection worker must never miss an event.

Step 1 — The outbox table

```sql
CREATE TABLE outbox (
  id           UUID PRIMARY KEY,
  aggregate_id UUID NOT NULL,
  topic        TEXT NOT NULL,
  payload      JSONB NOT NULL,
  created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
  sent_at      TIMESTAMPTZ
);

CREATE INDEX outbox_unsent_idx ON outbox (created_at) WHERE sent_at IS NULL; ```

The partial index keeps polling efficient even as the table grows.

Step 2 — Write business + outbox atomically

```java
@Entity @Table(name = "outbox")
@Getter @Setter @NoArgsConstructor
public class OutboxRow {
  @Id private UUID id;
  private UUID aggregateId;
  private String topic;
  @Type(JsonBinaryType.class)
  @Column(columnDefinition = "jsonb")
  private String payload;
  private Instant createdAt;
  private Instant sentAt;
}

@Service @RequiredArgsConstructor public class OrderService { private final OrderRepository orders; private final OutboxRepository outbox; private final ObjectMapper json;

@Transactional public Order place(CreateOrder cmd) throws JsonProcessingException { var order = Order.create(cmd); orders.save(order);

var row = new OutboxRow(); row.setId(UUID.randomUUID()); row.setAggregateId(order.getId()); row.setTopic("orders.events"); row.setPayload(json.writeValueAsString(new OrderPlaced(order.getId(), order.getTotal()))); row.setCreatedAt(Instant.now()); outbox.save(row);

return order; } } ```

Both inserts share the same JPA transaction. Postgres commits both or neither.

Step 3 — The polling relay

The simplest relay is a scheduled job that picks unsent rows with SKIP LOCKED so multiple instances can run safely.

```java
@Component
@RequiredArgsConstructor
public class OutboxRelay {

private final EntityManager em; private final KafkaTemplate<String, String> kafka;

@Scheduled(fixedDelay = 500) @Transactional public void flush() { List<OutboxRow> rows = em.createQuery( "SELECT o FROM OutboxRow o WHERE o.sentAt IS NULL " + "ORDER BY o.createdAt LIMIT 100", OutboxRow.class) .setLockMode(LockModeType.PESSIMISTIC_WRITE) .setHint("jakarta.persistence.lock.timeout", -2) // SKIP LOCKED .getResultList();

for (OutboxRow r : rows) { kafka.send(r.getTopic(), r.getAggregateId().toString(), r.getPayload()) .get(5, TimeUnit.SECONDS); r.setSentAt(Instant.now()); } } } ```

SKIP LOCKED (Postgres) means a second relay instance simply picks a different batch instead of blocking. The Kafka send is acknowledged before sentAt is set, so a crash mid-loop just re-publishes a few events — which is what consumers expect.

Step 4 — The CDC variant with Debezium

For high throughput or to eliminate the relay process entirely, point Debezium at the outbox table. It tails the Postgres WAL and republishes each insert to Kafka in real time.

{
  "name": "outbox-connector",
  "config": {
    "connector.class": "io.debezium.connector.postgresql.PostgresConnector",
    "database.hostname": "postgres",
    "database.dbname": "orders",
    "table.include.list": "public.outbox",
    "transforms": "outbox",
    "transforms.outbox.type": "io.debezium.transforms.outbox.EventRouter",
    "transforms.outbox.table.field.event.key": "aggregate_id",
    "transforms.outbox.route.topic.replacement": "${routedByValue}"
  }
}

The Debezium EventRouter transform inspects the topic column on each row and routes events to the right Kafka topic. There is no application code running between Postgres and Kafka — latency drops to milliseconds and there is no scheduler to operate.

Step 5 — Idempotent consumers

Because delivery is at-least-once, consumers must dedupe. The simplest pattern is to persist the event ID on the consumer side and skip duplicates.

@KafkaListener(topics = "orders.events", groupId = "inventory")
@Transactional
public void on(ConsumerRecord<String, String> r) throws Exception {
  var event = json.readValue(r.value(), OrderPlaced.class);
  if (processed.existsById(event.eventId())) return;
  inventory.reserve(event.orderId(), event.lines());
  processed.save(new ProcessedEvent(event.eventId(), Instant.now()));
}

The dedupe table and the business write must be in the same transaction — otherwise you reintroduce a dual-write on the consumer side.

Production best practices

• Partition by aggregate ID. Set the Kafka key to aggregate_id so events for one aggregate land on the same partition in order.
• Retain or purge. Keep sent rows for 7–30 days for audit and replay, then archive or delete. A nightly DELETE job is fine.
• Bound the outbox. Alert when unsent rows exceed a threshold; that means the relay or broker is down.
• Use idempotent Kafka producers. Set enable.idempotence=true and acks=all so retries on the producer don't duplicate.
• Run the relay on multiple replicas. With SKIP LOCKED, two or three instances give fault tolerance without coordination.
• Don't put huge blobs in the outbox. Reference object storage URLs instead. Outbox rows should be small and fast to publish.
• Embed schema version. { "schemaVersion": 1, "data": {...} }. Evolving event schemas is inevitable.

Security considerations

• The outbox table contains the same PII as the business tables — encrypt at rest and apply the same access controls.
• Sign events at the producer if downstream services are cross-tenant.
• Restrict who can write to the outbox table directly. Only the application user should be able to insert; only the relay role should be able to update sent_at.
• Audit the relay's outgoing traffic; the relay is the only path events take to Kafka.

Common mistakes

1. Publishing from a @TransactionalEventListener after commit. This is still a dual-write — the post-commit publish can fail and is not retried. 2. No SKIP LOCKED. Multiple relay instances will fight for the same rows and serialize the throughput. 3. Deleting outbox rows immediately on send. You lose the ability to replay. Mark sent and purge later. 4. Forgetting consumer idempotency. At-least-once delivery means consumers *will* see duplicates eventually. 5. Mixing many event types in one outbox without keys. Ordering guarantees are lost; partition by aggregate ID. 6. Letting the outbox grow unbounded. Polling slows, indexes bloat, vacuums struggle.

Troubleshooting guide

• Events stuck in outbox. Check relay logs. Common causes: Kafka unreachable, topic does not exist, ACL missing. Unblock by fixing the broker, then resume.
• Duplicate processing downstream. Verify the consumer dedupe table is in the same transaction as the business write.
• Out-of-order events. Confirm the Kafka producer key is aggregate_id. Single-partition order is only guaranteed per key.
• Relay falling behind. Increase batch size, add an index on (sent_at, created_at), or switch to Debezium.
• Database CPU spike. Vacuum the outbox more aggressively; the partial index needs maintenance once you purge rows.

FAQ

1. Why not use Kafka Transactions to write directly? You still need an atomic write across two systems (DB + Kafka). Kafka Transactions only help when both sides are Kafka.

2. Polling relay or Debezium — which should I pick? Polling is fine up to a few thousand events per second and is dead simple. Debezium scales further and removes the scheduler, at the cost of operating a Connect cluster.

3. Does the Outbox pattern guarantee exactly-once? No. It guarantees at-least-once. Combine it with consumer-side dedupe for effectively-once semantics.

4. Can I use the Outbox pattern without Kafka? Yes — the relay can publish to RabbitMQ, SNS, NATS, or an HTTP webhook. The pattern is broker-agnostic.

5. How big should the outbox table get? A few hundred thousand rows is fine. Beyond that, purge or partition aggressively.

6. What about ordering across aggregates? There is no global order in Kafka. If you need cross-aggregate order, you need a different design (single-partition topic, or an event-sourced log).

7. Can multiple services share one outbox? No. Each service owns its own database, schema and outbox. That is the whole point of the bounded context.

8. Does the Outbox pattern work with NoSQL? Yes, if your database supports multi-document transactions (MongoDB ≥4.0, DynamoDB transactions). Otherwise you need a single-document outbox embedded in the aggregate.

9. How does Outbox interact with CQRS? They are complementary. CQRS needs reliable events to project; the Outbox guarantees they are emitted. See our CQRS tutorial.

10. What latency should I expect? Polling relay: 100–500ms. Debezium: 10–50ms. Both are fine for most user-facing systems.

Key takeaways

• The dual-write problem is unavoidable when an application writes to both a database and a broker; the Outbox pattern solves it.
• Write the business row and the outbox row in the same local transaction; let a relay (polling or Debezium) republish.
• Partition by aggregate ID, make consumers idempotent, and purge old rows on a schedule.
• The Outbox is the foundation for CQRS projections, audit pipelines and reliable inter-service communication.

Related tutorials

• CQRS Pattern in Spring Boot — Separating Reads and Writes for Scale
• Designing Event-Driven Microservices with Kafka and Spring Boot
• Spring Boot Microservices Architecture Explained Step by Step
• Spring Boot Kafka Tutorial
• Domain-Driven Design with Spring Boot