Все заметки
Программирование

Transactional outbox: заказ сохранён, а событие потерялось

Записать в базу и потом отправить в брокер — это запись в две системы, и если процесс умрёт между ними, событие тихо исчезнет. Разбираем таблицу outbox, relay на SKIP LOCKED и идемпотентного потребителя.

Проблема: заказ есть, события нет

Представьте: пользователь оформляет заказ. Django view записывает строку Order в PostgreSQL, а затем отправляет событие order.created в Redis Stream (с RabbitMQ или Kafka всё будет так же). Это событие читает биллинг и создаёт счёт, склад резервирует товар, сервис уведомлений шлёт SMS.

Много дней всё работает. А потом во время деплоя под получает SIGKILL — ровно в те миллисекунды, когда COMMIT уже прошёл, а publish() ещё не вызван. Заказ в базе есть, клиент заплатил, а биллинг о нём не знает. В логах ни одной ошибки, потому что ошибки не было: процесс просто умер.

Бывает и наоборот: сообщение ушло в брокер, а транзакция откатилась. Теперь склад резервирует товар под заказ, которого не существует.

Это проблема dual write: одно бизнес-действие записывается в две независимые системы, а общей транзакции между ними нет. Сегодня разберём паттерн, который закрывает этот зазор, — transactional outbox: таблица, relay-процесс, SKIP LOCKED, порядок, дубликаты и идемпотентность на стороне потребителя.

Почему наивные решения ломаются

Первая попытка обычно выглядит так:

# orders/services.py — NAIVE
from django.db import transaction

from orders.events import publish
from orders.models import Order


def place_order(user, cart):
    with transaction.atomic():
        order = Order.objects.create(user=user, total=cart.total)
        publish("order.created", {"order_id": order.pk, "total": str(order.total)})
        # if this raises, the order rolls back,
        # but the event is already in the broker
        reserve_stock(order, cart)
    return order

Здесь publish() внутри транзакции. Если reserve_stock() бросит исключение, заказ откатится, а сообщение уже лежит в брокере — фантомное событие. Кроме того, если брокер тормозит, транзакция висит открытой и держит блокировки строк. Если брокер лежит, заказ не проходит вообще: второстепенная система останавливает основной бизнес-поток.

Опытный разработчик «чинит» это через transaction.on_commit():

def place_order(user, cart):
    with transaction.atomic():
        order = Order.objects.create(user=user, total=cart.total)
        reserve_stock(order, cart)
        transaction.on_commit(
            lambda: publish(
                "order.created",
                {"order_id": order.pk, "total": str(order.total)},
            )
        )
    return order

Фантомов больше нет: колбэк вызывается только после успешного COMMIT. Но между COMMIT и колбэком всё ещё есть окно. Если процесс умрёт в этом окне, брокер в эту секунду недоступен или сеть отдаст таймаут — событие потеряно, и не осталось никакого следа, чтобы отправить его повторно. on_commit живёт в памяти, а не на диске.

Следующая мысль — двухфазный коммит (2PC). В PostgreSQL есть PREPARE TRANSACTION, но Redis и большинство брокеров не умеют участвовать в распределённой транзакции, а координатор сам по себе отдельная проблема надёжности. На практике этим путём почти никто не идёт.

Атомарно записать в две системы нельзя. Но атомарно записать в одну — в базу — можно. В этом вся идея outbox: событие тоже пишем в базу.

Механизм: таблица outbox в той же транзакции

Идея в трёх шагах:

  1. Бизнес-данные (Order) и событие (OutboxEvent) пишутся в одной транзакции в одну базу. Либо коммитится и то и другое, либо ничего.
  2. Отдельный процесс — relay (иногда его называют poller) — читает из outbox ещё не отправленные строки, публикует их в брокер и проставляет published_at.
  3. Relay может умереть после отправки, но до отметки. Поэтому событие доставляется как минимум один раз (at-least-once), и потребитель обязан быть готов к дубликатам.

В итоге проблема «сообщение потерялось» превращается в проблему «сообщение пришло дважды». А вторую решить идемпотентностью гораздо проще.

Модель:

# orders/models.py
import uuid

from django.db import models


class OutboxEvent(models.Model):
    id = models.BigAutoField(primary_key=True)
    event_id = models.UUIDField(default=uuid.uuid4, unique=True, editable=False)
    aggregate_type = models.CharField(max_length=50)
    aggregate_id = models.CharField(max_length=64)
    event_type = models.CharField(max_length=100)
    payload = models.JSONField()
    created_at = models.DateTimeField(auto_now_add=True)
    published_at = models.DateTimeField(null=True, blank=True)
    attempts = models.PositiveIntegerField(default=0)
    last_error = models.TextField(blank=True, default="")

    class Meta:
        indexes = [
            models.Index(
                fields=["id"],
                name="outbox_pending_idx",
                condition=models.Q(published_at__isnull=True),
            ),
        ]

