2901 words
15 minutes
[Kafka] 발행 기록 테이블은 Outbox가 아니다 — 트랜잭션 없는 DB에서 Outbox 만들기

01. Overview#

  • 배치(Airflow)가 분석 DB(ClickHouse)의 상태를 보고 신규 주문·가입·장바구니 같은 이벤트를 Kafka로 발행하는 파이프라인
  • 중복 발행을 막으려고 발행 기록 테이블(sent_log)을 두고 있었음
  • 출발점은 “이 발행 기록 테이블을 Outbox 패턴이라고 봐도 되나?”라는 질문
  • 결론 — 아니다. 발행 기록은 “보낸 것”을 적는 테이블이고, Outbox는 “보낼 것”을 적는 테이블
  • 이 차이 때문에 유실과 ‘진짜’ 중복이 동시에 가능했음 → 트랜잭션이 없는 DB 위에서 Outbox로 다시 짬

02. 핵심 문제#

2-1. 원래 구조#

gold 테이블 ──LEFT JOIN──► sent_log (anti-join: 기록 없는 건 = 미발행)
│
▼
메시지 생성 (지금 시점의 값으로)
│
├──► Kafka produce
└──► sent_log INSERT ← 순서는 파이프라인마다 달랐음
  • “미발행”은 테이블에 저장된 상태가 아니라 매번 gold − sent_log로 계산됨
  • 메시지는 발행하는 순간의 값으로 새로 만들어짐

2-2. Dual Write — 순서를 어떻게 잡아도 한쪽이 샘#

DB INSERT와 Kafka produce는 하나의 트랜잭션으로 묶을 수 없음. 그래서 둘 중 하나가 먼저 일어나고, 그 사이에 프로세스가 죽을 수 있음.

순서사이에서 죽으면보장
기록 → 발행 (실패 시 롤백)기록만 남고 발행 안 됨. 롤백 코드는 except 블록이라 pod kill·OOM에서는 실행 안 됨 → 영구 유실at-most-once
기록 → 발행 → 일부 실패 → 전체 롤백이미 전달된 건까지 기록이 지워짐 → 다음 실행에 재발행 → 중복유실 + 중복 둘 다
발행 → 기록발행됐는데 기록이 없음 → 다음 실행에 재발행 → 중복at-least-once
  • 롤백으로 원자성을 흉내 내는 건 정상 경로의 예외만 막음. 프로세스가 죽는 경우는 못 막음
  • 현실적인 선택지는 “발행 → 기록”(at-least-once) + consumer 쪽 중복 제거

2-3. 중복이 ‘진짜 중복’이 되는 이유#

at-least-once라도 consumer가 중복을 접을 수 있으면 괜찮음. 이번 consumer는 ReplacingMergeTree의 정렬 키로 중복을 접고 있었음.

ENGINE = ReplacingMergeTree(loaded_at)
ORDER BY (site, log_type, user_id, event_timestamp, ma_id)

그런데 재발행 메시지가 처음과 다른 값을 들고 있었음.

필드재발행 시이유
event_timestamp (출고·배송완료)달라짐원천이 정확한 시점을 안 줘서 발행 시각 now() 로 대체
ma_id, session_id (가입)달라짐발행할 때마다 uuid4()
ma_id (주문)달라질 수 있음Redis TTL이 지나면 새로 발급
  • 키가 달라지면 consumer 입장에선 다른 이벤트 → 중복 제거가 무력화됨
  • 즉 문제의 본질은 발행 순서가 아니라 **“메시지를 매번 다시 만든다”**는 점

03. 개념 — Outbox 패턴#

3-1. 교과서적인 형태#

[App 트랜잭션]
BEGIN
UPDATE orders ... ← 업무 데이터
INSERT INTO outbox (payload) ← 보낼 이벤트
COMMIT
│
▼
[Relay] outbox의 미발행 행 → Kafka produce → 발행 완료 표시
(polling publisher 또는 CDC/Debezium log tailing)
  • 핵심 보장 두 가지
    • 원자성 : 업무 데이터가 커밋되면 이벤트도 반드시 남음. 롤백되면 이벤트도 없음
    • at-least-once : relay가 발행 후 표시 전에 죽으면 다시 보냄 → consumer는 멱등해야 함
  • Outbox도 정확히 한 번(exactly-once)은 아님. consumer 멱등성은 어떤 구조든 필요

3-2. 발행 기록 vs Outbox#

발행 기록 (sent log)Outbox
테이블에 적는 것보낸 것보낼 것 (+ 보냈는지 상태)
미발행 목록매번 계산 (원천 − 기록)저장된 상태 (status = pending)
메시지 내용발행할 때마다 다시 만듦적재 시점에 고정
재발행 내용처음과 다를 수 있음바이트까지 동일
발행 실패 시기록 순서에 따라 유실 또는 중복pending으로 남아 다음에 재시도
  • 결정적인 차이는 payload 고정. 재발행분이 동일해야 consumer 중복 제거가 동작함

