Tenant Isolation

Partition a multi-tenant system's data and resources such that one tenant's activity, load spikes, or data cannot affect the correctness or performance of other tenants: choosing from a spectrum of isolation models from shared schema through dedicated infrastructure.

In a multi-tenant system, one tenant consuming disproportionate resources degrades service for all others. Without isolation, a database query from one tenant can evict another's data from the buffer cache, a write burst can saturate WAL, and a schema migration can block all tenants sharing the table.

Multi-tenant SaaS systems host multiple customers on shared infrastructure. Without deliberate isolation, one tenant's high write rate can saturate the shared database, causing query latency spikes for all tenants (noisy neighbor). One tenant's schema migration can lock tables visible to other tenants. A bug in one tenant's query can trigger index scans that exhaust the shared buffer cache.

Isolation models exist on a spectrum of cost vs. isolation strength:

Shared schema (row-level): all tenants in the same tables, with a tenant_id column on every row. Lowest cost; highest noisy neighbor risk. Requires row-level security (RLS) at the database layer. A missing tenant_id filter is a data leak. Correct for small datasets and low-traffic tenants.

Schema-per-tenant: each tenant has a separate PostgreSQL schema (namespace) in the same database. Slightly stronger isolation: a VACUUM on one tenant's tables does not block others. Still shares connection pool, WAL, and buffer cache.

Database-per-tenant: each tenant has a separate database or cluster. Strong isolation: a runaway query on tenant A cannot affect tenant B. Operationally expensive: 1000 tenants = 1000 database instances to maintain, monitor, and patch. Reserved for high-value tenants or regulated industries requiring data residency.

Hybrid (tiered isolation): most tenants on shared schema; large or regulated tenants on dedicated databases. Routing layer maps tenant ID to the correct storage endpoint. This is the common production model for SaaS companies at scale (Notion, Figma, Salesforce, Shopify all use variants of this approach).

Resource isolation: even within a shared schema, quota enforcement (max queries/sec, max connections, max storage GB per tenant) limits a tenant's blast radius.

Row-level security enforces shared-schema isolation at the database layer:

ALTER TABLE documents ENABLE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON documents

USING (tenant_id = current_setting('app.current_tenant')::uuid);

-- set at connection time: SET app.current_tenant = '<tenant_id>';

Schema-per-tenant connection routing sets the search path per connection, for example in SQLAlchemy by listening for the connect event and issuing SET search_path TO {tenant_schema}, public. In a hybrid model, a tenants table records each tenant's tier (shared or dedicated) and connection string, and the request path looks up the tenant's tier to route to the correct connection.