Несколько решений:

  • id — BigAutoField, для порядка. event_id — UUID: глобальный идентификатор, по которому потребитель распознаёт дубликат. Внутренний id наружу не уходит, event_id путешествует вместе с событием.
  • payload — JSONField. Кладите туда не ORM-объект, а словарь с явной схемой. Decimal и datetime переводите в строки сами: стандартный JSON-энкодер их не сериализует.
  • Частичный (partial) индекс покрывает только строки с published_at IS NULL. Даже если в таблице миллионы отправленных записей, запрос relay идёт по крошечному индексу.

Создание заказа теперь выглядит так (reserve_stock — обычная функция вашего проекта):

# orders/services.py
from django.db import transaction

from orders.models import Order, OutboxEvent


def place_order(user, cart):
    with transaction.atomic():
        order = Order.objects.create(user=user, total=cart.total)
        reserve_stock(order, cart)
        OutboxEvent.objects.create(
            aggregate_type="order",
            aggregate_id=str(order.pk),
            event_type="order.created",
            payload={
                "version": 1,
                "order_id": order.pk,
                "user_id": user.pk,
                "total": str(order.total),
            },
        )
    return order

Обратите внимание: на пути запроса нет ни одного сетевого вызова к брокеру. Транзакция короткая, заказы принимаются даже при лежащем брокере — события просто ждут в таблице.

Relay: параллельное чтение через SKIP LOCKED

Relay раз в несколько сотен миллисекунд забирает неотправленные события. Если одновременно работает несколько экземпляров (скажем, два пода), они не должны брать одну строку дважды и не должны ждать друг друга. Для этого используем FOR UPDATE SKIP LOCKED из PostgreSQL:

# orders/outbox.py
import json

import redis
from django.conf import settings
from django.db import transaction
from django.utils import timezone

from orders.models import OutboxEvent

r = redis.Redis.from_url(settings.REDIS_URL, socket_timeout=5)


def publish_to_stream(event: OutboxEvent) -> None:
    r.xadd(
        f"events:{event.aggregate_type}",
        {
            "event_id": str(event.event_id),
            "type": event.event_type,
            "aggregate_id": event.aggregate_id,
            "payload": json.dumps(event.payload),
        },
        maxlen=1_000_000,
        approximate=True,
    )


def relay_batch(publish=publish_to_stream, batch_size: int = 100) -> tuple[int, bool]:
    """Publish one batch of pending events. Returns (sent, failed)."""
    with transaction.atomic():
        events = list(
            OutboxEvent.objects.select_for_update(skip_locked=True)
            .filter(published_at__isnull=True)
            .order_by("id")[:batch_size]
        )
        now = timezone.now()
        touched, failed = [], False
        for event in events:
            try:
                publish(event)
            except Exception as exc:
                event.attempts += 1
                event.last_error = repr(exc)[:2000]
                touched.append(event)
                failed = True
                break  # later events must not overtake this one
            event.published_at = now
            touched.append(event)
        if touched:
            OutboxEvent.objects.bulk_update(
                touched, ["published_at", "attempts", "last_error"]
            )
    return len(touched) - int(failed), failed

Django превращает этот queryset по сути в такой SQL:

SELECT *
FROM orders_outboxevent
WHERE published_at IS NULL
ORDER BY id
LIMIT 100
FOR UPDATE SKIP LOCKED;

Что происходит внутри: FOR UPDATE ставит блокировку на выбранные строки. SKIP LOCKED пропускает строки, уже заблокированные другой транзакцией, вместо того чтобы ждать их. Первый relay берёт строки 1–100; второй, придя в тот же момент, их не видит и берёт следующие 100. Никто никого не ждёт, одна строка не попадает в два relay. Блокировки снимаются, когда транзакция relay коммитится или откатывается.

Тонкий момент: блокировки удерживаются на время сетевого вызова к брокеру. Поэтому у Redis-клиента стоит socket_timeout, а батч маленький: если брокер завис, транзакция не должна висеть бесконечно.

При ошибке relay останавливается на этом месте (break): неудачное событие остаётся в голове очереди, и последующие его не обгоняют. Всё, что успели отправить, сохраняется с published_at. У упавшего события растёт счётчик attempts — он понадобится для алертов.

