llm-wiki/vault/20-evidence/official-docs/transactional-outbox-aws-prescriptive-guidance.md

title, source_type, url, archive_url, related_branches, related_projects, tags, created

title	source_type	url	archive_url	related_branches	related_projects	tags	created
Transactional Outbox Pattern — AWS Prescriptive Guidance: Cloud Design Patterns	official-doc	https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html		feature-domain-event-outbox-contract	ca-skeleton	official-doc ca-skeleton ca-outbox-pattern transactional-outbox aws backend distributed-systems messaging idempotency	2026-06-11

Transactional Outbox Pattern — AWS Prescriptive Guidance: Cloud Design Patterns

Layer: raw/ — 외부 자료(공식 문서)의 원문 발췌·출처 기록. 검증된 요약은 /ingest 후 wiki/concepts/에 별도 작성. 원본은 raw에 영구 보관.

Parent / 활용 branch

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-domain-event-outbox-contract	D2 — "transaction 과 외부 publish 의 원자성이 필요하면 outbox 를 기본 기준 (dual-write 금지)" 의 official-vendor-doc 격상 근거 — 현재 D2 는 microservices.io (Richardson personal catalog, engineering-blog) 에 의존하며, AWS Prescriptive Guidance 가 동일 패턴을 official-vendor-doc strength 으로 corroborate

출처 / Source

• 원본 URL: https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html
• 아카이브 URL: (미수집)
• 저자 / 조직: AWS (Amazon Web Services) — AWS Prescriptive Guidance, Cloud Design Patterns
• 발행일: (AWS Prescriptive Guidance 게시일 명시 없음 — 지속 업데이트 문서)
• 마지막 확인일: 2026-06-11

왜 저장했는지 / Why archived

feature-domain-event-outbox-contract D2 의 Decision Evidence Map 에서 "official best practice 로 격상하려면 AWS Prescriptive Guidance / Microsoft Cloud Design Patterns 같은 official-vendor-doc corroborate 필요" 라는 Open Risk 가 명시되어 있었다. 본 자료는 AWS 공식 벤더 문서로서 dual-write 문제 정의 · outbox 테이블의 동일 트랜잭션 내 업데이트 메커니즘 · at-least-once delivery + idempotency 요건 · polling publisher vs CDC relay 옵션 모두를 verbatim 으로 제공하며, D2 의 engineering-blog strength 의존을 official-vendor-doc 으로 corroborate 한다.

핵심 인용 / Key quotes (verbatim, 5문장)

[§Intent] "The transactional outbox pattern resolves the dual write operations issue that occurs in distributed systems when a single operation involves both a database write operation and a message or event notification. A dual write operation occurs when an application writes to two different systems; for example, when a microservice needs to persist data in the database and send a message to notify other systems. A failure in one of these operations might result in inconsistent data."

[§Motivation] "When a microservice sends an event notification after a database update, these two operations should run atomically to ensure data consistency and reliability."

[§Implementation / Using an outbox table with a relational database] "When the flight table is updated, the outbox table is also updated in the same transaction. Another service (for example, the event processing service) reads from the outbox table and sends the event to Amazon SQS. [...] the same message or event might be delivered more than once, so you should ensure that the event notification service is idempotent (that is, processing the same message multiple times shouldn't have an adverse effect)."

[§Implementation / Using an outbox table with a relational database] "If the flight table update fails or the outbox table update fails, the entire transaction is rolled back, so there are no downstream data inconsistencies."

[§Issues and considerations — Duplicate messages] "The events processing service might send out duplicate messages or events, so we recommend that you make the consuming service idempotent by tracking the processed messages."

[§Implementation / Using change data capture (CDC)] "Some databases support the publishing of item-level modifications to capture changed data. You can identify the changed items and send an event notification accordingly. This saves the overhead of creating another table to track the updates."

Claims Extracted / 추출된 주장