04. 트랜잭션 없는 DB에서 Outbox 만들기#

ClickHouse에는 다중 문장 트랜잭션이 없음. 업무 데이터 변경과 outbox INSERT를 원자적으로 묶을 수 없음.

4-1. 원자성이 꼭 필요한가#

  • 이 파이프라인의 이벤트는 gold 상태에서 결정적으로 다시 만들 수 있음 (상태 → 이벤트 파생)
  • 그러면 원자성 대신 멱등한 enqueue로 충분함
    • gold를 다시 적재해도, outbox에 이미 있는 키는 다시 만들지 않음
    • enqueue가 실패하면 다음 실행에서 같은 키를 다시 enqueue
  • “이벤트가 상태에서 파생되는가?” 가 원자성 필요 여부를 가름. 파생된다면 원자성은 필요 없음

4-2. 테이블 — version으로 상태 머신#

CREATE TABLE event_outbox
(
site Int64,
event_class LowCardinality(String),
event_type LowCardinality(String),
record_id String,
topic LowCardinality(String),
msg_key String,
payload String, -- 완성된 JSON. enqueue 시점에 고정
created_at DateTime DEFAULT now(),
version UInt64 DEFAULT 0, -- 0 = pending, 그 외 = 발행 시각(epoch ms)
sent_at Nullable(DateTime)
DEFAULT if(version = 0, NULL, toDateTime(intDiv(version, 1000)))
)
ENGINE = ReplacingMergeTree(version)
ORDER BY (site, event_type, record_id);
  • UPDATE 대신 같은 키로 더 큰 version 행을 INSERT → FINAL로 읽으면 최신 상태
  • pending의 version을 0으로 고정한 이유: 이미 발행된 키에 누가 다시 enqueue해도(version 0) 발행 완료 행(version > 0)을 덮어쓰지 못함
  • sent_at은 클라이언트가 보내지 않고 DEFAULT로 version에서 계산
    • naive datetime을 Arrow로 넣으면 서버가 UTC epoch로 해석해 9시간 어긋남
    • epoch ms 정수(version)는 시간대 영향이 없음

4-3. enqueue / publish#

def enqueue(ch, messages):
rows = [
{**ids, "payload": json.dumps(msg, ensure_ascii=False, default=str), "version": 0}
for ids, msg in messages
]
ch.insert(OUTBOX, rows)
def publish_pending(ch, kafka, event_class, event_type=None):
pending = ch.query(f"""
SELECT * FROM {OUTBOX} FINAL
WHERE event_class = '{event_class}' AND version = 0 ...
ORDER BY created_at, record_id
""")
for chunk in chunks(pending, 50_000):
kafka.produce_batch(chunk.topic, [json.loads(p) for p in chunk.payload],
keys=chunk.msg_key) # 브로커 ack까지 확인
ch.insert(OUTBOX, chunk.with_version(now_ms())) # 발행 완료 표시
  • 발행 후 표시 전에 죽으면 → 다음 실행이 같은 payload를 다시 보냄 → consumer 키가 같아 접힘
  • now()·uuid4()도 enqueue 시점에 한 번만 찍혀 payload에 갇힘
    • “정확한 시점이 없어 발행 시각을 쓴다”는 제약은 그대로 두면서, 재발행만 안전해짐
  • candidate 쿼리의 anti-join 대상은 outbox 자체(상태 무관)
  • 신규 건이 없어도 publish는 매번 실행 → 이전 실행에서 남은 pending을 비움
  • 순서가 중요한 이벤트(구매 → 취소 → 출고 → 배송완료)는 유형별로 enqueue → publish를 차례로 실행해 기존 순서를 유지
  • 출고 이벤트의 “구매가 먼저 발행됐어야 함” 조건은 p.version > 0으로 표현

4-4. 전환#

-- 기존 기록을 '발행 완료' 상태로 옮겨 과거 건이 재발행되지 않게
INSERT INTO event_outbox (site, event_class, event_type, record_id, created_at, version)
SELECT site, event_class, event_type, record_id, sent_at,
greatest(toUInt64(toUnixTimestamp(sent_at)) * 1000, 1) -- 0(pending)이 되지 않게
FROM sent_log FINAL;
  • 키·version이 같아 여러 번 실행해도 결과가 같음 → 배포 직전에 한 번, 직후에 한 번 더 실행해 그 사이에 쌓인 기록까지 반영
  • 이관된 행은 payload가 비어 있음. 이 행이 pending으로 읽히면 json.loads('')에서 바로 실패하게 둠 (조용히 넘어가지 않게)

05. 테이블 이름을 바꾸기 전에 — downstream 확인#

  • 코드 검색만으로는 부족. 다른 repo·다른 팀 잡이 같은 테이블을 읽을 수 있음
  • ClickHouse는 system.query_log의 tables 컬럼으로 실제로 읽는 쪽을 볼 수 있음
