Multi-Tenancy

Multi-tenancy serves many customers from shared infrastructure, requiring a tenant identity in every data path, isolation boundaries, and per-tenant resource limits.

architecture

Definition

Multi-tenancy is an architecture in which one deployment serves multiple tenants while keeping their data and behavior isolated. The main models are pooled (shared database and schema with a tenant key), siloed (a database or deployment per tenant), and bridge (shared application, separate schemas or databases for groups of tenants). Every model must enforce tenant identity on reads, writes, caches, queues, and background jobs.

Context and scope

Multi-tenancy is used by SaaS products to reduce cost and operational overhead. The trade-off is isolation: pooled tenancy is efficient but a missing tenant filter can leak data across customers.

Common misconceptions

Adding a tenant_id column is enough — every query, cache key, job, and export must enforce it
Pooled tenancy is always cheaper — noisy neighbors and blast radius can cost more than the infrastructure savings
Authorization at the API layer protects the database — background jobs and admin tools can bypass it

Anti-patterns

A query that filters by resource id but not tenant id
A shared cache key that omits the tenant
One tenant's batch job consuming the shared worker pool and starving others

Related concepts

Authoritative source

https://learn.microsoft.com/en-us/azure/architecture/guide/multitenant/approaches/overview

Tenant identity belongs in every path

In a pooled model, rows from many tenants share a table. A query must filter by tenant, not only by resource id, or a user can read another tenant’s record by guessing an id. The same rule applies to cache keys, object-storage prefixes, queue messages, search indexes, and analytics exports.

ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON orders
  USING (tenant_id = current_setting('app.tenant_id')::uuid);

Row-level security is a useful backstop, but it depends on the session setting being correct. Application queries should still include the tenant predicate so indexes and plans are explicit. Test with two tenants and a cross-tenant id to prove the boundary.

Choose the isolation model

Pooled tenancy maximizes efficiency and minimizes per-tenant operations. Siloed tenancy gives strong isolation and easier per-tenant backup/restore, at higher cost. Bridge models group tenants into schemas or databases. The choice depends on contract, regulation, noisy-neighbor tolerance, and the cost of a data leak. A hybrid can place high-value tenants in dedicated infrastructure while keeping the long tail pooled.

Protect shared capacity

A tenant can saturate a shared worker pool, connection pool, or queue. Apply per-tenant quotas, fair scheduling, and bulkheads for expensive operations. Monitor per-tenant latency and error rate, not only the aggregate; an aggregate dashboard can hide one customer’s outage.

When to use it

Use multi-tenancy when many customers can share infrastructure without violating isolation requirements. The advantage is cost and operational efficiency; the drawback is the constant risk of a missing tenant filter and noisy-neighbor effects. Compared to single-tenant deployments, pooled tenancy requires stronger automated tests and a clear isolation model.