Transactional Outbox: как надёжно отправить событие из базы в брокер
Паттерн Transactional Outbox простыми словами: проблема двойной записи в БД и брокер, таблица outbox, релей на опросе или CDC через Debezium, порядок событий и идемпотентный потребитель с inbox.
Коротко
| Вопрос | Ответ |
|---|---|
| Какую проблему решает | Двойная запись: изменить базу и отправить событие в брокер так, чтобы одно не потерялось без другого |
| Главная идея | Событие пишется в таблицу outbox той же базы в той же транзакции, что и бизнес-данные |
| Кто отправляет в брокер | Отдельный релей: опрашивает таблицу (polling) или читает журнал транзакций (CDC, Debezium) |
| Какая гарантия | At-least-once: событие уйдёт тогда и только тогда, когда транзакция зафиксирована, но может уйти дважды |
| Что нужно на той стороне | Идемпотентный потребитель: дедупликация по event_id, например таблицей inbox |
Outbox не делает распределённую транзакцию. Он сводит две записи в разные системы к одной локальной транзакции и честной повторной доставке.
Проблема двойной записи
Сервис заказов создаёт заказ и сообщает об этом остальным: складу, рассылке, аналитике. Самый очевидный код:
save_order(order) # 1. запись в базу
broker.publish(event) # 2. событие в Kafka / RabbitMQ
Между шагами 1 и 2 может случиться что угодно: процесс убили при деплое, брокер не ответил за таймаут, сеть моргнула. Заказ в базе есть, события нет. Склад не резервирует товар, письмо не уходит, и никто об этом не узнает, пока не пожалуется клиент.
Поменять шаги местами не помогает: событие ушло, а транзакция в базе откатилась из-за нарушения ограничения. Теперь склад резервирует товар под заказ, которого не существует.
Вот эта ситуация в коде. Здесь и дальше SQLite из стандартной библиотеки Python вместо Postgres, а брокер — список в памяти, чтобы пример запускался без инфраструктуры:
import json import sqlite3 import uuid class Crash(Exception): """Процесс упал в этой точке.""" class Broker: def __init__(self): self.messages = [] def publish(self, topic, key, value): self.messages.append((topic, key, value)) def make_db(): db = sqlite3.connect(':memory:', isolation_level=None) db.executescript(''' CREATE TABLE orders (id TEXT PRIMARY KEY, total INTEGER NOT NULL); CREATE TABLE outbox ( seq INTEGER PRIMARY KEY AUTOINCREMENT, event_id TEXT NOT NULL UNIQUE, aggregate_id TEXT NOT NULL, type TEXT NOT NULL, payload TEXT NOT NULL, published_at TEXT ); ''') return db # --- Двойная запись: база и брокер по отдельности --- def create_order_naive(db, broker, order_id, total, crash=False): db.execute('INSERT INTO orders VALUES (?, ?)', (order_id, total)) if crash: raise Crash('упали после коммита в базу, до публикации') broker.publish('orders', order_id, {'type': 'OrderCreated', 'total': total}) db, broker = make_db(), Broker() try: create_order_naive(db, broker, 'o-1', 500, crash=True) except Crash: pass print('naive: orders =', db.execute('SELECT count(*) FROM orders').fetchone()[0], 'events =', len(broker.messages)) # naive: orders = 1 events = 0
Почему не распределённая транзакция
Классический ответ на «две системы должны измениться атомарно» — двухфазный коммит (XA). Здесь он почти никогда не подходит:
- Kafka не участвует в XA-транзакциях. Её собственные транзакции атомарно связывают записи в несколько топиков и коммит смещений потребителя, но не вашу базу.
- 2PC блокирует ресурсы, пока координатор не примет решение. Упал координатор — участники ждут.
- Доступность системы становится произведением доступностей базы и брокера: недоступен брокер, и вы не можете принять заказ.
Подробнее о том, почему в микросервисах отказываются от 2PC, — в статье про паттерн Saga. Outbox решает задачу скромнее и надёжнее.
Идея outbox
Брокер на время забываем. В той же транзакции, где создаётся заказ, сервис вставляет строку в таблицу outbox своей же базы. Транзакция атомарна: либо есть и заказ, и событие, либо ни того, ни другого. Доставкой в брокер занимается отдельный процесс, релей: он читает новые строки, публикует их и отмечает отправленными.
┌──────────── сервис заказов ────────────┐
│ BEGIN │
│ INSERT INTO orders ... │
│ INSERT INTO outbox ... │
│ COMMIT │
└─────────────────┬───────────────────────┘
│ база данных
┌─────────▼──────────┐ ┌────────┐ ┌─────────────┐
│ релей (polling/CDC) │ ────► │ брокер │ ────► │ потребители │
└────────────────────┘ └────────┘ └─────────────┘
Код продолжает предыдущий блок:
# --- Outbox: заказ и событие в одной транзакции --- def create_order(db, order_id, total, crash=False): db.execute('BEGIN') try: db.execute('INSERT INTO orders VALUES (?, ?)', (order_id, total)) if crash: raise Crash('упали посреди транзакции') db.execute( 'INSERT INTO outbox (event_id, aggregate_id, type, payload) ' 'VALUES (?, ?, ?, ?)', (str(uuid.uuid4()), order_id, 'OrderCreated', json.dumps({'order_id': order_id, 'total': total})), ) db.execute('COMMIT') except BaseException: db.execute('ROLLBACK') raise def relay_once(db, broker, batch=100, crash_before_mark=False): """Один проход релея: прочитать неотправленное, опубликовать, отметить.""" rows = db.execute( 'SELECT seq, event_id, aggregate_id, type, payload FROM outbox ' 'WHERE published_at IS NULL ORDER BY seq LIMIT ?', (batch,) ).fetchall() for seq, event_id, aggregate_id, type_, payload in rows: broker.publish('orders', aggregate_id, {'event_id': event_id, 'type': type_, **json.loads(payload)}) if crash_before_mark: raise Crash('опубликовали, но не успели отметить') db.execute("UPDATE outbox SET published_at = datetime('now') WHERE seq = ?", (seq,)) return len(rows) db, broker = make_db(), Broker() create_order(db, 'o-1', 500) create_order(db, 'o-2', 300) try: create_order(db, 'o-3', 700, crash=True) except Crash: pass print('outbox: orders =', db.execute('SELECT count(*) FROM orders').fetchone()[0], 'pending events =', db.execute('SELECT count(*) FROM outbox WHERE published_at IS NULL').fetchone()[0]) # outbox: orders = 2 pending events = 2 try: relay_once(db, broker, crash_before_mark=True) # релей упал except Crash: pass relay_once(db, broker) # перезапуск print('published:', [(m[1], m[2]['type']) for m in broker.messages]) # published: [('o-1', 'OrderCreated'), ('o-1', 'OrderCreated'), ('o-2', 'OrderCreated')]
Три вывода из этого запуска:
- Заказ
o-3упал посреди транзакции — нет ни заказа, ни события. Рассинхронизации больше не бывает. - Релей опубликовал событие
o-1и упал, не поставив отметку. После рестарта событие ушло ещё раз. Это не баг реализации, а неустранимое свойство: публикация в брокер и отметка в базе — снова две системы, и между ними снова можно упасть. - Значит, outbox даёт at-least-once. Дубли надо гасить на стороне потребителя, о чём ниже.
Таблица outbox в Postgres
Минимальная схема:
CREATE TABLE outbox ( seq BIGSERIAL PRIMARY KEY, event_id UUID NOT NULL UNIQUE, aggregate_type TEXT NOT NULL, -- 'order', 'payment': по нему выбирается топик aggregate_id TEXT NOT NULL, -- ключ партиции в брокере type TEXT NOT NULL, -- 'OrderCreated', 'OrderPaid' payload JSONB NOT NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT now(), published_at TIMESTAMPTZ ); -- Релею нужны только неотправленные строки, индекс остаётся маленьким CREATE INDEX outbox_pending ON outbox (seq) WHERE published_at IS NULL;
Несколько решений, которые стоит принять сознательно:
event_idгенерирует отправитель, а не брокер. По нему потребители дедуплицируют, и он не меняется при повторной публикации. Смещение (offset) в Kafka для этого не годится: у дубля оно другое.aggregate_id— ключ сообщения. Брокер кладёт сообщения с одним ключом в одну партицию, и события одного заказа читаются по порядку.payload— контракт, а не дамп строки. Событие описывает факт для внешнего мира («заказ создан на 500 рублей»), а не внутреннюю схему таблицыorders. Тогда рефакторинг базы не ломает потребителей.
Релей на опросе (polling)
Простейший релей — цикл: выбрать пачку неотправленных строк, опубликовать, дождаться подтверждения брокера, отметить, повторить. В Postgres с несколькими экземплярами релея:
BEGIN; SELECT seq, event_id, aggregate_type, aggregate_id, type, payload FROM outbox WHERE published_at IS NULL ORDER BY seq LIMIT 100 FOR UPDATE SKIP LOCKED; -- публикуем каждую строку и ждём подтверждения брокера (acks=all) UPDATE outbox SET published_at = now() WHERE seq = ANY(:published_seqs); COMMIT;
FOR UPDATE SKIP LOCKED не даёт двум экземплярам взять одну и ту же строку: второй просто пропустит заблокированные. Базовая схема очереди на Postgres и цена этого запроса описаны в статье про очереди сообщений. Здесь разберём то, на чём спотыкаются в продакшене.
Порядок событий
Пусть заказ o-1 получил события OrderCreated и OrderPaid. Два экземпляра релея с SKIP LOCKED могут разобрать их по разным пачкам, и OrderPaid уйдёт первым. Потребитель увидит оплату несуществующего заказа.
Варианты:
- Один активный релей. Остальные в горячем резерве, лидер выбирается через advisory lock в Postgres или через распределённую блокировку. Пропускной способности одного процесса часто хватает на тысячи событий в секунду.
- Шардирование релеев по агрегату. Экземпляр из берёт только строки с
hash(aggregate_id) % k = i. Порядок внутри агрегата сохраняется, а разные агрегаты идут параллельно. - Порядок на стороне потребителя. В событии номер версии агрегата, потребитель отбрасывает или откладывает события «из будущего». Надёжнее всего, но сложнее.
Ещё одна ловушка: seq выдаётся в момент INSERT, а видимой строка становится в момент COMMIT. Транзакция с seq = 10 может закоммититься раньше транзакции с seq = 9. Если релей запоминает «последний отправленный seq» и читает WHERE seq > :last, строку 9 он не увидит никогда. Отбор по published_at IS NULL от этой потери защищает.
Публикация в брокер
- Ждите подтверждения брокера до отметки: в Kafka
acks=all, в RabbitMQ publisher confirms. Отметка до подтверждения — это прямая потеря события. - Включите идемпотентного продюсера Kafka (
enable.idempotence=true): он не создаст дубль при внутреннем ретрае и не перепутает порядок внутри партиции. Дубли из-за падения самого релея он не убирает — для этого естьevent_id.
Задержка и нагрузка
Опрос раз в 100 мс — это 10 запросов в секунду к базе от каждого экземпляра, даже когда событий нет. Длинный интервал увеличивает задержку доставки. Обычные приёмы: короткий интервал, пока строки есть, и экспоненциальная пауза, когда пусто. В Postgres можно будить релей через LISTEN/NOTIFY после коммита и оставить опрос как страховку.
Очистка
Отправленные строки копятся. Через месяц таблица на сотни миллионов строк замедлит и вставки, и автовакуум. Удаляйте пачками по published_at < now() - interval '7 days' или, лучше, партиционируйте таблицу по дням и отрезайте старые партиции целиком. Несколько дней хранения полезны: по ним удобно расследовать, что и когда ушло.
CDC: Debezium вместо опроса
Второй способ — не спрашивать базу, а читать её журнал транзакций. Postgres пишет все изменения в WAL; при wal_level = logical внешний процесс может получать их как поток через слот логической репликации. Debezium делает именно это: подписывается на изменения таблицы outbox и превращает каждую вставку в сообщение Kafka.
Фрагмент конфигурации Kafka Connect:
{ "name": "orders-outbox", "config": { "connector.class": "io.debezium.connector.postgresql.PostgresConnector", "plugin.name": "pgoutput", "database.hostname": "orders-db", "database.dbname": "orders", "topic.prefix": "orders", "table.include.list": "public.outbox", "transforms": "outbox", "transforms.outbox.type": "io.debezium.transforms.outbox.EventRouter" } }
Преобразование EventRouter разбирает строку outbox на части. По умолчанию оно ждёт колонки id, aggregatetype, aggregateid, type, payload, кладёт событие в топик outbox.event.<aggregatetype> и использует aggregateid как ключ сообщения. Имена колонок и шаблон топика настраиваются. Удаления строк из outbox оно отфильтровывает, поэтому распространённый приём — удалять строку в той же транзакции сразу после вставки: в WAL вставка остаётся, Debezium её опубликует, а таблица не растёт.
Чем CDC лучше опроса:
- Задержка — доли секунды без нагрузки на базу пустыми запросами.
- Порядок — события читаются в порядке коммитов, а не в порядке
seq, и ловушка с невидимой строкой исчезает. - Нет отметок
published_at: позицию в журнале хранит сам Debezium.
Чем платим:
- Ещё одна инфраструктура. Kafka Connect, мониторинг коннектора, обновления.
- Слот репликации держит WAL. Если коннектор остановился, Postgres не удаляет журнал, который тот ещё не прочитал. За выходные диск может закончиться. Нужен алерт на отставание слота.
- Дубли никуда не делись. После перезапуска коннектор может повторно отдать события с последней сохранённой позиции. Гарантия по-прежнему at-least-once.
CDC прямо с бизнес-таблиц?
Можно подписать Debezium на таблицу orders напрямую и обойтись без outbox. Так делают для репликации данных в хранилище или поиск. Для событий между сервисами это плохо: потребители начинают зависеть от внутренней схемы вашей таблицы, а из изменения строки не всегда понятно, какое бизнес-событие произошло. Outbox — это публичный контракт поверх приватной схемы.
Идемпотентный потребитель: inbox
Раз дубли неизбежны, потребитель обязан их распознавать. Надёжный способ — таблица inbox в базе потребителя: запись «событие обработано» и эффект обработки фиксируются в одной транзакции. Это зеркальное отражение outbox.
# --- Потребитель: дедупликация через таблицу inbox в своей базе --- def make_consumer_db(): db = sqlite3.connect(':memory:', isolation_level=None) db.executescript(''' CREATE TABLE inbox (event_id TEXT PRIMARY KEY); CREATE TABLE stats (name TEXT PRIMARY KEY, value INTEGER NOT NULL); INSERT INTO stats VALUES ('orders', 0), ('revenue', 0); ''') return db def handle(db, message): db.execute('BEGIN') try: cur = db.execute('INSERT OR IGNORE INTO inbox VALUES (?)', (message['event_id'],)) if cur.rowcount == 0: # уже обрабатывали db.execute('ROLLBACK') return 'duplicate' db.execute("UPDATE stats SET value = value + 1 WHERE name = 'orders'") db.execute("UPDATE stats SET value = value + ? WHERE name = 'revenue'", (message['total'],)) db.execute('COMMIT') # отметка и эффект — атомарно return 'applied' except BaseException: db.execute('ROLLBACK') raise consumer = make_consumer_db() print([handle(consumer, m[2]) for m in broker.messages]) # ['applied', 'duplicate', 'applied'] print(dict(consumer.execute('SELECT name, value FROM stats'))) # {'orders': 2, 'revenue': 800}
Дубль o-1 из-за падения релея отброшен, выручка посчитана один раз. В Postgres вместо INSERT OR IGNORE пишут INSERT ... ON CONFLICT (event_id) DO NOTHING и проверяют число вставленных строк.
Важные детали:
- Отметка и эффект — в одной транзакции. Если записать
event_idв Redis, а эффект в базу, вернётся та же проблема двойной записи, только на стороне потребителя. - Смещение в брокере коммитится после транзакции. Упали между ними — получите сообщение повторно, и inbox его отбросит.
- Inbox тоже чистят, но хранят дольше, чем возможный повтор: если релей может переотправить событие через сутки, неделя хранения — разумный запас.
- Естественная идемпотентность лучше inbox.
UPDATE orders SET status = 'paid' WHERE id = ?безопасно применять дважды и без таблицы. Inbox нужен для неидемпотентных эффектов: счётчиков, списаний, писем.
Шире про ключи идемпотентности, ретраи и почему exactly-once на практике означает at-least-once плюс дедупликацию, — в статье про идемпотентность.
Где outbox встречается
- Саги. Каждый шаг меняет свою базу и отправляет команду или событие следующему. Без outbox сага теряет шаги, подробности в статье про Saga.
- Event sourcing. Журнал событий сам по себе и есть outbox: события — это и данные, и сообщения. Отдельная таблица не нужна, см. Event Sourcing и CQRS.
- Уведомления, поиск, кэш. Любая производная система, которая должна узнать об изменении. Например, инвалидация кэша по событию не потеряется, если событие ушло через outbox.
Альтернативы
| Подход | Как работает | Когда уместен |
|---|---|---|
| Outbox + polling | Таблица и релей, опрашивающий её | По умолчанию: просто, не нужна новая инфраструктура |
| Outbox + CDC | Таблица, Debezium читает WAL | Много событий, важны задержка и порядок коммитов |
| Listen to yourself | Сначала событие в брокер, сервис сам его читает и пишет в базу | Когда клиенту можно ответить до записи в базу |
| Event sourcing | Журнал событий — единственный источник правды | Когда история изменений — часть домена |
| 2PC / XA | Распределённая транзакция | Почти никогда: брокер не поддерживает, доступность падает |
Как рассказывать на собеседовании
Тема всплывает в любом дизайне с микросервисами, когда вы говорите «сервис пишет в базу и отправляет событие». Хорошая реакция — остановиться и сказать это раньше интервьюера:
Здесь двойная запись: если сервис упадёт между коммитом и публикацией, событие потеряется. Поэтому событие пишу в таблицу outbox в той же транзакции, что и заказ. Релей публикует его в Kafka с ключом
order_id, чтобы сохранить порядок внутри заказа. Для начала хватит опроса сSKIP LOCKED, при росте нагрузки перейду на Debezium. Доставка at-least-once, потребители дедуплицируют поevent_idчерез таблицу inbox в своей базе.
Вопросы, которые спросят дальше
| Вопрос | Что ответить |
|---|---|
| Даёт ли outbox exactly-once? | Нет. Отправка at-least-once, «ровно один раз» — это эффект идемпотентного потребителя |
| Что будет, если брокер недоступен час? | Заказы принимаются, события копятся в outbox и уйдут после восстановления. Нужен алерт на возраст старейшей неотправленной строки |
| Как сохранить порядок? | Ключ партиции = aggregate_id, один релей или шардирование релеев по агрегату, версии в событиях |
| Почему не публиковать прямо из транзакции? | Публикация внутри транзакции не откатывается вместе с ней, и долгий запрос в брокер держит блокировки |
| Чем polling хуже CDC? | Задержка, нагрузка от пустых запросов, ловушка с порядком seq. Зато нет новой инфраструктуры |
| Что мониторить? | Число и возраст неотправленных строк, отставание слота репликации, ошибки публикации, размер таблицы |
Частые ошибки
- Публикация после коммита «с ретраями». Ретраи живут в памяти процесса и умирают вместе с ним. Надёжно только то, что записано в базу.
- Отметка до подтверждения брокера. Событие помечено отправленным, но до брокера не дошло — потеряно навсегда.
- Нет
event_idили он генерируется при публикации. Потребителю нечем отличить дубль от нового события. - Чтение по
seq > last_seq. Пропускает строки, закоммиченные позже соседей с большим номером. - Несколько релеев без мысли о порядке.
SKIP LOCKEDзащищает от двойного захвата, но не от перестановки событий одного агрегата. - Outbox в другой базе. Таблица обязана жить в той же базе и писаться в той же транзакции, иначе это снова двойная запись.
- Никто не чистит таблицу и не следит за слотом репликации. Обе проблемы проявляются не сразу, а через недели — заполненным диском.