Запускаем relay отдельным процессом:

# orders/management/commands/outbox_relay.py
import time

from django.core.management.base import BaseCommand
from django.db import close_old_connections

from orders.outbox import relay_batch


class Command(BaseCommand):
    help = "Publish pending outbox events to the broker"

    def handle(self, *args, **options):
        backoff = 1.0
        while True:
            close_old_connections()
            sent, failed = relay_batch()
            if failed:
                time.sleep(backoff)
                backoff = min(backoff * 2, 30.0)
                continue
            backoff = 1.0
            if sent == 0:
                time.sleep(0.5)
python manage.py outbox_relay

Запускайте его через systemd, supervisor или Kubernetes Deployment: если процесс упадёт из-за потери соединения с базой, оркестратор его поднимет. Если важна задержка, вместо sleep можно будить relay через PostgreSQL LISTEN/NOTIFY — NOTIFY доставляется только после коммита. Но периодический опрос всё равно оставьте: уведомление, отправленное, пока relay не подключён, теряется, а строка в outbox — нет.

Порядок и дубликаты

Здесь нужно честно признать две вещи.

Дубликаты неизбежны. Если relay умрёт после успешного xadd, но до COMMIT, транзакция откатится, и следующий relay отправит то же событие снова. Или xadd вернётся с таймаутом, хотя Redis на самом деле сообщение принял. Это не баг — это цена гарантии at-least-once.

Глобального порядка нет. Причин три:

  • Значение sequence выдаётся при INSERT, а не при коммите. Транзакция T1 получает id=10, T2 — id=11, но T2 коммитится первой. Relay отправит 11, а 10 появится позже.
  • Если несколько relay работают параллельно через SKIP LOCKED, батч второго может дойти до брокера раньше батча первого.
  • Брокер и потребители сами по себе параллельны.

На практике обычно нужен порядок в пределах одного агрегата (например, одного заказа). Способы его обеспечить:

  • Сериализуйте транзакции, меняющие один агрегат: блокируйте строку заказа через select_for_update(). Тогда события одного заказа получают id в порядке коммита.
  • Если нужен строгий порядок, запускайте один relay или добавьте в outbox колонку partition (crc32(aggregate_id) % N), и пусть каждый relay читает только свою партицию.
  • Проверяйте версию у потребителя: если в payload есть версия агрегата, устаревшее событие легко отбросить.

Идемпотентность на стороне потребителя

Раз дубликаты придут гарантированно, потребитель должен обрабатывать каждый event_id ровно один раз. Самый надёжный способ — таблица обработанных событий и бизнес-эффект в одной транзакции:

# billing/models.py
from django.db import models


class ProcessedEvent(models.Model):
    event_id = models.UUIDField(primary_key=True)
    processed_at = models.DateTimeField(auto_now_add=True)
# billing/consumers.py
import json

import redis
from django.conf import settings
from django.db import transaction

from billing.models import Invoice, ProcessedEvent

r = redis.Redis.from_url(settings.REDIS_URL)
STREAM, GROUP = "events:order", "billing"


def handle(event_id: str, event_type: str, payload: dict) -> None:
    with transaction.atomic():
        _, created = ProcessedEvent.objects.get_or_create(event_id=event_id)
        if not created:
            return  # duplicate delivery: the effect is already applied
        if event_type == "order.created":
            Invoice.objects.create(order_id=payload["order_id"], amount=payload["total"])


def run(consumer: str) -> None:
    try:
        r.xgroup_create(STREAM, GROUP, id="0", mkstream=True)
    except redis.ResponseError as exc:
        if "BUSYGROUP" not in str(exc):
            raise
    while True:
        resp = r.xreadgroup(GROUP, consumer, {STREAM: ">"}, count=50, block=5000)
        for _stream, messages in resp or []:
            for msg_id, fields in messages:
                handle(
                    fields[b"event_id"].decode(),
                    fields[b"type"].decode(),
                    json.loads(fields[b"payload"]),
                )
                r.xack(STREAM, GROUP, msg_id)  # only after the DB commit

Важные детали:

  • Строка ProcessedEvent и Invoice — в одной транзакции. Если обработчик бросит исключение, откатится и то и другое, и событие будет обработано заново при следующей попытке.
  • event_id — первичный ключ. Если два воркера одновременно получили одно событие, PostgreSQL заставит второй INSERT ждать завершения первого, а затем выдаст ошибку уникальности; get_or_create её перехватит и вернёт created=False.
  • XACK — после коммита. Если процесс умрёт между ними, сообщение останется в pending-списке и будет доставлено повторно — ProcessedEvent его отсечёт. Чтобы забрать pending-сообщения умерших consumer'ов, используйте XAUTOCLAIM.

