# 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를 되돌리면 아직 절반의 인스턴스에서 도는 코드가 깨진다.