Files
clean-architecture-backend-…/docs/mongodb/advanced/sharding.md
T
DongHyeonka 24eb1be36d docs(mongodb): MongoDB 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: 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 문서의 파일 존재만 본다.
2026-11-07 17:29:57 +09:00

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이다.