이 자료가 직접 말하는 것만 claim 으로 분리. 내 프로젝트에 적용한 결론은 여기 쓰지 않음.

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
OUTBOX-AWS-C1	Transactional outbox 패턴은 distributed system 에서 DB write 와 message/event notification 이 단일 operation 에 포함될 때 발생하는 dual write 문제를 해결한다	[§Intent] "The transactional outbox pattern resolves the dual write operations issue that occurs in distributed systems when a single operation involves both a database write operation and a message or event notification."	official-vendor-doc	분산 시스템에서 DB + 메시지 발행 원자성이 필요한 모든 마이크로서비스	특정 DB/broker 조합에서의 실제 성능 · 구현 복잡도 트레이드오프는 증명하지 않음
OUTBOX-AWS-C2	DB update 와 event notification 은 원자적으로 실행되어야 data consistency 와 reliability 를 보장할 수 있다	[§Motivation] "When a microservice sends an event notification after a database update, these two operations should run atomically to ensure data consistency and reliability."	official-vendor-doc	DB update 후 downstream 에 event 를 전파해야 하는 마이크로서비스	"원자적으로 실행" 의 구체 메커니즘(outbox 테이블 / CDC / 2PC 등)을 prescribe 하지 않음 — 단지 atomicity 필요성만 명시
OUTBOX-AWS-C3	outbox table 은 동일 transaction 내에서 업데이트된다. 어느 한 쪽 update 가 실패하면 전체 transaction 이 rollback 되어 downstream inconsistency 가 없다	[§Implementation / outbox table] "When the flight table is updated, the outbox table is also updated in the same transaction." + "If the flight table update fails or the outbox table update fails, the entire transaction is rolled back, so there are no downstream data inconsistencies."	official-vendor-doc	동일 DB 내 outbox table 을 사용하는 구현 (relational DB, 같은 transaction 지원 필요)	NoSQL / multi-DB 환경에서의 동일 transaction 지원 여부는 별도 확인 필요. CDC 방식(AWS DynamoDB Streams)의 경우 별도 설명
OUTBOX-AWS-C4	event processing service 는 committed transaction 의 row 만 인식한다. 이 설계가 dual write 문제를 해소하고 timestamp + sequence number 로 메시지 순서를 보존한다	[§Implementation / outbox table] "When the events processing service reads the outbox table, it recognizes only those rows that are part of a committed (successful) transaction, and then places the message for the event in the SQS queue [...] This design resolves the dual write operations issue and preserves the order of messages and events by using timestamps and sequence numbers."	official-vendor-doc	relational DB outbox + polling publisher 조합	SQS standard queue 사용 시 순서 보장은 별도 FIFO queue 요구. DB-native sequence/timestamp 사용이 전제
OUTBOX-AWS-C5	at-least-once delivery: event processing service 가 중복 메시지를 발행할 수 있으므로 consuming service 를 idempotent 로 만들어야 한다(동일 메시지 여러 번 처리해도 부작용 없어야 함)	[§Issues] "The events processing service might send out duplicate messages or events, so we recommend that you make the consuming service idempotent by tracking the processed messages." + [§Implementation] "the same message or event might be delivered more than once, so you should ensure that the event notification service is idempotent (that is, processing the same message multiple times shouldn't have an adverse effect)."	official-vendor-doc	outbox 패턴을 사용하는 모든 event consuming service	exactly-once 보장 방법(SQS FIFO deduplication ID 등)은 별도 AWS SQS 문서 필요. idempotency key 구현 메커니즘(TTL, scope 등)은 prescribe 안 함
OUTBOX-AWS-C6	CDC 방식은 별도 outbox table 없이 DB item-level 변경 사항을 캡처해 event notification 을 발행할 수 있다. outbox table 오버헤드를 절감한다	[§Implementation / CDC] "Some databases support the publishing of item-level modifications to capture changed data. You can identify the changed items and send an event notification accordingly. This saves the overhead of creating another table to track the updates."	official-vendor-doc	CDC 를 지원하는 DB (AWS DynamoDB Streams, 일부 relational DB). AWS 구현 예시는 DynamoDB + DynamoDB Streams	범용 RDBMS (PostgreSQL/MySQL) 에서의 CDC (Debezium 등) 는 별도 raw 필요. "오버헤드 절감" 이 모든 환경에서 동일하다는 의미는 아님

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:

  • OUTBOX-AWS-C1: dual write 문제의 정의와 outbox 패턴이 해결 방법임을 AWS 공식 벤더 문서가 명시
  • OUTBOX-AWS-C2: DB update + event notification 의 atomicity 필요성을 AWS 공식 벤더 문서가 prescribe
  • OUTBOX-AWS-C3: 동일 transaction 내 outbox table update → rollback 시 downstream inconsistency 없음
  • OUTBOX-AWS-C4: committed row 만 polling → dual write 해소 + timestamp/sequence 순서 보존
  • OUTBOX-AWS-C5: at-least-once delivery + consumer idempotency 필요성을 AWS 공식 벤더 문서가 명시
  • OUTBOX-AWS-C6: CDC 가 outbox table 없이 동일 목적 달성 가능한 대안임을 AWS 공식 벤더 문서가 설명

