Transaction outbox: что он гарантирует, чего не гарантирует и во что обходится

Задача

db.insert(order)
db.commit()
broker.publish(OrderPlaced(order.id))   # <- здесь процесс умер

Заказ есть, события нет — потребитель о нём не узнает никогда. Поменяйте строки местами: событие есть, заказа нет — потребитель обработает призрак.

Третьего порядка не существует.

Решение

Событие становится строкой той же базы:

CREATE TABLE outbox (
    id           bigserial PRIMARY KEY,
    payload      jsonb       NOT NULL,
    published_at timestamptz
);

db.insert(order)
db.insert(Outbox(payload={"type": "OrderPlaced", "order_id": order.id}))
db.commit()          # обе строки или ни одной

Отдельный процесс — релей — читает строки и отправляет их в брокер.

Что это стоит

Строка outbox добавляет к транзакции 30 %: она едет в тот же WAL и коммитится тем же fsync. Отдельная транзакция для события стоит вдвое дороже — два fsync вместо одного.

То есть небезопасный способ ещё и медленнее.

Ошибка, которая не даёт о себе знать

Самый естественный релей помнит, до какого номера дошёл:

SELECT id, payload FROM outbox WHERE id > :last_id ORDER BY id;   -- неправильно

bigserial выдаёт номер при INSERT, а видимой строка становится при COMMIT. Транзакция, начавшаяся раньше, коммитится позже — и появляется позади уже прочитанного. Отметка ушла вперёд, строка потеряна навсегда.

Ни исключения, ни лога. Метрика отставания показывает ноль.

Правильно — не помнить ничего:

SELECT id, payload FROM outbox
  WHERE published_at IS NULL
  ORDER BY id LIMIT 100
  FOR UPDATE SKIP LOCKED;

SKIP LOCKED заодно разводит два релея: первый берёт строки 1–3, второй 4–6, пересечения нет.

Чего паттерн не даёт

Порядок. Пока транзакции не пересекаются во времени, порядок вставок и порядок коммитов совпадают. Стоит двум пересечься — и всё: приложение вставило A, потом B, а доставлены будут B, потом A. Через чтение WAL то же самое. Сохранить порядок можно только внутри одного ключа: положите идентификатор заказа в ключ сообщения, и события одного заказа придут по порядку — пока релей один, потому что два релея со SKIP LOCKED обгоняют друг друга.

«Ровно один раз». Между отправкой и пометкой тоже можно упасть. Поменять их местами нельзя — тогда событие потеряется, а это хуже. Значит, дубли неизбежны, и потребитель должен быть идемпотентным:

INSERT INTO processed (event_id) VALUES (:id) ON CONFLICT DO NOTHING;
-- вставилось 0 строк -> дубль, работу не делаем

Вставка идентификатора и сама обработка — одной транзакцией. Иначе вы построили ту же двойную запись, с которой начали.

Два обязательных пункта эксплуатации

Частичный индекс. Релей почти всё время спрашивает «есть ли работа» и получает «нет». Без индекса на таблице в 71 МБ это 24 мс на каждый холостой опрос.

CREATE INDEX outbox_unpublished ON outbox (id) WHERE published_at IS NULL;

53 микросекунды вместо 24 миллисекунд. И индекс не растёт вместе с таблицей: при пустой очереди — 8192 байта против 71 МБ у таблицы.

Уборка. DELETE места не возвращает: полмиллиона строк удаляются за 0,55 с, таблица как весила 71 МБ, так и весит. VACUUM вернёт страницы под повторную запись (после него 11 МБ), но операционной системе отдаст только хвост файла. При заметном потоке — секции по времени и DROP секции.

Когда не нужен

Если получатель — та же база, пишите в одной транзакции. Если событие можно потерять без последствий, отправляйте напрямую.

Обязателен он там, где по событию произойдёт необратимое действие — списание, отгрузка, письмо, — а расхождение обнаружится не сразу.

Задача, у которой нет решения в лоб

Обработчик делает две вещи: пишет заказ в базу и сообщает о нём брокеру.

def place_order(request):
    order = Order(total=request.total)
    db.insert(order)
    db.commit()
    broker.publish(OrderPlaced(order.id))

Между commit() и publish() процесс может умереть. Не «теоретически»: деплой, OOM-killer, потеря сети до брокера, таймаут. Поменяйте строки местами — станет не лучше, а иначе.

Оба порядка неправильны, и по-разному. Потерянное событие тихо: обе системы считают, что у них всё в порядке, и узнаете вы об этом от пользователя. Событие-призрак шумно: потребитель спишет резерв или отправит письмо про заказ, которого нет.

Третьего порядка не существует. Пока брокер не участвует в транзакции базы, между двумя записями всегда есть момент.

