A B C D E F G H I J K L M N O P Q R S T V W Y Z А Б В Г Е И К Л М О П С Т Ц

Transactional Outbox

Transactional Outbox

 

Transactional outbox это паттерн надёжной публикации событий, при котором сервис записывает бизнес-изменение и событие о нём в одну локальную транзакцию своей базы данных, а отдельный процесс-ретранслятор потом доставляет событие в брокер сообщений. В русскоязычной практике его чаще называют паттерн outbox или Outbox pattern. Паттерн закрывает проблему двойной записи (dual write), когда коммит в базе и отправка в Kafka выполняются двумя независимыми операциями и сбой между ними разводит данные и события.

Практика ниже воспроизведена на PostgreSQL 18.6, Apache Kafka 4.3.2 и Debezium 3.7.0.Final.

 

Что такое Transactional outbox и какую задачу решает

Сервис заказов сохраняет заказ и должен сообщить о нём складу и сервису лояльности. Общей транзакции у базы и брокера нет, а двухфазный коммит (2PC, two-phase commit) на практике неприменим, потому что база или брокер могут его не поддерживать.

Остаются два порядка действий, и оба ломаются. Если сначала закоммитить заказ, а процесс упадёт до отправки, подписчики не узнают о заказе. Это потерянное событие. Если сначала отправить, а транзакция откатится после того, как брокер принял сообщение, склад получит событие о заказе, которого нет. Это фантомное событие. Подробно проблема разобрана в статье блога Неконсистентность данных в распределенной системе, Apache Kafka и проблема двойной записи.

Проблема двойной записи: сервис фиксирует заказ в базе и падает до отправки события в Kafka, событие теряется; при обратном порядке событие уходит, а транзакция откатывается

Каноническое описание паттерна дал Chris Richardson (Крис Ричардсон), автор каталога шаблонов микросервисной архитектуры, в описании паттерна Transactional outbox на microservices.io. Сервис сохраняет сообщение в базу в той же транзакции, что обновляет бизнес-сущности, а отдельный процесс затем отправляет его в брокер. Event Sourcing каталог приводит как альтернативное решение той же задачи.

 

Архитектура паттерна

Участников четыре. Отправитель это бизнес-код сервиса, дальше база данных, таблица outbox в ней и ретранслятор (message relay), который переносит записи из таблицы в брокер.

 

Таблица outbox и её поля

Таблица outbox живёт в той же базе, что и бизнес-таблицы. Колонки по умолчанию задаёт Debezium Outbox Event Router, и их удобно взять за образец даже для своего ретранслятора:

  • id. Уникальный идентификатор события, обычно UUID, ключ дедупликации у потребителя.
  • aggregatetype. Тип агрегата (aggregate, термин Domain-Driven Design для группы сущностей, которая меняется как одно целое), например order. Из него собирается имя топика outbox.event.order.
  • aggregateid. Номер заказа. Становится ключом сообщения Kafka, поэтому события одного заказа попадают в одну партицию.
  • type. Тип события, например OrderCreated или OrderPaid.
  • payload. Тело события, в PostgreSQL удобнее всего jsonb.

 

Ретранслятор, polling publisher и transaction log tailing

Для ретранслятора microservices.io описывает два шаблона. Polling publisher периодически опрашивает таблицу, отправляет неотправленные строки и отмечает их. Несколько экземпляров опросчика не шлют одно и то же дважды, если строки захватываются через FOR UPDATE SKIP LOCKED, потому что второй экземпляр пропускает заблокированные строки и берёт следующие.

Transaction log tailing читает журнал транзакций базы. В PostgreSQL это логическое декодирование WAL (Write-Ahead Log, журнал предзаписи) через слот репликации, и так работает Debezium, платформа CDC (Change Data Capture, захват изменений данных) поверх Kafka Connect. Преобразование SMT (Single Message Transformation) Outbox Event Router превращает вставку в outbox в доменное событие с нужным топиком, ключом и заголовками.

Опросчику нужны только база и клиент Kafka, но он постоянно нагружает базу запросами и добавляет задержку до одного интервала опроса. Чтение журнала таблицу не опрашивает, зато требует wal_level=logical, слот репликации и Kafka Connect.

 

Принцип работы от транзакции до топика

Путь события в паттерне outbox складывается из пяти шагов:

  • Транзакция. Сервис вставляет заказ в orders и строку OrderCreated в outbox, затем выполняет COMMIT.
  • Захват. Опросчик находит неотправленную строку, или Debezium читает вставку из WAL. Откатившаяся транзакция до ретранслятора не доходит.
  • Публикация. Событие уходит в топик outbox.event.order с ключом aggregateid и заголовком id.
  • Отметка. Опросчик ставит published_at после подтверждения брокера, Debezium записывает оффсет в служебный топик Kafka Connect connect_offsets и подтверждает прочитанную позицию WAL слоту репликации.
  • Обработка. Потребитель применяет эффект и запоминает id события, чтобы не применить его второй раз.

Атомарность обеспечивает локальная транзакция базы, доставку берёт на себя асинхронный ретранслятор. Пока Kafka недоступна, события копятся в таблице, а сервис продолжает принимать заказы.

Архитектура Transactional outbox: сервис в одной транзакции пишет заказ и строку outbox, ретранслятор забирает её опросом таблицы или Debezium читает WAL, событие уходит в топик Kafka по ключу агрегата, консьюмер отсекает дубль через таблицу inbox

Apache Kafka для инженеров данных

Код курса
DEVKI
Ближайшая дата курса
7 декабря, 2026
Продолжительность
24 ак.часов
Стоимость обучения
76 800

Гарантии доставки, дубли и порядок событий

Outbox даёт доставку «как минимум один раз» (at-least-once). Ретранслятор может упасть после отправки и до отметки строки и после рестарта отправить её снова, этот сценарий Chris Richardson называет прямо. Документация Debezium о коннекторе PostgreSQL говорит то же, потребителям стоит всегда ожидать повторных событий.

Поэтому вторая половина паттерна живёт у потребителя. Идемпотентный потребитель вставляет id события в таблицу inbox в той же транзакции, что и эффект, и повтор упирается в первичный ключ. Этот приём называют паттерном inbox.

Порядок гарантирован только внутри партиции. Ключ сообщения равен aggregateid, поэтому события одного заказа читаются по порядку, а между заказами порядка нет и не требуется. Хрупкое место это параллельные ретрансляторы. Если первый захватил OrderCreated и задержался, второй через SKIP LOCKED отправит OrderPaid того же заказа раньше. Три звена, где порядок рвётся, разобраны в статье блога Порядок событий в Kafka Outbox ломается на трёх звеньях.

Выходов три. Можно держать один ретранслятор, закрепить агрегаты за опросчиками по хешу aggregateid или читать журнал через Debezium, где коннектор PostgreSQL работает одной задачей.

 

Очистка outbox и вариант без таблицы

При опросе таблица растёт на каждую транзакцию с событием. Отправленные строки удаляют фоновой задачей пачками или отрезают старые секции секционированной таблицы. Частичный индекс по условию published_at IS NULL держит индекс опросчика маленьким, но мёртвые версии строк всё равно убирает VACUUM.

При чтении журнала строка после коммита не нужна, событие уже в WAL. Outbox Event Router ожидает только INSERT и отбрасывает DELETE, поэтому строку можно удалить в той же транзакции сразу после вставки. Прямой рекомендации так делать на странице SMT нет, это вывод из её поведения, подтверждённый прогоном. На UPDATE строки outbox SMT по умолчанию пишет предупреждение в лог без события, реакцию задаёт параметр table.op.invalid.behavior.

PostgreSQL позволяет обойтись и без таблицы. Функция pg_logical_emit_message пишет сообщение прямо в WAL, а с аргументом transactional = true сообщение становится частью транзакции и при откате пропадает. Debezium доставляет такие сообщения как события с op = m через плагин pgoutput на PostgreSQL 14 и новее, в отдельный топик с суффиксом message и с содержимым в двоичном виде. Документация Debezium допускает связку с Outbox Event Router после преобразования DecodeLogicalDecodingMessageContent, которое разбирает содержимое в обычную запись. На стенде этой статьи маршрутизатор ограничен таблицей outbox, такая связка не прогонялась.

 

