# MongoDB 플랫폼 — 지원 매트릭스 설계서 §4. 이 파일은 플랫폼이 우연히 돌아가는 환경이 아니라 *인증한* 환경을 적는다. 이 표에 없는 구성은 누군가 그 구성으로 게이트를 돌리고 행을 더하기 전까지 지원하지 않는다. ## 1. 런타임 기준 | 구성 요소 | 버전 | 정책 | |---|---|---| | Java | 21 | 저장소 런타임 기준. | | Spring Boot | `gradle/libs.versions.toml`의 `springBoot` | BOM이 관리한다. driver를 따로 덮어쓰는 것은 금지한다. | | Spring Data MongoDB | Boot BOM이 정한다 | repository와 `MongoTemplate` 통합. | | MongoDB Java Driver | Boot BOM이 정한다 | 모듈에서 직접 고정하지 않는다. | | Micrometer | Boot BOM이 정한다 | driver 자체 관측. | | Testcontainers | Boot BOM이 정한다 | replica set, failover, migration, compatibility lane. | BOM이 정한 실제 버전은 leaf의 잠금 파일 `src/adapter/outbound/persistence-mongo/gradle.lockfile`에 있다. 버전을 이 표에 옮겨 적지 않는다. 옮겨 적은 숫자는 다음 업그레이드에서 틀린 글이 된다. 설계의 기준은 Spring Boot 4.1 계열 / Spring Data MongoDB 5.1 계열이다. 이 저장소는 Spring Boot 4.0 계열 / Spring Data MongoDB 5.0 계열이므로, 플랫폼은 둘에 공통인 API 면만 쓴다. [repository-adaptation.md](repository-adaptation.md) §3을 본다. ## 2. 서버 버전 | Lane | 버전 | 고정한 이미지(key) | Gradle task | |---|---|---|---| | 주 인증 | MongoDB 8.0 | `mongo-8` | `mongoReplicaSetTest`, `mongoFailoverTest` | | 호환성 | MongoDB 7.0 | `mongo-7` | `mongoCompatibilityTest` | | 네트워크 장애 주입 | — | `toxiproxy` | `mongoFailoverTest` | 이미지는 고정하고 `latest`를 쓰지 않는다. 바뀌는 tag를 쓰면 인증 결과는 행에 적은 버전이 아니라 그날 아침 받은 무언가를 설명한다. 이미지의 정본은 `gradle/container-images.properties`다. 표의 key마다 digest와 그 digest의 tag(주석)가 거기 있다. patch 버전은 이 표에 옮겨 적지 않는다. 새 patch 버전을 시험할 때는 `-PmongoPrimaryImage=…` / `-PmongoCompatibilityImage=…`로 덮어쓰고, 게이트가 통과하면 그 파일을 고친다. `MongoVersionMatrix.standard()`가 이 표의 기계용 형태다. 그 밖의 버전은 `certifies()`에서 실패한다. ## 3. 토폴로지 | 토폴로지 | 상태 | 인증하는 것 | 인증하지 않는 것 | |---|---|---|---| | Standalone | **smoke만** | 기본 CRUD와 매핑. | 운영 profile이 아니고 Stable 릴리스 증거로 세지 않는다(D-03). Standalone 서버 위의 운영 profile이나 `platform.transactions=true`는 `MongoStartupValidator`가 시작할 때 거부한다. | | 노드 하나짜리 replica set | **로컬 기본값**(D-02) | transaction, retryable write, change stream — 운영과 같은 의미. | 선출. 노드 하나짜리 set은 선출을 하지 않으므로 여기서는 failover 동작을 시험하지 않는다. | | 노드 세 개짜리 replica set | **Stable 운영 게이트** | 위의 모든 것과 primary failover, commit 결과를 모를 때의 처리. | shard 라우팅. | | Sharded cluster | **Advanced 게이트** | shard key 라우팅 분류, scatter-gather 거부, `admin` plane 작업. | Stable 게이트에 들지 않는다. | | Atlas / provider 관리형 | **인증 안 함** | 실제 대상 배포에서의 암호화는 도입하는 쪽이 만들 증거다. | 검색과 vector 검색은 이 leaf에 구현이 없다. native `$search` 명령은 등록한 D3 연산으로 `PolicyAwareMongoNativeGateway`를 거쳐야만 갈 수 있다. | ## 4. Stable API와 client 세대 | Plane | Stable API | 용도 | |---|---|---| | D1 표준 문서 영속성 | V1, `apiStrict=true` | repository, 타입 있는 query, atomic update, 낙관적 revision. | | D2 고급 문서 연산 | V1, `apiStrict=true` | `MongoTemplate`, transaction, bulk, aggregation, keyset cursor. | | D3 명시적 Mongo capability | strict 아님 | native BSON, CSFLE/QE, shard를 아는 연산 — 각각 등록한 capability 뒤에 있다. | | D4 Admin plane | strict 아님 | collection, validator, index, migration, shard, repair 명령. credential도 client도 따로다. | D3는 날것의 client로 빠지는 출구가 아니다. 모든 호출은 이 순서대로 지나간다: capability 등록 → database profile → collection 허용 목록 → 연산 이름 → timeout → 일관성 profile → 결과 상한 → trace → 가리기 → 명령 분류 → D4 거부. ## 5. Validation action Stable validation action은 `error`와 `warn`이다. `errorAndLog`는 7.0이나 8.0에서 Stable 계약에 들지 **않고**, `MongoValidatorDescriptor`가 거부한다. ## 6. 명시적으로 지원하지 않는 것 설계 §3.4에 따라 아래는 하나도 제공하지 않는다. 하나라도 더하는 것은 기능 요청이 아니라 설계 변경이다. - 범용 `CommonMongoRepository`. - 실행 중 임의의 `runCommand`. - 운영에서 index 자동 생성. - Standalone 운영 계약. - 정확한 업무 일정 도구나 유일한 접근 제어로서의 TTL. - 날것의 change event를 외부 업무 통합 이벤트로 내보내기. - 새 파일의 정본으로서의 GridFS. - 오래 사는 BSON schema로서의 Java FQCN. - 상한 없는 skip 페이지 나누기, 상한 없는 aggregation pipeline, 상한 없는 regex, 상한 없는 결과. ## 7. Capability 등급 | 등급 | Capability | 켜는 법 | |---|---|---| | Stable, 자동 구성 | 매핑과 BSON converter, 명령형 실행, atomic update, bulk 부분 결과, 일관성 profile, 재시도/변환, 연산 예산, 관측, 타입 있는 client profile, 시작 검증, health | `app.persistence-mongo.enabled=true`일 때 bean을 등록한다. | | Stable, 라이브러리 API | transaction, causal session, 낙관적 revision, query builder와 keyset 페이지 나누기, aggregation executor, schema/index/validator manifest와 diff, TTL 계약, GeoJSON, migration runner, admin plane, native capability gateway | 도입하는 쪽의 어댑터 leaf가 이 leaf를 `implementation`으로 받고 타입을 만든다. | | Advanced, 라이브러리 API | shard를 아는 query와 shard admin, CSFLE, Queryable Encryption(equality/range), shared collection tenancy 정책 | 위와 같고, 그 capability를 켠 flag의 `MongoAdvancedCapabilityGuard`가 더 필요하다. 설정 속성은 없다. | | Experimental, 라이브러리 API | tenant마다 database client registry와 migration coordinator, reshard 승인 | Advanced와 같다. 승격에는 [ADR-MONGO-ADV-001](../adr/ADR-MONGO-ADV-001-capability-promotion.md)의 증거가 더 필요하다. | 검색, vector 검색, time series, GridFS 호환은 구현 없는 interface였고 2026-09-25에 지웠다 (`docs/capability-status.md`).