What is the inbox pattern, and why can't the broker give you exactly-once processing?

The inbox pattern makes an event consumer record each message it has processed in a durable table, in the same database transaction as the business change the message triggers. When a message arrives, the consumer checks the inbox for its ID. If the ID is already there, the consumer acknowledges the message and skips it. If not, it applies the change and inserts the ID in one commit. A consumer built this way is an idempotent consumer: handling the same message twice leaves the system in the same state as handling it once.

You need this because most brokers deliver at least once, and at-least-once delivery produces duplicates in normal operation:

  • A consumer commits its database work, then crashes before it acknowledges the message. The broker never sees the ack and delivers the message again.
  • Processing runs longer than the visibility or ack timeout, so the broker assumes the consumer failed and hands the message to another instance.
  • A producer times out waiting for confirmation and resends a message the broker had already stored.
  • A consumer group rebalances, and the new owner of a partition resumes from the last committed offset, replaying anything processed after it.

Some brokers can suppress duplicates within their own boundary, for example by deduplicating producer retries or by making offset commits transactional. That guarantee ends where your database begins. The broker cannot commit your database write and its own acknowledgment as one atomic step. End-to-end exactly-once processing is therefore an effectively-once outcome that the consumer has to build itself.

Use the pattern when your consumers write to a relational or transactional store and a duplicate causes real harm, such as a customer charged twice or an inventory count decremented twice.

Who should use the inbox pattern?

The inbox pattern is for teams that own event consumers meeting all three of these conditions:

  • The broker delivers at least once. This covers most queue and log-based brokers in their default configurations, and any setup where consumers acknowledge after processing.
  • The consumer writes to a transactional store it controls. The inbox table has to live in the same database as the business data so both can commit in one local transaction.
  • A duplicate is harmful and not naturally idempotent. Typical examples are billing and invoicing, payments ledgers, inventory reservations, loyalty points, counters, and any handler that appends rows or increments values.

It fits especially well for:

  • Services that already use the transactional outbox pattern. The outbox protects outgoing messages and the inbox protects incoming ones, with the same transactional discipline on both sides.
  • Platform or shared-library teams. The inbox logic is small and generic, so it can be built once into a consumer framework and reused by every handler instead of reimplemented per service.
  • Teams that regularly redrive dead-letter queues, reset offsets, or replay topics. The inbox makes those operations safe for handlers whose writes are not idempotent.

Teams whose consumers are stateless, whose writes are already idempotent upserts, or whose side effects all happen in external systems usually need something else. The section on when to avoid the pattern covers these cases.

How does the inbox pattern work?

In short: the consumer claims the message ID in a table protected by a unique key, and it does so in the same transaction as the business change. The database then decides, atomically, whether this delivery is the first one.

The inbox is a table in the same database as the consumer's business data. Its primary key is the pair (message ID, consumer name). The message ID must be stable across redeliveries, so it is assigned by the producer rather than the broker's delivery metadata. The consumer name lets several services, or several handlers in one service, each record their own processing of the same event without colliding.

The consumer handles each message in this order:

  1. Begin a local transaction. A failure here changes nothing. The message stays unacknowledged and is redelivered.
  2. Insert the inbox row. If the insert hits a unique-key violation, the message was already processed. The consumer skips the handler, rolls back, and acks. The database constraint makes this decision, so two concurrent deliveries cannot both pass a "have I seen this?" check.
  3. Apply the business state change. If this fails or the process crashes, the transaction never commits. The inbox row disappears along with the partial writes, and the redelivered message is processed cleanly.
  4. Commit. The inbox row and the state change become durable together, or neither does.
  5. Ack the broker. If the consumer crashes after commit but before the ack, the broker redelivers. Step 2 detects the duplicate, and the consumer acks it without reapplying anything.

The broker can still deliver a message more than once. What the pattern guarantees is that the state change commits only once. This is effectively-once processing, not exactly-once delivery, and it applies only to writes inside that transaction.

