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 в той же транзакции
Идея в трёх шагах:
- Бизнес-данные (
Order) и событие (OutboxEvent) пишутся в одной транзакции в одну базу. Либо коммитится и то и другое, либо ничего. - Отдельный процесс — relay (иногда его называют poller) — читает из outbox ещё не отправленные строки, публикует их в брокер и проставляет
published_at. - 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, но порядок вы обеспечиваете сами и только в пределах агрегата.
// комментарии
Загружаем комментарии...