Multi-Tenant Architecture

The Problem

SaaS applications serve multiple customers (tenants) from shared infrastructure. The challenge is balancing cost efficiency (shared resources) with isolation (one tenant’s data, load, or failures shouldn’t affect others). Multi-tenancy touches every layer — database, compute, caching, queues, and storage. You must decide how much isolation each tier of customer gets, how to route requests to the right tenant context, and how to handle tenants that outgrow the shared model.

Architectural Approaches

Architecture

Loading diagram...

Key Components

Data Model

Loading diagram...

Tenant Identification Strategies

Every request must be mapped to a tenant. Common strategies:

Subdomain-based: acme.yourapp.com → tenant “acme”. Parse the Host header, strip the platform domain, look up the tenant by slug. Simple and user-friendly. Requires wildcard DNS and certificates.

Path-based: yourapp.com/acme/... → tenant “acme”. Works without DNS configuration but pollutes the URL namespace. Less common for customer-facing apps.

Custom domain: app.acme.com → tenant “acme”. Lookup domain in the routing table. Best UX for customers but requires custom domain infrastructure (see Custom Domains guide).

JWT/API key: Extract tenant_id from the authentication token. Works for API-first products. The auth system must embed tenant context in the token at login/key-creation time.

Header-based: X-Tenant-ID header set by an upstream gateway. Used in microservice architectures where a gateway handles tenant resolution and downstream services trust the header.

Row-Level Security with PostgreSQL

PostgreSQL’s Row-Level Security (RLS) provides database-enforced tenant isolation in shared-schema mode.

Setup:

1. Add tenant_id column to every table
2. Enable RLS: ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
3. Create policy: CREATE POLICY tenant_isolation ON orders USING (tenant_id = current_setting('app.tenant_id'));
4. At request start, set the session variable: SET app.tenant_id = 'tenant_abc';

Benefits: Even if application code forgets to filter by tenant_id, the database enforces it. This is a defense-in-depth strategy — bugs in application code cannot leak data across tenants.

Caveats:

• RLS adds a small query planning overhead (~1-5%)
• Superuser roles bypass RLS — never use superuser in the application
• Must be applied to every table — easy to miss new tables
• Index on tenant_id is essential for performance
• Connection poolers (PgBouncer) in transaction mode require SET LOCAL instead of SET

Noisy Neighbor Mitigation

The “noisy neighbor” problem occurs when one tenant’s workload degrades performance for others.

Database layer:

• Set per-tenant statement timeouts to kill long-running queries
• Use connection pooling with per-tenant limits (max 10 connections per tenant)
• Monitor per-tenant query latency and alert on outliers
• Consider read replicas for heavy-read tenants

Application layer:

• Per-tenant rate limiting on API endpoints
• Separate job queues for background tasks (or priority queues with tenant-based priority)
• Memory/CPU limits per request using timeouts and circuit breakers

Cache layer:

• Prefix all cache keys with tenant_id to prevent collisions
• Set per-tenant memory limits or use separate Redis databases
• Implement cache eviction policies that don’t let one tenant flush others’ cache

Nuclear option: Automatically migrate noisy tenants to dedicated infrastructure when they consistently exceed thresholds. This is the “tiered isolation” approach — start shared, promote to dedicated as needed.

Real-World Examples

Architectural Tradeoffs

# Learn the System Design of: Multi-Tenant Architecture

You are an expert software architect and teacher. I want to understand multi-tenant architecture as a practical system design capability. (Shared infrastructure with tenant isolation, noisy neighbor protection, and per-tenant customization).

Use the following architectural guide as a learning reference. Avoid one-size-fits-all recommendations. Keep assumptions, costs, and tradeoffs explicit.

---

import { Mermaid, ComponentList, ComponentCard, ApproachList, Approach, Example, Tradeoff } from '@/components/mdx';

## The Problem

SaaS applications serve multiple customers (tenants) from shared infrastructure. The challenge is balancing cost efficiency (shared resources) with isolation (one tenant's data, load, or failures shouldn't affect others). Multi-tenancy touches every layer — database, compute, caching, queues, and storage. You must decide how much isolation each tier of customer gets, how to route requests to the right tenant context, and how to handle tenants that outgrow the shared model.

## Architectural Approaches

<ApproachList>
<Approach
  name="Shared Database, Shared Schema"
  pros={[
    'Lowest infrastructure cost — one database for all tenants',
    'Simplest to deploy and manage',
    'Easy cross-tenant analytics and reporting',
    'Database migrations apply to all tenants at once',
  ]}
  cons={[
    'Risk of data leaks if tenant_id filter is missed (security critical)',
    "Noisy neighbor — one tenant's heavy query affects all others",
    'Hard to meet data residency requirements per tenant',
    'Schema customization per tenant is difficult',
  ]}
>
All tenants share the same database and tables. A `tenant_id` column on every table discriminates data. Application code adds `WHERE tenant_id = ?` to every query. Simplest and most cost-effective approach, used by most early-stage SaaS.
</Approach>
<Approach
  name="Shared Database, Separate Schemas"
  pros={[
    'Logical data isolation...

[Full prompt copied to clipboard]