+----------+    deliver msg (producer msg_id)    +------------------------+
|  Broker  |------------------------------------>|   Consumer handler     |
|          |<------------ redeliver -------------|                        |
+----------+                                     +------------------------+
     ^                                                       |
     |              +----------------------------------------v------------+
     |              | Consumer DB: one local transaction                  |
     |              |                                                     |
     |              |  1. BEGIN                                           |
     |              |  2. INSERT INTO inbox (msg_id, consumer_name)       |
     |              |        |                         |                  |
     |              |      new row           unique-key violation         |
     |              |        v                         v                  |
     |              |  3. apply business     ROLLBACK, skip handler       |
     |              |     state change                 |                  |
     |              |        |  crash or error:        |                  |
     |              |        |  ROLLBACK, inbox row    |                  |
     |              |        |  gone, redelivered      |                  |
     |              |        v                         |                  |
     |              |  4. COMMIT: inbox row + state    |                  |
     |              |     change durable together      |                  |
     |              +--------|-------------------------|------------------+
     |                       |                         |
     +------ 5. ack ---------+--- ack duplicate -------+

  Crash after COMMIT, before ack: broker redelivers, step 2 hits the
  unique key, consumer acks. State commits once; delivery may repeat.

The inbox insert and the business state change commit in one local transaction keyed by (message ID, consumer name), so a redelivered message hits the unique key and is acked without its state change being applied again.

How do you implement an inbox table and an idempotent consumer?

The inbox is a small table: consumer_name, message_id, and processed_at, with a composite primary key on (consumer_name, message_id). Including the consumer name lets several services, or several handlers in one service, keep separate records for the same event without colliding. The processed_at timestamp is not used for deduplication. It supports retention cleanup and debugging.

The consumer opens a transaction and runs INSERT INTO inbox ... ON CONFLICT DO NOTHING. Then it checks the affected row count. If the count is 1, this is the first time the message has been seen, so the handler applies its business writes in the same transaction and commits. If the count is 0, the message is a duplicate, so the handler skips the business logic and commits or rolls back the empty transaction.

The obvious alternative is to SELECT from the inbox, then insert if nothing is found. That version races. Two consumers can receive the same redelivered message, both see no row, and both apply the side effect. Only the unique constraint is checked atomically by the database, so it is the real guard. The insert is the check.

A conflict counts as success. The handler must ack the message. If it throws instead, the broker redelivers the message and it conflicts again on every retry, until it ends up in the dead-letter queue as a false failure.

Rejected messages work the other way. If a message makes the handler fail, its transaction rolls back and takes the inbox row with it. The inbox never records the message, so it keeps getting redelivered. Retry limits and dead-letter handling are still required.

import psycopg2  # conn below is a psycopg2 connection

INBOX_DDL = """
CREATE TABLE IF NOT EXISTS inbox (
    consumer_name text        NOT NULL,
    message_id    text        NOT NULL,
    processed_at  timestamptz NOT NULL DEFAULT now(),  -- retention/debugging only
    PRIMARY KEY (consumer_name, message_id)            -- the real dedup guard
)"""

CONSUMER = "billing-invoice-handler"

def handle(conn, msg):
    """Return normally to ack. Raise to let the broker retry or dead-letter."""
    with conn:  # psycopg2: commit on normal exit, roll back on exception
        with conn.cursor() as cur:
            # The insert is the check. The unique constraint is enforced atomically,
            # unlike SELECT-then-INSERT, which two concurrent consumers can both pass.
            cur.execute(
                "INSERT INTO inbox (consumer_name, message_id) VALUES (%s, %s) "
                "ON CONFLICT DO NOTHING",
                (CONSUMER, msg["id"]),
            )
            if cur.rowcount == 0:
                return  # duplicate: a successful no-op (commits an empty transaction)
            # First delivery: business writes share the inbox row's transaction.
            cur.execute(
                "INSERT INTO invoices (order_id, amount_cents) VALUES (%s, %s)",
                (msg["order_id"], msg["amount_cents"]),
            )
    # If anything above raised, the rollback also removed the inbox row.
    # A poison message is never recorded, so it will be redelivered.

