Transactional Outbox: событие как часть транзакции
Transactional Outbox: событие как часть транзакции
Outbox - паттерн, который атомарно фиксирует бизнес-изменение и намерение опубликовать событие: если транзакция в БД прошла, событие точно есть что отправить. Без него возникает dual-write проблема.
Дальше событие досылает отдельный процесс, и вот здесь атомарности уже нет: доставка из outbox остаётся at-least-once и требует повторов плюс идемпотентного подписчика. Разбор границы - в event-driven.
Dual-Write Problem
Типичная ошибка - писать в БД и в брокер отдельно:
// ОПАСНО: dual write
func (uc *CompleteLessonUseCase) Execute(ctx context.Context, cmd CompleteLesson) error {
// Шаг 1: пишем в БД
err := uc.repo.MarkCompleted(ctx, cmd.UserID, cmd.LessonID)
if err != nil {
return err
}
// Шаг 2: публикуем событие
err = uc.publisher.Publish(ctx, "lesson.completed", event)
if err != nil {
// БД обновлена, но событие не отправлено!
// Откатить БД? А если откат тоже упадёт?
return err
}
return nil
}
<?php
declare(strict_types=1);
// ОПАСНО: dual write
final class CompleteLessonUseCase
{
public function __construct(
private readonly ProgressRepository $repo,
private readonly EventPublisher $publisher,
) {}
public function execute(CompleteLesson $cmd): void
{
// Шаг 1: пишем в БД
$this->repo->markCompleted($cmd->userId, $cmd->lessonId);
// Шаг 2: публикуем событие
try {
$this->publisher->publish('lesson.completed', $cmd);
} catch (Throwable $e) {
// БД обновлена, но событие не отправлено!
// Откатить БД? А если откат тоже упадёт?
throw $e;
}
}
}
# ОПАСНО: dual write
class CompleteLessonUseCase:
def __init__(self, repo: ProgressRepository, publisher: EventPublisher) -> None:
self._repo = repo
self._publisher = publisher
def execute(self, cmd: CompleteLesson) -> None:
# Шаг 1: пишем в БД
self._repo.mark_completed(cmd.user_id, cmd.lesson_id)
# Шаг 2: публикуем событие
try:
self._publisher.publish("lesson.completed", event)
except Exception:
# БД обновлена, но событие не отправлено!
# Откатить БД? А если откат тоже упадёт?
raise
Что может пойти не так:
Сценарий 1: БД ✓, Publish ✗ → данные есть, событие потеряно
Сценарий 2: БД ✓, Publish ✓, но ack от брокера не дошёл → дубль
Сценарий 3: Процесс упал между шагами → несогласованность
Никакая комбинация try/catch не решит эту проблему.
Решение: Transactional Outbox
Событие записывается в outbox-таблицу в той же транзакции, что и бизнес-данные. Отдельный процесс (publisher) потом отправляет его в брокер.
┌─────────────────────────────────────────┐
│ Одна транзакция PostgreSQL │
│ │
│ UPDATE progress SET completed = true │
│ INSERT INTO outbox (event_id, ...) │
│ │
│ COMMIT → обе операции или ни одной │
└─────────────────────────────────────────┘
│
▼
┌──────────────────┐ ┌──────────────┐
│ Outbox Publisher │ ──→ │ RabbitMQ │
│ (отдельный │ │ │
│ процесс/горутина)│ └──────────────┘
└──────────────────┘
Outbox-таблица
CREATE TABLE outbox (
id BIGSERIAL PRIMARY KEY,
event_id TEXT NOT NULL UNIQUE,
event_type TEXT NOT NULL,
payload JSONB NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
sent_at TIMESTAMPTZ, -- NULL = не отправлено
attempts INT NOT NULL DEFAULT 0,
next_attempt_at TIMESTAMPTZ NOT NULL DEFAULT now(), -- когда пробовать снова
last_error TEXT
);
CREATE INDEX idx_outbox_unsent ON outbox(created_at) WHERE sent_at IS NULL;
Запись в outbox из use case
type CompleteLessonUseCase struct {
db *gorm.DB
}
func (uc *CompleteLessonUseCase) Execute(ctx context.Context, cmd CompleteLesson) error {
return uc.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
// Бизнес-операция
if err := tx.Model(&Progress{}).
Where("user_id = ? AND lesson_id = ?", cmd.UserID, cmd.LessonID).
Update("completed", true).Error; err != nil {
return fmt.Errorf("mark completed: %w", err)
}
// Событие в outbox - в той же транзакции
event := OutboxEvent{
EventID: uuid.New().String(),
EventType: "lesson.completed",
Payload: map[string]any{
"user_id": cmd.UserID,
"lesson_id": cmd.LessonID,
"track_id": cmd.TrackID,
},
}
payload, _ := json.Marshal(event.Payload)
if err := tx.Exec(
`INSERT INTO outbox (event_id, event_type, payload) VALUES (?, ?, ?)`,
event.EventID, event.EventType, payload,
).Error; err != nil {
return fmt.Errorf("outbox insert: %w", err)
}
return nil
})
}
<?php
declare(strict_types=1);
use Doctrine\DBAL\Connection;
use Symfony\Component\Uid\Uuid;
final class CompleteLessonUseCase
{
public function __construct(
private readonly Connection $db,
) {}
public function execute(CompleteLesson $cmd): void
{
$this->db->transactional(function (Connection $tx) use ($cmd): void {
// Бизнес-операция
$tx->executeStatement(
'UPDATE progress SET completed = TRUE
WHERE user_id = :uid AND lesson_id = :lid',
['uid' => $cmd->userId, 'lid' => $cmd->lessonId],
);
// Событие в outbox - в той же транзакции
$payload = json_encode([
'user_id' => $cmd->userId,
'lesson_id' => $cmd->lessonId,
'track_id' => $cmd->trackId,
], JSON_THROW_ON_ERROR);
$tx->executeStatement(
'INSERT INTO outbox (event_id, event_type, payload)
VALUES (:id, :type, :payload)',
[
'id' => Uuid::v4()->toRfc4122(),
'type' => 'lesson.completed',
'payload' => $payload,
],
);
});
}
}
import uuid
from psycopg.types.json import Jsonb
from psycopg_pool import ConnectionPool
class CompleteLessonUseCase:
def __init__(self, pool: ConnectionPool) -> None:
self._pool = pool
def execute(self, cmd: CompleteLesson) -> None:
# Вместо gorm.Transaction - with-блок psycopg: вышли без исключения -
# commit, исключение - rollback обеих записей.
with self._pool.connection() as conn, conn.transaction():
# Бизнес-операция
conn.execute(
"UPDATE progress SET completed = true WHERE user_id = %s AND lesson_id = %s",
(cmd.user_id, cmd.lesson_id),
)
# Событие в outbox - в той же транзакции
event = OutboxEvent(
event_id=str(uuid.uuid4()),
event_type="lesson.completed",
payload={
"user_id": cmd.user_id,
"lesson_id": cmd.lesson_id,
"track_id": cmd.track_id,
},
)
# Jsonb вместо json.dumps: psycopg сам сериализует dict в jsonb-колонку
conn.execute(
"INSERT INTO outbox (event_id, event_type, payload) VALUES (%s, %s, %s)",
(event.event_id, event.event_type, Jsonb(event.payload)),
)
Outbox Publisher: Polling
Самый простой способ - polling: периодически читаем неотправленные события:
type OutboxPublisher struct {
db *sql.DB
publisher EventPublisher
interval time.Duration
}
func (p *OutboxPublisher) Run(ctx context.Context) error {
ticker := time.NewTicker(p.interval)
defer ticker.Stop()
for {
select {
case <-ctx.Done():
return nil
case <-ticker.C:
if err := p.processBatch(ctx); err != nil {
log.Printf("outbox batch error: %v", err)
}
}
}
}
type outboxEvent struct {
id int64
eventID string
eventType string
payload []byte
}
// outboxMessage - то, что уходит в брокер: конверт с event_id и готовым
// JSON из outbox. json.RawMessage сериализуется как есть; обычный []byte
// json.Marshal превратил бы в base64-строку.
type outboxMessage struct {
EventID string `json:"event_id"`
Type string `json:"type"`
Payload json.RawMessage `json:"payload"`
}
// MessageID - тот же event_id в свойстве MessageId (см. урок про producer):
// повторная отправка события уйдёт с тем же ID, и inbox подписчика её отбросит.
func (m outboxMessage) MessageID() string { return m.EventID }
func (p *OutboxPublisher) processBatch(ctx context.Context) error {
// Транзакция на весь батч: FOR UPDATE SKIP LOCKED держит строки
// занятыми только до её конца - см. врезку ниже.
tx, err := p.db.BeginTx(ctx, nil)
if err != nil {
return fmt.Errorf("begin tx: %w", err)
}
defer tx.Rollback()
events, err := claimBatch(ctx, tx)
if err != nil {
return err
}
for _, e := range events {
// p.publisher должен ждать publisher confirm (урок про producer):
// иначе sent_at появится у сообщения, которое брокер не принял.
msg := outboxMessage{EventID: e.eventID, Type: e.eventType, Payload: e.payload}
if err := p.publisher.Publish(ctx, e.eventType, msg); err != nil {
// Запоминаем ошибку и откладываем следующую попытку с растущей
// паузой (до 5 минут). Событие не выключается: оно уйдёт, когда
// брокер оживёт, а большое attempts - повод для алерта.
if _, uErr := tx.ExecContext(ctx,
`UPDATE outbox
SET attempts = attempts + 1,
last_error = $1,
next_attempt_at = now() + least(interval '5 seconds' * power(2, attempts), interval '5 minutes')
WHERE id = $2`,
err.Error(), e.id,
); uErr != nil {
return fmt.Errorf("bump attempts for %s: %w", e.eventID, uErr)
}
continue
}
if _, err := tx.ExecContext(ctx,
`UPDATE outbox SET sent_at = now() WHERE id = $1`, e.id,
); err != nil {
return fmt.Errorf("mark sent %s: %w", e.eventID, err)
}
}
return tx.Commit()
}
// claimBatch вычитывает пачку целиком и закрывает rows - только после этого
// можно делать другие запросы. Почему это обязательно - во врезке ниже.
func claimBatch(ctx context.Context, tx *sql.Tx) ([]outboxEvent, error) {
rows, err := tx.QueryContext(ctx,
`SELECT id, event_id, event_type, payload
FROM outbox
WHERE sent_at IS NULL AND next_attempt_at <= now()
ORDER BY created_at
LIMIT 100
FOR UPDATE SKIP LOCKED`, // конкурентные publisher'ы не мешают
)
if err != nil {
return nil, fmt.Errorf("query outbox: %w", err)
}
defer rows.Close()
var events []outboxEvent
for rows.Next() {
var e outboxEvent
if err := rows.Scan(&e.id, &e.eventID, &e.eventType, &e.payload); err != nil {
return nil, fmt.Errorf("scan row: %w", err)
}
events = append(events, e)
}
return events, rows.Err()
}
<?php
declare(strict_types=1);
use Doctrine\DBAL\Connection;
use Psr\Log\LoggerInterface;
// Конверт для брокера: event_id + готовый payload из outbox.
// Свойство eventId publisher из урока про producer кладёт в message_id.
final readonly class OutboxMessage implements JsonSerializable
{
public function __construct(
public string $eventId,
public string $type,
public mixed $payload,
) {}
public function jsonSerialize(): array
{
return ['event_id' => $this->eventId, 'type' => $this->type, 'payload' => $this->payload];
}
}
final class OutboxPublisher
{
public function __construct(
private readonly Connection $db,
private readonly EventPublisher $publisher,
private readonly LoggerInterface $logger,
private readonly int $intervalSeconds,
) {}
public function run(): void
{
while (true) {
try {
$this->processBatch();
} catch (Throwable $e) {
$this->logger->error('outbox batch error: {err}', ['err' => $e->getMessage()]);
}
sleep($this->intervalSeconds);
}
}
private function processBatch(): void
{
// Транзакция на весь батч: FOR UPDATE SKIP LOCKED держит строки
// занятыми только до её конца - см. врезку ниже.
$this->db->transactional(function (Connection $tx): void {
// fetchAllAssociative вычитывает пачку целиком - других запросов
// при открытом курсоре не будет.
$rows = $tx->fetchAllAssociative(
'SELECT id, event_id, event_type, payload
FROM outbox
WHERE sent_at IS NULL AND next_attempt_at <= NOW()
ORDER BY created_at
LIMIT 100
FOR UPDATE SKIP LOCKED' // конкурентные publisher'ы не мешают
);
foreach ($rows as $row) {
try {
$this->publisher->publish($row['event_type'], new OutboxMessage(
eventId: $row['event_id'],
type: $row['event_type'],
payload: json_decode($row['payload'], flags: JSON_THROW_ON_ERROR),
));
// Помечаем как отправленное
$tx->executeStatement(
'UPDATE outbox SET sent_at = NOW() WHERE id = :id',
['id' => $row['id']],
);
} catch (Throwable $e) {
// Запоминаем ошибку и откладываем попытку с растущей паузой.
$tx->executeStatement(
"UPDATE outbox
SET attempts = attempts + 1,
last_error = :err,
next_attempt_at = NOW() + LEAST(INTERVAL '5 seconds' * POWER(2, attempts), INTERVAL '5 minutes')
WHERE id = :id",
['err' => $e->getMessage(), 'id' => $row['id']],
);
}
}
});
}
}
В Symfony Messenger тот же эффект даёт doctrine транспорт + messenger:consume - таблица messenger_messages играет роль outbox, а worker сам делает FOR UPDATE SKIP LOCKED.
import logging
import threading
from dataclasses import dataclass
from typing import Any
import psycopg
from psycopg_pool import ConnectionPool
log = logging.getLogger(__name__)
class OutboxPublisher:
def __init__(self, pool: ConnectionPool, publisher: EventPublisher, interval: float) -> None:
self._pool = pool
self._publisher = publisher
self._interval = interval
# threading.Event вместо ctx: wait(interval) - это и тикер, и отмена
def run(self, stop: threading.Event) -> None:
while not stop.wait(self._interval):
try:
self._process_batch()
except Exception as e:
log.error("outbox batch error: %s", e)
def _process_batch(self) -> None:
# Транзакция на весь батч: FOR UPDATE SKIP LOCKED держит строки
# занятыми только до её конца - см. врезку ниже.
with self._pool.connection() as conn, conn.transaction():
events = claim_batch(conn)
for e in events:
try:
# Публикуем конверт с event_id (см. to_dict ниже), а не голый payload
self._publisher.publish(e.event_type, e)
except Exception as err:
# Запоминаем ошибку и откладываем попытку с растущей паузой.
# Если упадёт сам UPDATE - исключение откатит транзакцию,
# как return в Go.
conn.execute(
"""UPDATE outbox
SET attempts = attempts + 1,
last_error = %s,
next_attempt_at = now() + least(interval '5 seconds' * power(2, attempts), interval '5 minutes')
WHERE id = %s""",
(str(err), e.outbox_id),
)
continue
conn.execute("UPDATE outbox SET sent_at = now() WHERE id = %s", (e.outbox_id,))
@dataclass(frozen=True, slots=True)
class OutboxEventRow:
outbox_id: int
event_id: str
event_type: str
payload: dict[str, Any] # jsonb psycopg отдаёт уже разобранным
# Конверт для брокера: publisher из урока про producer вызывает to_dict(),
# а event_id берёт в message_id
def to_dict(self) -> dict[str, Any]:
return {"event_id": self.event_id, "type": self.event_type, "payload": self.payload}
def claim_batch(conn: psycopg.Connection) -> list[OutboxEventRow]:
"""Вычитывает пачку целиком (fetchall) - только после этого
можно делать другие запросы. Почему это обязательно - во врезке ниже.
"""
rows = conn.execute(
"""SELECT id, event_id, event_type, payload
FROM outbox
WHERE sent_at IS NULL AND next_attempt_at <= now()
ORDER BY created_at
LIMIT 100
FOR UPDATE SKIP LOCKED""", # конкурентные publisher'ы не мешают
).fetchall()
return [OutboxEventRow(*row) for row in rows]
⚠️ FOR UPDATE SKIP LOCKED - и три условия, без которых он бесполезен
Конструкция позволяет нескольким publisher'ам работать параллельно: каждый берёт свою пачку, не блокируя остальных. Но сама по себе строчка в запросе ничего не гарантирует - нужны три вещи.
1. Запрос обязан идти в транзакции.
db.QueryContextвне транзакции выполняется в неявной, которая закрывается по завершении запроса - блокировка снимается сразу, и второй publisher видит те же строки.FOR UPDATEв таком запросе декоративен.2. Транзакция обязана жить до отметки об отправке. Закоммить её сразу после выборки - тот же результат: блокировка защищала ровно на время чтения.
3. Пачку нужно вычитать до конца и закрыть
rowsперед другими запросами. Пока набор строк открыт, он держит соединение;UPDATEчерезdbпопросит второе - и на пуле из одного соединения процесс встанет навсегда, без ошибки и паники. На машине разработчика с пулом по умолчанию это работает, поэтому такой код спокойно доезжает до прода и ложится там под нагрузкой.Проверяется всё это прогоном:
examples/reliability/outboxперебирает сбои по каждой операции и запускает второй поллер, пока транзакция первого открыта. Сломанные версии лежат рядом - в том числе та, где тест проверяет не ошибку, а зависание.
Polling vs CDC (Change Data Capture)
Подход Как работает Плюсы / Минусы
──────── ────────────────────── ──────────────────────────
Polling SELECT WHERE sent_at IS NULL + Просто реализовать
каждые N секунд - Задержка до interval
- Нагрузка на БД
CDC Debezium читает WAL + Малая задержка (не нулевая)
PostgreSQL + Нет нагрузки на таблицу
- Сложный инфра-сетап
- Нужен Kafka Connect
Polling - правильный выбор для старта. Переходи на CDC (Debezium), когда задержка polling'а станет проблемой или нагрузка на outbox-таблицу вырастет. Как это выглядит в деле - compose с Kafka Connect, конфиг коннектора и мониторинг replication slot - в уроке Transactional Outbox с Kafka.
Очистка outbox
Отправленные события нужно удалять, иначе таблица вырастет бесконечно:
// Удаляем отправленные события старше 7 дней
func (p *OutboxPublisher) Cleanup(ctx context.Context) error {
result, err := p.db.ExecContext(ctx,
`DELETE FROM outbox WHERE sent_at IS NOT NULL AND sent_at < now() - interval '7 days'`,
)
if err != nil {
return err
}
rows, _ := result.RowsAffected()
if rows > 0 {
log.Printf("cleaned up %d outbox events", rows)
}
return nil
}
<?php
declare(strict_types=1);
use Doctrine\DBAL\Connection;
use Psr\Log\LoggerInterface;
final class OutboxCleanup
{
public function __construct(
private readonly Connection $db,
private readonly LoggerInterface $logger,
) {}
// Удаляем отправленные события старше 7 дней
public function cleanup(): void
{
$deleted = $this->db->executeStatement(
"DELETE FROM outbox
WHERE sent_at IS NOT NULL
AND sent_at < NOW() - INTERVAL '7 days'"
);
if ($deleted > 0) {
$this->logger->info('cleaned up {n} outbox events', ['n' => $deleted]);
}
}
}
class OutboxPublisher: # продолжение класса из блока про polling
# Удаляем отправленные события старше 7 дней
def cleanup(self) -> None:
with self._pool.connection() as conn:
cur = conn.execute(
"DELETE FROM outbox WHERE sent_at IS NOT NULL AND sent_at < now() - interval '7 days'"
)
if cur.rowcount > 0:
log.info("cleaned up %d outbox events", cur.rowcount)
⚠️ Publisher может отправить дубль
Outbox publisher может отправить одно сообщение дважды (упал после publish, но до UPDATE sent_at). Поэтому consumer на другой стороне обязан быть идемпотентным (inbox-таблица из прошлого урока). Для этого в сообщении и едет
event_id: по нему inbox отличает повтор от нового события.
Полная картина
Use Case Outbox Publisher RabbitMQ
───────── ──────────────── ────────
BEGIN TX
UPDATE progress
INSERT INTO outbox
COMMIT
SELECT unsent
Publish(event) ──────────→ Exchange
UPDATE sent_at │
▼
Consumer (с inbox)
Гарантии:
- Если транзакция откатилась - событие не попадёт в outbox
- Если publisher упал или брокер недоступен - событие останется в outbox и будет отправлено позже. Лимит попыток не выключает событие молча: следующую попытку откладывает
next_attempt_at(растущая пауза), а события с большимattempts- повод для алерта, а не для тихого фильтраattempts < 10 - Если consumer получил дубль - inbox отфильтрует
Мини-задание
- Создай таблицу outbox с индексом на неотправленные события
- Перепиши use case: бизнес-операция + INSERT INTO outbox в одной транзакции
- Напиши Outbox Publisher с polling каждые 5 секунд
- Проверь: останови publisher, выполни use case 3 раза, запусти publisher - все 3 события должны уйти в RabbitMQ