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 PollerDebezium CDC
СложностьПросто (пара сотен строк Go)Сложнее (Kafka Connect + коннектор)
Задержка100ms - 5s (polling interval)обычно десятки ms, под нагрузкой до секунд (WAL streaming)
Нагрузка на БДПериодические SELECTRepslot 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-воркером и аналитикой - в финальном проекте трека.

Смотри также

Мини-задание

  • Создай таблицу outbox с полями из урока, добавь индекс на WHERE sent_at IS NULL
  • Напиши use case: CompleteLesson сохраняет прогресс и событие в outbox в одной транзакции
  • Реализуй OutboxPoller с FOR UPDATE SKIP LOCKED и batch size 10
  • Проверь: убей poller на середине batch - убедись что при перезапуске он обработает оставшиеся
  • Добавь goroutine очистки sent_at старше 7 дней

Зарегистрируйтесь бесплатно, чтобы пройти квиз, вести прогресс.