def on_message(conn, msg, ack, nack):
    try:
        handle(conn, msg)
        ack()   # ack first-time AND duplicate deliveries, so duplicates don't loop
    except Exception:
        nack()  # redeliver; the broker's retry limit routes poison messages to the DLQ

An inbox table with a composite primary key, and a psycopg2 consumer. The consumer uses INSERT ... ON CONFLICT DO NOTHING and checks the affected row count. It acks duplicates as no-ops and leaves real failures to retry limits and the dead-letter queue.

Which deduplication key should you use for message deduplication?

The inbox is only as good as its key, and a bad key fails in one of two ways. If the key changes when the producer retries, the redelivered copy looks new and gets processed twice, so the duplicate is missed. If the key is too coarse, two legitimately different messages share a key and the second is discarded as a "duplicate." The second failure is worse because nothing errors. The data is quietly wrong.

Candidate key Stable across producer retries Distinguishes distinct messages Main risk
Producer-assigned message ID Yes, if assigned before the first send Yes Regenerated on each attempt if created in the send path
Business key (order ID + event type) Yes Only if each combination occurs once Too coarse: a second OrderUpdated for the same order is dropped
Broker offset or delivery ID No Only within one partition, queue or channel Changes on resend; values collide or repeat across partitions and topics

An offset or delivery ID records where the broker stored or delivered one copy. It does not identify the message itself. A producer that times out waiting for an acknowledgement and resends can leave two copies at two different offsets. Offsets are also numbered per partition, so the same value in two partitions or topics refers to unrelated messages.

Assign the message ID when the event is created, not when it is sent. Ideally, write it in the same transaction as the business change, for example on the outbox row, and reuse it on every retry. Never generate it inside a retry loop or a client wrapper. If you must use a business key, add a version or sequence number so that repeated events for the same entity stay distinct.

How do you handle side effects outside the database, retention, and replays?

Side effects beyond the transaction

The inbox only deduplicates writes that commit in the same transaction as the inbox row. An HTTP call, an email, a payment request, or a write to a second database happens outside that transaction. If the consumer crashes after the side effect but before the commit, the message is redelivered and the side effect runs again. For these calls, pass an idempotency key derived from the message ID downstream, so the receiving system can recognize the repeat. For messages your consumer publishes in turn, write them to an outbox table in the same transaction and let a relay send them. The inbox then covers incoming duplicates and the outbox covers outgoing ones.

Retention

The inbox cannot grow forever, but every deleted row reopens a duplicate window for that message ID. Base the retention period on the longest realistic redelivery or replay horizon: broker retention, the maximum consumer lag you tolerate, and how far back an operator might reset offsets. If you prune more aggressively than that, an old message can arrive after its row is gone and be processed twice. Prune in small batches ordered by the processed timestamp. A single large delete holds locks longer, competes with live consumers, and leaves dead tuples or fragmentation behind.

Intentional replays

When you replay a topic to rebuild a projection, the inbox treats every message as a duplicate and silently skips all of them. Use an explicit bypass flag for the rebuild, or run the replay under a separate consumer identity with its own inbox scope.

-- PostgreSQL. Scope the inbox by consumer identity so a rebuild consumer
-- (e.g. 'orders-projection-rebuild') gets its own dedup scope during a replay.
CREATE TABLE IF NOT EXISTS inbox (
  consumer_id  text        NOT NULL,
  message_id   uuid        NOT NULL,
  processed_at timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY (consumer_id, message_id)
);

-- Supports pruning in processed_at order without a full scan.
CREATE INDEX IF NOT EXISTS inbox_processed_at_idx ON inbox (processed_at);

