> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택 - 작성일: 2026-08-13 - 요약: 인덱스와 스키마 변경은 관리 평면이 맡는다는 결정이다. - 현재 정본: `docs/mongodb/schema-index-migration-guide.md` # ADR-MONGO-004 — index와 schema 변경은 admin plane의 것이다 - **상태:** 채택 - **날짜:** 2026-08-13 - **설계 출처:** 설계 §21–§25, 결정 D-11, D-13 ## 배경 Spring Data는 애너테이션에서 index를 자동으로 만들 수 있다. 노트북에서는 편하다. 문서 1억 개가 든 collection에서 index 만들기는 용량 사건이다: primary의 CPU, IO, 메모리를 몇 분에서 몇 시간 동안 쓰고, pod 하나가 재시작했다는 이유로 시작된다. 더 나쁘게, pod N개가 재시작하면 N번 시작하고, 승인 단계도, 그 index가 필요한 코드와의 순서도, 나중에 무엇을 만들었는지의 기록도 없다. schema validator도 같은 모양인데 날이 더 서 있다: 데이터가 있는 collection에서 validator를 조이면, 쓸 때는 적법했던 문서에 대한 쓰기를 거절한다. TTL은 세 번째 모양이다. scheduler처럼 보이지만 아니다: TTL monitor는 대략 1분에 한 번 돌고 batch로 지우므로, 만료된 문서가 몇 분에서 몇 시간 동안 읽히는 것이 예사다. ## 결정 **index와 validator는 manifest에 선언하고 admin plane(D4)이 적용한다.** 운영에서 자동 index 만들기는 끈다. 1. `MongoManifestRegistry`가 collection마다 선언한 index(`MongoIndexManifest`)와 validator(`MongoSchemaManifest`)를 가진다. manifest가 정본이고 pull request에서 리뷰한다. 2. `MongoIndexDiffEngine`이 manifest를 관찰한 상태와 비교해 빠진 index, 남는 index, *바뀐* index를 알린다. 바뀐 것은 다시 내지 않고 알린다: MongoDB는 정의가 움직인 index를 소리 없이 다시 만들지 않는다. 3. `MongoIndexApplyPolicy`가 환경이 할 수 있는 것을 정한다 — `APPLY`(로컬), `APPLY_WITH_DIFF`(staging), `DIFF_WITH_APPROVED_APPLY`(운영), `REPORT_ONLY`(감사). 4. **모든 drop은 소유권이 막는다.** `MongoMetadataOwnership`이 `APPLICATION_MANAGED`를 `SEARCH_MANAGED`, `ENCRYPTION_MANAGED`, `EXTERNAL`과 구별한다. 어긋났을 때 지울 수 있는 것은 애플리케이션이 관리하는 객체뿐이다. 소유권 없는 diff 엔진은 결국 `enxcol_.customers.esc`를 지우자고 제안하고, 「drift 도구가 치웠다」는 아주 나쁜 사고 요약이다. 5. **은퇴는 단계를 밟는다.** `MongoIndexRetirementState`가 index를 선언됨 → 숨김 → 안 쓰는 것 확인 → 지울 수 있음으로 옮기고, 전이마다 배포 한 번이다. 숨기기는 바로 되돌릴 수 있다. 지우기는 다시 만들기다. 6. **Stable validation action은 `error`와 `warn`뿐이다.** `errorAndLog`는 7.0이나 8.0에서 Stable 계약에 속하지 않아 거절한다. 조이기는 `warn`+`MODERATE` → 경고 0 확인 → `error`+`STRICT`로, 배포 두 번에 걸쳐 간다. 7. **TTL은 물리적 치우기일 뿐이다**(D-13). `MongoExpirationAccessPolicy`가 규칙을 말한다: 문서가 있다고 인가가 아니고, 없다고 기한이 아니다. 접근 통제는 만료 필드를 검사하고, 일정은 scheduler를 쓴다. 8. **migration은 checksum을 두고, 잠그고, 전제 조건을 검사하고, 이어서 할 수 있다.** `MongoMigrationRunner`는 적용한 id의 checksum이 바뀌면 단단히 실패한다 — 두 환경이 id 하나 아래 다른 코드를 돌리는 것은 실패한 배포보다 나쁘다. ## 결과 **좋은 점.** index 만들기 일정은 용량을 아는 사람이 잡는다. 모든 단계에서 되돌릴 수 있다. drift는 위험하지 않게 보인다. 아무것도 자기가 가지지 않은 것을 지우지 않는다. **나쁜 점.** index 더하기는 애너테이션이 아니라 manifest 변경 + 적용이다. 로컬 개발은 `APPLY`를 쓰므로 마찰은 그것이 정당한 환경에만 머문다. **버린 대안 — 「feature flag와 함께 자동으로 만들기」.** flag가 운영에서 켜져 있으면 그것이 문제이고, 꺼져 있으면 manifest가 실제 장치이고 애너테이션은 두 번째의 갈라진 정본이다.