100 lines
12 KiB
Markdown
100 lines
12 KiB
Markdown
---
|
|
title: "official-doc / MongoDB — Write Concern (w / j / wtimeout)"
|
|
source_type: official-doc
|
|
url: https://www.mongodb.com/docs/manual/reference/write-concern/
|
|
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 — Write Concern (w / j / wtimeout)
|
|
|
|
> Layer: `raw/official-docs/` — MongoDB 공식 Manual reference (`write-concern`) 원문 발췌.
|
|
> `feature-mongo-runtime-baseline-contract` 의 "MongoDB write 는 write concern 을 명시하고 기본값에 의존하지 않는다" + "journaling(j) / wtimeout 을 명시한다" 결정 근거.
|
|
|
|
## Parent / 활용 branch (필수)
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-mongo-runtime-baseline-contract]] | MongoDB write 는 write concern 을 명시하고 기본값(`w: "majority"` 여부)에 의존하지 않는다 + journaling(`j`) / `wtimeout` 을 명시한다 — `w`/`j`/`wtimeout` 옵션 의미, 서버 implicit default, `wtimeout` 초과 시 write 가 rollback 되지 않는다는 실패 의미의 verbatim 근거 |
|
|
|
|
## 컨텍스트
|
|
|
|
ca-skeleton 은 MongoDB 를 optional adapter(문서 저장소 축)로 채택할 수 있다. 본 branch 는 write concern 을 애플리케이션/드라이버 레벨에서 **명시**할지, 서버 implicit default 에 의존할지를 결정해야 한다. 이 판단에는 (1) `w` 값의 의미(숫자 vs `"majority"`), (2) `j` 가 무엇을 보장하는지, (3) `wtimeout` 초과 시 실제로 무슨 일이 일어나는지(=write 취소 여부), (4) 서버가 실제로 어떤 값을 implicit default 로 쓰는지에 대한 공식 정의가 필요하다.
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://www.mongodb.com/docs/manual/reference/write-concern/
|
|
- 아카이브 URL: (미수집)
|
|
- 저자 / 조직: MongoDB, Inc.
|
|
- 발행일: MongoDB Manual (현재 버전 — 본문에 "Starting in MongoDB 8.0" 문구 포함되어 있어 8.0 이후 반영분 포함된 최신 manual 로 판단)
|
|
- 마지막 확인일: 2026-07-28
|
|
|
|
## 핵심 인용 / Key quotes (verbatim)
|
|
|
|
> [§Write Concern Definition] "Write concern describes the level of acknowledgment requested from MongoDB for write operations"
|
|
|
|
> [§`w` Option (Acknowledgment Count)] "requests acknowledgment that the write operation has propagated to a specified number of `mongod` instances or to `mongod` instances with specified tags."
|
|
|
|
> [§`w` Values — `"majority"` row] "calculated majority of data-bearing voting members have durably written the change to their local oplog"
|
|
|
|
> [§`j` Option (Journal Durability)] "requests acknowledgment from MongoDB that the write operation has been written to the on-disk journal."
|
|
|
|
> [§`wtimeout` Option (Time Limit)] "`wtimeout` specifies a time limit, in milliseconds, for a write operation to propagate to enough members to achieve the write concern after the operation succeeds on the primary."
|
|
|
|
> [§`wtimeout` Option — Key behaviors] "MongoDB returns a write concern error after the specified limit, even if the required write concern will eventually succeed"
|
|
|
|
> [§`wtimeout` Option — Key behaviors] "When these write operations return, MongoDB does not undo successful data modifications performed before the write concern exceeded the `wtimeout` time limit"
|
|
|
|
> [§Implicit Default Write Concern] "The implicit default write concern is `{ w: "majority" }`"
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| MONGO-WRITECONCERN-C1 | Write concern 은 MongoDB 가 write 작업에 대해 요청하는 acknowledgment(확인 응답) 수준을 기술하는 개념이다 | [§Write Concern Definition] "Write concern describes the level of acknowledgment requested from MongoDB for write operations" | `official-vendor-doc` | standalone `mongod` / replica set / sharded cluster 전반의 write 요청 | 특정 드라이버(Java/Node 등)가 write concern 을 설정하는 구체 API 형태 — 이 인용은 서버 개념 정의만 다룸 |
|
|
| MONGO-WRITECONCERN-C2 | `w` 옵션은 write 가 지정된 개수의 `mongod` 인스턴스(또는 지정 태그를 만족하는 인스턴스)로 전파되었음을 확인해달라는 요청이다 | [§`w` Option] "requests acknowledgment that the write operation has propagated to a specified number of `mongod` instances or to `mongod` instances with specified tags." | `official-vendor-doc` | `w: <number>` 형태 값의 일반 의미 | 각 멤버가 durable write 로 카운트되는 순서·우선순위(예: arbiter 제외 여부)의 세부 규칙 — 본 인용 범위 밖 |
|
|
| MONGO-WRITECONCERN-C3 | `w: "majority"` 는 데이터를 보유한 투표권 멤버들의 계산된 과반수가 자신의 local oplog 에 변경사항을 durable 하게 기록했음을 확인하는 것을 요청한다 | [§`w` Values] "calculated majority of data-bearing voting members have durably written the change to their local oplog" | `official-vendor-doc` | `w: "majority"` write concern 을 사용하는 모든 replica set 배포 | journal(`j`) 까지 포함해서 확인하는지는 이 문장 자체엔 없음 — `writeConcernMajorityJournalDefault` 설정에 따라 별도 결정됨 (C8 참고) |
|
|
| MONGO-WRITECONCERN-C4 | `j` 옵션은 write 작업이 on-disk journal 에 기록되었음을 MongoDB 로부터 확인받는 것을 요청한다 | [§`j` Option] "requests acknowledgment from MongoDB that the write operation has been written to the on-disk journal." | `official-vendor-doc` | `j: true` 를 명시한 write 요청 전반 | journal 없이 write 가 유실될 수 있는 구체적 장애 시나리오(OS crash 등) 자체는 이 문장이 다루지 않음 |
|
|
| MONGO-WRITECONCERN-C5 | `wtimeout` 은 write 작업이 primary 에서 성공한 뒤 write concern 을 달성할 만큼 충분한 멤버로 전파되는 데 허용되는 시간 제한(밀리초)을 지정한다 | [§`wtimeout` Option] "`wtimeout` specifies a time limit, in milliseconds, for a write operation to propagate to enough members to achieve the write concern after the operation succeeds on the primary." | `official-vendor-doc` | `wtimeout` 이 명시된 모든 write 요청 | `w<=1` 일 때는 `wtimeout` 이 적용되지 않는다는 것 — 본 인용은 그 예외 조건 자체를 포함하지 않음(별도 bullet) |
|
|
| MONGO-WRITECONCERN-C6 | `wtimeout` 시간 제한 초과 시, 요청한 write concern 이 결국 충족될 것이었다 해도 MongoDB 는 write concern error 를 반환한다 | [§`wtimeout` Option — Key behaviors] "MongoDB returns a write concern error after the specified limit, even if the required write concern will eventually succeed" | `official-vendor-doc` | `wtimeout` 을 명시한 write 요청의 클라이언트 응답 성격 | 이 에러를 받은 애플리케이션이 재시도해야 하는지, 재시도 시 idempotent 하게 처리되는지는 이 문장이 규정하지 않음 — 애플리케이션 레벨 결정 |
|
|
| MONGO-WRITECONCERN-C7 | `wtimeout` 이 초과되어 write 작업이 반환되더라도, MongoDB 는 write concern 이 초과되기 전에 이미 적용된 성공적인 data modification 을 되돌리지(undo) 않는다 | [§`wtimeout` Option — Key behaviors] "When these write operations return, MongoDB does not undo successful data modifications performed before the write concern exceeded the `wtimeout` time limit" | `official-vendor-doc` | `wtimeout` 을 명시한 모든 write 작업의 실패 모드 — **`wtimeout` 은 write 자체를 취소하는 옵션이 아니라, 확인 응답 대기의 시간 제한일 뿐임을 증명** | 이 write 가 다른 replica 로 반드시 복제된다는 durability 보장 자체까지는 증명하지 않음 — primary 에 적용된 변경을 rollback 하지 않는다는 것만 증명 |
|
|
| MONGO-WRITECONCERN-C8 | 대부분의 MongoDB 배포에서 implicit(암묵적) default write concern 은 `{ w: "majority" }` 이다 | [§Implicit Default Write Concern] "The implicit default write concern is `{ w: "majority" }`" | `official-vendor-doc` | arbiter 가 없거나, arbiter 가 있어도 non-arbiter 수가 투표 노드 과반수를 초과하는 replica set 배포 | arbiter 를 포함한 특정 topology(예: non-arbiter ≤ majority(voting nodes))에서는 default 가 `{ w: 1 }` 로 낮아지는 예외 공식이 별도로 존재함 — 이 문장 자체는 그 예외 공식을 포함하지 않음(별도 코드 블록, 이번 raw 에 verbatim self-grep 미시도) |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- **이 자료가 직접 증명하는 것**:
|
|
- `MONGO-WRITECONCERN-C1`: write concern 의 일반 정의
|
|
- `MONGO-WRITECONCERN-C2`~`C3`: `w` 옵션 값의 의미(숫자 propagation count / `"majority"` = 과반수 durable oplog write)
|
|
- `MONGO-WRITECONCERN-C4`: `j` 옵션 = on-disk journal 기록 확인
|
|
- `MONGO-WRITECONCERN-C5`: `wtimeout` = 시간 제한(ms) 정의
|
|
- `MONGO-WRITECONCERN-C6`~`C7`: `wtimeout` 초과 시 write concern error 를 반환하지만, 이미 적용된 write 를 rollback/undo 하지 않는다는 실패 모드
|
|
- `MONGO-WRITECONCERN-C8`: 대부분 배포의 implicit default 는 `{ w: "majority" }`
|
|
- **이 자료가 증명하지 않는 것**:
|
|
- arbiter 가 있는 replica set 에서 default 가 `{ w: 1 }` 로 낮아지는 정확한 공식 조건(코드 블록 형태 — 이번 raw 에서 verbatim 인용/self-grep 미포함, 별도 확인 필요)
|
|
- MongoDB Atlas 등 managed 서비스가 self-managed 배포와 동일한 implicit default 를 쓰는지 여부
|
|
- 특정 드라이버(Java Reactive Streams / Spring Data MongoDB 등)가 write concern 을 어떤 설정 키·API 로 노출하는지 — 이 자료는 서버 개념만 정의, 드라이버 바인딩은 별도 자료 필요
|
|
- 트랜잭션 레벨 write concern 설정 방식(문서 본문에 "멀티 도큐먼트 트랜잭션은 개별 operation 이 아니라 트랜잭션 레벨에서 write concern 을 설정해야 한다"는 별도 주의사항이 있으나, 이번 raw 에는 별도 claim 으로 등록하지 않음 — 아래 메모 참고)
|
|
- **ca-skeleton 프로젝트에 적용하려면 추가 확인이 필요한 것**:
|
|
- ca-skeleton 이 실제로 채택할 replica set 구성(arbiter 유무)에 따라 서버 implicit default 가 `{ w: "majority" }` 인지 `{ w: 1 }` 인지 확인 필요 — `C8` 의 예외 공식 verbatim 별도 수집
|
|
- Spring Data MongoDB(또는 채택할 드라이버)의 `WriteConcern` 설정 API/property 이름 — 별도 official-doc 필요
|
|
- `j`/`wtimeout` 을 애플리케이션에서 명시할 구체 값(예: `wtimeout` 몇 ms) 은 이 자료가 아니라 branch 의 §구현 가이드에서 결정 — 본 자료는 "명시하지 않으면 무엇에 의존하게 되는지"와 "초과 시 무슨 일이 일어나는지"까지만 증명
|
|
|
|
## 메모 / Notes
|
|
|
|
- 이번 WebFetch 결과는 소형 모델이 원문을 markdown(볼드 `**`) 으로 재구성한 형태였다. Self-Grep 시 `**` 강조 마커가 인용 중간에 끼어 있는 경우 grep -F 매칭이 깨져(`w` 옵션 정의 인용 1차 시도 실패), 볼드 구간 경계를 벗어나지 않는 부분 문자열로 재선정해 재검증 통과시켰다. 원문 페이지 자체의 실제 HTML 은 이번에 별도 curl 로 대조하지 않음 — 다음 재검증 시 curl 직접 fetch 로 교차 확인 권장.
|
|
- 미수집: 멀티 도큐먼트 트랜잭션의 write concern 설정 위치(transaction-level vs operation-level) 관련 문장. `wtimeout: 0` 이 "wtimeout 옵션 없는 것과 동일"이라는 문장도 이번엔 별도 claim 화하지 않음(2차 우선순위) — 필요 시 재수집.
|
|
- 다음 fetch 후보: MongoDB 공식 `journaling` 페이지(journal 미기록 시 실제 유실 시나리오), `replica-set-election` 페이지(arbiter 예외 공식의 정확한 조건).
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 official-doc: 없음 (vault 내 최초 MongoDB 공식 문서)
|
|
- 인용하는 branch: [[raw/branch-notes/feature-mongo-runtime-baseline-contract]]
|
|
- 인용하는 project: [[raw/project-notes/ca-skeleton-operational-contract]]
|
|
- 인용한 wiki 요약: (미작성)
|