Распределённая транзакция на два ресурса эту задачу решала бы — но платить за неё придётся координатором и блокировками на время согласования. А для брокера это и вовсе не вариант: Kafka в двухфазном коммите не участвует.

Решение: сделать событие строкой той же базы

CREATE TABLE outbox (
    id           bigserial PRIMARY KEY,
    payload      jsonb       NOT NULL,
    published_at timestamptz
);

def place_order(request):
    order = Order(total=request.total)
    db.insert(order)
    db.insert(Outbox(payload={"type": "OrderPlaced", "order_id": order.id}))
    db.commit()          # обе строки или ни одной

Обратите внимание, чего здесь нет. Нет ничего специфического для паттерна: это обычная атомарность транзакции. Всё изобретение — в том, что сообщение перестало быть сообщением и стало строкой.

Дальше нужен второй процесс — релей, который читает строки и отправляет их в брокер. Именно в нём и живут все настоящие вопросы.

payload jsonb — это не схема, а её отсутствие

В таблице выше payload — столбец jsonb, и это упрощение, за которое платят позже. Релей его содержимого не читает и не проверяет:

То есть между отправителем и потребителем нет ни одной точки, где несовместимое изменение было бы замечено. Оно проявится у потребителя, в продакшене, на сообщениях, которые уже нельзя не отправить.

Ссылочная форма таблицы у Debezium поэтому шире трёх столбцов:

id            | uuid                   | not null
aggregatetype | character varying(255) | not null
aggregateid   | character varying(255) | not null
type          | character varying(255) | not null
payload       | jsonb                  |

Каждый столбец здесь отвечает за что-то, что иначе придётся решать в коде. aggregatetype определяет имя топика, aggregateid становится ключом сообщения (а значит — разделом и порядком), type уезжает заголовком, а id — тем, по чему потребитель убирает дубли: You can use this ID, for example, to remove duplicate messages (Этот идентификатор можно использовать, например, чтобы убирать дубли сообщений).

Разница с bigserial из нашего DDL здесь принципиальная, и к ней мы вернёмся в следующем разделе.

Отдельно про сам конверт. Как только полей становится больше одного, значение сообщения перестаёт быть голой нагрузкой:

Что делать со сменой схемы. Правила совместимости придумывать не надо — они записаны в форматах, которые для этого и сделаны. У Avro они сформулированы как правила чтения, и из них прямо следуют обе совместимости:

Первое правило — про старого читателя и нового писателя, второе — про нового читателя и старого писателя. Обоих не будет, если у нового поля нет значения по умолчанию: тогда старое сообщение просто не прочитается.

У протокол-буферов те же три правила названы прямым текстом: Adding new fields is safe (Добавлять новые поля безопасно), Removing fields is safe (Удалять поля безопасно) и, в противоположность им, Changing field numbers for any existing field is not safe (Менять номера у любого существующего поля небезопасно). Плюс отдельная оговорка, которой в JSON-схеме соответствия нет: удалённый номер нельзя переиспользовать, для этого есть reserved.

Практическое правило для outbox складывается из этого само: менять смысл существующего поля нельзя, добавлять поле со значением по умолчанию можно, удалять — можно, если ни один потребитель его не требует. Всё остальное — новый type, а не новая версия старого. И если нужен не договор на словах, а проверка, Debezium называет способ:

Переиграть события: почему это не «просто прочитать таблицу снова»

Рано или поздно топик придётся наполнить заново: потребитель появился позже событий, топик удалили, данные испортили. Debezium перечисляет поводы прямо:

И тут же — предложение, ради которого этот раздел написан:

Дописывает, а не заменяет. Потребитель получает вторую копию всего. Это не дефект инструмента: у топика нет операции «переписать», и быть её не может. Значит, вся тяжесть переигрывания ложится на дедупликацию у потребителя — ту самую, которая обязательна из-за доставки «не менее одного раза» — ей посвящён отдельный раздел ниже:

И вот здесь id bigserial из нашего DDL перестаёт годиться. Дедупликация работает по стабильному идентификатору события, а bigserial при переигрывании выдаст новый номер — тот же INSERT … ON CONFLICT DO NOTHING пропустит дубль как новое событие. Поэтому у Debezium id — uuid, задаваемый при вставке, а не последовательностью. Менять это дешевле до первого переигрывания, чем после.

Второе следствие, и оно противоречит разделу про рост таблицы ниже. Совет удалять отправленные строки — DROP секции вместо DELETE — экономит место ровно за счёт возможности переиграть. Удалённая секция — это удалённая история. Решать здесь приходится один вопрос, и лучше явно: сколько времени назад вы готовы переиграть события. Отсюда и срок хранения секций, а не наоборот.