-- Dedup step: run inside the same transaction as the business write.
-- If 0 rows are inserted, the message was already handled. Skip it.
INSERT INTO inbox (consumer_id, message_id)
VALUES ('orders-projection', '0b6f3c1e-8a2d-4f5b-9c7e-2d1a4b6e8f90')
ON CONFLICT (consumer_id, message_id) DO NOTHING;

-- Pruning: delete one small batch per statement. A scheduler reruns it
-- until it reports 0 rows. That keeps lock time short and spreads the
-- dead-tuple cleanup across many small autovacuum passes.
-- The 14-day window is a placeholder. It must exceed the broker retention
-- plus the maximum tolerated lag plus how far back operators may reset offsets.
-- A shorter window lets an old redelivery slip through as new.
WITH batch AS (
  SELECT consumer_id, message_id
  FROM inbox
  WHERE processed_at < now() - interval '14 days'
  ORDER BY processed_at
  LIMIT 1000
  FOR UPDATE SKIP LOCKED  -- don't wait on rows that live consumers hold locked
)
DELETE FROM inbox i
USING batch b
WHERE i.consumer_id = b.consumer_id
  AND i.message_id  = b.message_id;

A PostgreSQL inbox scoped by consumer identity, so replays can run under a separate scope, with a batched prune whose retention window has to cover the full redelivery and replay horizon.

When should you avoid the inbox pattern, and what are the alternatives?

The inbox is a general-purpose guard, and many consumers don't need it. If applying a message twice leaves the same state as applying it once, deduplication is already built into the write. An upsert keyed by the entity ID, or a set-based assignment such as status = 'shipped', can run any number of times safely. Increments, appends, and "add 10 to balance" are not idempotent, and those are where an inbox pays off.

When ordering matters, a version or sequence check on the target row works better. The update applies only if the incoming version is newer than the stored one. That rejects duplicates and stale out-of-order messages in a single conditional write, which an inbox alone does not do.

Avoid the inbox in three cases:

  • Very high-throughput consumers. The extra insert and index entry per message add latency and write amplification.
  • Consumers whose side effects all live outside the database. The inbox row cannot commit atomically with an API call or email. Use the downstream system's idempotency key instead.
  • Stateless or read-only consumers. They have no state to corrupt.
Approach Protects against Cost Fits
Inbox table Duplicate delivery for any operation Extra write, index, and retention job per message Non-idempotent writes in the same database
Upsert or set-based state Duplicates where the final state is absolute Near zero Projections, status fields
Version or sequence check Duplicates and stale reordering A version column and a conditional update Entity state with a per-key order
Downstream idempotency key Duplicate external side effects Depends on support from the downstream API Payments, notifications, third-party calls

How do you test an idempotent consumer, and what does the inbox pattern cost?

A test plan that proves the guarantee

Handler unit tests won't catch duplicate delivery. Run these against a real database and broker so they reproduce actual failure modes:

  1. Replay the same message. Process a message, then publish it again with the same ID. Assert that the business state changed once and the inbox holds one row.
  2. Kill the process between commit and ack. Inject a crash after the transaction commits but before acknowledgment. On restart the broker redelivers. Assert that the consumer detects the duplicate, acks it, and produces no new side effects.
  3. Race concurrent consumers. Deliver one message ID to two instances at once. Assert that one commits and the other hits the unique constraint and exits cleanly instead of retrying forever.

Assert on final state, such as balances, counts and emitted events. Log lines can say "processed" even when the state is wrong.

What it costs, and what it saves

The pattern adds an inbox table, a unique index, an extra insert inside each transaction, a pruning job, and replay tooling that knows to bypass or clear inbox rows. In return, you remove per-handler dedup logic, and you can answer "was this applied twice?" with a single query.

