llm-wiki/raw/official-docs/transactions-mongodb-official.md

---
title: official-doc / MongoDB — Multi-Document Transactions (Replica Set / Sharded Cluster Requirements, Concern Defaults)
source_type: official-doc
url: https://www.mongodb.com/docs/manual/core/transactions/
archive_url:
related_branches: [feature-mongo-runtime-baseline-contract]
related_projects: []
tags: [official-doc, ca-skeleton, persistence, mongodb, transaction]
created: 2026-07-28
---

# official-doc / MongoDB — Multi-Document Transactions (Replica Set / Sharded Cluster Requirements, Concern Defaults)

> Layer: `raw/` — 외부 자료(공식 문서 / 대기업 기술 블로그)의 **원문 발췌·출처 기록**.
> 본 템플릿은 `raw/official-docs/` 와 `raw/company-tech-blogs/` 두 폴더가 공유.
> 검증된 요약은 `/ingest` 후 `wiki/concepts/`에 `source-summary-template` 형식으로 별도 작성. 원본은 raw에 영구 보관.

## source_type 허용값

`source_type: official-doc` — MongoDB 공식 매뉴얼(레퍼런스) 문서.

## Parent / 활용 branch

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-mongo-runtime-baseline-contract]] | (1) multi-document transaction 은 replica-set/sharded 요건 검증을 통과할 때만 활성화한다 — FCV 최소버전(Replica Set 4.0 / Sharded Cluster 4.2), WiredTiger storage engine 요건, `writeConcernMajorityJournalDefault: false` 샤드 배제 근거. (2) transaction 은 시간·크기 한계를 가지므로 무제한 사용을 전제하지 않는다 — "runtime limit" 이 공식적으로 별도 usage consideration 으로 취급된다는 근거(단, 구체 수치는 이 URL 범위 밖, 아래 Usage Boundaries 참고) |

## 출처

- 원본 URL: https://www.mongodb.com/docs/manual/core/transactions/
- 아카이브 URL: (미제공)
- 저자 / 조직: MongoDB, Inc. (공식 매뉴얼)
- 발행일: (문서 자체에 명시 없음 — 버전별 롤링 업데이트되는 레퍼런스 페이지. 2026-07-28 fetch 시점 기준 "Starting in MongoDB 8.1" 문구 포함 확인)
- 마지막 확인일: 2026-07-28

## 왜 저장했는지

`feature-mongo-runtime-baseline-contract` branch가 "multi-document transaction 은 replica-set/sharded 요건 검증을 통과할 때만 활성화하고 standalone 에서는 사용하지 않는다"와 "transaction 은 시간·크기 한계를 가지므로 무제한 사용을 전제하지 않는다"를 결정하는 데 필요한 FCV/storage-engine 배포 요건, read/write concern 기본값 결정 체인, runtime limit 서술의 공식 근거로 보관.

## 핵심 인용

> [§Transactions and Atomicity — intro] "In MongoDB, an operation on a single document is atomic." [...] "multi-document transactions are not necessary for many practical use cases."

> [§Feature Compatibility Version (FCV)] "To use transactions, the featureCompatibilityVersion for all members of the deployment must be at least:" — 표: Replica Set → `4.0`, Sharded Cluster → `4.2`

> [§Storage Engines] "Transactions are supported on replica sets and sharded clusters where:" [...] "the secondary members use either the WiredTiger storage engine or the in-memory storage engines."

> [§Shard Configuration Restriction] "You cannot run transactions on a sharded cluster that has a shard with writeConcernMajorityJournalDefault set to false, such as a shard with a voting member that uses the in-memory storage engine."

> [§Transactions and Read Concern — MongoDB Defaults] "By default, the client-level read concern is "local" for reads on the primary."

> [§Transactions and Write Concern — MongoDB Defaults] "If the transaction-level write concern and the session-level write concern are unset, the transaction-level write concern defaults to the client-level write concern of:" — `w: "majority"` (MongoDB 5.0+) 또는 `w: 1` (이전 버전)

> [§Transactions and Write Concern — Tip] "Don't explicitly set the write concern for the individual write operations inside a transaction. Setting write concerns for the individual write operations inside a transaction returns an error."

> [§Transactions and Sessions] "If a session ends and it has an open transaction, the transaction aborts."

> [§Transactions and Atomicity — Important] "For additional transactions usage considerations (such as runtime limit and oplog size limit), see also Production Considerations."

> [§Transactions and Write Concern — Note] "Regardless of the write concern specified for the transaction, the driver applies w: "majority" as the write concern when retrying commitTransaction."

