아웃박스 패턴(Transactional Outbox) — 이중 쓰기 문제와 신뢰성 있는 이벤트 발행

DB에 데이터를 저장하면서 동시에 메시지 브로커로 이벤트를 보내려는 순간, 두 시스템 중 하나가 실패하면 데이터는 어긋난다. 아웃박스 패턴은 이벤트를 같은 트랜잭션 안의 테이블에 함께 커밋해서 이 "이중 쓰기" 구멍을 원천 봉쇄한다.

핵심은 하나다. DB 커밋과 이벤트 발행을 두 번의 원격 호출로 나누지 말고, 로컬 트랜잭션 하나로 묶은 뒤 발행은 나중에 별도 프로세스가 책임진다. 이 글은 dual write 문제의 정확한 원인부터 outbox 테이블 스키마, 릴레이/CDC 발행 방식, at-least-once 하에서의 멱등 소비까지 실전 코드로 정리한다.

아웃박스 패턴은 어떻게 이 구멍을 막나

핵심 아이디어는 단순하다. 이벤트를 브로커로 바로 보내지 말고, 비즈니스 데이터와 같은 DB, 같은 트랜잭션 안의 outbox 테이블에 한 줄로 함께 INSERT 한다. 그러면 "주문 저장"과 "이벤트 기록"은 하나의 로컬 트랜잭션이므로 둘 다 커밋되거나 둘 다 롤백된다. 원자성 문제가 사라진다.

발행은 그 다음이다. 별도의 릴레이(relay) 프로세스가 outbox 테이블을 읽어 브로커로 보내고, 성공한 행을 처리 완료로 표시한다. 발행이 실패하면? 행이 그대로 남아 있으니 다음 주기에 다시 시도한다. 즉 커밋된 이벤트는 결국 반드시 한 번 이상 나간다. 이게 at-least-once의 정체다.

흐름을 정리하면 이렇다.

1. 트랜잭션 시작 → 비즈니스 테이블 변경 + outbox INSERT → 커밋 (원자적)
2. 릴레이가 미발행 outbox 행을 조회
3. 브로커로 발행 → 성공 시 행을 삭제하거나 published_at 표시
4. 소비자는 이벤트의 고유 ID로 중복을 걸러내며 멱등하게 처리

아웃박스 테이블 스키마는 어떻게 잡나

스키마의 목표는 세 가지다. (1) 이벤트를 고유하게 식별할 id, (2) 소비자가 라우팅할 aggregate_type/topic, (3) 순서 보장과 재시도를 위한 시간·상태 컬럼. 아래는 PostgreSQL 기준 실전 스키마다.

-- 아웃박스 테이블 (PostgreSQL)
CREATE TABLE outbox (
    id            UUID        PRIMARY KEY,            -- 이벤트 고유 ID(멱등 키로 그대로 사용)
    aggregate_type VARCHAR(64) NOT NULL,             -- 예: 'order', 'payment'
    aggregate_id  VARCHAR(64) NOT NULL,              -- 예: 주문번호 (같은 키끼리 순서 보장용)
    event_type    VARCHAR(64) NOT NULL,             -- 예: 'OrderPlaced'
    payload       JSONB       NOT NULL,              -- 이벤트 본문
    created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
    published_at  TIMESTAMPTZ                          -- NULL이면 아직 미발행
);

-- 미발행 행만 빠르게 스캔하기 위한 부분 인덱스 (핵심)
CREATE INDEX idx_outbox_unpublished
    ON outbox (created_at)
    WHERE published_at IS NULL;

여기서 문서에 잘 안 나오는 포인트 하나. WHERE published_at IS NULL 부분 인덱스가 생각보다 중요하다. 발행된 행이 수백만 건 쌓여도 릴레이 쿼리는 미발행 행만 보므로 인덱스가 작게 유지된다. 이걸 안 하면 테이블이 커질수록 폴링 쿼리가 느려진다. 실제로 이 인덱스 하나 빠뜨려서 릴레이 지연이 계단식으로 늘어나는 걸 겪은 적이 있다.

발행은 폴링 릴레이로 하나, CDC로 하나

outbox 행을 브로커로 옮기는 방법은 크게 둘이다. 애플리케이션이 주기적으로 SELECT 하는 폴링 릴레이와, DB의 트랜잭션 로그(WAL)를 읽는 CDC(Change Data Capture). 둘 다 결과는 같지만 운영 성격이 다르다.

