# Advanced — Multi-tenancy **Capability:** `MongoCapability.SHARED_COLLECTION_TENANCY`(Advanced), `MongoCapability.DATABASE_PER_TENANT`(Experimental) **켜는 법:** 라이브러리 API다. 설정 속성은 없다. 서비스의 어댑터가 진입점을 만들 때 `MongoAdvancedCapabilityGuard`를 넘긴다. 이 guard는 그 capability를 켠 `MongoAdvancedCapabilityFlags`로 만든다. 켜지 않았으면 생성 자체가 거부된다. shared collection tenancy에는 진입점이 없다(타입이 모두 정책이다). 그래서 실제로 검사하는 것은 `DATABASE_PER_TENANT`뿐이다. ## 1. Shared collection 모든 tenant의 문서가 collection 하나에 있고, tenant 필드로 구분한다. `MongoTenantContext`가 tenant를 들고 다닌다. `MongoTenantPredicateInjector`가 tenant 조건을 세 곳에 넣는다: 모든 query, 모든 atomic filter, aggregation의 **첫** stage. 도입하는 쪽의 repository가 tenant 범위의 모든 경로에서 이 injector를 부른다. 이 leaf에는 tenant 범위 작업을 대신해 주는 facade가 없다. 빠지면 안 되는 세부가 셋이다. - **관례가 아니라 주입이다.** query마다 tenant 조건을 스스로 넣기를 기대하면 `where(...)` 하나만 빠져도 tenant 사이로 데이터가 샌다. injector는 조건을 구조적으로 넣는다. - **aggregation 첫 stage.** `firstStageMatch(...)`는 tenant `$match`를 맨 앞에 둔다. tenant filter보다 먼저 도는 `$lookup`이나 `$group`은 뒤 stage가 결과를 걸러도 이미 경계를 넘은 것이다. - **tenant가 없으면 「모든 tenant」가 아니다.** injector는 `Optional`를 받는다. tenant가 빠진 경우를 정책이 명시적으로 정하게 하려는 것이다. 조건이 조용히 사라지면 안 된다. `MongoTenantManifestValidator.validate(manifest, tenantScopedUniqueIndexes)`는 tenant별이어야 하는 unique index가 정말 tenant 필드를 포함하는지 본다. shared collection에서 `email` 하나만으로 만든 unique index는 email을 모든 tenant에 걸쳐 유일하게 만든다. 그러면 tenant A가 쓴 주소를 tenant B가 등록할 수 없다. 결함이면서 정보 유출이다. `requireShardKeyAnalysed(...)`는 shared collection tenant 모델을 shard하기 전에 shard key 준비 보고서를 요구한다. tenant id를 shard key 앞부분으로 쓰면 가장 큰 tenant가 shard 하나에 몰린다. ### 관측 `tenantId`와 `rawTenantId`는 `MongoObservationConvention`의 금지 tag 목록에 있다. 값의 가짓수가 고객 수만큼 늘고, tag가 tenant 식별자를 metric 저장소로 보낸다. ## 2. tenant마다 database (Experimental) `MongoTenantClientRegistry`는 tenant마다 client를 하나 둔다. 개수 상한이 있고 쓰지 않는 client는 내보낸다. tenant를 어느 database에 대응시킬지는 도입하는 쪽의 코드가 정한다. `acquire`는 `Lease`를 돌려주고, 그 client는 lease를 모두 닫을 때까지 쓰는 중이다. 쓰는 중인 client는 얼마나 오래전에 받았든 내보내지 않는다. 내보낸 client를 닫다가 실패하면 그 tenant 대신 `evictionCloseFailures()`가 센다. 닫기를 부른 다른 tenant의 `acquire`는 실패하지 않는다(round9 리뷰 2026-11-12, RR9-01-27). Experimental인 이유가 분명하다. 작을 때는 맞고, 클 때는 한계가 없다. tenant database마다 connection, file handle, 모니터링 가짓수가 든다. tenant 20개에서는 잘 돌고 2,000개에서는 쓰러진다. 기능 테스트로는 둘을 구분할 수 없다. 승격하려면 운영 규모의 증거가 필요하다. `MongoTenantLifecyclePolicy`: - `requireActivationReady(tenantKey, schemaAndIndexesValidated)` — schema와 index를 검증하기 전에는 tenant를 켜지 않는다. 먼저 켜면 첫 고객 요청이 마이그레이션 시험이 된다. - `requireDeleteAllowed(...)` — 삭제에는 보존 기간에 대한 명시적 결정이 필요하다. tenant database를 지우면 되돌릴 수 없고 백업 대상도 함께 사라진다. `MongoTenantMigrationCoordinator`는 tenant database 전체에 마이그레이션을 돌리고 결과를 tenant별로 낸다. 일부 실패는 정상이고 tenant별로 보고해야 한다. database 500개에 대해 「마이그레이션 실패」 한 줄은 아무도 대응할 수 없는 보고다. ## 3. 고르기 | | Shared collection | tenant마다 database | |---|---|---| | 격리 | 논리적, 주입으로 강제 | 물리적 | | tenant 수 | 제한 없음 | connection과 file handle이 제한 | | tenant별 복구 | 어렵다 | 자연스럽다 | | 시끄러운 이웃 | 자원을 나눠 쓴다 | 격리된다 | | 마이그레이션 | collection 하나 | database N개, 일부 실패가 생긴다 | | tenant를 넘는 query | 가능하다(그래서 막아야 한다) | 구조상 불가능하다 | 기본은 shared collection이다. tenant마다 database는 tenant 수가 적고, 계약상 격리나 tenant별 복구가 필요한 경우에 쓴다. ## 4. 실패 복구 | 증상 | 원인 | 조치 | |---|---|---| | 다른 tenant의 데이터가 보인다 | 어떤 작업이 `MongoTenantPredicateInjector`를 건너뛰었다 | 보안 사고로 다룬다. 그 경로를 찾아 막고 접근 기록을 감사한다. | | tenant를 넘어 unique 제약이 걸린다 | unique index에 tenant 필드가 없다 | tenant 필드를 앞에 둔 index로 다시 만든다. validator가 배포 전에 잡는다. | | shard 하나에 데이터 대부분이 있다 | tenant id가 shard key 앞부분이고 큰 tenant가 하나 있다 | 가짓수가 많은 뒷부분을 더해 shard key를 다듬는다. | | connection이 바닥난다 | tenant마다 database가 connection 예산을 넘었다 | 규모 한계다. 합치거나 shared collection으로 옮긴다. | | 마이그레이션이 tenant 일부에만 적용됐다 | 정상이다 | `MongoTenantMigrationCoordinator`가 tenant별로 보고한다. 실패한 것만 다시 돌린다. | ## 5. 승격 증거 shared collection tenancy: 실제 토폴로지 증거, tenant를 넘는 접근을 다룬 보안 검토, 마이그레이션 경로, 실패 사례(query·atomic filter·aggregation 첫 stage에서 주입이 되는지 증명), 이 runbook. tenant마다 database는 여기에 **운영 규모 증거**가 더 필요하고, 그것이 생길 때까지 Experimental이다.