## Claims Extracted

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

| Claim ID | Claim | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| MONGO-TXN-C1 | 단일 document 에 대한 연산은 원자적이며, 이 때문에 많은 실무 사용 사례에서 multi-document transaction 이 필수가 아니다 | [§Transactions and Atomicity] "In MongoDB, an operation on a single document is atomic." [...] "multi-document transactions are not necessary for many practical use cases." | `official-vendor-doc` | 임베디드 document/array 로 관계를 표현할 수 있는 일반적인 스키마 설계 | 특정 도메인(예: 여러 collection 에 걸친 정산·재고 이동)이 transaction 없이 처리 가능한지는 이 문장이 증명하지 않음 — 스키마별 개별 판단 필요 |
| MONGO-TXN-C2 | Transaction 을 사용하려면 배포의 모든 멤버가 최소 FCV 를 만족해야 한다 — Replica Set 은 `4.0` 이상, Sharded Cluster 는 `4.2` 이상 | [§Feature Compatibility Version (FCV)] "To use transactions, the featureCompatibilityVersion for all members of the deployment must be at least:" (표: Replica Set `4.0` / Sharded Cluster `4.2`) | `official-vendor-doc` | replica-set 또는 sharded-cluster 로 배포된 MongoDB 전반 | standalone(단일 `mongod`, replica set 아님) 배포에서 transaction 시도 시 정확히 어떤 에러/거부 메시지가 발생하는지는 이 문장 자체가 규정하지 않음 — FCV 표가 애초에 standalone 을 대상에서 제외하고 있을 뿐 |
| MONGO-TXN-C3 | Transaction 은 replica set 과 sharded cluster 에서 지원되며, primary 는 WiredTiger storage engine 을 사용해야 하고 secondary 는 WiredTiger 또는 in-memory storage engine 을 사용해야 한다 | [§Storage Engines] "Transactions are supported on replica sets and sharded clusters where:" [...] "the secondary members use either the WiredTiger storage engine or the in-memory storage engines." | `official-vendor-doc` | replica-set/sharded-cluster 배포의 storage engine 조합 검증 | standalone 인스턴스에 대한 명시적 언급은 없음 — "replica sets and sharded clusters where" 로 지원 범위를 positively 한정할 뿐, standalone 을 명시적으로 거부한다고 말하지는 않음 |
| MONGO-TXN-C4 | `writeConcernMajorityJournalDefault` 가 `false` 로 설정된 shard(예: in-memory storage engine 을 쓰는 voting member 를 가진 shard)가 있는 sharded cluster 에서는 transaction 을 실행할 수 없다 | [§Shard Configuration Restriction] "You cannot run transactions on a sharded cluster that has a shard with writeConcernMajorityJournalDefault set to false, such as a shard with a voting member that uses the in-memory storage engine." | `official-vendor-doc` | sharded cluster 배포에서 shard 별 `writeConcernMajorityJournalDefault` 설정 검증 | replica set(비-sharded) 배포에 동일 제약이 적용되는지는 이 문장이 명시하지 않음 — 문장 자체가 sharded cluster 로 범위를 한정함 |
| MONGO-TXN-C5 | Transaction 의 read concern 은 transaction-level → session-level → client-level 순으로 기본값이 결정되며, client-level read concern 의 기본값은 primary 읽기 기준 `"local"` 이다 | [§Transactions and Read Concern] "By default, the client-level read concern is "local" for reads on the primary." | `official-vendor-doc` | read concern 을 명시하지 않고 transaction 을 시작하는 모든 경우 | `"majority"`/`"snapshot"` 을 명시적으로 설정했을 때의 동작까지는 이 한 문장이 다루지 않음(별도 절에서 각각 정의됨, 이번 raw 에는 claim 화하지 않음) |
| MONGO-TXN-C6 | Transaction 의 write concern 은 transaction-level → session-level → client-level 순으로 기본값이 결정되며, client-level write concern 기본값은 MongoDB 5.0 이상에서 `w: "majority"`, 그 이전 버전에서는 `w: 1` 이다 | [§Transactions and Write Concern] "If the transaction-level write concern and the session-level write concern are unset, the transaction-level write concern defaults to the client-level write concern of:" (`w: "majority"` MongoDB 5.0+ / `w: 1` 이전) | `official-vendor-doc` | write concern 을 명시하지 않고 transaction 을 커밋하는 모든 경우(버전에 따라 분기) | arbiter 를 포함한 배포에서 이 기본값이 달라지는 정확한 조건은 이 문장 자체에 없음 — 링크된 "Implicit Default Write Concern" 별도 페이지 확인 필요(`write-concern-mongodb-official.md` C8 의 동일 gap 참고) |
| MONGO-TXN-C7 | Transaction 내부의 개별 write 연산에는 명시적 write concern 을 설정할 수 없으며, 설정 시 에러가 발생한다 — write concern 은 반드시 transaction/session/client 레벨에서만 설정한다 | [§Transactions and Write Concern] "Don't explicitly set the write concern for the individual write operations inside a transaction. Setting write concerns for the individual write operations inside a transaction returns an error." | `official-vendor-doc` | transaction 내부에서 실행되는 모든 write 연산의 write concern 설정 위치 제약 | 이 제약을 어겼을 때 반환되는 정확한 에러 코드/메시지 문자열은 이 문장이 제공하지 않음 |
| MONGO-TXN-C8 | Transaction 은 session 에 연결되며, session 이 열린 transaction 을 가진 채 종료되면 그 transaction 은 abort 된다 | [§Transactions and Sessions] "If a session ends and it has an open transaction, the transaction aborts." | `official-vendor-doc` | 세션 종료(연결 끊김, 명시적 session 종료 등)로 인한 transaction abort 조건 | 이것은 **세션 종료로 인한 abort** 이며, 실행 시간(runtime) 초과로 인한 abort(`transactionLifetimeLimitSeconds` 등)와는 별개의 트리거다 — 시간 초과 abort 의 구체 파라미터/기본값/동작은 이 URL 에 없음(C9 참고, Usage Boundaries 에 gap 명시) |
| MONGO-TXN-C9 | MongoDB 공식 문서는 transaction 의 "runtime limit" 과 "oplog size limit" 을 별도의 usage consideration 으로 명시적으로 인정하며, 상세는 Production Considerations 페이지로 위임한다 | [§Transactions and Atomicity] "For additional transactions usage considerations (such as runtime limit and oplog size limit), see also Production Considerations." | `needs-confirmation` | transaction 이 "무제한 사용을 전제하지 않는다"는 원칙적 근거(런타임 한계가 공식적으로 존재한다는 사실 자체) | **구체적인 시간 한계 값(예: `transactionLifetimeLimitSeconds` 기본값 60초)과 초과 시 정확한 abort 동작은 이 URL 에 없다** — 별도 페이지(`Production Considerations for Transactions`, https://www.mongodb.com/docs/manual/core/transactions-production-consideration/)의 fetch 가 필요하며, 1 dispatch = 1 URL 원칙에 따라 이번 raw 에는 포함하지 않음 |
| MONGO-TXN-C10 | Transaction 커밋에 어떤 write concern 이 지정되었든 관계없이, driver 가 `commitTransaction` 을 재시도할 때는 항상 `w: "majority"` write concern 을 적용한다 | [§Transactions and Write Concern] "Regardless of the write concern specified for the transaction, the driver applies w: "majority" as the write concern when retrying commitTransaction." | `needs-confirmation` | driver 가 `commitTransaction` 명령 자체를 재시도하는 경우의 write concern 승격 규칙 | **일반적인 TransientTransactionError 라벨 감지 → 전체 transaction 재시도 루프 패턴**은 이 문장이 다루지 않는다 — 그 패턴은 드라이버별 에러 처리 가이드(별도 페이지)의 범위이며 이 URL 에는 없음 |

### Strength 허용값

- `official-standard` — RFC, 표준 사양, 언어/프로토콜 표준
- `official-vendor-doc` — Spring, Keycloak, AWS, Google, MongoDB 등 공식 벤더 문서
- `official-reference` — 공식 reference/API 문서
- `company-case-study` — 대기업/실무 기술 블로그의 특정 사례
- `engineering-blog` — 개인/팀 블로그의 엔지니어링 해설
- `tutorial` — 튜토리얼/가이드. 일반화 금지
- `needs-confirmation` — 원문만으로는 적용 판단 불가

## Usage Boundaries

- 이 자료가 직접 증명하는 것:
  - `MONGO-TXN-C1`: 단일 document 연산은 이미 원자적이라 다수 실무 사용 사례에서 transaction 이 필수가 아니라는 공식 서술
  - `MONGO-TXN-C2`~`C4`: transaction 활성화의 배포 형태 요건 — FCV 최소버전(Replica Set 4.0 / Sharded Cluster 4.2), storage engine 조합(primary WiredTiger 필수), `writeConcernMajorityJournalDefault: false` shard 배제
  - `MONGO-TXN-C5`~`C7`: read concern(기본 `"local"`)·write concern(기본 `w:"majority"` 또는 `w:1`, 버전 의존) 기본값 결정 체인과 "개별 write op 에 명시적 write concern 금지" 제약
  - `MONGO-TXN-C8`: session 종료로 인한 transaction abort — 시간 초과와는 별개의 abort 트리거이지만 "transaction 이 무한정 열려있지 않는다"는 원칙의 부분 근거
  - `MONGO-TXN-C9`: "runtime limit" 이 공식 문서에서 별도 usage consideration 으로 인정된다는 사실 — 단 구체 수치는 없음
  - `MONGO-TXN-C10`: `commitTransaction` 재시도 시 write concern 승격 규칙 — 단 일반 transient error 재시도 패턴 전체는 아님
- 이 자료가 증명하지 않는 것:
  - **`transactionLifetimeLimitSeconds` 의 정확한 기본값과, 시간 한계 초과 시의 구체적 abort 동작·에러 코드** — 이 URL 은 "runtime limit" 을 언급만 하고 상세를 `Production Considerations for Transactions` 페이지로 위임한다. 그 페이지는 이번 dispatch 에 포함되지 않음(1 dispatch = 1 URL)
  - **TransientTransactionError / UnknownTransactionCommitResult 라벨 기반의 일반 재시도 루프 패턴** — 이 URL 은 `commitTransaction` 재시도 시 write concern 규칙 하나만 언급하며, 드라이버별 에러 처리 가이드에 있는 전체 재시도 패턴은 다루지 않음
  - standalone(비-replica-set) `mongod` 인스턴스에서 transaction 시도 시 정확한 거부 메커니즘(기동 시 거부 vs 런타임 에러) — 이 URL 은 지원 범위를 replica-set/sharded-cluster 로 positively 서술할 뿐, standalone 명시적 거부 문구는 없음
  - 특정 드라이버(Java Reactive Streams, Spring Data MongoDB 등)가 transaction 을 어떤 API 로 노출하는지 — 이 자료는 서버/개념 문서
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - `transactionLifetimeLimitSeconds` 기본값과 초과 시 동작 — 별도 raw 자료(`transactions-production-consideration-mongodb-official` 가칭) dispatch 필요
  - ca-skeleton 이 실제로 채택할 MongoDB 배포가 replica set 인지 sharded cluster 인지(양쪽 FCV 요건이 다름)
  - Spring Data MongoDB(또는 채택할 드라이버)가 이 기본값들을 어떤 설정 키로 노출하는지

## 메모

- 사용자가 명시적으로 요구한 "transactionLifetimeLimitSeconds 같은 실행 시간 한계와 초과 시 abort 동작" 및 "transient transaction error / retry 권고"는 이 URL(`/docs/manual/core/transactions/`)의 fetch 결과에 상세 수치·패턴으로 존재하지 않았다. 대신 이 페이지가 "runtime limit" 을 별도 considerations 로 인정하고 Production Considerations 페이지로 위임한다는 사실(C9)과, `commitTransaction` 재시도 시 write concern 규칙(C10)만 verbatim 으로 확보했다. Self-Grep 통과분만 claim 화했고, 구체 수치는 fabrication 방지를 위해 claim 에 포함하지 않았다.
- WebFetch 로 1차 처리한 결과가 원문 표(FCV 표 등)를 산문으로 재구성하면서 일부 수치 매핑이 모호해질 위험이 있어, curl 로 원본 HTML 을 직접 받아 self-grep 검증했다(WebFetch 결과는 참고용으로만 사용, 최종 인용은 curl 원문 기준).
- 추가로 봐야 할 동일 출처 페이지: `https://www.mongodb.com/docs/manual/core/transactions-production-consideration/` (runtime limit 구체 수치, `transactionLifetimeLimitSeconds`), 드라이버별 transient transaction error 처리 가이드(예: `https://www.mongodb.com/docs/drivers/node/current/fundamentals/transactions/` 등 언어별 페이지)

## 관련

- 같은 주제 다른 official-doc: [[raw/official-docs/write-concern-mongodb-official]] (write concern `w`/`j`/`wtimeout` 상세), [[raw/official-docs/read-preference-mongodb-official]] (read preference 5종 모드 및 트랜잭션 내 `primary` 고정 제약)
- 이 자료를 인용한 wiki 요약: `[[wiki/concepts/...]]` (생성 시)