문제: docs/mongodb 아래 살아 있는 문서 14개가 영어였고(문서 검사 language 예외), 몇 가지 주장이 지금 코드와 달랐다. - repository-adaptation.md가 registry의 leaf 수(19)와 Spring Boot 버전을 옮겨 적었다(number 예외 두 줄). - 같은 문서와 advanced/signoff/README.md가 scripts/verify-mongodb-platform.sh· verify-mongodb-advanced.sh를 2026-08-15에 지웠다고 했다. 두 스크립트는 지금도 있고 lane을 돌린다. - testkit을 `testkit` source set에 둔다고 했다. 지금은 `testFixtures`(ADR-BUILD-001)와 `mongoProviderTestkit`이다. `…mongo.architecture`도 main이 아니라 testFixtures에 있다. - ArchUnit 규칙 이름 `stableNeverDependsOnAdvanced`·`productionNeverDependsOnTestkit`은 없다. 실제는 MongoModuleBoundaryTest의 `noStablePackageDependsOnAnAdvancedCapability`· `noProductionPackageDependsOnTheTestkit`이다. - support-matrix.md의 Boot·Spring Data·driver·Micrometer·Testcontainers 버전이 lockfile과 달랐다(예: driver 5.6.1 → 5.6.5). - consumer-leaf-guide.md가 템플릿에 없는 Gradle 경로를 인라인 코드로 적었다 (reference 예외). - document-modeling-guide.md가 타입 metadata를 bson-mapping-guide §4로 가리켰다(§5). 고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·표 구조는 원문으로 둔다. 버전과 leaf 수는 숫자 대신 정본(src/gradle/libs.versions.toml, registry, gradle.lockfile, container-images.properties)을 가리킨다. 서비스가 만들 leaf의 확인 명령은 다른 단계와 같이 코드 블록에 두고 템플릿에 없는 경로라고 밝힌다. 버린 대안: support-matrix 버전을 lockfile 값으로 고쳐 적기. 다음 업그레이드에서 다시 틀리고, 같은 시간에 도는 의존성 세션과 같은 줄을 고치게 된다. 위험·한계: 내용 감사는 하지 않았다. 번역하며 본 불일치만 고쳤다. 설계 번호(§, D-xx)는 그대로 두었다. 검증: python3 scripts/check-docs.py rc=0(이 폴더 language·reference·number 예외 줄 0). docs/mongodb를 읽는 테스트는 주석뿐이다(`grep -rn 'docs/mongodb' src --include=*.java` — package-info.java·MongoModuleBoundaryTest 주석). scripts/verify-mongodb-advanced.sh는 advanced 문서의 파일 존재만 본다.
4.9 KiB
Advanced — Sharding
Capability: MongoCapability.SHARDING
켜는 법: 라이브러리 API다. 설정 속성은 없다. 서비스의 어댑터가 진입점을 만들 때
MongoAdvancedCapabilityGuard를 넘긴다. 이 guard는 그 capability를 켠 MongoAdvancedCapabilityFlags로
만든다. 켜지 않았으면 생성 자체가 거부된다.
상태: Advanced. reshard 진행 관리는 Experimental로 남는다.
요구 사항
| 토폴로지 | 실제 sharded cluster. replica set으로는 라우팅을 시험할 수 없다. |
| 서버 | MongoDB 7.0 또는 8.0. |
| 권한 | admin plane에는 MongoPrincipalRole.SHARD_ADMIN. 애플리케이션 role은 바뀌지 않는다. |
| 게이트 | 승격하지 않았다. 등록된 mongoShardedTest lane이 없고, sharded cluster는 이 repo가 띄우는 환경이 아니다. src/adapter/outbound/persistence-mongo/release/release-contracts.json의 experimental_contracts에 있다. 승격하려면 lane, 그 lane이 요구하는 클래스, 보호된 환경의 증거가 먼저 있어야 한다. |
Shard key
ShardKeyDescriptor는 key를 ShardKeyPart의 순서 있는 목록과 ShardStrategy로 선언한다.
| 전략 | 나누는 기준 | 비용 |
|---|---|---|
RANGE |
값의 범위 | 범위 조회가 특정 shard로 간다. 계속 커지는 key(timestamp, ObjectId)는 모든 insert를 shard 하나로 보낸다. |
HASHED |
key의 hash | insert가 고르게 퍼진다. 모든 범위 조회가 scatter-gather가 된다. |
둘 다 잘하는 전략은 없다. 그래서 기본값으로 두지 않고 선언하게 한다.
라우팅 분류
ShardAwareQueryValidator는 실행 전에 query마다 분류한다.
MongoRoutingClassification |
뜻 |
|---|---|
TARGETED |
shard key 전체가 있다. shard 하나가 답한다. |
PREFIX_TARGETED |
복합 key의 앞부분이 있다. shard 일부가 답한다. |
SCATTER_GATHER |
shard key 조건이 없다. 모든 shard가 답한다. |
REJECTED |
profile이 금지한 곳의 scatter-gather. |
scatter-gather는 오류가 아니다. 모든 shard가 필요한 query도 있다. 다만 선언해야 한다. 선언하지 않은
scatter-gather는 MongoShardRoutingException을 던진다. 이유는 이렇다. scatter-gather는 shard 하나짜리
개발 cluster에서는 모든 테스트를 통과하고 cluster가 커진 뒤에야 느려진다. 그때는 query가 이미 운영에
있고, 고치려면 schema를 바꿔야 한다.
지원하지 않는 조합
- shard key의 앞부분이 아닌 필드의 unique index. MongoDB가 shard를 넘어 강제할 수 없다. 조회 때가 아니라 index를 만들 때 실패한다.
- 여러 shard의 문서를 건드리는 transaction은 지원하지만 shard를 넘는 two-phase commit 비용이 든다. transaction의 문서를 한곳에 모으는 shard key를 고른다.
- sharded collection의 CSFLE: 거부하는 조합은 encryption.md를 본다.
Admin plane
MongoShardingAdminGateway(D4, SHARD_ADMIN credential)가 shard-collection, refine-shard-key,
reshard를 맡는다.
ShardKeyAnalyzer는 collection을 shard하기 전에 ShardKeyReadinessReport를 만든다: 값의 가짓수,
빈도 치우침, 단조 증가 여부. 가짓수가 적은 key는 나눌 수 없는 jumbo chunk를 만든다. 단조 증가하는
key는 한 shard에 부하를 몰아준다. 둘 다 보고서에는 보이고 기능 테스트에는 보이지 않는다.
reshard에는 ReshardApproval이 필요하다: 승인한 사람 이름과 작업 시간대. reshard는 collection을 다시
쓴다. 작업 중에 데이터를 복제하고 IO를 가득 채운다. 실행 중에 하는 작업이 아니고, 타입도 그런 척하지
않는다.
실패 복구
| 증상 | 원인 | 조치 |
|---|---|---|
MongoShardRoutingException |
선언하지 않은 scatter-gather | 조건에 shard key를 넣는다. 아니면 검토를 거쳐 그 query를 profile에서 scatter-gather로 선언한다. |
| Jumbo chunk | 가짓수가 적은 shard key | reshard를 생각하기 전에 shard key를 다듬는다(뒷부분을 더한다. 데이터를 지우지 않는다). |
| 한 shard에 부하가 몰린다 | 단조 증가하는 range key | 가짓수가 많은 앞부분으로 다듬거나, 범위 조회가 필요 없으면 hashed로 reshard한다. |
| balancer가 끝나지 않는다 | 오래 도는 작업이 chunk 이동을 막는다 | 긴 transaction과 cursor를 찾는다. balancer는 그것들을 기다린다. |
승격 증거
ADR-MONGO-ADV-001에 따라: 실제 sharded cluster
증거, SHARD_ADMIN role의 보안 검토, 이미 있는 unsharded collection의 마이그레이션 경로, 실패 사례(선언하지
않은 scatter-gather 거부, jumbo chunk 감지), 그리고 runbook으로서 이 문서. reshard 진행 관리는 운영
규모 증거가 생길 때까지 Experimental이다.