Multi-tenant architecture
Database isolation patterns for SaaS: shared schema, separate databases, and hybrid.
Multi-tenancy is the financial foundation of SaaS: one application serves dozens, hundreds, or thousands of customers, each seeing only their own data. The catch is that data isolation must be ironclad — a bug or a shortcut can expose one customer's data to another. This template maps the three core architectures: shared schema (rows tagged by tenant_id, isolated by row-level security), separate database per tenant (full isolation, higher cost), and hybrid approaches (shared metadata, isolated user data).
The choice depends on your scale and your risk tolerance. Early-stage teams optimize for cost and speed; mature platforms reinvest in isolation as data sensitivity rises. This diagram helps you document which approach you picked and why.
When to use this template
- SaaS architecture review — clarify for stakeholders why you chose shared databases instead of separate, and how row-level security protects one customer's data from another.
- Onboarding new engineers — explain the isolation strategy so they understand that every query must filter by tenant_id, and that the database enforces it if they forget.
- Compliance and security audits — show auditors exactly how you enforce tenant isolation, so they can trace the guarantee through code and database rules.
How to adapt it
Build out the isolation guarantees for your real architecture:
- Add billing and usage tables that track per-tenant consumption, showing how the isolation strategy affects metering and quota enforcement.
- Expand the API Gateway to show authentication (validating the token identifies a tenant), authorization (checking which resources that tenant can access), and logging (auditing which tenant touched which data).
- Insert data sync / replication paths if you maintain read replicas or backup databases, showing how isolation is preserved in secondary systems.
Visual edits regenerate clean Mermaid, so you can sketch different isolation topologies and share the diagram with your security and database teams.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
classDiagram
class Tenant {
tenant_id
name
plan
}
class SharedSchema {
users
documents
settings
}
class SeparateDatabase {
isolated_db_per_tenant
full_isolation
higher_cost
}
class HybridApproach {
shared_metadata
isolated_user_data
balanced_cost
}
class ApiGateway {
routes_by_tenant_id
validates_access_token
enforces_isolation
}
ApiGateway --> Tenant : routes to
Tenant --> SharedSchema : option_1
Tenant --> SeparateDatabase : option_2
Tenant --> HybridApproach : option_3
SharedSchema --> SharedSchema : row_level_security
Frequently asked questions
- What is multi-tenant architecture?
- Multi-tenant architecture serves multiple customers (tenants) from a single application. The tenant is the unit of isolation — one company's data must never be visible to another. Architects choose between shared databases (rows tagged by tenant_id, enforced by row-level security), separate databases per tenant (full isolation, higher cost), or hybrid (shared metadata, isolated data). Each trades cost against operational overhead and data safety.
- Why not just give every tenant their own database?
- Separate databases guarantee isolation and make per-tenant scaling easy, but they multiply infrastructure costs, backup complexity, and operational toil. Most SaaS platforms share a database and enforce isolation at the application and database (row-level security) layers. This trades operational simplicity for the discipline to check tenant_id on every query.
- What happens if a tenant ID leaks in a query?
- If code forgets to filter by tenant_id, a user in one tenant can see data from all tenants — a data breach. This is why multi-tenant systems use row-level security (RLS) at the database layer: even a buggy query that leaves out the WHERE clause gets filtered by RLS rules. RLS is the safety net.
- How do I choose between shared schema, separate databases, and hybrid?
- Shared schema is cheapest and best for early-stage SaaS; add row-level security and test isolation thoroughly. Separate databases become attractive when tenants are large enough to need their own infrastructure. Hybrid (shared metadata, isolated data) sits in the middle. Diagram your option with this template and walk through the isolation rules with your team before building.