Иногда эффект идемпотентен сам по себе: UPDATE ... SET status = 'paid' даёт тот же результат при повторе, или достаточно уникального ограничения на Invoice.order_id. Подробнее об этом я писал в статьях про ключи идемпотентности и задачи Celery.

CDC: вариант без поллера

Вместо поллера применяют и Change Data Capture. Инструмент вроде Debezium читает WAL через logical decoding PostgreSQL (wal_level = logical, replication slot, плагин pgoutput) и передаёт каждую новую строку outbox в Kafka. Для этого паттерна в Debezium есть готовое преобразование Outbox Event Router.

Плюсы: нет опрашивающих запросов, события идут в порядке коммита, задержка маленькая. Минусы: нужна инфраструктура Kafka Connect, и replication slot обязательно мониторить — если потребитель остановился, PostgreSQL не удаляет WAL для слота, и диск может заполниться. Таблица outbox всё равно нужна: CDC заменяет только relay.

Подход Потеря события Фантомное событие Что нужно
publish() внутри транзакции нет, но при лежащем брокере не проходит и заказ да ничего
on_commit + publish() да, при падении нет ничего
Outbox + поллер нет нет таблица, relay-процесс, идемпотентный потребитель
Outbox + CDC нет нет Debezium/Kafka Connect, мониторинг replication slot

Подводные камни в продакшене

  • Таблица outbox распухает. Удаляйте отправленные строки периодически — не одним большим DELETE, а батчами. Каждая удалённая строка становится dead tuple, так что следите, успевает ли autovacuum за этой таблицей:
# orders/outbox.py (continued)
from datetime import timedelta


def purge_published(older_than=timedelta(days=7), batch_size=5000) -> None:
    cutoff = timezone.now() - older_than
    while True:
        ids = list(
            OutboxEvent.objects.filter(published_at__lt=cutoff)
            .values_list("id", flat=True)[:batch_size]
        )
        if not ids:
            break
        OutboxEvent.objects.filter(id__in=ids).delete()
  • «Ядовитое» событие блокирует очередь. Relay останавливается на ошибке, значит одно битое событие держит все остальные. Когда attempts превышает порог, шлите алерт, и пусть решение принимает человек: исправить payload или вручную убрать событие.
  • Relay не должен читать с реплики. SELECT ... FOR UPDATE выполняется на primary; проверьте настройки database router.
  • Длинная транзакция relay. Если брокер тормозит, открытая транзакция мешает VACUUM. Таймауты и маленький батч обязательны.
  • on_commit + Celery — это не outbox. task.delay() тоже сетевой вызов к брокеру и точно так же может потеряться после коммита.
  • Схема payload — это API. Потребители к ней привязываются. event_type, версия и только нужные поля. Не кладите лишние персональные данные: outbox хранится как лог и попадает в бэкапы.
  • Надёжность брокера. Outbox доводит событие до брокера, дальше ответственность на нём. Если используете Redis Streams, разберитесь с persistence (AOF) и с тем, когда maxlen начнёт обрезать старые сообщения.

Чеклист

  • Бизнес-запись и OutboxEvent — в одном transaction.atomic().
  • На пути запроса нет сетевых вызовов к брокеру.
  • Частичный индекс по published_at IS NULL.
  • Relay: select_for_update(skip_locked=True), маленький батч, таймаут брокера.
  • Не полагайтесь на глобальный порядок; для порядка внутри агрегата — блокировка или партиции.
  • У каждого события глобальный event_id; у потребителя ProcessedEvent и эффект в одной транзакции.
  • ACK в брокере — только после коммита.
  • Отправленные строки чистятся батчами.
  • Мониторинг: возраст самого старого неотправленного события, порог attempts, autovacuum.

Итог

Атомарно записать в две системы нельзя, поэтому событие пишется в базу вместе с бизнес-данными, а до брокера его доводит отдельный relay. Это меняет «потерянное сообщение» на «повторное сообщение», а повтор обезвреживается идемпотентностью потребителя. SKIP LOCKED позволяет безопасно распараллелить relay, но порядок вы обеспечиваете сами и только в пределах агрегата.

// комментарии

Загружаем комментарии...

    // следующий шаг

    Давайте построим что-нибудь вместе.

    Написать в Telegram
    aslbek@asldev: ~
    ❯