2nd/10_Wiki/Topic_Programming/Coding/Backend_Outbox_Pattern.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
backend-outbox-pattern	Outbox — DB write + 메시지 발행 원자성	Coding	draft	B	conceptual	2026-05-09	2026-05-09	backend outbox messaging vibe-coding	language applicable_to TS / SQL Backend		outbox transactional outbox dual-write CDC event publisher

Outbox Pattern

"DB commit + Kafka publish" 둘 다 동시 = 불가능. DB 트랜잭션 안에서 events 테이블에 같이 insert → 별도 publisher 가 events 읽어 publish. 원자성 보장.

📖 핵심 개념

• Dual-write 문제: DB OK + 메시지 실패 → 메시지 없음 / DB 실패 + 메시지 OK → 잘못된 메시지.
• Outbox: 같은 트랜잭션 안 outbox 테이블 insert.
• Publisher: outbox 읽어 broker 로 보내고 sent 표시.
• CDC 변형: outbox 도 안 쓰고 Debezium 이 binlog/WAL 직접.

💻 코드 패턴

Outbox 테이블

CREATE TABLE outbox (
  id BIGSERIAL PRIMARY KEY,
  aggregate_type TEXT NOT NULL,
  aggregate_id TEXT NOT NULL,
  event_type TEXT NOT NULL,
  payload JSONB NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  sent_at TIMESTAMPTZ
);

CREATE INDEX outbox_unsent ON outbox(id) WHERE sent_at IS NULL;

Write (트랜잭션 안)

async function createOrder(input: CreateOrder) {
  return db.transaction(async (tx) => {
    const order = await tx.orders.insert(input);
    await tx.outbox.insert({
      aggregateType: 'order',
      aggregateId: order.id,
      eventType: 'OrderCreated',
      payload: { orderId: order.id, userId: input.userId, amount: input.amount },
    });
    return order;
  });
}

Publisher (poll loop)

async function publishLoop() {
  while (true) {
    const batch = await db.outbox.findUnsent({ limit: 100 });
    if (batch.length === 0) {
      await sleep(500);
      continue;
    }

    for (const e of batch) {
      try {
        await broker.publish(e.eventType, e.payload, {
          headers: { 'x-event-id': String(e.id), 'aggregate-id': e.aggregateId },
        });
        await db.outbox.markSent(e.id);
      } catch (err) {
        log.error('publish failed', err);
        // 재시도 — 다음 loop 에서 또 시도
      }
    }
  }
}

At-least-once 보장 + idempotency 헤더

// Consumer 측
on('OrderCreated', async (msg) => {
  const id = msg.headers['x-event-id'];
  if (await db.processed.exists(id)) return; // 이미 처리
  await handle(msg.payload);
  await db.processed.insert({ id, processedAt: now() });
});

CDC (Debezium) 변형

• DB binlog/WAL 을 Debezium 이 읽음.
• Outbox 테이블의 INSERT 만 필터.
• Kafka 로 자동 발행.
• 앱 코드는 outbox INSERT 만 — publisher 코드 불필요.

# Debezium connector
{
  "connector.class": "io.debezium.connector.postgresql.PostgresConnector",
  "transforms": "outbox",
  "transforms.outbox.type": "io.debezium.transforms.outbox.EventRouter",
  "transforms.outbox.table.field.event.id": "id",
  "transforms.outbox.table.field.event.key": "aggregate_id",
  "transforms.outbox.table.field.event.payload": "payload"
}

TX-side cleanup

// 발행된 이벤트 N일 후 삭제
DELETE FROM outbox WHERE sent_at < NOW() - INTERVAL '30 days';

Lock for parallel publishers

-- N 개 publisher 가 동시에 도는 경우
SELECT * FROM outbox
WHERE sent_at IS NULL
ORDER BY id
LIMIT 100
FOR UPDATE SKIP LOCKED;

🤔 의사결정 기준

상황	추천
Postgres + 이벤트 발행	Outbox + poll publisher
큰 처리량 + Kafka	Outbox + Debezium CDC
Strict ordering 필요	Outbox + partition key (aggregate_id)
여러 broker	Outbox + 여러 publisher
Email / Slack 알림	Outbox 패턴 그대로
Idempotency 강	Consumer 측 dedupe table

❌ 안티패턴

• Dual-write 직접: DB commit + publish 사이 crash → 한쪽 실패.
• Outbox publish 후 삭제: 한 번에 안 되면 stuck.
• Polling 대신 immediate publish (트랜잭션 후): crash 위험.
• Sent_at 기반 ID 정렬 X: skip 가능. id 정렬.
• Partitioning 없이 강 ordering: 불가능.
• Cleanup 안 함: 테이블 무한.
• Consumer 멱등성 없음: at-least-once 가 중복.

🤖 LLM 활용 힌트

• DB commit + 이벤트 발행 = outbox.
• Postgres SKIP LOCKED 로 병렬 publisher.
• Debezium 도입 시 publisher 코드 X.

🔗 관련 문서

• Backend_Saga_Patterns
• Backend_Event_Sourcing
• Backend_Webhook_Patterns