MongoDB Multi-Tenancy

MongoDB Multi-Tenancy Architecture Patterns

Overview

Multi-tenancy in MongoDB means a single deployment serves multiple customers (tenants) while keeping their data logically or physically isolated. The right architecture depends on the number of tenants, their relative size, compliance requirements, and how much operational complexity you can absorb.

When to use this skill

When NOT to use this skill

Quick decision flowchart

Need contractual isolation, dedicated throughput, or custom cloud region per tenant?
├─ Yes → Model D: Separate Atlas Project per tenant
└─ No — How many tenants?
        ├─ <100, stable, varied schemas → Model C: Separate database per tenant
        ├─ Growing (100s–millions), uniform schemas → Model A: Shared collection
        └─ Mixed tiers → Hybrid: A for SMB, C for mid-market, D for enterprise

1. Tenant Isolation Models

Model A: Shared Collection — every document has tenantId field; compound indexes lead with tenantId; scalable to millions of tenants

Model B: Collection-per-tenant — AVOID; hits 1,000 data files/node limit quickly

Model C: Database-per-tenant — strong RBAC isolation; best for <100 tenants with varied schemas

Model D: Atlas Project-per-tenant — hardest isolation; separate VPC, billing, API keys; requires Atlas Admin API automation

Hybrid (Production SaaS)

2. Shard Key Design and Zone Sharding

Always compound shard key with tenantId prefix: { tenantId: 1, _id: 1 }

Strategy Use when Risk
{ tenantId: "hashed" } Many small similar tenants No zones; scatter-gather range queries
{ tenantId: 1, _id: 1 } Mixed sizes; data residency Jumbo chunks for large tenants
{ tenantId: 1, timestamp: 1 } Time-series Hot shard for large tenants

Zone sharding (MongoDB 6.0+):

sh.addShardToZone("shard-eu-west-1", "EU")
sh.updateZoneKeyRange("app.events", { tenantId: "eu-" }, { tenantId: "eu-￿" }, "EU")

Atlas Global Clusters = managed zone sharding; shard key { location: 1, _id: 1 }.

3. RBAC and Connection Security

4. Connection Pooling

5. Schema Design

6. Atlas Projects as Hard Isolation

Per-project isolation: DB users, network access lists, PrivateLink, API keys, alerts, backup, BYOK encryption.

Provision via Atlas Admin API v2 or Terraform mongodbatlas_project + mongodbatlas_cluster.

7. Billing and Cost Chargeback

8. Tenant Lifecycle

9. Row-Level Security Patterns

  1. Query filter injection (recommended): TenantScopedCollection middleware automatically appends tenantId to all operations
  2. MongoDB views: read-only pre-filtered view per tenant; grant role on view not base collection
  3. Atlas App Services rules: %%user.custom_data.tenantId — requires populating custom user data on provisioning; strongest guarantee (enforced before query runs)

10. Anti-Patterns

# Anti-Pattern Impact
AP-1 No tenantId leading field in compound indexes Full collection scan
AP-2 Omitting tenantId from query filters Cross-tenant data leakage
AP-3 Unscoped analytics on secondary Noisy-neighbor CPU/IO
AP-4 Unbounded $push arrays per tenant 16MB document limit
AP-5 No TTL indexes on short-lived tenant data Unbounded storage
AP-6 All enterprise tenants in one Atlas Project No billing isolation
AP-7 Collection-per-tenant (Model B) 1,000 file limit hit
AP-8 Default maxPoolSize in Lambda Connection exhaustion
AP-9 Single-field tenantId shard key Jumbo chunks
AP-10 Queries without shard key prefix Scatter-gather

References

See Also

[[mongodb-schema-design]] [[mongodb-sharding]] [[mongodb-atlas-expert]] [[mongodb-security-architecture]] [[mongodb-indexes-deep]] [[mongodb-atlas-iac]]