폴링은 코드로 완결되고 인프라 추가가 없다. 대신 폴링 간격만큼 지연이 생기고, 그 간격을 줄이면 DB 부하가 는다. CDC(대표적으로 Debezium)는 WAL을 tail 하므로 지연이 짧고 DB에 폴링 쿼리를 안 날리지만, 커넥터와 Kafka Connect 같은 운영 요소가 늘어난다. 팀에 Kafka Connect 운영 경험이 없다면 나는 폴링부터 시작하라고 한다. 트래픽이 정말 커지면 그때 CDC로 옮겨도 늦지 않다.

실전 코드 1 — 주문 저장과 이벤트를 한 트랜잭션에

가장 중요한 규칙: 비즈니스 INSERT와 outbox INSERT는 반드시 같은 트랜잭션이어야 한다. 커넥션을 따로 열거나 오토커밋이 켜져 있으면 원자성이 깨진다. 아래는 Node.js(pg) 예시다.

// 주문 생성 서비스 — 비즈니스 쓰기와 outbox 쓰기를 하나의 트랜잭션으로 묶는다
import { randomUUID } from 'crypto';

async function placeOrder(pool, order) {
  const client = await pool.connect();
  try {
    await client.query('BEGIN');

    // 1) 비즈니스 데이터
    await client.query(
      'INSERT INTO orders (id, user_id, amount, status) VALUES ($1,$2,$3,$4)',
      [order.id, order.userId, order.amount, 'PLACED']
    );

    // 2) 같은 트랜잭션 안에서 outbox에 이벤트 기록
    await client.query(
      `INSERT INTO outbox (id, aggregate_type, aggregate_id, event_type, payload)
       VALUES ($1,$2,$3,$4,$5)`,
      [
        randomUUID(),          // 이벤트 고유 ID = 소비자 멱등 키
        'order',
        order.id,
        'OrderPlaced',
        JSON.stringify({ orderId: order.id, amount: order.amount }),
      ]
    );

    await client.query('COMMIT');   // 둘 다 커밋 or 둘 다 롤백
  } catch (e) {
    await client.query('ROLLBACK');
    throw e;
  } finally {
    client.release();
  }
}

이 시점에서 이벤트는 아직 Kafka로 안 나갔다. 하지만 커밋된 이상 outbox에 안전하게 박혀 있으니, 발행은 릴레이가 책임진다. 애플리케이션 요청 응답은 여기서 끝내도 된다.

실전 코드 2 — 릴레이가 안전하게 집어가는 법

릴레이 인스턴스를 여러 개 띄우면 같은 행을 두 릴레이가 동시에 집어갈 수 있다. 이걸 막는 표준 트릭이 FOR UPDATE SKIP LOCKED다. 잠긴 행은 건너뛰고 자기 몫만 잠가서 가져오므로, 워커를 수평 확장해도 중복 처리가 줄어든다.

-- 릴레이: 미발행 행을 배치로 잠그고 가져오기 (여러 워커 안전)
BEGIN;

SELECT id, aggregate_id, event_type, payload
FROM outbox
WHERE published_at IS NULL
ORDER BY created_at          -- 순서 보장
FOR UPDATE SKIP LOCKED       -- 다른 워커가 잡은 행은 건너뜀
LIMIT 100;

-- (애플리케이션이 이 배치를 브로커로 발행)
-- 발행 성공한 id들에 대해:
UPDATE outbox SET published_at = now() WHERE id = ANY($1);

COMMIT;

-- 소비자 측 멱등 처리 (PostgreSQL)
CREATE TABLE processed_events (
    event_id   UUID PRIMARY KEY,
    handled_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- 컨슈머 로직
BEGIN;
  -- 이미 처리한 이벤트면 아무 것도 안 함 (ON CONFLICT로 중복 흡수)
  INSERT INTO processed_events (event_id)
  VALUES ($1)
  ON CONFLICT (event_id) DO NOTHING;

  -- 방금 INSERT가 실제로 적용됐을 때만(=처음 보는 이벤트) 비즈니스 처리
  -- 애플리케이션에서 affected rows == 0 이면 커밋만 하고 종료
  UPDATE inventory SET qty = qty - $2 WHERE sku = $3;
COMMIT;