Files

T

DongHyeonka 58515ab0f3 feat: 공식 문서 근거자료, 브랜치 기능 문서 작성

2026-07-29 18:05:17 +09:00

13 KiB

Raw Blame History

title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed

title

source_type

url

archive_url

status

confidence

official-doc / MongoDB — Retryable Writes (Once-Only Retry Semantics)

Layer: raw/official-docs/ — MongoDB 공식 Manual reference (retryable-writes) 원문 발췌. feature-mongo-runtime-baseline-contract 의 "Mongo write 재시도 의미를 명시한다 — 드라이버의 retryable writes 가 무엇을 보장하고 무엇을 보장하지 않는지를 계약에 적고, 애플리케이션 재시도와 겹치지 않게 한다" 결정 근거.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-mongo-runtime-baseline-contract	Mongo write 재시도 의미를 명시한다 — 드라이버의 retryable writes 가 무엇을 보장하고 무엇을 보장하지 않는지를 계약에 적고, 애플리케이션 재시도와 겹치지 않게 한다 — 기본 활성 여부, 재시도 1회 한정 서술, 재시도 가능/불가능 연산의 정확한 목록, 배포 형태 요건의 verbatim 근거

컨텍스트

ca-skeleton 이 MongoDB 를 optional adapter 로 채택할 경우, 드라이버가 기본 제공하는 retryable writes 가 애플리케이션 재시도 로직과 겹치면 이중 재시도·의미 혼동이 생길 수 있다. 이 판단에는 (1) retryable writes 가 기본으로 켜져 있는지, (2) 재시도가 정확히 몇 번 수행되는지(무한 재시도가 아님을 확인), (3) 어떤 write 연산이 재시도 대상이고 어떤 연산(특히 multi-document update/delete, unacknowledged write concern)이 대상 밖인지, (4) 어떤 배포 형태(standalone 은 제외)에서만 지원되는지에 대한 공식 정의가 필요하다.

출처 / Source

원본 URL: https://www.mongodb.com/docs/manual/core/retryable-writes/
아카이브 URL: (미수집)
저자 / 조직: MongoDB, Inc.
발행일: MongoDB Manual (현재 버전 — 본문에 "Starting in MongoDB 6.1" 문구 포함되어 있어 6.1 이후 반영분까지 포함된 최신 manual 로 판단)
마지막 확인일: 2026-07-28

핵심 인용 / Key quotes (verbatim)

[§Compatibility — Deployment Topologies] "A replica set or sharded cluster. Not supported on standalone instances."

[§Enabling Retryable Writes] "Drivers compatible with MongoDB 4.2 and higher enable Retryable Writes by default."

[§Retryable Write Behaviors — Retry Behavior] "By default, MongoDB retries writes once. One retry attempts to address transient network errors and replica set elections, but not persistent network errors."

[§Retryable Write Operations] "MongoDB retries the following operations if they have acknowledged write concern:"

[§Retryable Write Operations — Non-retryable operations] "Writes with Write Concern 0 (unacknowledged)"

[§Retryable Write Operations — Non-retryable operations] "Multi-document write operations like updateMany() and deleteMany()"

[§Multi-Document Transactions] "Transaction commit and abort operations are retryable. Drivers retry these operations once on error, even if retryWrites is false."

[§Multi-Document Transactions] "Writes inside a transaction are not individually retryable, regardless of the value of retryWrites."

