К содержимому
Войти

Go Road Map

📤 Transactional outbox

Сервис создал заказ в базе и должен сообщить о нём складу через Kafka. Это две записи в две системы, и общей транзакции у них нет: процесс может упасть между ними, и тогда заказ есть, а события нет. Transactional outbox закрывает эту дыру: событие пишется в таблицу той же базы и в той же транзакции, а в брокер его относит отдельный процесс. На собеседовании от кандидата ждут, что он объяснит, откуда берутся потери, как устроен релей и почему дубли всё равно остаются

🧠 Проблема двойной записи

Обработчик делает два шага: insert into orders и producer.Send(OrderCreated). В каком порядке их ни ставь, есть момент, когда один шаг сделан, а другой нет

ПорядокЧто ломается
Коммит в базу, потом отправкаПроцесс упал или брокер недоступен после коммита. Заказ есть, события нет, склад о нём не узнает
Отправка внутри транзакции, потом коммитСобытие ушло, а коммит не прошёл: конфликт, таймаут, рестарт базы. Склад собирает заказ, которого нет
Отправка с ретраями в фоне после коммитаРетраи живут в памяти процесса. Деплой или OOM, и неотправленное пропало

Распределённая транзакция здесь не помогает. Kafka не участвует в XA вместе с Postgres, а транзакции Kafka атомарны только внутри самой Kafka. Двухфазный коммит к тому же связывает доступность сервиса с доступностью обеих систем сразу

Ошибка редкая, поэтому её не видно на тестах. Она проявляется при деплое, когда под получает SIGTERM посреди запроса, или при сбое брокера. Заказы изредка не доезжают до склада, а в логах обработчика всё чисто

📤 Как работает outbox

Идея в том, чтобы свести две записи к одной. В базе заводится таблица outbox, и бизнес-изменение вместе с событием пишутся в одной транзакции. Либо закоммичено и то и другое, либо ничего

create table outbox (
    id           bigserial primary key,
    aggregate_id text        not null,  -- id заказа, станет ключом сообщения
    event_type   text        not null,
    payload      jsonb       not null,
    created_at   timestamptz not null default now(),
    published_at timestamptz
);
create index on outbox (id) where published_at is null;
begin;
insert into orders (id, user_id, total) values ('o-42', 7, 1990);
insert into outbox (aggregate_id, event_type, payload)
values ('o-42', 'OrderCreated', '{"orderId":"o-42","total":1990}');
commit;

Дальше работает релей (message relay): отдельный процесс или горутина, которая забирает неотправленные строки, публикует их в брокер и отмечает отправленными. Если брокер лежит час, события копятся в таблице и уйдут, когда он вернётся. Обработчик запроса о брокере вообще не знает

Релей бывает двух видов:

  • Polling publisher — опрашивает таблицу по таймеру. Просто, без новой инфраструктуры, но добавляет задержку и нагрузку на базу запросами вхолостую
  • Чтение журнала транзакций (CDC) — инструмент вроде Debezium читает WAL Postgres через слот логической репликации и превращает вставки в outbox в сообщения. Задержка меньше, базу никто не опрашивает, но появляется Kafka Connect, который надо держать и мониторить

🛠️ Релей на Go

Рабочая схема для polling: в транзакции выбрать пачку строк с for update skip locked, отправить, проставить published_at, закоммитить. skip locked нужен, чтобы несколько копий релея не ждали друг друга: строки, которые уже взяла другая транзакция, просто пропускаются. Документация Postgres прямо называет это способом разобрать таблицу-очередь несколькими потребителями без конкуренции за блокировки

Go · Пачка outbox-релея через pgx