• 이 자료가 증명하지 않는 것:

  • AWS-specific 서비스(Lambda, RDS, SQS, DynamoDB)가 필수임을 의미하지 않음 — 패턴 자체는 generic, AWS 서비스는 구현 예시
  • outbox row status enum (PENDING / IN_FLIGHT / PUBLISHED / FAILED / DEAD 등) 의 표준을 prescribe 하지 않음 — AWS 예시 코드는 outbox row 를 발행 후 DELETE 하는 단순 패턴 사용
  • idempotency key 의 구체 구현(TTL, scope, 저장 방식)을 prescribe 하지 않음
  • multi-instance publisher 의 ownership lock 메커니즘을 prescribe 하지 않음 (AWS 예시는 scheduled polling 방식)
  • PostgreSQL FOR UPDATE SKIP LOCKED 같은 특정 DB-level locking 전략을 prescribe 하지 않음

• 내 프로젝트 (ca-tmpl) 에 적용하려면 추가 확인이 필요한 것:

  • ca-tmpl 의 outbox row status enum (PENDING/IN_FLIGHT/PUBLISHED/FAILED/DEAD) 은 AWS 예시와 다른 내부 결정 (D5) — D5 는 UNSUPPORTED_DECISION 유지, 이 raw 로 corroborate 되지 않음
  • SQS FIFO queue 가 아닌 다른 broker (RabbitMQ, NATS, Kafka) 에서의 exactly-once 보장은 별도 raw 필요
  • D2 corroborate 완료: "outbox 기본 기준 (dual-write 금지)" 는 OUTBOX-AWS-C1 + OUTBOX-AWS-C2 + OUTBOX-AWS-C3 으로 official-vendor-doc strength 격상 가능

메모 / Notes

• 본 문서는 D2 Open Risk("official vendor corroboration 필요") 해소를 위해 수집. D2 Evidence Strength 를 needs-confirmation + engineering-blog 에서 official-vendor-doc (OUTBOX-AWS-C1~C5) 으로 격상하는 근거.
• AWS 예시 코드는 Spring Boot + Amazon RDS + Amazon SQS 조합 — ca-tmpl 이 SQS 를 사용하지 않더라도 패턴 원리(same-transaction outbox insert + polling publisher + at-least-once + idempotency) 는 동일하게 적용됨.
• CDC 옵션 (OUTBOX-AWS-C6, DynamoDB Streams) 은 ca-tmpl 채택 결정 범위 밖 — D3 (broker-agnostic, polling 기본) 에 영향 없음.
• 추가로 봐야 할 동일 출처 페이지: AWS Prescriptive Guidance 의 Saga Orchestration 패턴 (service-level transaction handling cross-reference), Event Sourcing 패턴 (ordering guarantee cross-reference).

Related / 관련

• 같은 주제 다른 official-doc / company-tech-blog:
  • raw/official-docs/microservices-io-transactional-outbox — Chris Richardson personal pattern catalog (engineering-blog strength)
  • raw/official-docs/outbox-debezium-official-docs — Debezium CDC outbox (needs-confirmation — WebFetch 차단)
  • raw/official-docs/dual-write-antipattern-microservices-io — dual-write antipattern 정의 (outbox 도입 근거)
  • raw/official-docs/skip-locked-postgres-docs — PostgreSQL SKIP LOCKED (D4/D8/D9 근거)
• 이 자료를 인용한 wiki 요약: wiki/concepts/transactional-outbox-pattern (생성 시)