문제: 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 문서의 파일 존재만 본다.
131 lines
7.8 KiB
Markdown
131 lines
7.8 KiB
Markdown
# 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. 배포와의 순서
|
|
|
|
```text
|
|
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를 되돌리면 아직 절반의 인스턴스에서 도는 코드가 깨진다.
|