103 lines
13 KiB
Markdown
103 lines
13 KiB
Markdown
---
|
|
title: "official-doc / MongoDB — Retryable Writes (Once-Only Retry Semantics)"
|
|
source_type: official-doc
|
|
url: https://www.mongodb.com/docs/manual/core/retryable-writes/
|
|
archive_url:
|
|
status: raw
|
|
confidence: high
|
|
tags: [official-doc, ca-skeleton, persistence, mongodb, write-concern]
|
|
related_projects: [ca-skeleton]
|
|
related_branches: [feature-mongo-runtime-baseline-contract]
|
|
created: 2026-07-28
|
|
last_reviewed: 2026-07-28
|
|
---
|
|
|
|
# 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 후보.
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 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 요약: (미작성)
|