Where the tenant boundary sits, how each request finds its tenant, and what keeps one tenant's data and load away from another's.
These guides build on each other. The first decides where the boundary between tenants is drawn; the next three make sure every request respects it; the last keeps one tenant's traffic from becoming everyone's outage. If you are reviewing an existing system rather than designing a new one, start with the leak-prevention guide: its linter lab gives you a quick count of the database calls that bypass your tenant scoping.
Choose shared tables, schemas, or databases, and see what each costs in capacity, connections, and restores.
Lab finding: 76% less at the peak minute (594 vs. 2,482 units); average utilization 53% shared vs. 13% dedicated.
Turn each request's hostname into a tenant safely, before authentication or database work.
Lab finding: The shortcut turned an IPv6 host into "[2001" and kept duplicate keys. Cancelling the first caller failed all 500 shared lookups; a detached context failed only that one.
Make PostgreSQL enforce the boundary when application code forgets, and know who bypasses it.
Lab finding: A session-level SET leaked tenant A's rows to the next request, and a string-formatted SET LOCAL let tenant B read tenant A. set_config with a bind parameter prevented both.
Add structural linting, cross-tenant tests, and production probes around the boundary.
Lab finding: The string rule missed queries in constants, built by concatenation, or with tenant_id only in a comment, and flagged two safe calls. The structural rule caught every unsafe call.
Stop one tenant's flood from consuming everyone's capacity with per-tenant limits.
Lab finding: No limit: 24.4%. Global limit: 17.2%, because the flooder takes most tokens. Per-tenant buckets: 100%, with a 34 ms p99.
Put numbers on it: Tenant Isolation Decision Planner
Where tenant data leaks come from, which controls catch each path, and a lab in which a popular tenant_id linter missed three unsafe queries and a structural rule caught them.
How the three PostgreSQL tenant isolation models differ in leak risk, connections, migrations, and restores, including what per-tenant point-in-time recovery really requires.
Why a global rate limit hurts the customers it should protect, how a per-tenant token bucket works, and a lab that compares both under the same flood.
A tenant policy that fails closed, setting the tenant safely through a pool, and the roles that bypass RLS, tested on PostgreSQL 18.6, including a leak through a reused connection.
How to map Host headers to tenants without key mismatches, certificate surprises, or a cold-cache stampede, with a lab that tests a common normalizer and singleflight.