Про сторону потребителя (сдвинуть смещение и прочитать топик заново) — то же самое с другой стороны: дубли создаёт не только повторная отправка, но и повторное чтение, и защищает от обеих одна и та же таблица обработанных идентификаторов.

Сколько это стоит

Возражение против outbox почти всегда одно: лишняя запись в горячем пути. Возражение проверяемое.

Строка outbox добавляет к транзакции 30 % — она едет в тот же WAL и коммитится тем же fsync, что и заказ. А популярный способ «не грузить транзакцию» — записать событие отдельно — стоит вдвое дороже, потому что в нём два коммита и два fsync. То есть небезопасный вариант здесь ещё и медленнее безопасного.

Это тот случай, когда интуиция подводит ровно наоборот: люди избегают outbox из соображений производительности и получают решение медленнее.

Релей: два способа, и между ними не «вкус»

Разница между ними не в надёжности: доставят всё и тот и другой. Различий пять, и выбирают обычно по последнему — по цене эксплуатации:

Debezium, основная реализация чтения журнала, требование к таблице формулирует прямо:

То есть таблица под эти два способа выглядит по-разному, и переехать с одного на другой — не смена процесса, а миграция схемы.

Ошибка, которая стоит дороже всех

Самая естественная реализация опрашивающего релея — помнить, до какого номера дошёл:

SELECT id, payload FROM outbox WHERE id > :last_id ORDER BY id;

Она неправильна, и ломается не в редком случае, а в обычном.

Причина в том, что два момента жизни строки разъехались. bigserial выдаёт номер при INSERT — из последовательности, вне транзакции. Видимой для других строка становится при COMMIT. Между этими двумя моментами проходит столько времени, сколько работает транзакция, и за это время кто угодно успевает получить номер побольше и закоммититься раньше.

Дальше арифметика: релей увидел строку 2, поднял отметку до 2, а строка 1 появилась после. Условие id > 2 её не найдёт уже никогда.

Ни исключения, ни записи в логе. Метрика «отставание релея», построенная как max(id) - last_id, показывает ноль: с её точки зрения всё отправлено.

Лечится это отказом от памяти — состояние переносится в саму строку:

SELECT id, payload FROM outbox
  WHERE published_at IS NULL
  ORDER BY id
  LIMIT 100
  FOR UPDATE SKIP LOCKED;

Условие «не отправлено» ничего не помнит, поэтому находит строку заново, сколько бы она ни просидела незакоммиченной. У чтения журнала этой проблемы нет по построению: журнал устроен как последовательность коммитов, и записи в нём появляются в том же порядке, в каком коммиты произошли.

Чего паттерн не даёт: порядок

На канонической странице паттерна в списке достоинств стоит:

Обещание выполняется, пока транзакции не пересекаются во времени: тогда порядок вставок и порядок коммитов совпадают, и спорить не о чем. Стоит двум пересечься — и оно перестаёт быть верным. Опыт нужен ровно тот же, что в предыдущем разделе: приложение вставило A, потом B, а доставлены они будут B, потом A — потому что B закоммитилась первой.

Через чтение журнала — то же самое. test_decoding показывает транзакцию со строкой id = 2 раньше транзакции со строкой id = 1, причём у той, что пришла первой, номер транзакции больше: она началась позже, а закоммитилась раньше. Значит, порядок и не по номеру строки, и не по номеру транзакции, а по моменту коммита.

Ту же трудность признаёт и страница про опрашивающий релей — в списке недостатков у неё стоит Tricky to publish events in order (Непросто публиковать события по порядку). Измерение уточняет её природу: это не трудность реализации, которую можно преодолеть аккуратностью, а свойство любого релея на PostgreSQL.

Что с этим делать. Общего порядка у вас не будет — на него нельзя опираться, и потребителя нельзя писать так, будто он есть. Порядок можно сохранить только внутри одного ключа, и только пока таблицу читает один релей: два релея со SKIP LOCKED из раздела ниже ломают и его. На этом построена промышленная реализация: Debezium кладёт идентификатор агрегата в ключ сообщения Kafka — This is important for maintaining correct order in Kafka partitions (Это важно для сохранения правильного порядка в разделах Kafka). События одного заказа попадают в один раздел и приходят по порядку; события разных заказов между собой не упорядочены — и не должны быть.

Чего паттерн не даёт: «ровно один раз»

Релей делает две вещи: отправляет и помечает. Между ними, как и в самом начале статьи, можно упасть.

Поменять их местами нельзя: тогда падение между ними потеряет событие, а это строго хуже дубля. Поэтому выбор сделан в пользу дубля, и он окончательный — на уровне отправителя эта задача не решается вовсе.

