트랜잭션 Outbox: 업무 쓰기와 같은 부수 효과

핵심 요약: DB에 쓴 뒤 메일·웹훅·ERP 호출은 이중 쓰기입니다. 어느 단계든 혼자 성공할 수 있습니다. Outbox 행을 업무와 같은 트랜잭션에 두고 릴레이가 커밋된 행을 최소 한 번 배달합니다. 수신은 멱등이어야 합니다.

트랜잭션 outbox 다이어그램. 요청 핸들러가 같은 데이터베이스 트랜잭션에서 업무 행과 outbox 행을 쓰고, 커밋 후 릴레이가 outbox를 폴링하거나 로그를 추적해 메일·웹훅·ERP를 최소 한 번 배달한다. 수신 측은 멱등 관문을 둔다. 하단 주석은 내구성 있는 outbox 없이 업무 쓰기를 커밋한 뒤 네트워크를 호출하지 말라고 경고한다.
그림 1. 업무 쓰기와 outbox 행을 한 트랜잭션에 두고, 릴레이가 커밋 후 배달을 맡는다.

1.0 이중 쓰기 문제

주문을 저장한 뒤 확인 메일을 보내는 핸들러는 데이터베이스와 메일 제공자라는 두 시스템에 쓰고 있습니다. 전표를 ERP로 보내거나 파트너에게 웹훅을 내는 경우도 같은 모양입니다.

데이터베이스는 커밋됐는데 네트워크 호출이 실패하면 업무 상태는 맞는데 알림은 아무도 못 받습니다. 먼저 알리고 커밋이 실패하면 상대는 존재하지 않았던 일에 반응한 셈입니다. 데이터베이스와 메일 API에 걸친 2단계 커밋은 거의 쓸 수 없고 대개 바람직하지도 않습니다. 이것이 트랜잭션 outbox 패턴이 다루는 이중 쓰기 문제입니다(끝의 Chris Richardson 패턴 설명과 AWS Prescriptive Guidance 참고).

2.0 한 트랜잭션에 무엇을 넣을지

쓰기업무 변경과 같은 트랜잭션인가?
업무 행(주문, 결제, 티켓 등)예
Outbox 행(type, message id, payload, status)예
메일 / 웹훅 / ERP HTTP 호출아니요 — 커밋 뒤, 릴레이를 통해
Outbox 행을 published로 표시 / 삭제릴레이 성공 후(또는 로그 추적 정리)

Outbox 행은 이미 선로에서 일어난 일의 로그가 아닙니다. 부수 효과를 수행하겠다는 내구성 있는 의도이며, 업무 쓰기가 커밋될 때만 기록됩니다.

3.0 릴레이: 폴링 또는 로그 추적

별도 프로세스(또는 같은 서비스의 워커)가 커밋된 outbox 행을 바깥 세계로 옮깁니다.

방식일을 찾는 방법전형적인 트레이드오프
폴링 퍼블리셔id 또는 created_at 순으로 대기 행 SELECT단순함; 일반 SQL에서 동작; 간격과 표 크기에 따라 지연·부하 증가
트랜잭션 로그 추적DB 로그(WAL, binlog, streams)에서 삽입 읽기지연이 낮음; DB 전용 도구 필요; 여전히 최소 한 번

microservices.io는 둘 다 outbox의 동반자로 적습니다. 양이나 지연이 로그 추적을 강제하기 전까지는 폴링으로 충분합니다. 어느 쪽이든 Publish는 최소 한 번입니다. “전송 성공”과 “행 완료 표시” 사이에서 죽으면 다시 보냅니다.

4.0 안정적으로 유지하는 행 형태

운영이 애플리케이션 메모리를 읽지 않고도 “무엇이 막혔나”에 답할 수 있을 만큼의 열을 둡니다.

  • id — 단조 또는 ULID. 순서와 릴레이 체크포인트용.
  • message_id / 멱등 키 — 이 논리 부수 효과에 안정적. 수신 측이 이것으로 중복 제거.
  • type — 어떤 릴레이 핸들러가 도는지(email.order_paid, erp.order_push 등).
  • aggregate_key — 주문 id, 리드 id, 디바이스 id. 순서와 지원 조회용.
  • payload — 핸들러가 필요로 하는 버전 있는 JSON. 비밀은 넣지 않음.
  • status — pending → publishing(선택 임대) → published / failed_terminal.
  • attempts, next_attempt_at, last_error — 백오프와 알림용.
  • created_at — 선택적으로 published_at.