Transactional outbox против двойной записи, транзакций Kafka и Event Sourcing

Альтернативы паттерну outbox отличаются тем, что гарантирует атомарность и где лежит источник истины.

Критерий Двойная запись Транзакции Kafka Transactional outbox Event Sourcing
Атомарность с базой Нет Нет, транзакция покрывает только записи в Kafka и оффсеты Да, одна локальная транзакция Да, событие и есть запись
Доставка Потеря или фантом при сбое Exactly-once внутри Kafka At-least-once, нужен идемпотентный потребитель Зависит от подписки на журнал
Порядок Не гарантирован Внутри партиции Внутри агрегата при одном ретрансляторе или CDC Внутри потока агрегата по версии
Нагрузка на базу Нет Нет Лишняя вставка, опрос или слот репликации Весь журнал в базе
Инфраструктура Клиент Kafka Клиент Kafka с transactional.id Опросчик или Kafka Connect с Debezium Хранилище событий и проекции
Источник истины База и брокер порознь Kafka Бизнес-таблицы, события производные Журнал событий

В Event Sourcing события первичны и таблица outbox не нужна, но меняется вся модель хранения сервиса.

Практическая архитектура данных

Код курса
PRAR
Ближайшая дата курса
30 ноября, 2026
Продолжительность
24 ак.часов
Стоимость обучения
76 800

Когда outbox нужен и когда нет

Паттерн outbox оправдан, когда сервис меняет свою базу и обязан сообщить об этом другим:

  • Событийная интеграция микросервисов. Заказ, оплата и склад общаются событиями, и потеря одного события означает зависший заказ.
  • Saga. Шаги распределённого бизнес-процесса передаются событиями, и каждый шаг публикуется атомарно со своим локальным изменением.
  • Наполнение аналитики и кэшей. Получателям нужны доменные события, а не сырые изменения таблиц из обычного CDC.

Без outbox можно обойтись, когда сервис пишет только в брокер или когда событие допустимо потерять, как телеметрию. Опрос не подходит, если критична задержка в миллисекунды. Outbox Event Router не работает с коннектором MongoDB, а несколько outbox-таблиц обслуживает, только если у них одинаковая структура.

 

Практика, outbox на PostgreSQL 18 и Kafka 4.3

Transactional outbox на PostgreSQL, Kafka и Debezium from airflow import DAG from airflow.operators.bash import BashOperator from datetime import datetime with DAG( dag_id="spark_submit_demo", start_date=datetime(2025, 1, 1), schedule="@daily", catchup=False ) as dag: run = BashOperator( task_id="run_job", bash_command="spark-submit app.py" ) GitHub code example Transactional outbox на PostgreSQL, Kafka и Debezium

Демо моделирует сервис заказов и сервис лояльности, который начисляет 1 балл за каждые 100 рублей заказа. Лояльность для простоты живёт в схеме loyalty той же базы. Оркестратор outbox_demo.py показан целиком по частям рядом со своими сценариями.

 

Стенд

Стенд состоит из трёх контейнеров. PostgreSQL 18.6 запущен с wal_level=logical, Kafka 4.3.2 работает одним узлом в режиме KRaft (Kafka Raft, встроенный кворум метаданных вместо ZooKeeper), а образ Debezium Connect 3.7.0.Final содержит Kafka Connect с коннектором PostgreSQL и Outbox Event Router.

# postgres 18.6, apache/kafka 4.3.2 (KRaft), debezium/connect 3.7.0.Final в Docker, прогнано на стенде 2026-11-06
services:
  pg:
    image: postgres:18.6
    container_name: outbox-pg
    mem_limit: 1g
    # logical нужен Debezium и pg_logical_emit_message: без него логическое декодирование выключено
    command: ["postgres", "-c", "wal_level=logical", "-c", "max_replication_slots=4", "-c", "max_wal_senders=4"]
    environment:
      POSTGRES_USER: demo
      POSTGRES_PASSWORD: demo
      POSTGRES_DB: shop
    ports:
      - "127.0.0.1:55438:5432"
    volumes:
      - pgdata:/var/lib/postgresql
      # таблицы заказов, outbox и inbox создаются при первом старте на чистом томе
      - ./schema.sql:/docker-entrypoint-initdb.d/01_schema.sql:ro
    healthcheck:
      # -h 127.0.0.1: на время initdb временный сервер слушает только сокет, по TCP готов уже рабочий
      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U demo -d shop"]
      interval: 2s
      timeout: 3s
      retries: 30

  kafka:
    image: apache/kafka:4.3.2
    container_name: outbox-kafka
    mem_limit: 1g
    environment:
      # один узел KRaft: он же брокер, он же контроллер
      KAFKA_NODE_ID: 1
      KAFKA_PROCESS_ROLES: broker,controller
      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@kafka:9093
      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
      # PLAINTEXT для контейнеров в сети compose, EXTERNAL для Python-скриптов на хосте
      KAFKA_LISTENERS: PLAINTEXT://:9092,CONTROLLER://:9093,EXTERNAL://:59092
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092,EXTERNAL://127.0.0.1:59092
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT,CONTROLLER:PLAINTEXT,EXTERNAL:PLAINTEXT
      KAFKA_INTER_BROKER_LISTENER_NAME: PLAINTEXT
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
      KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0
      KAFKA_NUM_PARTITIONS: 3
      KAFKA_HEAP_OPTS: "-Xms256m -Xmx512m"
    ports:
      - "127.0.0.1:59092:59092"
    healthcheck:
      test: ["CMD-SHELL", "/opt/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server localhost:9092 >/dev/null 2>&1"]
      interval: 5s
      timeout: 10s
      retries: 30

  connect:
    image: quay.io/debezium/connect:3.7.0.Final
    container_name: outbox-connect
    mem_limit: 1536m
    depends_on:
      pg:
        condition: service_healthy
      kafka:
        condition: service_healthy
    environment:
      BOOTSTRAP_SERVERS: kafka:9092
      GROUP_ID: outbox-connect
      CONFIG_STORAGE_TOPIC: connect_configs
      OFFSET_STORAGE_TOPIC: connect_offsets
      STATUS_STORAGE_TOPIC: connect_statuses
      # один брокер: служебные топики Kafka Connect без реплик
      CONFIG_STORAGE_REPLICATION_FACTOR: 1
      OFFSET_STORAGE_REPLICATION_FACTOR: 1
      STATUS_STORAGE_REPLICATION_FACTOR: 1
      HEAP_OPTS: "-Xms256m -Xmx768m"
    ports:
      - "127.0.0.1:58083:8083"
    healthcheck:
      test: ["CMD-SHELL", "curl -sf http://localhost:8083/connector-plugins >/dev/null"]
      interval: 5s
      timeout: 5s
      retries: 60

volumes:
  pgdata:

Зависимости Python закреплены точными версиями в requirements.txt.

# пины версий, прогнано на стенде 2026-11-06 (Python 3.12.3)
psycopg[binary]==3.3.8
confluent-kafka==2.16.1

Стенд поднимается одной командой, после чего стоит проверить уровень WAL и наличие коннектора. Все сценарии разом запускает последняя строка.

# PostgreSQL 18.6, Kafka 4.3.2, Debezium 3.7.0.Final, Docker Compose 2.40.3, Python 3.12.3, проверено на стенде 2026-11-06
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
docker compose up -d --wait
# ожидаемо logical
docker compose exec -T pg psql -U demo -d shop -XAtc "SHOW wal_level"
# ожидаемо плагин коннектора с версией 3.7.0.Final
curl -s http://127.0.0.1:58083/connector-plugins | grep -o 'io.debezium.connector.postgresql.PostgresConnector[^}]*'
# все сценарии по порядку, по одному запускаются как outbox_demo.py polling и так далее
.venv/bin/python outbox_demo.py all

Схема schema.sql создаётся при первом старте контейнера. Таблица outbox повторяет колонки по умолчанию Debezium, а created_at и published_at нужны только опросчику. Inbox и баллы лежат в схеме loyalty.

-- PostgreSQL 18.6, прогнано на стенде 2026-11-06: сервис заказов с таблицей outbox и сервис лояльности с inbox