func relayBatch(ctx context.Context, db *pgxpool.Pool, pub Publisher) (int, error) {
	tx, err := db.Begin(ctx)
	if err != nil {
		return 0, err
	}
	defer tx.Rollback(ctx)

	rows, err := tx.Query(ctx, `
		select id, aggregate_id, payload from outbox
		where published_at is null
		order by id
		limit 100
		for update skip locked`)
	if err != nil {
		return 0, err
	}
	events, err := pgx.CollectRows(rows, pgx.RowToStructByPos[Event])
	if err != nil {
		return 0, err
	}
	for _, e := range events {
		// ключ — id агрегата: события одного заказа попадут в одну партицию
		if err := pub.Publish(ctx, e.AggregateID, e.Payload); err != nil {
			return 0, err // откат: пачка уйдёт в следующий раз
		}
	}
	ids := make([]int64, len(events))
	for i, e := range events {
		ids[i] = e.ID
	}
	if _, err := tx.Exec(ctx,
		`update outbox set published_at = now() where id = any($1)`, ids); err != nil {
		return 0, err
	}
	return len(events), tx.Commit(ctx)
}

Релей крутится в цикле. Если пачка вернула 100 строк, он сразу берёт следующую, если ноль, спит до следующего тика. Остановка по context вместе с остальными воркерами сервиса, как на странице «Конфигурация, миграции и graceful shutdown»

Проверка на PostgreSQL 16 в Docker и pgx v5.12. Вместо брокера счётчик отправок по id. Четыре копии релея параллельно разобрали 10 000 строк, и ни одна не ушла дважды. Потом релей отправил пачку из 100 событий и упал до коммита, а после рестарта отправил её снова:

4 релея: событий 10000, дублей 0, за 138ms
релей: упали после отправки, до коммита
после рестарта: событий 100, дублей 100

Последняя строка и есть главное свойство outbox. Он даёт at-least-once, а не exactly-once: между «отправил» и «отметил» всегда есть окно, и сбой в нём повторит всю пачку. Поэтому outbox без идемпотентного потребителя решает только половину задачи

📥 Inbox на стороне получателя

Inbox — зеркальная таблица у получателя. Потребитель не обрабатывает сообщение сразу, а записывает его в inbox с уникальным ключом по id события и только после коммита подтверждает брокеру. Повтор упирается в первичный ключ и отбрасывается. Обрабатывает строки из inbox отдельный воркер, в своей транзакции вместе с бизнес-изменением

Чем это лучше, чем обработать сообщение прямо в потребителе с таблицей обработанных id (она разобрана на странице «Гарантии доставки»)? Подтверждение брокеру становится быстрым и не зависит от того, сколько длится обработка и жив ли внешний сервис. Сообщение, которое упало при обработке, остаётся в базе со статусом, его видно и можно перезапустить запросом. Платишь за это ещё одной таблицей, ещё одним воркером и задержкой. Если обработка короткая и вся в одной базе, хватит таблицы обработанных id

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

🔀 CDC вместо опроса

Debezium с преобразованием Outbox Event Router ждёт таблицу с колонками id, aggregatetype, aggregateid, type, payload. Топик выбирается по aggregatetype (по умолчанию outbox.event.<тип>), ключом сообщения становится aggregateid, поэтому события одного агрегата идут по порядку в одной партиции. Удаления строк из outbox преобразование отфильтровывает

Отсюда известный приём: вставить строку и удалить её в той же транзакции. Вставка всё равно попала в WAL, Debezium её прочитает и отправит, а таблица всегда пустая, и чистить её не нужно. С polling-релеем так нельзя: ему нечего будет читать

Цена CDC — слот репликации. Пока Debezium лежит, слот держит WAL, а по умолчанию max_slot_wal_keep_size = -1, то есть без ограничения. Если коннектор упал в пятницу, к понедельнику на мастере может кончиться диск. Поэтому лимит ставят явно и следят за отставанием слота в pg_replication_slots

PollingCDC (Debezium)
ИнфраструктураТолько код сервисаKafka Connect, слот репликации
ЗадержкаДо интервала опросаБез ожидания тика, вставка читается из WAL
Нагрузка на базуЗапросы опроса, обновления published_atЧтение WAL
Чистка таблицыНужнаНе нужна с приёмом вставка + удаление
Где ломаетсяМедленные запросы на распухшей таблицеСлот держит WAL, диск заканчивается