SELECT normalized_query_hash, query_kind, count(), max(event_time),
any(http_user_agent), any(substring(query, 1, 200))
FROM system.query_log
WHERE type = 'QueryFinish' AND has(tables, 'db.sent_log')
GROUP BY normalized_query_hash, query_kind
ORDER BY count() DESC;
  • user_agent가 같으면(같은 클라이언트 라이브러리) reader가 하나로 묶여 보임 → normalized_query_hash로 쿼리 패턴별로 나눠야 구분됨
  • query_log 보존 기간 밖에서 가끔 도는 수동 잡은 안 보임 → 스케줄러 쪽 정의도 같이 확인
  • INSERT에 걸린 MV는 query_log에 SELECT로 안 잡힘 → system.tables에서 create_table_query로 따로 확인

06. 남는 한계#

한계왜 괜찮은가 / 언제 손볼까
consumer 중복 제거가 merge 시점에 일어남읽을 때 FINAL 필요. Outbox가 해결하는 문제는 아님
consumer 정렬 키에 이벤트 ID가 없음user_id·ma_id가 비면 서로 다른 이벤트가 접힐 수 있음. 근본 해결은 consumer 테이블 키에 이벤트 ID 추가(테이블 재구축)
relay가 동시에 둘 돌면 같은 건을 두 번 보냄payload가 같아 consumer에서 접힘. 꺼림칙하면 스케줄러 pool로 직렬화
pending을 한 번에 메모리로 읽음평상시 pending은 그날 enqueue한 건뿐. 적체가 커지면 LIMIT 페이지 루프로

07. Key Takeaway#

  • 발행 기록 ≠ Outbox. 보낸 것을 적느냐, 보낼 것을 적느냐. 이름보다 “미발행이 저장된 상태인가, 계산된 결과인가”를 볼 것
  • DB 쓰기와 Kafka produce 사이의 dual write는 순서를 바꿔서 해결되지 않음. 롤백 코드는 프로세스가 죽는 경우를 못 막음
  • at-least-once의 전제는 재발행분이 처음과 동일하다는 것. now()·uuid4()·TTL 캐시 값을 발행 시점에 만들면 consumer 중복 제거가 깨짐 → payload를 적재 시점에 고정
  • 트랜잭션이 없어도 이벤트가 상태에서 결정적으로 파생된다면 멱등한 enqueue로 Outbox의 효과를 얻을 수 있음
  • ReplacingMergeTree에서는 version이 곧 상태 머신. pending을 0으로 두면 늦게 들어온 재enqueue가 발행 완료를 덮지 못함
  • 시간 컬럼은 클라이언트에서 넣지 말고 서버가 정수(epoch)에서 계산하게 하면 시간대 문제가 사라짐
  • 테이블을 바꾸기 전에 query_log로 실제 reader를 확인. 코드 검색은 “있을 수 있는 reader”, query_log는 “실제로 읽은 reader”

Concept

  • Transactional Outbox : 업무 데이터 변경과 발행할 이벤트를 같은 DB 트랜잭션으로 저장하고, 별도 relay가 이벤트를 메시지 브로커로 옮기는 패턴. 원자성 + at-least-once
  • Dual Write : 두 저장소(DB, Kafka)에 각각 쓰는 것. 둘을 원자적으로 묶을 수 없어 중간 실패 시 불일치가 생김
  • Polling Publisher : relay가 outbox 테이블을 주기적으로 조회해 미발행 행을 발행하는 방식. 배치 파이프라인과 잘 맞음
  • Transaction Log Tailing (CDC) : relay가 DB 변경 로그(binlog, WAL)를 읽어 outbox INSERT를 발행하는 방식. Debezium Outbox Event Router가 대표적
  • at-most-once / at-least-once : 최대 한 번(유실 가능, 중복 없음) / 최소 한 번(유실 없음, 중복 가능). Outbox는 at-least-once
  • Idempotent Consumer : 같은 메시지를 여러 번 받아도 결과가 같도록 처리하는 consumer. at-least-once 구조에서 필수
  • ReplacingMergeTree(ver) : 같은 정렬 키의 행을 merge 시점에 하나로 접고 ver가 가장 큰 행을 남기는 ClickHouse 엔진. merge 전에는 FINAL로 읽어야 최신 상태가 보장됨
  • Anti-join : LEFT JOIN ... WHERE right.key IS NULL로 “상대 테이블에 없는 행”만 고르는 조인. ClickHouse는 기본 설정(join_use_nulls=0)에서 매칭이 없으면 NULL이 아니라 기본값('')을 넣으므로 OR right.key = '' 조건이 필요
  • system.query_log : ClickHouse가 실행한 쿼리를 기록하는 시스템 테이블. tables, normalized_query_hash, http_user_agent로 누가 어떤 테이블을 읽는지 추적 가능
[Kafka] 발행 기록 테이블은 Outbox가 아니다 — 트랜잭션 없는 DB에서 Outbox 만들기
https://yjinheon.netlify.app/posts/02de/04-kafka/kafka-batch-outbox/
Author
Datamind
Published at
2026-11-10
License
CC BY-NC-SA 4.0