Transactional Inbox

Overview

The inbox is the receiving counterpart of the outbox. Where the outbox makes publishing atomic with a state change, the inbox makes consuming atomic with its effects.

The unique message id is the heart of it: the database becomes the arbiter of whether a message was already handled.

Two variants exist. In the inline variant, the handler does the work inside the same transaction that records the id, which is simplest. In the deferred variant, the receiver only stores the message and a separate processor handles pending rows, which isolates slow handlers from the broker connection and gives you a queryable backlog.

How it works

Within one transaction the handler inserts into inbox, applies business changes and commits. Only then does it acknowledge the broker.

BEGIN;
  INSERT INTO inbox(message_id, received_at) VALUES (:id, now())
    ON CONFLICT DO NOTHING;
  -- if 0 rows inserted: duplicate, skip to ack
  UPDATE stock SET qty = qty - :n WHERE sku = :sku;
COMMIT;
broker.ack(id)

The inbox also helps with diagnostics, because each row records when a message arrived and its outcome. Add a status column and attempt count to support retries and manual inspection. Index the id column, keep rows small, and partition the table by time so old data can be dropped cheaply instead of running slow deletes.

Pitfalls

• Acknowledging before the commit.
• Using a consumer-generated id, which differs per delivery.
• Purging rows sooner than the broker can redeliver.
• Calling external APIs inside the transaction and holding locks.

Key takeaways

• Dedup row and effect commit together.
• Use the producer-assigned message id.
• Ack only after commit.
• Purge on a schedule longer than redelivery windows.