Files
clean-architecture-backend-…/docs/mongodb/schema-index-migration-guide.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

7.8 KiB

Schema, index, 마이그레이션 가이드

설계서 §21–§25, 결정 D-13. index와 validator는 manifest에 선언하고, 명시적인 plane이 적용한다. 운영에서 index를 자동으로 만드는 것은 명시적으로 지원하지 않는다(§3.4). 큰 collection의 index 생성은 용량 사건이다. 배포가 그것을 시작해서야 알게 되는 것은 운영 방식이라 할 수 없다.

1. Manifest가 정본이다

MongoManifestRegistry는 collection마다 MongoCollectionManifest를 하나 가진다. 그 안에 있는 것:

  • MongoIndexManifest — 선언한 index(MongoIndexKey, MongoIndexDirection, unique 여부, partial filter, collation)
  • MongoSchemaManifest — 선언한 $jsonSchema validator
  • MongoMetadataOwnership — 관측한 객체마다 누가 소유하는지

drift(선언과 실제의 차이) 처리를 안전하게 만드는 것이 소유 필드다.

소유 소유자 drift일 때 지워도 되나
APPLICATION_MANAGED 이 manifest 그렇다
SEARCH_MANAGED 검색 서비스 아니다
ENCRYPTION_MANAGED Queryable Encryption 아니다
EXTERNAL 다른 누군가(DBA, 다른 서비스) 아니다

소유를 모르는 diff 엔진은 결국 enxcol_.customers.esc나 검색 index를 지우자고 한다. 「drift 도구가 정리했다」는 아주 나쁜 장애 요약이다.

2. Index diff와 적용

MongoIndexDiffEngine은 manifest를 MongoIndexDescriptorView 관측값과 비교해 MongoIndexDiff를 만든다: 빠진 것, 남는 것, 바뀐 것(이름은 같고 정의가 다름. MongoDB는 이것을 조용히 다시 만들지 않으므로 다시 내보내지 말고 보고해야 한다).

MongoIndexApplyPolicy가 diff로 무엇을 할지 정한다.

정책 동작 환경
APPLY 빠진 것을 만든다 local / test
APPLY_WITH_DIFF 빠진 것을 만들고 나머지는 보고한다 staging
DIFF_WITH_APPROVED_APPLY 사람이 승인한 것만 적용한다 production
REPORT_ONLY 절대 쓰지 않는다 감사

삭제는 암묵적으로 일어나지 않는다. MongoIndexRetirementPlan이 index를 MongoIndexRetirementState로 옮긴다 — 선언됨 → 숨김 → 안 쓰임 관측 → 지워도 됨 — 그리고 단계마다 따로 배포한다. index를 숨기면 planner는 무시하지만 유지는 계속된다. 그래서 뜻밖의 회귀는 명령 하나로 되돌린다. 지운 것은 그렇게 되돌릴 수 없다.

3. Validator

MongoValidatorDescriptor는 $jsonSchema, MongoValidationLevel(OFF / MODERATE / STRICT), MongoValidationAction을 가진다.

Stable validation action은 error와 warn뿐이다. errorAndLog는 MongoDB 7.0이나 8.0에서 Stable 계약에 들지 않고, descriptor가 거부한다.

MongoValidatorDiffEngine이 MongoValidatorDiff를 만들고 MongoValidatorApplyPolicy가 적용을 막거나 허락한다. 데이터가 이미 있는 collection의 validator를 조이는 것이 위험한 방향이다. warn + MODERATE로 넣고, 경고 수가 0인지 확인한 뒤, 두 번째 배포에서 error + STRICT로 올린다.

4. TTL

D-13: TTL은 물리적 정리일 뿐이다.

MongoTtlIndexDescriptor가 필드와 expireAfterSeconds를 선언한다. MongoTtlPolicyValidator가 MongoTtlPolicy가 허락하는 것을 강제하고, MongoExpirationAccessPolicy가 중요한 규칙을 말한다.

문서가 있다고 권한이 있는 것이 아니고, 문서가 없다고 기한이 지난 것도 아니다.

TTL monitor는 대략 1분에 한 번 돌고 묶어서 지운다. 그래서 부하가 있으면 문서가 만료 후 몇 분에서 몇 시간 더 남는다. 따라서:

  • 접근 제어는 문서가 있는지가 아니라 만료 필드를 본다. 아직 남아 있는 만료된 session은 유효한 문서이자 무효한 session이다.
  • 업무 일정을 TTL 위에 세우지 않는다. 정해진 때에 일어나야 하는 일이면 일정을 잡는다.
  • TTL 필드는 BSON date여야 한다. 문자열에 건 TTL index는 조용히 아무것도 지우지 않는다.