Значит, идемпотентность обязана быть у потребителя. Обычный способ — таблица обработанных идентификаторов:

INSERT INTO processed (event_id) VALUES (:id) ON CONFLICT DO NOTHING;
-- 0 строк вставлено -> это дубль, работу не делаем

Ключевое здесь — что вставка идентификатора и сама обработка идут одной транзакцией. Иначе вы построили ту же двойную запись, с которой начали.

Два релея

Один релей — точка отказа и потолок пропускной способности. Два релея на одной таблице без специальных мер друг друга блокируют: второй ждёт, пока первый отпустит строки.

Проверено: с SKIP LOCKED первый релей взял строки 1–3, второй 4–6, пересечение пусто. Без него второй релей на lock_timeout = 300ms падает, не взяв ни строки, — то есть не ускоряет, а простаивает.

Оговорка в документации про несогласованное представление здесь не мелким шрифтом. Именно она и означает, что порядок сломан ещё раз: второй релей обгоняет первый. Для очереди это допустимо ровно потому, что порядка у нас уже нет.

Прежде чем добавлять второй релей, стоит покрутить ручку подешевле. Партия по одной строке даёт 1 627 строк/с, партия по тысяче — 104 656: разница почти вся состоит из коммитов, и один процесс с большой партией обгоняет несколько процессов с маленькой. И порядок внутри ключа при одном релее ещё цел.

Таблица, которая растёт

Две вещи, которые ломают outbox в эксплуатации, обе про размер.

Первая — холостой опрос. Релей почти всё время спрашивает «есть ли работа» и получает «нет». Если очередь пуста, а отправленные строки лежат в той же таблице, запрос без подходящего индекса перебирает всё, что накопилось: на таблице в 71 МБ это 24 миллисекунды на каждый холостой опрос.

Спасает частичный индекс.

CREATE INDEX outbox_unpublished ON outbox (id) WHERE published_at IS NULL;

24 миллисекунды превращаются в 53 микросекунды. И главное свойство: индекс не растёт вместе с таблицей. При пустой очереди он занимает 8192 байта — одну страницу, минимум, — тогда как таблица рядом весит 71 МБ. Обычный индекс по published_at так не умеет: он хранит запись для каждой строки.

Вторая — уборка. Отправленные строки надо удалять, и DELETE места не возвращает: полмиллиона строк удаляются за 0,55 с, а таблица как весила 71 МБ, так и весит. VACUUM вернёт страницы под повторную запись (0,10 с, после него 11 МБ), но операционной системе отдаст только хвост файла.

Отсюда обычный совет для заметного потока: секции по времени и DROP секции вместо DELETE. DROP удаляет файл целиком — и это единственная операция, которая возвращает место немедленно.

Когда outbox не нужен

Паттерн решает одну задачу: согласовать запись в базу с сообщением наружу. Если такой задачи нет, он лишний.

• Если получатель — та же база, никакого outbox не нужно: пишите в одной транзакции.
• Если сообщение можно потерять без последствий (метрика, лог, прогрев кеша), цена паттерна не окупается: отправляйте напрямую.
• Если потребитель и так регулярно перечитывает состояние из базы, событие — всего лишь подсказка «загляни пораньше», и его потеря стоит задержки, а не расхождения.

И один случай, когда он обязателен: если по событию где-то произойдёт необратимое действие — списание, отгрузка, письмо, — а расхождение обнаружится не сразу.

Недостаток назван точно: строку в outbox тоже можно забыть вставить. Разница в том, что забытая строка — ошибка одного места в коде, которую видно на ревью, а разъехавшаяся двойная запись — свойство архитектуры, которое не видно нигде.

Как воспроизвести числа

Два скрипта, оба на живой базе, оба печатают то, что вернул PostgreSQL.

createdb -p 5433 outbox_bench
python3 relay.py     # восемь наблюдений, ни одного замера времени
python3 cost.py      # четыре блока замеров

Скрипты лежат в каталоге замеров репозитория, рядом с описанием того, что получилось. Нужен psycopg 3; адрес базы берётся из OUTBOX_DSN. Пятый раздел relay.py читает WAL и требует wal_level = logical — при другом уровне он скажет об этом и пропустится, остальные семь работают на любом.

Опубликованный прогон: PostgreSQL 16.13, synchronous_commit = on, fsync = on, psycopg 3.3.4, Python 3.11.15, август 2026 года. Всё измеренное упирается в fsync, поэтому на другом диске абсолютные значения будут другими — переносятся отношения внутри блока и порядок величин.

Чем измерено

Числа этой статьи получены этими скриптами. Каждый открывается прямо отсюда — вместе с записью прогона: на чём считали, что получилось и с каким разбросом.

• bench/outbox/cost.py
• bench/outbox/relay.py