Illustrative estimate (assumed numbers, not a benchmark): Net hours per year = (incidents × hours saved per incident) − (build hours + maintenance hours). Assume 4 double-apply incidents per year, 6 hours saved on each, 16 hours to build and 4 hours to maintain: (4 × 6) − (16 + 4) = 4 hours saved in the first year. In later years, without the build cost, the savings are 20 hours a year.

Document the guarantee as effectively-once. On-call engineers should expect redelivery and check the inbox first. They should not assume that duplicates are impossible.

-- PostgreSQL. Replay test: run the handler statement twice for one message ID.
CREATE TABLE inbox (
  message_id   text PRIMARY KEY,  -- unique constraint is the dedup guard
  processed_at timestamptz NOT NULL DEFAULT now()
);
CREATE TABLE accounts (id text PRIMARY KEY, balance numeric NOT NULL);
INSERT INTO accounts VALUES ('acct-42', 100);

-- Handler: claim the ID and apply the change in one statement.
-- If the claim conflicts (a replay, or a concurrent consumer that
-- committed first), RETURNING yields no row and the UPDATE is skipped.
-- Execute this block twice to simulate redelivery.
WITH claimed AS (
  INSERT INTO inbox (message_id) VALUES ('msg-7f3a')
  ON CONFLICT (message_id) DO NOTHING
  RETURNING message_id
)
UPDATE accounts SET balance = balance + 25
WHERE id = 'acct-42' AND EXISTS (SELECT 1 FROM claimed);

-- Assert on final state, not on logs.
DO $$
BEGIN
  IF (SELECT count(*) FROM inbox WHERE message_id = 'msg-7f3a') <> 1 THEN
    RAISE EXCEPTION 'expected exactly one inbox row';
  END IF;
  IF (SELECT balance FROM accounts WHERE id = 'acct-42') <> 125 THEN
    RAISE EXCEPTION 'balance changed more or less than once';
  END IF;
END $$;

A PostgreSQL replay test that claims a message ID through the inbox's unique key, applies the change only on a successful claim, and asserts the final balance and inbox row count.

How can the inbox pattern save engineering time?

Most of the time savings come from work that disappears rather than work that gets faster:

  • Less incident investigation and data repair. A double-applied charge or inventory decrement usually means tracing logs across services, working out which messages were applied twice, and writing one-off repair scripts. With an inbox, duplicates are stopped at the unique key. When someone suspects a double apply, one query against the inbox by message ID shows whether and when it was processed.
  • No per-handler deduplication code. Without a shared pattern, each handler tends to get its own ad hoc check, such as a "processed" flag on a business row or an in-memory cache of recent IDs. Each one needs separate design, review, and tests, and many race under concurrency. A single inbox step in a shared consumer wrapper replaces all of them, and reviewers only need to confirm the handler's writes are in the inbox transaction.
  • Safe retries and redrives. Operators can redeliver dead-lettered messages, restart stuck consumers, or reset offsets after an outage without first auditing which messages were already applied. The inbox skips those, so recovery becomes a routine operation instead of a coordinated manual procedure.
  • Simpler reasoning about failures. The crash-between-commit-and-ack case, rebalances, and producer resends all reduce to the same outcome: redelivery, detected by the unique key. Engineers don't need a separate mental model or fix for each failure mode.
  • Reusable tests. The three-part test plan above (replay, crash before ack, concurrent consumers) can be written once against the shared wrapper and reused for every handler that adopts it.

The savings depend on how often duplicates actually cause harm in your system and how many handlers share the implementation. The illustrative estimate in the previous section shows how to weigh them against build and maintenance cost. Plug in your own assumed incident counts and hours rather than relying on its example inputs. If your consumers are already idempotent through upserts or version checks, the inbox adds cost without much saving, and the alternatives above are the better use of time.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to inbox pattern microservices, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • The dependency graph answers "what does this touch?" in seconds instead of a manual audit.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • You can size a change's blast radius before merging, avoiding surprise cross-team firefighting.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.