-- Бизнес-таблица сервиса заказов
CREATE TABLE orders (
    id         bigserial PRIMARY KEY,
    customer   text          NOT NULL,
    amount     numeric(10,2) NOT NULL CHECK (amount > 0),
    status     text          NOT NULL DEFAULT 'created',
    created_at timestamptz   NOT NULL DEFAULT now()
);

-- Outbox: колонки id, aggregatetype, aggregateid, type, payload это имена по умолчанию
-- у Debezium Outbox Event Router. published_at нужна только ретранслятору-опросчику.
CREATE TABLE outbox (
    id            uuid         PRIMARY KEY DEFAULT gen_random_uuid(),
    aggregatetype varchar(255) NOT NULL,
    aggregateid   varchar(255) NOT NULL,
    type          varchar(255) NOT NULL,
    payload       jsonb        NOT NULL,
    created_at    timestamptz  NOT NULL DEFAULT clock_timestamp(),
    published_at  timestamptz
);

-- Частичный индекс: опросчик читает только неотправленное, отправленные строки индекс не раздувают
CREATE INDEX outbox_unpublished ON outbox (created_at) WHERE published_at IS NULL;

-- Сервис лояльности в своей схеме (в жизни это отдельная база): начисленные баллы и inbox
CREATE SCHEMA loyalty;

CREATE TABLE loyalty.points (
    customer text    PRIMARY KEY,
    points   integer NOT NULL DEFAULT 0
);

-- Inbox: id уже обработанных событий. Вставка в inbox и эффект идут одной транзакцией
CREATE TABLE loyalty.inbox (
    event_id     uuid        PRIMARY KEY,
    processed_at timestamptz NOT NULL DEFAULT now()
);

Общая часть оркестратора. Функция place_order пишет заказ и OrderCreated одной транзакцией, pay_order так же пишет оплату и OrderPaid.

# confluent-kafka 2.16.1, psycopg 3.3.8, Kafka 4.3.2, PostgreSQL 18.6, Debezium 3.7.0.Final, прогнано на стенде 2026-11-06
"""Transactional outbox на PostgreSQL, Kafka и Debezium: сценарии демо.

python outbox_demo.py all|dual_write|polling|duplicate|emit_message|cdc
"""
import base64
import json
import os
import random
import subprocess
import sys
import threading
import time
import urllib.request
from collections import Counter

import psycopg
from confluent_kafka.admin import AdminClient, NewTopic

from consumer import consume_naive, consume_with_inbox, read_topic
from relay import KAFKA, PG_DSN, RelayCrash, make_producer, relay_batch, run_relay

CONNECT_URL = os.environ.get("CONNECT_URL", "http://127.0.0.1:58083")
HERE = os.path.dirname(os.path.abspath(__file__))


# ── сервис заказов ──────────────────────────────────────────────────────────

def pg():
    return psycopg.connect(PG_DSN, autocommit=True)


def place_order(conn, customer: str, amount: int, fail: bool = False,
                delete_outbox: bool = False) -> int:
    """Заказ и событие OrderCreated одной локальной транзакцией: либо оба, либо ничего."""
    with conn.transaction():
        order_id = conn.execute(
            "INSERT INTO orders (customer, amount) VALUES (%s, %s) RETURNING id",
            (customer, amount)).fetchone()[0]
        payload = {"orderId": order_id, "customer": customer, "amount": amount}
        event_id = conn.execute(
            "INSERT INTO outbox (aggregatetype, aggregateid, type, payload) "
            "VALUES ('order', %s, 'OrderCreated', %s) RETURNING id",
            (str(order_id), json.dumps(payload))).fetchone()[0]
        if delete_outbox:
            # для CDC строка не нужна после коммита: событие уже лежит в WAL
            conn.execute("DELETE FROM outbox WHERE id = %s", (event_id,))
        if fail:
            raise RuntimeError("ошибка бизнес-логики после записи в outbox")
    return order_id


def pay_order(conn, order_id: int, customer: str) -> None:
    with conn.transaction():
        conn.execute("UPDATE orders SET status = 'paid' WHERE id = %s", (order_id,))
        conn.execute(
            "INSERT INTO outbox (aggregatetype, aggregateid, type, payload) "
            "VALUES ('order', %s, 'OrderPaid', %s)",
            (str(order_id), json.dumps({"orderId": order_id, "customer": customer})))


def ensure_topics(*names: str, partitions: int = 3) -> None:
    admin = AdminClient({"bootstrap.servers": KAFKA})
    futures = admin.create_topics([NewTopic(n, partitions, 1) for n in names])
    for name, f in futures.items():
        try:
            f.result(15)
        except Exception as e:  # уже есть: нормально при повторном запуске
            if "TOPIC_ALREADY_EXISTS" not in str(e):
                raise
    time.sleep(1)  # метаданные новых топиков расходятся по клиентам не мгновенно


def count(conn, sql: str, *args) -> int:
    return conn.execute(sql, args).fetchone()[0]


def order_violations(msgs: list[dict]) -> list[str]:
    """Заказы, у которых OrderPaid лежит в партиции раньше, чем OrderCreated."""
    seen_created, bad = set(), []
    for m in sorted(msgs, key=lambda m: (m["partition"], m["offset"])):
        etype = m["headers"]["eventType"]
        if etype == "OrderCreated":
            seen_created.add(m["key"])
        elif etype == "OrderPaid" and m["key"] not in seen_created:
            bad.append(m["key"])
    return bad

Стенд поднялся за 46 с и занял меньше 1 ГиБ памяти. Версия 4.3.1 в ответе REST API это рантайм Kafka Connect внутри образа Debezium, брокер при этом 4.3.2.

# вывод прогона на стенде 2026-11-06, фрагмент run_output.txt
=== ВЕРСИИ ===
PRETTY_NAME="Ubuntu 24.04.4 LTS"
x86_64
docker 29.1.3
Docker Compose version 2.40.3+ds1-0ubuntu1~24.04.1
postgres:18.6 sha256:3a4264520e121176619f54ff867d12774bc81e95e7b84db58d63bccdb6144b81 162522305
apache/kafka:4.3.2 sha256:852a0d49fc4e656b022e7f23785411802c9a088c78a7c5e39f33969de9c227a7 238812381
quay.io/debezium/connect:3.7.0.Final sha256:b9b983eda59570c526ddffa86ff73e56c53180d2676158ba5a5184cfd1b59a79 820074158
Python 3.12.3
psycopg 3.3.8 libpq 180006
confluent-kafka 2.16.1 librdkafka ('2.16.0', 34603263)

 Container outbox-kafka  Healthy
 Container outbox-pg  Healthy
 Container outbox-connect  Healthy
--- стенд поднялся за 46 с
PostgreSQL 18.6 (Debian 18.6-1.pgdg13+2) on x86_64-pc-linux-gnu, compiled by gcc (Debian 14.2.0-19) 14.2.0, 64-bit
logical
4.3.2
{"version":"4.3.1","commit":"26b251a451ce941d","kafka_cluster_id":"5L6g3nShT-eMCtK--X86sw"}
io.debezium.connector.postgresql.PostgresConnector 3.7.0.Final
outbox-pg 29.53MiB / 1GiB
outbox-kafka 421.1MiB / 1GiB
outbox-connect 478.7MiB / 1.5GiB

 

Двойная запись теряет событие

Сценарий dual_write делает ровно то, от чего защищает паттерн, а именно пишет в базу и в Kafka двумя операциями.

# confluent-kafka 2.16.1, psycopg 3.3.8, Kafka 4.3.2, PostgreSQL 18.6, прогнано на стенде 2026-11-06
# outbox_demo.py, продолжение: сценарий dual_write

# ── сценарии ────────────────────────────────────────────────────────────────