[§Error Handling] "Starting in MongoDB 6.1, if both the first and second attempt of a retryable write fail without a single write being performed, MongoDB returns an error with the NoWritesPerformed label."

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
MONGO-RETRYWRITE-C1	Retryable writes 는 standalone instance 에서는 지원되지 않고, replica set 또는 sharded cluster 배포에서만 동작한다	[§Compatibility] "A replica set or sharded cluster. Not supported on standalone instances."	`official-vendor-doc`	ca-skeleton 이 MongoDB 를 replica set/sharded cluster 로 배포할 때만 retryable writes 를 전제할 수 있음	standalone 단일 인스턴스로 운영 중인 환경에서 retryable writes 관련 동작을 기대할 수 있다는 것 — 이 문장이 명시적으로 부정함
MONGO-RETRYWRITE-C2	MongoDB 4.2 이상과 호환되는 드라이버는 retryable writes 를 기본으로 활성화한다	[§Enabling Retryable Writes] "Drivers compatible with MongoDB 4.2 and higher enable Retryable Writes by default."	`official-vendor-doc`	4.2+ 호환 드라이버를 사용하는 애플리케이션 — 별도 `retryWrites=true` 설정 없이도 활성 상태	4.2 미만 호환 드라이버의 기본값(이 경우 `retryWrites=true` 를 명시해야 함) — 이 문장은 4.2+ 케이스만 증명
MONGO-RETRYWRITE-C3	MongoDB 는 기본적으로 write 를 정확히 한 번만 재시도하며, 이 1회 재시도는 일시적(transient) 네트워크 오류와 replica set election 상황을 커버할 뿐 지속적(persistent) 네트워크 오류는 커버하지 않는다	[§Retry Behavior] "By default, MongoDB retries writes once. One retry attempts to address transient network errors and replica set elections, but not persistent network errors."	`official-vendor-doc`	`timeoutMS` 를 별도 설정하지 않은 기본 동작. 애플리케이션 레벨 재시도 설계 시 "드라이버가 이미 1회 재시도한다"는 전제로 중복 재시도 설계를 피해야 함	`timeoutMS` 를 설정했을 때는 문서가 별도로 "성공/재시도불가오류/타임아웃 중 하나까지 여러 번 재시도할 수 있다"고 규정하므로, 이 문장은 그 case 를 다루지 않음
MONGO-RETRYWRITE-C4	MongoDB 는 acknowledged write concern 을 가진 특정 연산(insert, single-document update/delete, findAndModify 계열, single-document 로만 구성된 bulkWrite)만 재시도 대상으로 삼는다	[§Retryable Write Operations] "MongoDB retries the following operations if they have acknowledged write concern:"	`official-vendor-doc`	위 나열된 단일 문서 단위 연산들. write concern 이 acknowledged(즉 `w != 0`)일 때만 성립	나열되지 않은 연산(예: multi-document 연산)이 재시도된다는 것 — 아래 C5 가 명시적으로 부정
MONGO-RETRYWRITE-C5	Write Concern `0`(unacknowledged) 인 write 와 `updateMany()`/`deleteMany()` 같은 multi-document write 연산은 재시도되지 않는다	[§Non-retryable operations] "Writes with Write Concern `0` (unacknowledged)" / "Multi-document write operations like `updateMany()` and `deleteMany()`"	`official-vendor-doc`	애플리케이션이 `w:0` 로 fire-and-forget write 를 하거나 multi-document update/delete 를 쓸 때, 드라이버 재시도에 의존할 수 없다는 계약	애플리케이션이 이런 연산에 대해 직접 idempotent 재시도 로직을 구현해야 하는지 여부의 구체적 방법 — 이 문장은 "드라이버가 안 해준다"는 사실만 증명
MONGO-RETRYWRITE-C6	트랜잭션의 commit/abort 연산 자체는 `retryWrites` 값과 무관하게 오류 시 1회 재시도되지만, 트랜잭션 내부의 개별 write 는 `retryWrites` 값과 무관하게 개별적으로 재시도되지 않는다	[§Multi-Document Transactions] "Transaction commit and abort operations are retryable. Drivers retry these operations once on error, even if `retryWrites` is `false`." / "Writes inside a transaction are not individually retryable, regardless of the value of `retryWrites`."	`official-vendor-doc`	멀티 도큐먼트 트랜잭션을 쓰는 write 흐름 — 트랜잭션 경계(commit/abort) 재시도와 트랜잭션 내부 개별 write 재시도를 구분해서 설계해야 함	트랜잭션 자체가 실패했을 때 애플리케이션이 트랜잭션 전체를 재시도해야 하는지 여부의 구체적 정책 — 이 문장은 "드라이버가 commit/abort 만 1회 재시도한다"는 사실만 증명
MONGO-RETRYWRITE-C7 (보조)	MongoDB 6.1 부터, retryable write 의 1차·2차 시도가 모두 실패하고 write 가 하나도 수행되지 않았다면 `NoWritesPerformed` 라벨이 붙은 에러를 반환한다	[§Error Handling] "Starting in MongoDB 6.1, if both the first and second attempt of a retryable write fail without a single write being performed, MongoDB returns an error with the `NoWritesPerformed` label."	`official-vendor-doc`	MongoDB 6.1+ 배포에서 `insertMany()` 등 batch 연산의 부분 실패 여부를 구분해야 하는 에러 핸들링 로직	6.1 미만 버전에서의 동일 상황 에러 형태 — 이 문장은 6.1+ 에만 적용됨을 명시

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- MONGO-RETRYWRITE-C1: 배포 형태 요건 — replica set/sharded cluster 필수, standalone 불가
- MONGO-RETRYWRITE-C2: MongoDB 4.2+ 호환 드라이버는 retryable writes 기본 활성
- MONGO-RETRYWRITE-C3: 기본 재시도는 정확히 1회, transient 오류/election 만 커버
- MONGO-RETRYWRITE-C4: 재시도 대상 연산 조건 — acknowledged write concern + 단일 문서 단위 연산
- MONGO-RETRYWRITE-C5: 재시도 불가 연산 — unacknowledged(w:0) write, multi-document update/delete
- MONGO-RETRYWRITE-C6: 트랜잭션 commit/abort 는 재시도되지만 트랜잭션 내부 개별 write 는 재시도되지 않음
- MONGO-RETRYWRITE-C7: 6.1+ 에서 완전 실패 시 NoWritesPerformed 에러 라벨
이 자료가 증명하지 않는 것:
- timeoutMS 설정 시 정확히 몇 회까지 재시도되는지의 구체적 상한 — 문서는 "성공/재시도불가오류/타임아웃 중 하나까지" 라고만 규정, 횟수 자체는 명시하지 않음
- Spring Data MongoDB(또는 채택할 드라이버)가 retryWrites 옵션을 어떤 설정 키/property 로 노출하는지 — 이 자료는 서버·프로토콜 레벨 계약만 정의
- 애플리케이션 레벨 재시도(예: idempotency key 기반 재시도)와 드라이버 레벨 retryable writes 를 어떻게 조합해야 하는지에 대한 설계 지침 — 이 자료는 드라이버가 "무엇을 하는지"만 말하고 "애플리케이션이 무엇을 더 해야 하는지"는 말하지 않음
- local 데이터베이스로의 write 에 대한 retryable writes 비활성화 권고의 정확한 근거 문장(이번 raw 에는 verbatim 인용/self-grep 미포함 — 별도 확인 필요)
ca-skeleton 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-skeleton 이 채택할 MongoDB 드라이버(Java/Reactive Streams 또는 Spring Data MongoDB)가 실제로 4.2+ 호환인지, 그래서 별도 retryWrites=true 설정 없이 기본 활성인지 확인 필요
- branch 의 §구현 가이드에서 애플리케이션 레벨 재시도(예: idempotent write 재시도)를 드라이버의 1회 재시도와 어떻게 겹치지 않게 설계할지는 이 자료가 아니라 branch 자체 결정 사항

