What is the inbox pattern and why does at-least-once delivery need it?
The inbox pattern does not make message delivery exactly-once. Brokers rarely promise that. Instead, it makes the effect of processing a message happen exactly once. The consumer records each message's identifier in its own database, in the same transaction as the business change. A redelivered copy then finds that record and is skipped instead of being applied again.
Duplicates come from several places, and at-least-once delivery treats all of them as expected behaviour rather than errors:
- Crash between commit and ack. The consumer commits its database transaction, then dies before acknowledging the message or committing its offset. The broker has no record of success, so it delivers the message again.
- Consumer group rebalances. When partitions move between instances, the new owner resumes from the last committed offset. Any messages processed after that offset get processed a second time.
- Broker redelivery and retries. Visibility timeouts, lost acks, and negative acknowledgements all put a message back on the queue. A slow handler can even still be working when its own message is handed to another consumer.
- Producer retries. A producer that times out waiting for confirmation publishes again. The result is two broker messages carrying the same logical event. Broker-level dedup cannot always catch this, so the consumer needs a stable business or message ID to recognise it.
You need the inbox pattern when consumers apply non-idempotent changes to a transactional store. Examples include incrementing balances, decrementing stock, or inserting rows without a natural unique key. If replaying a message is already harmless, you may not need it.
How does the inbox pattern work inside a single transaction?
The consumer treats the dedup record and the business change as one unit of work. Both rows live in the same database, so a single local transaction makes them succeed or fail together. The broker acknowledgement happens only after commit.
Broker Consumer Database
|--- deliver(msg) --->| |
| |--- BEGIN -------------->|
| |--- INSERT msg_id ------>| (unique key)
| |--- apply change ------->|
| |--- COMMIT ------------->|
|<------- ack --------| |
If the INSERT fails with a unique-constraint violation, another delivery already committed this message. The consumer rolls back, skips the business logic, and acks. The constraint is the source of truth. It is not a SELECT-then-INSERT check, which leaves a race window open.
Failure windows
- Crash before commit. The database rolls back both the dedup row and the business change. The broker never received an ack, so it redelivers. The retry starts from a clean state.
- Crash after commit, before ack. Both rows are durable. The broker redelivers, the insert hits the constraint, and the consumer skips and acks. The effect was applied once.
- Ack lost or failed in transit. From the database's point of view this is the same as the previous case. Redelivery is caught by the constraint and skipped.
Every path ends in one of two outcomes. Either nothing was persisted and the message is retried, or everything was persisted and the duplicate is skipped. No path leaves a business change committed without its dedup record, or the reverse. That guarantee depends on both writes sharing one transaction.
+----------+ deliver +-----------------+ +------------------------+
| Broker |----------->| Consumer | | Database |
| | | | BEGIN | +--------------------+ |
| | | |------->| | ONE LOCAL TXN | |
| | | | INSERT | | | |
| | | |------->| | processed_messages | |
| | | | apply | | msg_id UNIQUE | |
| | | |------->| | | |
| | | [1] crash | COMMIT | | business tables | |
| | | |------->| +--------------------+ |
| | | [2] crash | | both rows commit or |
| | ack | | | roll back together |
| |<-----------| [3] ack lost | +------------------------+
+----------+ +-----------------+
Duplicate delivery:
INSERT msg_id --> UNIQUE violation --> ROLLBACK --> skip logic --> ack
Failure windows (every path ends in a retry or a safe skip):
[1] crash before COMMIT --> txn rolls back both rows, no ack sent
--> broker redelivers, retry from clean state
[2] crash after COMMIT, --> both rows durable, broker redelivers
before ack --> INSERT hits UNIQUE, skip and ack
[3] ack lost in transit --> same as [2]: duplicate caught and skipped
The dedup insert and the business change commit in one local transaction before the broker is acked, so a crash at [1] leads to a clean retry and a crash or lost ack at [2] or [3] leads to a duplicate that the unique constraint catches and skips.
How do you implement a processed messages table for consumer deduplication?
…living in the same database, so the processed messages table belongs in the consumer's own schema, next to the business tables it protects.
The table needs three columns: consumer_name, message_id, and processed_at. The primary key is the composite (consumer_name, message_id). The handler opens a transaction and inserts the dedup row first. If that insert raises a unique-key violation, the message was already handled, so the handler rolls back, acknowledges the message, and returns. If the insert succeeds, it applies the business update and commits. Only after the commit does it acknowledge the broker. Inserting first means a concurrent duplicate fails early, before any business work is done.
Choosing the dedup key
| Key source | Stable across redelivery | Stable across replay or re-partition | Risk |
|---|---|---|---|
| Producer-assigned ID | Yes | Yes | Breaks if the producer regenerates the ID on retry |
| Broker offset or delivery tag | Usually | No | A replayed or re-partitioned message gets a new position |
| Content hash | Yes | Yes | Distinct messages with identical payloads are merged |
Offsets describe where a message sits in the broker, not what the message is. When you replay a topic into a new one or change partition counts, the same event lands at a new offset. The consumer then treats it as new and processes it again.
Content hashes have the opposite problem. Two legitimate "add 1 item" commands with the same payload produce the same hash, so the second one is silently dropped.
A producer-assigned ID is the right key only if the producer creates it once and reuses it on every retry. If the producer generates a fresh ID on each send attempt, the dedup table cannot recognise the duplicate.
Scope the key with consumer_name. If several handlers consume the same message, each one needs its own dedup record. Otherwise the first handler to finish would cause the others to skip the message.
import psycopg
from psycopg.errors import UniqueViolation
# Generic schema; lives in the consumer's own database next to business tables.
SCHEMA = """
CREATE TABLE processed_messages (
consumer_name VARCHAR(100) NOT NULL, -- scopes the key per handler
message_id VARCHAR(100) NOT NULL, -- producer-assigned, reused on retry
processed_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (consumer_name, message_id)
);
"""
CONSUMER = "inventory-reserver" # a second handler on the same topic uses its own name
def handle(conn: psycopg.Connection, msg, ack) -> None:
# Use the producer's stable ID, never the broker offset or a payload hash.
message_id = msg.headers["message-id"]
try:
with conn.transaction(): # commits on success, rolls back on exception
# Insert the dedup row first so a concurrent duplicate fails early.
conn.execute(
"INSERT INTO processed_messages (consumer_name, message_id) "
"VALUES (%s, %s)",
(CONSUMER, message_id),
)
# Business effect in the same transaction as the dedup row.
conn.execute(
"UPDATE inventory SET reserved = reserved + %s WHERE sku = %s",
(msg.body["quantity"], msg.body["sku"]),
)
except UniqueViolation:
pass # already processed by this consumer: skip the work
# Acknowledge only after commit (or after detecting a duplicate).
# A crash before this line causes redelivery, which the table absorbs.
ack(msg)
A processed_messages table keyed on (consumer_name, message_id) and a psycopg handler that inserts the dedup row and applies the business update in one transaction, treats a unique-key violation as an already-processed skip, and acknowledges the broker only afterwards.
What happens when two consumers process the same message concurrently?
Redelivery often lands while the first attempt is still running. A visibility timeout expires, a consumer group rebalances, or a broker retries after a missed ack, and two workers hold the same message_id at the same moment. Without care, both see an empty inbox and both apply the side effect.
The unique constraint on (consumer_name, message_id) settles the race, provided the inbox insert runs in the same transaction as the business write. Both workers attempt the insert. The database lets one proceed. The other blocks on the pending index entry until the first transaction finishes. If the first commits, the second gets a unique-violation error and rolls back its business changes with it. If the first rolls back, the second's insert succeeds and it does the work. Exactly one effect survives either way.
Check-then-insert breaks this. If a worker runs SELECT ... WHERE message_id = ?, sees no row, and only then inserts, both workers can pass the check before either inserts. Under typical read-committed isolation, neither can see the other's uncommitted row. Without a constraint, both inserts succeed. Moving the check outside the transaction makes the gap wider. The constraint is the arbiter, and the SELECT is only an optimisation.
At high throughput, every consumer writes to one index, which becomes a contention point. Partitioning the inbox by message key or tenant spreads that load.
Deduplication does not order messages. To process messages in order per key, route each key to a single consumer, which caps parallelism at the number of active keys.
-- PostgreSQL. The primary key is the arbiter for duplicates.
CREATE TABLE inbox (
consumer_name text NOT NULL,
message_id text NOT NULL,
received_at timestamptz NOT NULL DEFAULT now(),
PRIMARY KEY (consumer_name, message_id)
);
-- BROKEN: check-then-insert against a table with no unique constraint.
-- Workers A and B both run the SELECT before either inserts. Under
-- read committed neither sees the other's uncommitted row, so both
-- find nothing, both debit the account, and both inserts succeed.
SELECT 1 FROM inbox_no_key
WHERE consumer_name = 'billing' AND message_id = 'msg-7f3a';
-- (no row found, so the worker continues)
UPDATE accounts SET balance = balance - 40 WHERE id = 1001;
INSERT INTO inbox_no_key (consumer_name, message_id)
VALUES ('billing', 'msg-7f3a');
-- CORRECT: claim the message and apply the effect in one transaction.
BEGIN;
INSERT INTO inbox (consumer_name, message_id)
VALUES ('billing', 'msg-7f3a');
-- Worker B blocks on this insert until A's transaction ends.
-- If A commits, B fails with SQLSTATE 23505 (unique_violation)
-- and rolls back, so its debit never happens.
-- If A rolls back, B's insert succeeds and B performs the debit.
UPDATE accounts SET balance = balance - 40 WHERE id = 1001;
COMMIT;
A PostgreSQL contrast: check-then-insert without a constraint lets two concurrent workers apply the same debit. Inserting into a keyed inbox in the same transaction as the business write lets only one of them commit.
Dedup-only table vs full inbox, and combining inbox with outbox
The simplest variant is a dedup-only table. The handler opens a transaction, inserts the message ID into the processed messages table, applies the state change, and commits. The broker ack follows the commit. Nothing new runs, but retries, ordering, and pacing remain the broker's job.
A full inbox splits receipt from processing. The consumer only persists the raw message and acks. A separate worker claims rows and processes them. Because the broker is out of the loop after the ack, the worker sets its own retry backoff and per-key ordering, and a slow handler no longer holds broker deliveries open. The price is new machinery to build and run.
| Concern | Dedup-only table | Full inbox |
|---|---|---|
| Moving parts | Handler only | Receiver plus worker |
| Retries and backoff | Broker redelivery | Worker-controlled |
| Per-key ordering | Depends on broker partitioning | Enforced by worker claim logic |
| Broker ack timing | After processing | After persisting |
| Operational cost | Low | Polling or notification, stuck-claim recovery, poison-message policy, backlog-age alerts |
In a consume-transform-produce service, the inbox and the outbox share one transaction. The dedup insert, the state change, and the outgoing event row commit together or not at all. This prevents a redelivery from emitting a second event, and it prevents a state change from being saved without its event.
This guarantee ends at the database boundary. An HTTP call, an email, or a write to another store made inside the handler can still run twice. Pass a stable idempotency key, derived from the message ID, to the downstream system. Better still, write the request to the outbox and let a relay perform it.
How long should you keep processed message records, and how do you test the inbox?
Size the retention window from the longest gap that can separate two deliveries of the same message. Do not pick a round-number TTL. That gap covers the broker's maximum redelivery delay, how far back an operator can rewind a consumer's offset, how long a message can sit in a dead-letter queue before someone re-drives it, and how long producers keep retrying. If the log can be replayed for seven days, a 24-hour dedup window is a latent bug. Take the largest of these and add a margin.
Purging too early fails silently. Once the record is gone, a late duplicate looks like a new message, and the handler applies its effect a second time.
Cleanup is time-based. A periodic job runs something like DELETE FROM processed_messages WHERE processed_at < now() - interval '14 days' (PostgreSQL syntax). Run it in bounded batches, with an index on processed_at, so it does not hold long locks. At high volume, partition the table by day on processed_at and drop expired partitions instead. Dropping a partition is nearly free, while large deletes create write load and vacuum work.
Testing the inbox
The failures this pattern exists for rarely happen in normal runs, so force them:
- Duplicate injection: deliver the same message twice. Assert one effect and one inbox row.
- Crash before commit: kill the handler mid-transaction. Assert redelivery processes the message exactly once.
- Crash after commit, before ack: assert redelivery is detected and skipped.
- Concurrent delivery: hand one message to two consumers at once. Assert that one commits and the other produces no effect.
- Expired record: replay a message older than retention. Document the result as known behavior.
-- Inbox table (PostgreSQL). The PK on (consumer, message_id) is what rejects duplicates.
CREATE TABLE IF NOT EXISTS processed_messages (
consumer_name text NOT NULL,
message_id text NOT NULL,
processed_at timestamptz NOT NULL DEFAULT now(),
PRIMARY KEY (consumer_name, message_id)
);
-- Lets the cleanup job find expired rows without a full scan.
CREATE INDEX IF NOT EXISTS processed_messages_processed_at_idx
ON processed_messages (processed_at);
-- Retention = longest redelivery/replay horizon (e.g. 7-day log replay)
-- plus margin. 14 days is an assumed value; derive yours from broker config.
-- Delete in bounded batches so each statement holds locks briefly.
-- The job reruns this until it reports 0 rows deleted.
DELETE FROM processed_messages
WHERE (consumer_name, message_id) IN (
SELECT consumer_name, message_id
FROM processed_messages
WHERE processed_at < now() - interval '14 days'
ORDER BY processed_at
LIMIT 5000
);
-- Partitioning caveat: on a table partitioned by processed_at, the primary
-- key must include processed_at. That turns it into (consumer, id, time),
-- so a duplicate arriving on a later day would NOT conflict. If you
-- partition, use a partition key fixed per message (e.g. the producer's
-- event timestamp carried in the message) so both deliveries map to the
-- same row, then drop whole expired partitions instead of deleting rows.
A PostgreSQL inbox table with a batched, index-backed time-based cleanup query, plus a warning that naive partitioning by processed_at breaks duplicate detection.
When should you avoid the inbox pattern, and what are the alternatives?
The inbox has costs. Every message adds an insert and a unique-index lookup to the handler's transaction. That raises per-message latency, increases write load on the database, and can lower throughput on busy partitions. It also only protects state committed in that same transaction. If a handler also updates a cache, a search index, or a second database, those effects can still run twice. Someone also has to own retention jobs, table growth, and monitoring.
Cheaper options often cover the same risk:
| Approach | Works when | Limitation |
|---|---|---|
| Idempotent upsert keyed by entity ID with a version check | The message carries full state or a monotonic version | Does not fit increments or appends |
| Downstream idempotency key | The effect is an external call that accepts a key | Relies on the receiver's dedup window |
| Broker-level transactions | Consumed offsets and outputs both live in the broker | Does not cover writes to an external database |
Per-handler decision guide
Use the inbox only when all three conditions hold:
- The effect is not naturally idempotent, such as counters, ledger entries, or sent notifications.
- The effect lands in the same transactional store as the inbox table.
- A duplicate causes harm that users or auditors would notice.
If any condition fails, use an alternative from the table or accept the duplicates.
A shared inbox library and the test harness from the previous section replace ad-hoc duplicate checks in each team's code. They also cut the time spent debugging double-processing incidents. Applying the pattern to every handler by default undoes those savings, because handlers that never needed it pay the latency and maintenance cost.
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, 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.
- Changing a shared variable is one edit and one review instead of editing every service's
.envby hand.
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.
- A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
- 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.