Transactional Outbox с Kafka: событие как часть транзакции
Transactional Outbox с Kafka: событие как часть транзакции
Проблема dual-write: нельзя атомарно записать в PostgreSQL и опубликовать в Kafka. Если сначала записать в БД, потом отправить в Kafka - при краше между ними событие потеряно. Если наоборот - возможен phantom-event.
Outbox pattern решает это: событие сначала сохраняется в таблицу outbox в той же транзакции, что и бизнес-данные. Отдельный процесс читает outbox и публикует в Kafka.
Теорию и RabbitMQ-вариант разобрали в event-driven - Outbox и RabbitMQ Outbox. Здесь - Kafka-специфика и CDC через Debezium.
Схема outbox-таблицы
CREATE TABLE outbox (
id BIGSERIAL PRIMARY KEY,
event_id UUID NOT NULL DEFAULT gen_random_uuid(),
topic TEXT NOT NULL, -- Kafka топик
partition_key TEXT, -- для routing
payload JSONB NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
sent_at TIMESTAMPTZ,
attempts INT NOT NULL DEFAULT 0,
next_attempt_at TIMESTAMPTZ NOT NULL DEFAULT NOW() -- backoff между попытками
);
-- Индекс на неотправленные события (для polling)
CREATE INDEX idx_outbox_unsent ON outbox (created_at)
WHERE sent_at IS NULL;
Use Case: запись в транзакции
func (uc *CompleteLessonUseCase) Execute(ctx context.Context, userID, lessonID string) error {
return uc.db.WithTx(ctx, func(tx *sql.Tx) error {
// 1. Бизнес-данные
if err := uc.progressRepo.MarkCompleted(ctx, tx, userID, lessonID); err != nil {
return err
}
// 2. Событие в outbox (в той же транзакции)
event := map[string]any{
"event": "lesson.completed",
"userId": userID,
"lessonId": lessonID,
"at": time.Now().UTC(),
}
payload, _ := json.Marshal(event)
_, err := tx.ExecContext(ctx, `
INSERT INTO outbox (topic, partition_key, payload)
VALUES ($1, $2, $3)`,
"lesson-events", userID, payload,
)
return err
})
}
Если транзакция откатится - outbox запись тоже не появится. Бизнес-данные и намерение опубликовать событие всегда в одном состоянии.
Что при этом не гарантировано: сама доставка. Она остаётся at-least-once
- поллер может упасть после публикации, но до отметки, и отправить событие второй раз. Поэтому идемпотентный консумер обязателен, а не желателен.
Outbox Poller
type OutboxPoller struct {
db *sql.DB
producer *kgo.Client
interval time.Duration
batchSize int
}
func (p *OutboxPoller) Run(ctx context.Context) {
ticker := time.NewTicker(p.interval)
defer ticker.Stop()
for {
select {
case <-ctx.Done():
return
case <-ticker.C:
if err := p.poll(ctx); err != nil {
log.Printf("outbox poll error: %v", err)
}
}
}
}
func (p *OutboxPoller) poll(ctx context.Context) error {
// FOR UPDATE SKIP LOCKED работает только внутри транзакции: в неявной
// транзакции одиночного запроса блокировки снимаются сразу после SELECT,
// и параллельный poller возьмёт те же строки. Транзакция живёт до отметки.
tx, err := p.db.BeginTx(ctx, nil)
if err != nil {
return fmt.Errorf("begin tx: %w", err)
}
defer tx.Rollback()
rows, err := tx.QueryContext(ctx, `
SELECT id, event_id, topic, partition_key, payload
FROM outbox
WHERE sent_at IS NULL AND next_attempt_at <= NOW()
ORDER BY created_at
LIMIT $1
FOR UPDATE SKIP LOCKED`,
p.batchSize,
)
if err != nil {
return fmt.Errorf("query outbox: %w", err)
}
type outboxRow struct {
id int64
eventID, topic, partitionKey string
payload []byte
}
// Вычитываем пачку целиком и закрываем rows до следующих запросов в tx
var records []outboxRow
for rows.Next() {
var r outboxRow
if err := rows.Scan(&r.id, &r.eventID, &r.topic, &r.partitionKey, &r.payload); err != nil {
rows.Close()
return fmt.Errorf("scan outbox row: %w", err)
}
records = append(records, r)
}
if err := rows.Close(); err != nil {
return err
}
if err := rows.Err(); err != nil {
return err
}
if len(records) == 0 {
return nil
}
ids := make([]int64, len(records))
kafkaRecords := make([]*kgo.Record, len(records))
for i, r := range records {
ids[i] = r.id
kafkaRecords[i] = &kgo.Record{
Topic: r.topic,
Key: []byte(r.partitionKey),
Value: r.payload,
Headers: []kgo.RecordHeader{
// Заголовок "id" - как у Debezium Outbox Event Router:
// consumer одинаково работает и с poller-ом, и с CDC
{Key: "id", Value: []byte(r.eventID)},
},
}
}
// Публикуем в Kafka
results := p.producer.ProduceSync(ctx, kafkaRecords...)
if err := results.FirstErr(); err != nil {
// Откладываем пачку с растущей паузой (до 5 минут). Событие не
// выключается навсегда: большое attempts - повод для алерта.
if _, uErr := tx.ExecContext(ctx, `
UPDATE outbox
SET attempts = attempts + 1,
next_attempt_at = NOW() + LEAST(INTERVAL '5 seconds' * POWER(2, attempts), INTERVAL '5 minutes')
WHERE id = ANY($1)`,
pq.Array(ids)); uErr != nil {
return fmt.Errorf("bump attempts: %w", uErr)
}
if cErr := tx.Commit(); cErr != nil {
return cErr
}
return fmt.Errorf("produce: %w", err)
}
// Помечаем как отправленные - в той же транзакции, что и выборка
if _, err := tx.ExecContext(ctx,
`UPDATE outbox SET sent_at = NOW() WHERE id = ANY($1)`,
pq.Array(ids)); err != nil {
return fmt.Errorf("mark sent: %w", err)
}
return tx.Commit()
}
FOR UPDATE SKIP LOCKED позволяет нескольким poller-инстансам работать параллельно без конфликтов - но только потому, что выборка, публикация и отметка sent_at идут в одной транзакции (подробно - в RabbitMQ Outbox). Публикация внутри открытой транзакции держит строки заблокированными, поэтому пачку делают небольшой, а RecordDeliveryTimeout у producer-а - ограниченным.
CDC через Debezium: нет polling overhead
Debezium читает PostgreSQL WAL (Write-Ahead Log) и публикует изменения в Kafka. Для outbox-таблицы это даёт:
- Малая задержка: от десятков миллисекунд до секунд после commit (не нулевая: чтение WAL, батчинг Kafka Connect, коммиты коннектора), без ожидания интервала опроса
- Нет нагрузки polling-запросами на БД
- Гарантированный порядок (WAL строго последовательный)
# docker-compose.yml (Kafka и PostgreSQL - как в уроке про Kafka в Compose)
postgres:
image: postgres:16
# Debezium читает WAL через logical replication - без этого коннектор не стартует
command: ["postgres", "-c", "wal_level=logical"]
environment:
POSTGRES_DB: backendstart
POSTGRES_USER: app
POSTGRES_PASSWORD: secret
connect:
# Debezium 3.x; образы публикуются на quay.io (на Docker Hub выпуск прекращён)
image: quay.io/debezium/connect:3.3
ports:
- "8083:8083"
environment:
BOOTSTRAP_SERVERS: kafka:29092 # INTERNAL listener из урока про Kafka в Compose
GROUP_ID: "debezium"
CONFIG_STORAGE_TOPIC: "debezium_configs"
OFFSET_STORAGE_TOPIC: "debezium_offsets"
STATUS_STORAGE_TOPIC: "debezium_statuses"
depends_on:
- kafka
- postgres
Регистрируем коннектор через REST API Kafka Connect:
curl -X POST http://localhost:8083/connectors -H 'Content-Type: application/json' -d '{
"name": "outbox-connector",
"config": {
"connector.class": "io.debezium.connector.postgresql.PostgresConnector",
"database.hostname": "postgres",
"database.port": "5432",
"database.user": "app",
"database.password": "secret",
"database.dbname": "backendstart",
"topic.prefix": "app",
"plugin.name": "pgoutput",
"table.include.list": "public.outbox",
"transforms": "outbox",
"transforms.outbox.type": "io.debezium.transforms.outbox.EventRouter",
"transforms.outbox.route.topic.replacement": "${routedByValue}",
"transforms.outbox.table.field.event.id": "event_id",
"transforms.outbox.route.by.field": "topic",
"transforms.outbox.table.field.event.key": "partition_key",
"transforms.outbox.table.field.event.payload": "payload"
}
}'
Debezium Outbox Event Router автоматически маршрутизирует записи из одной outbox-таблицы в нужные Kafka топики по колонке, указанной в route.by.field (по умолчанию он ищет колонку aggregatetype, которой в нашей таблице нет, поэтому её задаём явно). topic.prefix обязателен с Debezium 2.0: это логическое имя коннектора. ID события Event Router кладёт в заголовок id - тот же заголовок ставит и наш poller.
Outbox Poller vs CDC: когда что
| Outbox Poller | Debezium CDC | |
|---|---|---|
| Сложность | Просто (пара сотен строк Go) | Сложнее (Kafka Connect + коннектор) |
| Задержка | 100ms - 5s (polling interval) | обычно десятки ms, под нагрузкой до секунд (WAL streaming) |
| Нагрузка на БД | Периодические SELECT | Repslot overhead (~0.1%) |
| Масштабируемость | Несколько pollers с SKIP LOCKED | Один CDC процесс на БД |
| PostgreSQL replication slot | Не нужен | Нужен (следи за lag!) |
Для стартапа - Outbox Poller, проще в ops. Для высоконагруженного сервиса (>1K событий/сек) - CDC.
Cleanup старых записей
-- Удалять отправленные записи старше 7 дней
DELETE FROM outbox
WHERE sent_at IS NOT NULL
AND sent_at < NOW() - INTERVAL '7 days';
// Запускать как background goroutine
func (p *OutboxPoller) runCleanup(ctx context.Context) {
ticker := time.NewTicker(1 * time.Hour)
defer ticker.Stop()
for {
select {
case <-ctx.Done(): return
case <-ticker.C:
p.db.ExecContext(ctx, `
DELETE FROM outbox
WHERE sent_at IS NOT NULL
AND sent_at < NOW() - INTERVAL '7 days'`)
}
}
}
Inbox pattern на Kafka-стороне
Consumer обеспечивает идемпотентность через processed_events таблицу (почему проверка и отметка обязаны лежать в одной транзакции с бизнес-логикой, а не рядом с ней - в уроке про идемпотентность):
func processWithInbox(ctx context.Context, db *sql.DB, r *kgo.Record) error {
// "id" ставят и poller, и Debezium Outbox Event Router
eventID := getHeader(r, "id")
if eventID == "" {
// Без ID дедупликация невозможна, а пустая строка как ключ inbox
// после первого же события отбрасывала бы все следующие как «дубли»
return fmt.Errorf("missing event id header at %s/%d@%d", r.Topic, r.Partition, r.Offset)
}
return withTx(ctx, db, func(tx *sql.Tx) error {
// Отметка идёт первой и служит одновременно проверкой: отдельный
// SELECT прошли бы два воркера сразу, оба увидев "не обработано".
// Ключ составной - у одного события несколько обработчиков.
res, err := tx.ExecContext(ctx,
`INSERT INTO processed_events (event_id, handler)
VALUES ($1, $2)
ON CONFLICT (event_id, handler) DO NOTHING`,
eventID, handlerName)
if err != nil {
return fmt.Errorf("mark processed: %w", err)
}
rows, err := res.RowsAffected()
if err != nil {
return fmt.Errorf("rows affected: %w", err)
}
if rows == 0 {
return nil // дубль - пропускаем
}
// Бизнес-логика в той же транзакции: откат отменит и отметку.
return applyEvent(ctx, tx, r)
})
}
Типичные ошибки
Poller без SKIP LOCKED - несколько poller-инстансов блокируют одни записи, вместо распределения нагрузки. SKIP LOCKED решает это.
Неограниченный рост outbox-таблицы - без cleanup за год могут накопиться миллионы строк. Индекс WHERE sent_at IS NULL тоже растёт со временем. Cleanup обязателен.
Replication slot без мониторинга (CDC) - если Debezium лагает или падает, PostgreSQL не может вычистить WAL пока slot не прочитает изменения. Диск переполняется. Мониторь pg_replication_slots lag - набор метрик и alert-rules для Kafka и коннекторов собран в уроке мониторинг Kafka, а сквозной рабочий пример с outbox, email-воркером и аналитикой - в финальном проекте трека.
Смотри также
- Event-Driven - Outbox + Inbox - теория и anti-patterns
- Message Brokers - RabbitMQ Outbox - тот же паттерн с RabbitMQ
- SQL - Транзакции - BEGIN/COMMIT и atomicity
Мини-задание
- Создай таблицу
outboxс полями из урока, добавь индекс наWHERE sent_at IS NULL - Напиши use case:
CompleteLessonсохраняет прогресс и событие в outbox в одной транзакции - Реализуй
OutboxPollerсFOR UPDATE SKIP LOCKEDи batch size 10 - Проверь: убей poller на середине batch - убедись что при перезапуске он обработает оставшиеся
- Добавь goroutine очистки sent_at старше 7 дней