def dual_write():
    """Двойная запись без outbox: коммит в БД и отправка в Kafka не атомарны."""
    topic = "dualwrite.order"
    ensure_topics(topic)
    producer = make_producer("dual-write")
    with pg() as conn:
        # A. сначала БД, потом брокер: процесс падает между COMMIT и produce
        with conn.transaction():
            a_id = conn.execute("INSERT INTO orders (customer, amount) VALUES ('dw-anna', 1500) "
                                "RETURNING id").fetchone()[0]
        print(f"A: заказ {a_id} закоммичен в БД; процесс упал до produce, событие не отправлено")

        # B. сначала брокер, потом БД: событие ушло, а транзакция откатилась
        b_id = None
        try:
            with conn.transaction():
                b_id = conn.execute("INSERT INTO orders (customer, amount) VALUES ('dw-boris', 2300) "
                                    "RETURNING id").fetchone()[0]
                producer.produce(topic, key=str(b_id), headers=[("eventType", "OrderCreated")],
                                 value=json.dumps({"orderId": b_id, "customer": "dw-boris", "amount": 2300}))
                producer.flush(15)
                print(f"B: событие OrderCreated для заказа {b_id} подтверждено брокером")
                raise ConnectionError("соединение с БД оборвалось до COMMIT")
        except ConnectionError as e:
            print(f"B: {e}, транзакция откатилась")

        msgs = read_topic(topic)
        order_ids_in_topic = {m["value"]["orderId"] for m in msgs}
        a_in_db = count(conn, "SELECT count(*) FROM orders WHERE id = %s", a_id)
        b_in_db = count(conn, "SELECT count(*) FROM orders WHERE id = %s", b_id)
    print(f"итог A: заказ {a_id} в БД: {a_in_db}, событий о нём в топике: {int(a_id in order_ids_in_topic)}"
          f"  -> потерянное событие")
    print(f"итог B: заказ {b_id} в БД: {b_in_db}, событий о нём в топике: {int(b_id in order_ids_in_topic)}"
          f"  -> фантомное событие")
# вывод прогона на стенде 2026-11-06, фрагмент run_output.txt
=== dual_write ===
A: заказ 1 закоммичен в БД; процесс упал до produce, событие не отправлено
%4|1793978877.801|GETPID|dual-write#producer-2| [thrd:main]: Failed to acquire idempotence PID from broker 127.0.0.1:59092/1: Broker: Coordinator load in progress: retrying
B: событие OrderCreated для заказа 2 подтверждено брокером
B: соединение с БД оборвалось до COMMIT, транзакция откатилась
итог A: заказ 1 в БД: 1, событий о нём в топике: 0  -> потерянное событие
итог B: заказ 2 в БД: 0, событий о нём в топике: 1  -> фантомное событие

В варианте A заказ 1 сохранён без события, в варианте B брокер подтвердил событие о заказе 2, которого в базе нет. Строка библиотеки librdkafka, на которой построен клиент confluent-kafka, про идентификатор идемпотентного продюсера (idempotence PID) на первом запросе к свежему брокеру безвредна.

 

Polling publisher с SKIP LOCKED

Ретранслятор relay.py в одной транзакции забирает пачку через FOR UPDATE SKIP LOCKED, отправляет её, ждёт подтверждения брокера и отмечает published_at. Падение до COMMIT откатывает отметку, и строки уйдут повторно.

# confluent-kafka 2.16.1, psycopg 3.3.8, Kafka 4.3.2, PostgreSQL 18.6, прогнано на стенде 2026-11-06
"""Polling publisher: ретранслятор outbox в Kafka опросом таблицы.

Каждая пачка идёт одной транзакцией: забрать строки с FOR UPDATE SKIP LOCKED, отправить,
дождаться подтверждения брокера, отметить published_at, COMMIT. Падение между отправкой и
COMMIT откатывает отметку, и строки уходят повторно: доставка «как минимум один раз».
"""
import json
import os
import time

import psycopg
from confluent_kafka import Producer

PG_DSN = os.environ.get("PG_DSN", "postgresql://demo:demo@127.0.0.1:55438/shop")
KAFKA = os.environ.get("KAFKA_BOOTSTRAP", "127.0.0.1:59092")

# SKIP LOCKED: второй экземпляр ретранслятора не ждёт чужую пачку, а берёт следующие строки
FETCH_BATCH = """
SELECT id, aggregatetype, aggregateid, type, payload
  FROM outbox
 WHERE published_at IS NULL
 ORDER BY created_at
 LIMIT %s
   FOR UPDATE SKIP LOCKED
"""


class RelayCrash(Exception):
    """Имитация падения процесса ретранслятора."""


def make_producer(client_id: str) -> Producer:
    # acks=all и идемпотентный продюсер: брокер не задвоит сообщение при ретраях внутри сессии,
    # но от повтора после рестарта самого ретранслятора это не спасает
    return Producer({
        "bootstrap.servers": KAFKA,
        "client.id": client_id,
        "acks": "all",
        "enable.idempotence": True,
        "linger.ms": 5,
    })


def relay_batch(conn, producer, topic_prefix: str, batch_size: int = 10,
                crash_after_produce: bool = False, before_produce=None) -> int:
    """Одна пачка outbox -> Kafka. Возвращает число отправленных событий.

    before_produce вызывается после захвата строк и до отправки: в демо им имитируется пауза
    ретранслятора (сборка мусора, сеть), пока строки пачки уже заблокированы.
    """
    with conn.transaction():
        rows = conn.execute(FETCH_BATCH, (batch_size,)).fetchall()
        if not rows:
            return 0
        if before_produce is not None:
            before_produce(rows)
        errors = []

        def on_delivery(err, _msg):
            if err is not None:
                errors.append(err)

        for event_id, agg_type, agg_id, event_type, payload in rows:
            producer.produce(
                f"{topic_prefix}.{agg_type}",
                key=agg_id,  # ключ агрегата: все события заказа в одной партиции
                value=json.dumps(payload, ensure_ascii=False),
                headers=[("id", str(event_id)), ("eventType", event_type)],
                on_delivery=on_delivery,
            )
        # ждём подтверждения брокера до отметки строк, иначе отметка может опередить потерю
        if producer.flush(15) > 0 or errors:
            raise RuntimeError(f"брокер не подтвердил пачку: {errors[:1]}")
        if crash_after_produce:
            # сообщения уже в Kafka, а UPDATE ещё не выполнен: транзакция откатится
            raise RelayCrash("ретранслятор упал после отправки и до отметки строк")
        conn.execute("UPDATE outbox SET published_at = now() WHERE id = ANY(%s)",
                     ([r[0] for r in rows],))
    return len(rows)


def run_relay(name: str, topic_prefix: str, batch_size: int = 10,
              idle_exit: float = 1.0, poll_interval: float = 0.2) -> dict:
    """Крутит пачки, пока outbox пуст дольше idle_exit секунд. Возвращает счётчики."""
    producer = make_producer(name)
    stats = {"relay": name, "batches": 0, "events": 0}
    with psycopg.connect(PG_DSN, autocommit=True) as conn:
        idle_since = None
        while True:
            sent = relay_batch(conn, producer, topic_prefix, batch_size)
            if sent:
                stats["batches"] += 1
                stats["events"] += sent
                idle_since = None
                continue
            idle_since = idle_since or time.monotonic()
            if time.monotonic() - idle_since > idle_exit:
                return stats
            time.sleep(poll_interval)


if __name__ == "__main__":
    import sys
    prefix = sys.argv[1] if len(sys.argv) > 1 else "polling.event"
    print(run_relay("relay-cli", prefix))

Сценарий polling сначала проверяет откат, затем публикует 100 заказов с оплатами вперемешку одним ретранслятором и двумя параллельно, а последним шагом намеренно замораживает первый ретранслятор.

# confluent-kafka 2.16.1, psycopg 3.3.8, Kafka 4.3.2, PostgreSQL 18.6, прогнано на стенде 2026-11-06
# outbox_demo.py, продолжение: сценарий polling

def _fill_outbox(conn, tag: str, n: int, rng: random.Random) -> None:
    """n заказов вперемешку с оплатами: OrderPaid идёт через 0-8 чужих событий после OrderCreated."""
    pending = []  # (момент оплаты, order_id, customer)
    for i in range(n):
        customer = f"{tag}-{i % 17}"
        oid = place_order(conn, customer, 100 * rng.randint(3, 40))
        pending.append((i + rng.randint(0, 8), oid, customer))
        for item in [p for p in pending if p[0] <= i]:
            pay_order(conn, item[1], item[2])
            pending.remove(item)
    for _, oid, customer in pending:
        pay_order(conn, oid, customer)