메모 / Notes

WebFetch 1차 시도는 원문 링크를 markdown [text](url) 문법으로 감싼 형태로 반환해 self-grep 인용에 마크다운 아티팩트가 섞일 위험이 있었다. 재요청 시 "링크를 순수 텍스트로" 명시해 재fetch, 브래킷 없는 깨끗한 인용을 확보했다.
G2 재검증 1차 시도에서 4개 인용("A replica set or sharded cluster...", "Drivers compatible with MongoDB 4.2...", "By default, MongoDB retries writes once...", "Transaction commit and abort operations..."/"Writes inside a transaction...")이 grep -nF 불일치로 확인됨 — WebFetch 결과의 **볼드** 강조 마커를 인용에서 임의로 제거했기 때문. 원문 그대로 ** 를 보존하도록 정정하고 재검증 통과.
local 데이터베이스 write 에 대한 retryable writes 비활성화 권고, timeoutMS 재시도 상한의 정확한 조건 문장은 이번 라운드에서 verbatim 미수집 — 필요 시 재수집.
MongoDB 드라이버(Java/Reactive)의 retryWrites 구체 설정 API 는 별도 official-doc 후보.

같은 주제 다른 official-doc: raw/official-docs/write-concern-mongodb-official (write concern 정의 — 본 문서의 "acknowledged write concern" 조건과 직결)
같은 주제 다른 official-doc: raw/official-docs/spring-data-mongodb-index-management-official (같은 branch cluster 의 다른 MongoDB 공식 근거)
인용하는 branch: raw/branch-notes/feature-mongo-runtime-baseline-contract
인용하는 project: raw/project-notes/ca-skeleton-operational-contract
인용한 wiki 요약: (미작성)

13 KiB Raw Blame History