liveBook · Manning

Outbox pattern

As explained in Clean Applications with Hexagonal Architecture

A pattern that stores a message in the same transaction as a business change so it can be published reliably afterward.

A handler that updates a database and sends a message to a broker faces a dual-write problem: either operation can succeed while the other fails. The outbox pattern records the integration event in the same database transaction as the business change, leaving delivery to a separate process. section 6.5.3

The transaction and relay have separate responsibilities:

  • The handler or listener writes a pending integration event to an outbox table alongside the domain state. A commit stores both; a rollback stores neither. section 6.5.3
  • A separate poller or change-data-capture process reads the outbox and forwards events to the broker. The publisher can proceed without waiting for external consumers. section 6.5.3 section 10.3.2
  • Delivery is at least once, not exactly once. Consumers must handle duplicates safely, for example by recording processed event IDs and skipping repeats. section 6.5.3
Listing 6.14 Outbox table schema (simplified)
CREATE TABLE integration_event_outbox (
  event_id       VARCHAR(36) PRIMARY KEY, #A
  event_type     VARCHAR(100) NOT NULL, #B
  payload        JSONB NOT NULL, #C
  created_at     TIMESTAMP NOT NULL,
  published_at   TIMESTAMP #D
);

A simplified outbox row stores the event ID, type, payload and creation time, plus a publication timestamp. section 6.5.3

Recording an article publication

Publishing an article raises an ArticlePublished domain event. A BEFORE_COMMIT listener dispatches a command; its handler calls an output port whose adapter records the integration event in the outbox. The article and row commit together, and an outbox failure marks the transaction for rollback. section 9.4.3 section 9.5.2

Listing 9.18 RecordIntegrationEventListener: Before commit, atomic with the article
@Slf4j
@Adapter
@RequiredArgsConstructor
public class RecordIntegrationEventListener {
 
  private final CommandBus commandBus; #A
 
  @TransactionalEventListener(
    phase = TransactionPhase.BEFORE_COMMIT) #B
  public void on(final ArticlePublished event) {
    RecordIntegrationEventCommand
      .validateThenCreate( #C
        event.articleId(), event.authorId(), event.publishedAt())
    .flatMap(this.commandBus::execute) #D
    .peekLeft(error -> log.warn(
      "Failed to record integration event for article [{}]: {}",
      event.articleId(), error));
  }
 
}

The listener joins the open publication transaction. Logging a returned error alone does not cause rollback; the transactional handler must mark the transaction for rollback on an outbox failure. section 9.4.3

Keep the domain event, integration event and outbox row distinct. The domain event is an in-process signal; the integration event is a stable external contract; the row is its pending storage representation. The article contract exposes an article ID and publication time, with an event ID and creation time, rather than copying all internal state. section 9.5.2 section 6.5.2

An after-commit side effect is not a substitute for the atomic outbox write: a crash or failure after commit can lose that side effect. Even with an outbox, consumers learn of changes later and may receive duplicate or out-of-order events. The illustrated implementation records intent atomically; its relay is left unimplemented. section 9.4.3 section 9.5.2 section 10.3.2

How Clean Applications with Hexagonal Architecture covers it

How deep it goes
Implements atomic event recording through a listener, handler and adapter, while leaving the relay out of scope.
Examples
Traces article publication through a before-commit listener, an integration-event contract and an outbox row.
What you can do after
Apply the pattern using Java and Spring to record publication intent atomically with a business change.
How it connects
Connects database transactions and domain events to integration events, message brokers and consumer idempotency.

Also explained in

Compare how 4 books explain outbox pattern →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Clean Applications with Hexagonal Architecture. The section links point to the parts of the book it draws on.