def _relays(prefix: str, n_relays: int, batch_size: int) -> tuple[list[dict], float]:
    results, threads = [], []
    t0 = time.monotonic()
    for k in range(n_relays):
        th = threading.Thread(target=lambda k=k: results.append(
            run_relay(f"relay-{k + 1}", prefix, batch_size)))
        threads.append(th)
        th.start()
    for th in threads:
        th.join()
    return sorted(results, key=lambda r: r["relay"]), time.monotonic() - t0


def polling():
    """Polling publisher: заказ и событие одной транзакцией, два ретранслятора через SKIP LOCKED."""
    rng = random.Random(42)
    n = 100
    with pg() as conn:
        # откат: ни заказа, ни события
        try:
            place_order(conn, "poll-rollback", 999, fail=True)
        except RuntimeError as e:
            print(f"откат: {e}")
        print("после отката: заказов", count(conn, "SELECT count(*) FROM orders WHERE customer = 'poll-rollback'"),
              "строк outbox", count(conn, "SELECT count(*) FROM outbox WHERE payload->>'customer' = 'poll-rollback'"))

        for variant, n_relays in (("one", 1), ("two", 2)):
            prefix = f"polling_{variant}.event"
            topic = f"{prefix}.order"
            ensure_topics(topic)
            _fill_outbox(conn, f"poll-{variant}", n, rng)
            pending = count(conn, "SELECT count(*) FROM outbox WHERE published_at IS NULL")
            stats, took = _relays(prefix, n_relays, batch_size=10)
            msgs = read_topic(topic)
            ids = Counter(m["headers"]["id"] for m in msgs)
            left = count(conn, "SELECT count(*) FROM outbox WHERE published_at IS NULL")
            print(f"\n[{n_relays} ретранслятор(а)] в outbox к отправке: {pending} событий ({n} заказов x 2)")
            for s in stats:
                print(f"  {s['relay']}: пачек {s['batches']}, событий {s['events']}")
            print(f"  в топике {topic}: сообщений {len(msgs)}, уникальных id {len(ids)}, "
                  f"повторов {sum(v - 1 for v in ids.values())}")
            print(f"  неотправленных строк в outbox: {left}; ушло за {took:.2f} с "
                  f"(включая {1.0:.1f} с ожидания пустой таблицы)")
            bad = order_violations(msgs)
            print(f"  заказов, у которых OrderPaid в партиции раньше OrderCreated: {len(bad)} из {n}")
            if bad:
                trail = [f"{m['headers']['eventType']}@p{m['partition']}:{m['offset']}"
                         for m in sorted(msgs, key=lambda m: m["offset"]) if m["key"] == bad[0]]
                print(f"  пример, заказ {bad[0]}: {' -> '.join(trail)}")

        _paused_relay(conn)


def _paused_relay(conn) -> None:
    """Детерминированно: первый ретранслятор держит пачку с OrderCreated, второй отправляет OrderPaid."""
    prefix = "polling_pause.event"
    topic = f"{prefix}.order"
    ensure_topics(topic)
    oid = place_order(conn, "poll-pause", 1500)
    pay_order(conn, oid, "poll-pause")
    locked, second_done = threading.Event(), threading.Event()

    def hold(rows):
        print(f"  relay-1 захватил {[r[3] for r in rows]} и замер до отправки")
        locked.set()
        second_done.wait(15)

    def first():
        with pg() as c1:
            relay_batch(c1, make_producer("relay-1"), prefix, batch_size=1, before_produce=hold)

    th = threading.Thread(target=first)
    th.start()
    locked.wait(15)
    with pg() as c2:
        # SKIP LOCKED пропускает строку relay-1 и отдаёт следующую: OrderPaid того же заказа
        relay_batch(c2, make_producer("relay-2"), prefix, batch_size=1,
                    before_produce=lambda rows: print(f"  relay-2 захватил {[r[3] for r in rows]}, строку relay-1 пропустил"))
    second_done.set()
    th.join()
    msgs = sorted(read_topic(topic), key=lambda m: m["offset"])
    trail = [f"{m['headers']['eventType']}@p{m['partition']}:{m['offset']}" for m in msgs]
    print(f"\n[2 ретранслятора, relay-1 замер] заказ {oid}: {' -> '.join(trail)}")
# вывод прогона на стенде 2026-11-06, фрагмент run_output.txt
=== polling ===
откат: ошибка бизнес-логики после записи в outbox
после отката: заказов 0 строк outbox 0

[1 ретранслятор(а)] в outbox к отправке: 200 событий (100 заказов x 2)
  relay-1: пачек 20, событий 200
  в топике polling_one.event.order: сообщений 200, уникальных id 200, повторов 0
  неотправленных строк в outbox: 0; ушло за 1.34 с (включая 1.0 с ожидания пустой таблицы)
  заказов, у которых OrderPaid в партиции раньше OrderCreated: 0 из 100

[2 ретранслятор(а)] в outbox к отправке: 200 событий (100 заказов x 2)
  relay-1: пачек 10, событий 100
  relay-2: пачек 10, событий 100
  в топике polling_two.event.order: сообщений 200, уникальных id 200, повторов 0
  неотправленных строк в outbox: 0; ушло за 1.20 с (включая 1.0 с ожидания пустой таблицы)
  заказов, у которых OrderPaid в партиции раньше OrderCreated: 1 из 100
  пример, заказ 104: OrderPaid@p0:0 -> OrderCreated@p0:2
  relay-1 захватил ['OrderCreated'] и замер до отправки
  relay-2 захватил ['OrderPaid'], строку relay-1 пропустил

[2 ретранслятора, relay-1 замер] заказ 204: OrderPaid@p0:0 -> OrderCreated@p0:1

Откат не оставил ни заказа, ни строки outbox. Один ретранслятор отправил 200 событий без повторов и нарушений порядка. Два поделили работу пополам, повторов тоже 0, но у заказа 104 OrderPaid лёг в партицию раньше OrderCreated. На пяти прогонах таких заказов было 1, 0, 3, 1 и 2 из 100, поэтому последний шаг воспроизводит эффект детерминированно на заказе 204. Таким образом SKIP LOCKED масштабирует опросчик без дублей ценой порядка внутри агрегата.

 

Дубль после сбоя и inbox на консьюмере

Консьюмеры сервиса лояльности лежат в consumer.py. Наивный начисляет баллы на каждое сообщение, идемпотентный вставляет id события в loyalty.inbox и начисляет баллы в одной транзакции, а оффсет коммитит только после неё.

# confluent-kafka 2.16.1, psycopg 3.3.8, Kafka 4.3.2, PostgreSQL 18.6, прогнано на стенде 2026-11-06
"""Консьюмеры сервиса лояльности: наивный и с таблицей inbox.

Эффект события OrderCreated: начислить покупателю баллы, 1 балл за каждые 100 рублей.
Наивный консьюмер применяет эффект на каждое сообщение и задваивает баллы на повторах.
Консьюмер с inbox вставляет id события в loyalty.inbox и начисляет баллы в одной транзакции:
повтор упирается в первичный ключ и эффект не применяется второй раз.
"""
import json
import os
import time
import uuid

import psycopg
from confluent_kafka import Consumer, KafkaException, OFFSET_BEGINNING, TopicPartition

PG_DSN = os.environ.get("PG_DSN", "postgresql://demo:demo@127.0.0.1:55438/shop")
KAFKA = os.environ.get("KAFKA_BOOTSTRAP", "127.0.0.1:59092")

ADD_POINTS = """
INSERT INTO loyalty.points (customer, points) VALUES (%s, %s)
ON CONFLICT (customer) DO UPDATE SET points = loyalty.points.points + EXCLUDED.points
"""


def _decode(msg) -> dict:
    headers = {k: (v.decode() if v is not None else None) for k, v in (msg.headers() or [])}
    value = msg.value()
    return {
        "partition": msg.partition(),
        "offset": msg.offset(),
        "key": msg.key().decode() if msg.key() is not None else None,
        "headers": headers,
        "value": json.loads(value) if value else None,
    }