Для одного-двух сервисов polling обычно проще и надёжнее. CDC окупается, когда outbox много и уже есть Kafka Connect

⚠️ Где ошибаются

Читают outbox курсором по id. Релей запоминает последний отправленный id и выбирает where id > $last. Но bigserial выдаёт номер при вставке, а видна строка становится при коммите. Долгая транзакция получила id 1, быстрая получила id 2 и закоммитилась первой. Проверка на том же стенде:

курсор, проход 1: [2]
курсор, проход 2: []
строк в таблице: 2

Событие 1 лежит в таблице и не уйдёт никогда. Выбирают по флагу published_at is null, а не по позиции

Ломают порядок параллельными релеями. skip locked раздаёт строки разным копиям релея, и два события одного заказа могут уйти из разных процессов в обратном порядке. Если порядок важен, держат один активный релей (через advisory lock или выбор лидера) или делят строки между релеями по хешу aggregate_id. Ключ сообщения по агрегату сохраняет порядок только после того, как сообщения попали в брокер

Не чистят таблицу. Миллионы строк с published_at, и запрос релея начинает читать индекс по мёртвым записям. Отправленные строки удаляют фоновой задачей пачками или держат outbox в партициях по дням и отрезают старые. Частичный индекс where published_at is null держит выборку быстрой, пока таблица под контролем

Кладут в событие ссылку вместо данных. В payload только orderId, и получатель идёт за заказом в API отправителя. Через минуту заказ уже изменился, и получатель видит не то состояние, о котором было событие. В событие кладут всё, что нужно для обработки

Пишут outbox не в той базе. Таблица outbox в отдельной базе или в другом соединении без общей транзакции возвращает ту же двойную запись. Бизнес-изменение и событие должны жить в одной транзакции одной базы

🎯 Вопросы с собеседований

Что такое проблема двойной записи?

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

Как работает transactional outbox?

Событие пишется в таблицу outbox той же базы в одной транзакции с бизнес-изменением, поэтому они коммитятся вместе. Отдельный релей читает неотправленные строки, публикует их в брокер и отмечает отправленными. Релей бывает polling, который опрашивает таблицу, или CDC, который читает журнал транзакций, как Debezium

Даёт ли outbox exactly-once?

Нет, он даёт at-least-once. Релей может отправить сообщение и упасть до того, как отметил строку, и после рестарта отправит её ещё раз. Поэтому на стороне получателя нужен отсев дублей по id события: таблица обработанных сообщений или inbox

Как запустить несколько копий релея и не отправить событие дважды?

Выбирать пачку в транзакции с for update skip locked: строки, взятые одной копией, остальные пропускают и не ждут. Отметку published_at ставить в той же транзакции после отправки. Дубли от падения между отправкой и коммитом это не убирает, а порядок событий одного агрегата между копиями не гарантирован

Как сохранить порядок событий при outbox?

Ключ сообщения — id агрегата, тогда события одного заказа идут в одну партицию Kafka. Но порядок должен сохраниться и до брокера: если релеев несколько и они берут строки через skip locked, события могут уйти в другом порядке. Помогает один активный релей с выбором лидера или распределение строк между релеями по хешу id агрегата

Чем polling-релей отличается от CDC?

Polling опрашивает таблицу по таймеру, ему не нужна дополнительная инфраструктура, но есть задержка и нагрузка на базу, а таблицу надо чистить. CDC читает WAL через слот логической репликации, задержка меньше и опрашивать базу не нужно. Зато появляются Kafka Connect и слот, который при упавшем коннекторе копит WAL и может съесть диск

Зачем inbox, если есть идемпотентный потребитель?

Inbox отделяет приём от обработки: потребитель только кладёт сообщение в таблицу по уникальному id и сразу подтверждает брокеру. Обработка идёт отдельно, её ошибки видны в базе и перезапускаются запросом, а медленный внешний сервис не держит партицию. Если обработка короткая и в той же базе, достаточно таблицы обработанных id в одной транзакции с изменением

Почему нельзя читать outbox по последнему отправленному id?

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

📚 Что почитать