원자적 갱신으로 행을 점유합니다(pending → publishing, 소유자와 임대 만료 포함). 두 릴레이 워커가 같은 메일을 보내지 않게 하기 위해서입니다. 성공하면 published(표를 작게 유지하고 감사는 백업에 맡기면 삭제도 가능). 재시도 가능한 실패에서는 attempts를 늘리고 next_attempt_at을 설정합니다. 설정 한도를 넘으면 failed_terminal로 옮기고 사람에게 알립니다.

5.0 순서와 중복

단일 집계에서는 할당된 outbox id(또는 일련번호) 순으로 Publish해 파트너가 “출고됨”을 “생성됨”보다 먼저 보지 않게 합니다. 집계를 가로지르는 병렬 워커는 괜찮습니다.

중복은 예상됩니다. 이 노트와 웹훅 멱등성과 재시도: 중복 제거 키, 보관 기간, 부수 효과 처리를 함께 보세요. Outbox는 업무 쓰기 성공 후 부수 효과가 시도됨을 보장하고, 수신 측 중복 제거 저장소가 한 번만 적용됨을 보장합니다. ERP 전송도 상대 쪽에서 같은 규율이 필요합니다 — 전표의 안정적인 업무 키는 ERP와 주문 연동하기: 수동 검토, 멱등 전송, 동기화 로그를 참고하세요.

6.0 요청 경로에 두지 말 것

  • DB 트랜잭션을 연 채로 제3자 HTTP API를 호출한 뒤 커밋하지 마세요. 타임아웃과 잠금 때문에 실패 모드를 추론하기 어렵습니다.
  • 크래시 때 그 부수 효과를 잃는 것이 허용되지 않으면, 내구성 있는 outbox(또는 동등물) 없이 goroutine이나 큐 Publish를 fire-and-forget하지 마세요.
  • 메일 API의 “HTTP 200”을 “고객에게 알림”의 권위 기록으로 쓰지 마세요. 그 결과도 지속화하지 않았다면 말입니다. 더 나은 쪽은 outbox가 published이고 제공자 message id를 행에 남기는 것입니다.

7.0 관측 가능성

  • 지표: pending 나이(p50/p95), Publish 성공/실패율, 종단 실패, 릴레이 지연.
  • 알림: 가장 오래된 pending/publishing이 임계값 초과; 배포 후 종단 실패 급증.
  • 지원: aggregate_key로 찾고 업무 기록 옆에 outbox 상태를 표시.

결제·ERP·디바이스 클라우드용 부수 효과를 연결한다면 웹·클라우드·디바이스 관리를 참고하거나 프로젝트 상담으로 연락 주세요.

참고 자료

자주 묻는 질문

Outbox가 메시지 큐와 같은 것인가요?

Outbox는 업무 쓰기와 같은 데이터베이스 안의 테이블(또는 문서 필드)이라 둘 다 함께 커밋되거나 함께 롤백됩니다. 큐나 브로커는 릴레이 뒤에 둡니다. 업무 쓰기 없이는 Publish가 성공하지 않고, 그 반대도 없도록 하는 것이 Outbox의 역할입니다.

수신 측에서도 멱등성이 필요한가요?

필요합니다. 릴레이는 여러 번 Publish할 수 있습니다. 전송은 성공했는데 행을 완료로 표시하기 전에 죽으면 다시 보냅니다. 소비자는 최소 한 번 배달로 다루어야 하며, 웹훅 노트에 적은 멱등 키와 보관 창 방식이 한 예입니다.

데이터베이스 트랜잭션 안에서 메일 API를 호출해도 되나요?

피하세요. 네트워크 호출을 기다리며 DB 트랜잭션을 열어 두면 잠금이 길어지고, 타임아웃이 나면 메일이 나갔는지조차 모호해집니다. Outbox 행을 쓰고 커밋한 뒤, 네트워크 작업은 릴레이에 맡기세요.

Outbox 테이블을 폴링하는 것이 낭비해 보입니다. 다른 방법이 있나요?

폴링은 어떤 SQL 데이터베이스에서도 동작하며 중간 규모에서는 대개 충분합니다. 데이터베이스가 지원하면 트랜잭션 로그 추적(예: WAL이나 binlog에서 outbox 삽입을 읽기)으로 지연과 부하를 줄입니다. 두 방식 모두 최소 한 번 배달입니다.

Outbox payload에는 무엇을 넣나요?

릴레이가 의도를 다시 끌어내지 않고도 움직일 만큼이면 됩니다. 유형, 안정적인 멱등 또는 메시지 id, 업무 키, 다운스트림 호출에 필요한 필드. 집계 전체를 불투명하게 덤프하기보다 버전 있는 스키마를 써서, 코드가 바뀐 뒤에도 옛 행을 읽을 수 있게 합니다.