def _partitions(consumer, topic: str) -> list[int]:
    md = consumer.list_topics(topic, timeout=10)
    return sorted(md.topics[topic].partitions)


def _high_watermark(consumer, topic: str, p: int) -> int:
    # у только что созданного топика лидер партиции выбирается не сразу: NOT_LEADER, пробуем ещё
    for attempt in range(20):
        try:
            return consumer.get_watermark_offsets(TopicPartition(topic, p), timeout=10)[1]
        except KafkaException:
            if attempt == 19:
                raise
            time.sleep(0.5)


def _read_until_end(consumer, topic: str, starts: dict[int, int], timeout: float) -> list:
    """Читает назначенные партиции до верхней границы, снятой в момент вызова."""
    highs = {p: _high_watermark(consumer, topic, p) for p in starts}
    consumer.assign([TopicPartition(topic, p, off) for p, off in starts.items()])
    done = {p for p in starts if highs[p] == 0 or (starts[p] >= 0 and starts[p] >= highs[p])}
    out, deadline = [], time.monotonic() + timeout
    while len(done) < len(starts) and time.monotonic() < deadline:
        msg = consumer.poll(0.5)
        if msg is None or msg.error():
            continue
        out.append(msg)
        if msg.offset() + 1 >= highs[msg.partition()]:
            done.add(msg.partition())
    return out


def read_topic(topic: str, timeout: float = 20.0) -> list[dict]:
    """Все сообщения топика с начала, без группы и без коммитов: для подсчётов в демо."""
    c = Consumer({"bootstrap.servers": KAFKA, "group.id": f"reader-{uuid.uuid4()}",
                  "enable.auto.commit": False})
    try:
        parts = _partitions(c, topic)
        msgs = _read_until_end(c, topic, {p: OFFSET_BEGINNING for p in parts}, timeout)
        return [_decode(m) for m in msgs]
    finally:
        c.close()


def _group_consumer(group: str):
    return Consumer({"bootstrap.servers": KAFKA, "group.id": group,
                     "enable.auto.commit": False, "auto.offset.reset": "earliest"})


def _group_starts(c, topic: str) -> dict[int, int]:
    # с последнего закоммиченного оффсета группы, а если его нет, то с начала
    committed = c.committed([TopicPartition(topic, p) for p in _partitions(c, topic)], timeout=10)
    return {tp.partition: (tp.offset if tp.offset >= 0 else OFFSET_BEGINNING) for tp in committed}