5. 마이그레이션

MongoMigrationRunner는 다음과 함께 MongoMigration 단위를 실행한다.

  • MongoMigrationId — 순서가 있고 유일하다
  • MongoMigrationChecksum — 내용 hash. 이미 적용한 id의 checksum이 바뀌면 다시 돌리지 않고 바로 실패한다. 적용한 마이그레이션을 고치면 두 환경이 같은 id로 다른 코드를 돌린 것이 된다.
  • MongoMigrationLedger — 무엇이 적용됐는지
  • MongoMigrationLock — 한 번에 runner 하나. rolling 배포는 인스턴스 여럿을 한꺼번에 띄운다
  • MongoMigrationPrecondition / MongoMigrationPostcondition — 전후로 확인한다. 자기 결과를 확인하지 못하는 마이그레이션은 실패를 고객이 발견한다
  • MongoMigrationCheckpoint — backfill을 이어 할 수 있는 위치

MongoMigrationResult는 applied / incomplete / dry-run과 그 이유를 보고한다. INCOMPLETE는 실패가 아니다. 속도를 제한한 backfill이 시간 예산을 다 썼으면 실제 일을 했고 checkpoint를 저장했다. 그것을 실패로 알리면 다음 실행이 처음으로 돌아간다.

MongoCollectionMigrationLedger와 MongoCollectionMigrationLock이 MongoDB에 기대는 구현이다. 빠지면 안 되는 세부가 둘 있고, 둘 다 서버에만 있다.

  • ensureIndexes()가 만드는 ledger의 마이그레이션 id unique index. 이것이 없으면 「아직 적용 안 됨」 읽기를 둘 다 통과한 runner 둘이 둘 다 insert한다. 그러면 ledger는 마이그레이션 하나가 checksum 둘로 두 번 적용됐다고 보고한다. 조작과 구분할 수 없다.
  • lease는 읽고-쓰기가 아니라 조건부 update 한 번으로 잡는다. 비었거나 만료된 lease에만 맞는 filter를 쓰면 서버가 승자를 고른다. runner 둘이 각자 「비었음」을 읽고 쓰면 둘 다 자기가 잡았다고 믿는다.

lease에는 만료가 있다. 그래야 마이그레이션 도중 죽은 runner가 이후 모든 배포를 막지 않는다. batch 사이의 refresh가 lease를 가진 쪽이 아직 살아 있다는 증거다.

Backfill은 이어서 시작하고, 처음부터 다시 하지 않는다

긴 backfill은 끊긴다. 배포, OOM, 노드 교체. checkpoint가 마지막으로 끝낸 key를 적어 두므로 다시 시작하면 처음부터 다시 처리하지 않고 이어 간다. testkit의 MongoBackfillRestartFixture가 정확히 이것을 단언한다: 도중에 죽이고 다시 시작해도 결과가 끊기지 않은 실행과 같고, 끝낸 일을 다시 적용하지 않는다.

Flamingock

FlamingockMongoMigrationAdapter가 플랫폼이 소유한 FlamingockChangeUnitView를 거쳐 Flamingock에 잇는다. FlamingockLedgerAdapter와 FlamingockLockAdapter가 ledger와 lock을 대응시킨다. 공개 계약은 Flamingock 타입을 참조하지 않으므로 마이그레이션을 건드리지 않고 provider를 바꿀 수 있다.

6. 배포와의 순서

1. index를 더한다(크면 숨긴 채로)          -> 배포 N
2. 숨김을 풀고 쓰이는지 확인한다           -> 배포 N+1
3. 그 index에 기대는 코드를 내보낸다       -> 배포 N+1
4. 데이터를 backfill한다                   -> 마이그레이션, 이어 할 수 있음
5. validator를 warn에서 error로 조인다     -> 배포 N+2
6. 옛 index를 은퇴 단계에 따라 내린다      -> 배포 N+3…

단계마다 따로 되돌릴 수 있다. index와 그 index가 필요한 코드를 같은 배포에 넣으면 안전하게 되돌릴 길이 없다. 코드를 되돌리면 index 생성은 계속 돌고, index를 되돌리면 아직 절반의 인스턴스에서 도는 코드가 깨진다.