Loading published curriculum…

20 · Production engineering and architecture / LESSON 100 OF 102

Events, async work, queues, and the outbox pattern

Database commitment and message publication are two operations that can fail independently.

Before this lesson: Caching, eviction, and scheduled work

Understand the topic

An in-process application event is not a durable queue. @Async moves execution to an executor but needs bounded capacity, error handling, and context propagation. Do not assume an asynchronous listener observes committed data unless its timing is explicitly arranged.

An outbox stores an event in the same database transaction as the business change. A worker publishes pending rows and records completion. Publication can happen more than once after a crash, so consumers need idempotency keys or deduplication. Order and retention are explicit design choices.

EXAMPLE · SQL

V4__outbox.sql

CREATE TABLE outbox_event (
 id uuid PRIMARY KEY,
 aggregate_id bigint NOT NULL,
 event_type text NOT NULL,
 payload jsonb NOT NULL,
 created_at timestamptz NOT NULL DEFAULT now(),
 published_at timestamptz
);
CREATE INDEX outbox_pending ON outbox_event(created_at) WHERE published_at IS NULL;

What to expect

Insert the business change and its event in one transaction. This schema is the durable handoff; the lab implements the publisher and idempotent consumer.

YOUR TURN

Put it into practice

  1. 01Write a task-completed event into an outbox transaction.
  2. 02Crash a local worker after publishing but before marking completion and replay the event.
  3. 03Verify: The event is not lost and the consumer applies the business effect at most once using a deduplication key.

Pass a quiz or complete a lab to check today’s streak. Each lesson counts once per day, including when you review it later.

UNDER THE HOOD

Build the mental model

Database commitment and message publication are two operations that can fail independently.

  1. 01An in-process application event is not a durable queue. @Async moves execution to an executor but needs bounded capacity, error handling, and context propagation. Do not assume an asynchronous listener observes committed data unless its timing is explicitly arranged.
  2. 02An outbox stores an event in the same database transaction as the business change. A worker publishes pending rows and records completion. Publication can happen more than once after a crash, so consumers need idempotency keys or deduplication. Order and retention are explicit design choices.
  3. 03Trace the example: Insert the business change and its event in one transaction. This schema is the durable handoff; the lab implements the publisher and idempotent consumer.

A mistake worth avoiding

A database update commits but its notification is lost during process failure.

DEBUGGING ROOM

Something broke. Where do you look?

A database update commits but its notification is lost during process failure.

Before revealing the diagnosis, write down your first investigation step.

CHECK YOUR UNDERSTANDING

Does an outbox automatically guarantee exactly-once delivery?

Choose one answer

BUILD IT YOURSELF

Write a task-completed event into an outbox transaction.

  1. 1.Write a task-completed event into an outbox transaction.
  2. 2.Crash a local worker after publishing but before marking completion and replay the event.
  3. 3.Reproduce this failure, then repair it: A database update commits but its notification is lost during process failure.

Acceptance checklist

Lab completion is your self-report. Knowledge checks do not certify project quality.

RETRIEVE IT FROM MEMORY

Does an outbox automatically guarantee exactly-once delivery?

Revisit this lesson in three days after a successful check or lab.

Ready for the next step?

The event is not lost and the consumer applies the business effect at most once using a deduplication key.

Reading is separate from passing a knowledge check or completing a lab.

Go deeper · official references