def consume_naive(topic: str, group: str) -> dict:
    """Начисляет баллы на каждое сообщение, без проверки повторов."""
    c = _group_consumer(group)
    stats = {"messages": 0, "applied": 0}
    try:
        msgs = _read_until_end(c, topic, _group_starts(c, topic), 20.0)
        with psycopg.connect(PG_DSN, autocommit=True) as conn:
            for msg in msgs:
                ev = _decode(msg)
                stats["messages"] += 1
                if ev["headers"].get("eventType") != "OrderCreated":
                    continue
                with conn.transaction():
                    conn.execute(ADD_POINTS, (ev["value"]["customer"], int(ev["value"]["amount"]) // 100))
                stats["applied"] += 1
                c.commit(message=msg, asynchronous=False)
    finally:
        c.close()
    return stats


def consume_with_inbox(topic: str, group: str, crash_before_offset_commit: bool = False) -> dict:
    """Идемпотентный консьюмер: inbox и эффект в одной транзакции, оффсет коммитится после неё."""
    c = _group_consumer(group)
    stats = {"messages": 0, "applied": 0, "skipped": 0}
    try:
        msgs = _read_until_end(c, topic, _group_starts(c, topic), 20.0)
        with psycopg.connect(PG_DSN, autocommit=True) as conn:
            for msg in msgs:
                ev = _decode(msg)
                stats["messages"] += 1
                with conn.transaction():
                    # id события из заголовка: его ставит и наш ретранслятор, и Debezium Outbox Event Router
                    cur = conn.execute(
                        "INSERT INTO loyalty.inbox (event_id) VALUES (%s) ON CONFLICT DO NOTHING",
                        (ev["headers"]["id"],))
                    if cur.rowcount == 0:
                        stats["skipped"] += 1  # уже обработано: эффект не повторяем
                    else:
                        if ev["headers"].get("eventType") == "OrderCreated":
                            conn.execute(ADD_POINTS, (ev["value"]["customer"],
                                                      int(ev["value"]["amount"]) // 100))
                        stats["applied"] += 1
                if crash_before_offset_commit:
                    continue  # процесс «упадёт» после транзакции в БД, оффсет в Kafka не сдвинут
                c.commit(message=msg, asynchronous=False)
    finally:
        c.close()
    return stats

Сценарий duplicate роняет ретранслятор после отправки и до отметки строк, затем запускает его повторно и прогоняет оба консьюмера по одному и тому же топику.

# confluent-kafka 2.16.1, psycopg 3.3.8, Kafka 4.3.2, PostgreSQL 18.6, прогнано на стенде 2026-11-06
# outbox_demo.py, продолжение: сценарий duplicate

def duplicate():
    """Ретранслятор падает после отправки и до отметки: повтор, который гасит inbox."""
    prefix, topic = "dup.event", "dup.event.order"
    ensure_topics(topic)
    amounts = [1200, 800, 4500, 300, 2100]
    expected = sum(a // 100 for a in amounts)
    with pg() as conn:
        conn.execute("TRUNCATE loyalty.points, loyalty.inbox")
        for i, a in enumerate(amounts):
            place_order(conn, f"dup-{i}", a)
        try:
            with pg() as relay_conn:
                relay_batch(relay_conn, make_producer("relay-crash"), prefix, batch_size=10,
                            crash_after_produce=True)
        except RelayCrash as e:
            print(f"1-й запуск ретранслятора: {e}")
        print("  сообщений в топике:", len(read_topic(topic)),
              "| неотправленных строк в outbox:", count(conn, "SELECT count(*) FROM outbox WHERE published_at IS NULL"))
        print("2-й запуск ретранслятора:", run_relay("relay-restart", prefix))
        msgs = read_topic(topic)
        ids = Counter(m["headers"]["id"] for m in msgs)
        print(f"  сообщений в топике: {len(msgs)}, уникальных id: {len(ids)}")

        print(f"\nожидаемые баллы: {expected}")
        print("наивный консьюмер:", consume_naive(topic, "loyalty-naive"),
              "| баллов начислено:", count(conn, "SELECT coalesce(sum(points), 0) FROM loyalty.points"))
        conn.execute("TRUNCATE loyalty.points, loyalty.inbox")
        print("inbox, 1-й проход (падает до коммита оффсетов):",
              consume_with_inbox(topic, "loyalty-inbox", crash_before_offset_commit=True))
        print("inbox, 2-й проход после рестарта:", consume_with_inbox(topic, "loyalty-inbox"))
        print("inbox, 3-й проход:", consume_with_inbox(topic, "loyalty-inbox"))
        print("  баллов начислено:", count(conn, "SELECT coalesce(sum(points), 0) FROM loyalty.points"),
              "| строк в inbox:", count(conn, "SELECT count(*) FROM loyalty.inbox"))
# вывод прогона на стенде 2026-11-06, фрагмент run_output.txt
=== duplicate ===
1-й запуск ретранслятора: ретранслятор упал после отправки и до отметки строк
  сообщений в топике: 5 | неотправленных строк в outbox: 5
2-й запуск ретранслятора: {'relay': 'relay-restart', 'batches': 1, 'events': 5}
  сообщений в топике: 10, уникальных id: 5

ожидаемые баллы: 89
наивный консьюмер: {'messages': 10, 'applied': 10} | баллов начислено: 178
inbox, 1-й проход (падает до коммита оффсетов): {'messages': 10, 'applied': 5, 'skipped': 5}
inbox, 2-й проход после рестарта: {'messages': 10, 'applied': 0, 'skipped': 10}
inbox, 3-й проход: {'messages': 0, 'applied': 0, 'skipped': 0}
  баллов начислено: 89 | строк в inbox: 5

После рестарта ретранслятора в топике 10 сообщений при 5 уникальных id. Наивный консьюмер начислил 178 баллов вместо 89. Консьюмер с inbox на первом проходе отсёк 5 повторов и упал до коммита оффсетов, а после рестарта перечитал все 10 сообщений и не применил ни одного, итог 89 баллов. Оффсет коммитится после транзакции с эффектом, поэтому сбой между ними даёт повторное чтение, а не потерю.

 

Событие в WAL без таблицы

Сценарий emit_message проверяет pg_logical_emit_message без Debezium, через временный слот с плагином test_decoding.

# confluent-kafka 2.16.1, psycopg 3.3.8, Kafka 4.3.2, PostgreSQL 18.6, прогнано на стенде 2026-11-06
# outbox_demo.py, продолжение: сценарий emit_message

def emit_message():
    """pg_logical_emit_message: событие прямо в WAL, без строки в таблице outbox."""
    with pg() as conn:
        outbox_before = count(conn, "SELECT count(*) FROM outbox")
        conn.execute("SELECT pg_create_logical_replication_slot('emit_demo', 'test_decoding')")
        with conn.transaction():
            oid = conn.execute("INSERT INTO orders (customer, amount) VALUES ('emit-1', 700) "
                               "RETURNING id").fetchone()[0]
            conn.execute("SELECT pg_logical_emit_message(true, 'outbox', %s)",
                         (json.dumps({"type": "OrderCreated", "orderId": oid}),))
        for transactional in (True, False):
            try:
                with conn.transaction():
                    # flush=true сбрасывает нетранзакционное сообщение в WAL сразу: без него оно ждёт
                    # в буферах, а pg_logical_slot_get_changes читает только сброшенное на диск
                    conn.execute("SELECT pg_logical_emit_message(%s, 'outbox', %s, true)",
                                 (transactional, json.dumps({"type": "OrderCreated",
                                                             "note": f"rollback, transactional={transactional}"})))
                    raise RuntimeError("откат")
            except RuntimeError:
                pass
        rows = conn.execute("SELECT lsn, xid, data FROM pg_logical_slot_get_changes('emit_demo', NULL, NULL) "
                            "WHERE data LIKE 'message%%' OR data LIKE 'table public.orders%%'").fetchall()
        for lsn, xid, data in rows:
            print(f"  {lsn} xid={xid} {data}")
        conn.execute("SELECT pg_drop_replication_slot('emit_demo')")
        print("строк в outbox до и после:", outbox_before, count(conn, "SELECT count(*) FROM outbox"))
# вывод прогона на стенде 2026-11-06, фрагмент run_output.txt
=== emit_message ===
  0/1C86EC8 xid=1242 table public.orders: INSERT: id[bigint]:210 customer[text]:'emit-1' amount[numeric]:700.00 status[text]:'created' created_at[timestamp with time zone]:'2026-11-06 15:28:12.296961+00'
  0/1C86FD0 xid=1242 message: transactional: 1 prefix: outbox, sz: 40 content:{"type": "OrderCreated", "orderId": 210}
  0/1C87128 xid=0 message: transactional: 0 prefix: outbox, sz: 65 content:{"type": "OrderCreated", "note": "rollback, transactional=False"}
строк в outbox до и после: 407 407

Сообщение пришло в той же транзакции xid=1242, что и заказ 210. Из откатившихся транзакций в слот попало только нетранзакционное сообщение с xid=0, а строк в outbox так и осталось 407.

 

Debezium Outbox Event Router

Сценарий cdc регистрирует коннектор через REST API Kafka Connect. Предикат применяет SMT только к топику outbox, а type уезжает в заголовок eventType, как у опросчика.

# connector.json для Debezium 3.7.0.Final, прогнано на стенде 2026-11-06 (строка-комментарий статьи, в файле её нет)
{
  "name": "outbox-connector",
  "config": {
    "connector.class": "io.debezium.connector.postgresql.PostgresConnector",
    "plugin.name": "pgoutput",
    "database.hostname": "pg",
    "database.port": "5432",
    "database.user": "demo",
    "database.password": "demo",
    "database.dbname": "shop",
    "topic.prefix": "shop",
    "table.include.list": "public.outbox",
    "publication.name": "outbox_pub",
    "publication.autocreate.mode": "filtered",
    "slot.name": "outbox_slot",
    "snapshot.mode": "no_data",
    "tombstones.on.delete": "false",
    "message.prefix.include.list": "outbox",

    "transforms": "outbox",
    "transforms.outbox.type": "io.debezium.transforms.outbox.EventRouter",
    "transforms.outbox.predicate": "isOutboxTable",
    "transforms.outbox.table.expand.json.payload": "true",
    "transforms.outbox.table.fields.additional.placement": "type:header:eventType",
    "transforms.outbox.table.op.invalid.behavior": "warn",

    "predicates": "isOutboxTable",
    "predicates.isOutboxTable.type": "org.apache.kafka.connect.transforms.predicates.TopicNameMatches",
    "predicates.isOutboxTable.pattern": "shop\\.public\\.outbox",

    "key.converter": "org.apache.kafka.connect.storage.StringConverter",
    "value.converter": "org.apache.kafka.connect.json.JsonConverter",
    "value.converter.schemas.enable": "false"
  }
}

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

# confluent-kafka 2.16.1, psycopg 3.3.8, Debezium 3.7.0.Final, Kafka 4.3.2, PostgreSQL 18.6, прогнано на стенде 2026-11-06
# outbox_demo.py, окончание: сценарий cdc и запуск по имени

def _connect(method: str, path: str, body: dict | None = None) -> dict:
    req = urllib.request.Request(CONNECT_URL + path, method=method,
                                 data=json.dumps(body).encode() if body is not None else None,
                                 headers={"Content-Type": "application/json"})
    with urllib.request.urlopen(req, timeout=15) as r:
        return json.loads(r.read() or b"{}")


def _wait_for(topic: str, n: int, timeout: float = 60.0) -> list[dict]:
    deadline = time.monotonic() + timeout
    while True:
        msgs = read_topic(topic, timeout=5)
        if len(msgs) >= n or time.monotonic() > deadline:
            return msgs
        time.sleep(0.3)


def cdc():
    """Тот же outbox через Debezium: WAL -> PostgreSQL connector -> Outbox Event Router -> топик."""
    topic, msg_topic = "outbox.event.order", "shop.message"
    ensure_topics(topic, msg_topic)
    cfg = json.load(open(os.path.join(HERE, "connector.json"), encoding="utf-8"))
    _connect("PUT", f"/connectors/{cfg['name']}/config", cfg["config"])
    deadline = time.monotonic() + 90
    while time.monotonic() < deadline:
        try:
            st = _connect("GET", f"/connectors/{cfg['name']}/status")
            if st["connector"]["state"] == "RUNNING" and st["tasks"] and \
                    all(t["state"] == "RUNNING" for t in st["tasks"]):
                break
        except Exception:
            pass
        time.sleep(1)
    print("коннектор:", st["connector"]["state"], "задачи:", [t["state"] for t in st["tasks"]])
    with pg() as conn:
        # слот должен стать активным, иначе первые вставки уйдут в WAL раньше, чем коннектор начнёт читать
        for _ in range(60):
            if count(conn, "SELECT count(*) FROM pg_replication_slots WHERE slot_name = 'outbox_slot' AND active"):
                break
            time.sleep(1)
        print("слот:", conn.execute("SELECT slot_name, plugin, active FROM pg_replication_slots "
                                    "WHERE slot_name = 'outbox_slot'").fetchone())
        t_commit = time.monotonic()
        ids = [place_order(conn, f"cdc-{i}", a) for i, a in enumerate((1100, 2600, 900))]
        ids += [place_order(conn, f"cdc-del-{i}", a, delete_outbox=True) for i, a in enumerate((1700, 500))]
        try:
            place_order(conn, "cdc-rollback", 999, fail=True)
        except RuntimeError:
            pass
        msgs = _wait_for(topic, len(ids))
        print(f"5 коммитов -> {len(msgs)} сообщений в {topic} за {time.monotonic() - t_commit:.2f} с")
        for m in sorted(msgs, key=lambda m: int(m["key"])):
            print(f"  p{m['partition']} key={m['key']} eventType={m['headers'].get('eventType')} "
                  f"id={m['headers'].get('id')} value={json.dumps(m['value'], ensure_ascii=False)}")
        print("строк outbox у заказов cdc-del-*:",
              count(conn, "SELECT count(*) FROM outbox WHERE payload->>'customer' LIKE 'cdc-del-%%'"),
              "| событий cdc-rollback в топике:",
              sum(1 for m in msgs if m["value"]["customer"] == "cdc-rollback"))

        # UPDATE строки outbox: SMT не превращает его в событие, а пишет предупреждение в лог
        conn.execute("UPDATE outbox SET payload = payload || '{\"amount\": 1}' "
                     "WHERE payload->>'customer' = 'cdc-0'")
        time.sleep(5)
        print("после UPDATE строки outbox сообщений в топике:", len(read_topic(topic)))
        try:
            log = subprocess.run(["docker", "logs", "outbox-connect"], capture_output=True, text=True,
                                 timeout=30)
            lines = [ln for ln in (log.stdout + log.stderr).splitlines()
                     if "WARN" in ln and "EventRouter" in ln]
            for ln in lines[-2:]:
                print("  лог Connect:", ln[:400])
        except (FileNotFoundError, subprocess.TimeoutExpired):
            print("  docker logs недоступен, смотрите лог контейнера outbox-connect вручную")

        # логическое сообщение в той же транзакции, что и заказ: Debezium пишет его в <topic.prefix>.message
        with conn.transaction():
            oid = conn.execute("INSERT INTO orders (customer, amount) VALUES ('cdc-msg', 3100) "
                               "RETURNING id").fetchone()[0]
            conn.execute("SELECT pg_logical_emit_message(true, 'outbox', %s)",
                         (json.dumps({"type": "OrderCreated", "orderId": oid}),))
        try:  # нетранзакционное сообщение в откатившейся транзакции: дойдёт ли оно до Debezium
            with conn.transaction():
                conn.execute("SELECT pg_logical_emit_message(false, 'outbox', %s, true)",
                             (json.dumps({"type": "OrderCreated", "note": "rollback, transactional=false"}),))
                raise RuntimeError("откат")
        except RuntimeError:
            pass
        mm = _wait_for(msg_topic, 2, timeout=30)
        print(f"сообщений в {msg_topic}: {len(mm)}")
        for m in mm:
            msg = m["value"]["message"]
            print(f"  op={m['value']['op']} txId={m['value']['source']['txId']} prefix={msg['prefix']} "
                  f"content={base64.b64decode(msg['content']).decode()}")
        if mm:
            print("  value целиком:", json.dumps(mm[0]["value"], ensure_ascii=False)[:700])

    print("\ninbox-консьюмер на топике Debezium:", consume_with_inbox(topic, "loyalty-cdc"))


SCENARIOS = {"dual_write": dual_write, "polling": polling, "duplicate": duplicate,
             "emit_message": emit_message, "cdc": cdc}

if __name__ == "__main__":
    name = sys.argv[1] if len(sys.argv) > 1 else "all"
    for key, fn in SCENARIOS.items():
        if name in ("all", key):
            print(f"\n=== {key} ===")
            t0 = time.monotonic()
            fn()
            print(f"--- {key}: {time.monotonic() - t0:.1f} с")
# вывод прогона на стенде 2026-11-06, фрагмент run_output.txt
=== cdc ===
коннектор: RUNNING задачи: ['RUNNING']
слот: ('outbox_slot', 'pgoutput', True)
5 коммитов -> 5 сообщений в outbox.event.order за 0.79 с
  p1 key=211 eventType=OrderCreated id=a0f12844-63dd-45b3-97dc-b7de9cee03df value={"amount": 1100, "orderId": 211, "customer": "cdc-0"}
  p2 key=212 eventType=OrderCreated id=23f95cd5-2133-4176-ba70-6da470db114d value={"amount": 2600, "orderId": 212, "customer": "cdc-1"}
  p2 key=213 eventType=OrderCreated id=14b0dee2-2bef-4255-83a7-b0ab79111295 value={"amount": 900, "orderId": 213, "customer": "cdc-2"}
  p2 key=214 eventType=OrderCreated id=db02747f-023f-4e4a-9dd2-58a7c62d0505 value={"amount": 1700, "orderId": 214, "customer": "cdc-del-0"}
  p0 key=215 eventType=OrderCreated id=8d50857f-8e73-419e-9186-2af8355cfa75 value={"amount": 500, "orderId": 215, "customer": "cdc-del-1"}
строк outbox у заказов cdc-del-*: 0 | событий cdc-rollback в топике: 0
после UPDATE строки outbox сообщений в топике: 5
  лог Connect: 2026-11-06T15:28:16,755 WARN   Postgres||lifecycle  Unexpected update message received [REDACTED] and ignored   [io.debezium.transforms.outbox.EventRouterDelegate]
сообщений в shop.message: 2
  op=m txId=1253 prefix=outbox content={"type": "OrderCreated", "orderId": 217}
  op=m txId=None prefix=outbox content={"type": "OrderCreated", "note": "rollback, transactional=false"}
  value целиком: {"op": "m", "ts_ms": 1793978901500, "source": {"version": "3.7.0.Final", "connector": "postgresql", "name": "shop", "ts_ms": 1793978901062, "snapshot": "false", "db": "shop", "sequence": "[\"29943496\",\"29943760\"]", "ts_us": 1793978901062392, "ts_ns": 1793978901062392000, "schema": "", "table": "", "txId": 1253, "lsn": 29943760, "xmin": null, "origin": null, "origin_lsn": null}, "transaction": null, "message": {"prefix": "outbox", "content": "eyJ0eXBlIjogIk9yZGVyQ3JlYXRlZCIsICJvcmRlcklkIjogMjE3fQ=="}}

inbox-консьюмер на топике Debezium: {'messages': 5, 'applied': 5, 'skipped': 0}

Все 5 закоммиченных заказов дошли до outbox.event.order за 0.79 с с ключом, равным номеру заказа. Строки cdc-del-* удалены в той же транзакции, а события всё равно доставлены. Откатившийся заказ в топик не попал, UPDATE строки outbox дал только предупреждение EventRouterDelegate в логе. В shop.message пришли оба логических сообщения, включая нетранзакционное из откатившейся транзакции, поэтому для outbox годится только transactional = true. Inbox-консьюмер обработал топик Debezium без правок, потому что заголовок id тот же.

Итог по таблице outbox и отставание слота репликации снимают два запроса к базе.

# PostgreSQL 18.6, Docker Compose 2.40.3, прогнано на стенде 2026-11-06
docker compose exec -T pg psql -U demo -d shop -Xc \
  "SELECT type, count(*) AS rows, count(published_at) AS published FROM outbox GROUP BY type ORDER BY type"
docker compose exec -T pg psql -U demo -d shop -Xc \
  "SELECT slot_name, plugin, active, pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), confirmed_flush_lsn)) AS lag FROM pg_replication_slots"
# вывод прогона на стенде 2026-11-06, фрагмент run_output.txt
=== ПОСЛЕ ВСЕХ СЦЕНАРИЕВ ===
     type     | rows | published 
--------------+------+-----------
 OrderCreated |  209 |       206
 OrderPaid    |  201 |       201
(2 rows)

  slot_name  |  plugin  | active |    lag     
-------------+----------+--------+------------
 outbox_slot | pgoutput | t      | 9896 bytes
(1 row)

После всех сценариев слот outbox_slot активен с отставанием 9896 байт. Слот удерживает WAL, пока коннектор его не прочитает, поэтому надолго остановленный коннектор раздувает диск базы, и отставание слота нужно держать под мониторингом.

 

Заключение

Transactional outbox сводит согласованность базы и брокера к одной локальной транзакции и переносит сложность в ретранслятор и потребителя. Опросчик проще, но параллельные экземпляры ломают порядок агрегата. Debezium таблицу не опрашивает и позволяет держать её пустой ценой слота репликации и Kafka Connect. Доставка в обоих случаях at-least-once, поэтому без inbox паттерн outbox защищает от потери событий, но не от дублей. Эти темы на практике разбирает курс Apache Kafka для разработчиков.

 

Референсные ссылки