Multi-tenancy design

TL;DR

• Multi-tenancy means multiple customers (tenants) share the same system infrastructure while their data remains logically or physically isolated.
• Three isolation models: silo (one database per tenant, maximum isolation, highest cost), bridge (shared database, schema per tenant), pool (shared tables with a tenant_id column, minimum cost, maximum risk).
• Data leakage between tenants is the single most dangerous failure mode. One missed WHERE clause can expose customer data to the wrong tenant.
• Noisy neighbor is the operational risk: one tenant's heavy usage degrades performance for everyone sharing the same resources.
• Most production SaaS systems use a hybrid: small tenants in the pool model, enterprise tenants in silo, with automated migration tooling between tiers.

The Problem It Solves

Your SaaS application has 2,000 paying customers. During a routine database query, an engineer runs a report without a WHERE clause on tenant_id. The resulting CSV contains order data from all 2,000 tenants. It gets attached to an email thread. An enterprise customer's confidential pricing data is now exposed.

Or the less dramatic but equally painful version: one of your largest tenants runs an expensive analytics query that locks shared tables for 30 seconds. During that window, your 1,999 other tenants experience timeouts. Your support queue fills up, but the tenant running the query doesn't even notice because their workload completed successfully.

These are the two fundamental multi-tenancy risks: data leakage (one tenant sees another's data) and noisy neighbor (one tenant's workload degrades everyone else's performance). Both stem from sharing infrastructure between customers.

The single-tenant approach (deploy a completely separate stack per customer) avoids these risks but doesn't scale. Managing 2,000 independent deployments means 2,000 database upgrades, 2,000 schema migrations, and 2,000 monitoring dashboards. The operational cost makes it economically unviable for all but the largest enterprise contracts.

Multi-tenancy is the engineering discipline of sharing infrastructure safely. The question isn't whether to share, it's how much isolation each customer needs, and at what cost.

What Is It?

Multi-tenancy is an architecture where a single instance of software serves multiple customers (tenants), with mechanisms to ensure each tenant's data, performance, and configuration are isolated from every other tenant.

Analogy: Think of an apartment building. Each tenant has their own unit with a lock on the door (data isolation). They share the building's plumbing, electrical, and elevator (shared infrastructure). Some tenants pay extra for a penthouse with a private elevator (silo model). Most share the common elevator but have a maximum occupancy limit so one large family doesn't monopolize it (noisy neighbor controls). The building management company runs one maintenance team for the whole building, not one per unit (operational efficiency).

The isolation level you choose is the central architecture decision. There's a spectrum from full isolation (expensive, simple to secure) to full sharing (cheap, operationally risky).

No single model is correct. The right answer depends on your customer mix, regulatory requirements, and cost constraints. Most mature SaaS products use a hybrid.

How It Works

Let's trace a request through a multi-tenant system. A user at Acme Corp hits acme.myapp.com/api/orders. The system must: (1) identify the tenant, (2) route to the right data, (3) enforce isolation.

Tenant routing middleware

Every request passes through tenant resolution before reaching business logic:

class TenantMiddleware:
    def process_request(self, request):
        # Strategy 1: Subdomain
        tenant_slug = request.host.split('.')[0]  # "acme" from acme.myapp.com
        
        # Strategy 2: JWT claim
        # tenant_id = request.auth.claims["tenant_id"]
        
        # Strategy 3: API key prefix
        # tenant_slug = request.headers["X-API-Key"].split("-")[1]
        
        tenant = cache.get(f"tenant:{tenant_slug}")
        if not tenant:
            tenant = db.query("SELECT * FROM tenants WHERE slug = %s", tenant_slug)
            cache.set(f"tenant:{tenant_slug}", tenant, ttl=3600)
        
        request.tenant = tenant
        request.db = TenantScopedDB(tenant.id, tenant.isolation_model)

The middleware caches tenant lookups (they're effectively read-only) and sets a tenant context that all downstream code uses. I'll often see teams skip the caching step, which adds a database round-trip to every single request for data that changes maybe once a month.

Data isolation by model

Silo model routes the entire database connection to a dedicated instance:

class TenantScopedDB:
    def get_connection(self):
        if self.isolation_model == "silo":
            return connection_pool.get(self.tenant.dedicated_db_url)
        elif self.isolation_model == "bridge":
            conn = connection_pool.get(shared_db_url)
            conn.execute(f"SET search_path TO tenant_{self.tenant.id}")
            return conn
        else:  # pool
            return connection_pool.get(shared_db_url)
            # All queries auto-filtered by tenant_id

Pool model enforces tenant_id at the query layer. This is the most critical code path in any multi-tenant system:

class TenantScopedQuerySet:
    """All database access goes through this. No bypass allowed."""
    
    def __init__(self, tenant_id: UUID):
        self._tenant_id = tenant_id
    
    def orders(self) -> QuerySet:
        return Order.objects.filter(tenant_id=self._tenant_id)
    
    def users(self) -> QuerySet:
        return User.objects.filter(tenant_id=self._tenant_id)

# Never expose the raw ORM to application code
request.db = TenantScopedQuerySet(tenant_id=request.tenant.id)

Row-level security as a safety net

PostgreSQL's Row-Level Security (RLS) provides database-enforced isolation for the pool model:

-- Enable RLS on the orders table
ALTER TABLE orders ENABLE ROW LEVEL SECURITY;

-- Create a policy: each session can only see rows matching its tenant
CREATE POLICY tenant_isolation ON orders
    USING (tenant_id = current_setting('app.current_tenant_id')::uuid);

-- Middleware sets the session variable before every query
SET app.current_tenant_id = 'acme-tenant-uuid';
SELECT * FROM orders;  -- RLS automatically filters to Acme's rows only

Even if application code forgets the WHERE clause, the database itself enforces the filter. My recommendation: use RLS as a safety net alongside application-layer filtering, not as a replacement. RLS adds query overhead (the policy evaluation) and complicates EXPLAIN plans, but the data leakage prevention is worth it.

For your interview: say "tenant resolution in middleware, scoped query layer in the app, and RLS in the database as defense in depth." Three layers of isolation, any one of which prevents data leakage.

Key Components

Types / Variations

The rule of thumb: start with pool for your first 100 tenants, add bridge for mid-tier accounts, offer silo for enterprise deals that demand it.

Noisy Neighbor Mitigation

In the pool model, one tenant's heavy usage affects every other tenant sharing those resources. This is not a theoretical risk. I've seen a single tenant's reporting query (a full table scan with GROUP BY across 50M rows) bring response times from 20ms to 8 seconds for all 500 other tenants.

The most effective approach combines all five layers. Rate limiting caps request volume. Connection pool limits prevent one tenant from exhausting shared connections. Query timeouts kill runaway queries. Tenant-aware sharding separates heavy tenants physically. And graduated isolation automatically migrates consistently heavy tenants to their own infrastructure.

Hybrid Model

Most production SaaS systems don't pick one model. They use a hybrid based on customer tier:

New tenants start in the pool. When a customer upgrades to a higher tier (or signs an enterprise contract), your platform migrates their data to the appropriate isolation level. This migration tooling (copy data, verify integrity, switch connection routing, validate) is a core platform capability, not an afterthought.

Trade-offs

The fundamental tension is cost efficiency vs. isolation guarantees. Sharing infrastructure reduces cost per tenant dramatically, but every shared resource is a potential vector for data leakage or performance interference.

When to Use It / When to Avoid It

Use multi-tenancy when:

• You're building SaaS with more than ~10 customers on the same product
• Infrastructure cost per customer must be low (self-serve tiers, freemium models)
• You want a single deployment to maintain, patch, and upgrade
• Your customer base spans a wide range of sizes (many small, few large)
• Regulatory requirements can be satisfied with logical isolation (RLS, encryption)

Avoid multi-tenancy (use single-tenant) when:

• Every customer requires physically separate infrastructure by contract or regulation
• You have fewer than 10 customers, each paying enterprise prices
• Customers need fully independent upgrade schedules (different versions running simultaneously)
• Data residency requirements make shared infrastructure impossible across regions
• The engineering complexity of tenant isolation exceeds the operational cost of separate deployments

Ok, but here's the thing most people miss: multi-tenancy is not a binary decision. You don't "do multi-tenancy" or "not do it." You choose an isolation model per customer tier and build the platform to support migration between them.

Real-World Examples

Salesforce is the original multi-tenant SaaS platform, serving 150,000+ organizations from shared infrastructure since 1999. Their pool model uses a metadata-driven architecture where tenant customizations (fields, objects, workflows) are stored as rows in shared system tables rather than as schema changes. This lets them deploy a single codebase serving every customer from small businesses to Fortune 500 enterprises. Their key innovation: "virtual custom objects" that represent per-tenant schema extensions without actual DDL, enabling millions of tenant-specific fields on shared physical tables.

Slack uses workspace-level isolation with a hybrid approach. Each workspace is a tenant, but the isolation model varies by scale. Small workspaces share infrastructure (pool model). Slack's Enterprise Grid product gives large organizations (100K+ users) dedicated infrastructure with cross-workspace federation. Their largest operational challenge was noisy neighbor mitigation during viral adoption: when a company of 50,000 users onboards, their initial data import can generate 10x normal database write load.

AWS uses account-level silo isolation for its largest multi-tenancy challenge: the cloud itself. Each AWS account is a tenant that gets hard resource boundaries (VPC isolation, IAM policy enforcement, quota limits). For services like S3 (which stores trillions of objects across millions of accounts), internal data partitioning uses a pool-like model with extremely rigorous tenant-id enforcement. Their 2017 S3 outage (triggered by a single operator command) demonstrated why tenant-level blast radius isolation matters even within infrastructure providers.

How This Shows Up in Interviews

When to bring it up: Any SaaS design question ("Design Slack," "Design a CRM," "Design a project management tool") requires multi-tenancy. Also relevant when the interviewer asks about data isolation, compliance, or cost optimization for a platform serving multiple customers.

Depth expected at senior/staff level:

• Name all three isolation models and state cost/isolation tradeoffs of each
• Explain the hybrid model and tenant migration between tiers
• Describe the data leakage risk and how RLS + scoped queries provide defense-in-depth
• Know noisy neighbor mitigations: per-tenant rate limiting, connection caps, query timeouts
• Discuss tenant-aware routing strategies and where tenant context is resolved
• Address compliance (data residency, GDPR right-to-deletion) and how isolation model affects it

Follow-up Q&A:

Test Your Understanding

Quick Recap

1. Multi-tenancy serves multiple customers from shared infrastructure, with the core architecture decision being how much isolation to provide at what cost.
2. Three models: silo (DB per tenant, max isolation, max cost), bridge (schema per tenant, medium), pool (shared tables with tenant_id, min cost, highest risk).
3. Data leakage is prevented through defense-in-depth: scoped query layers in application code, PostgreSQL RLS as a database safety net, and automated cross-tenant testing in CI.
4. Noisy neighbor is controlled through per-tenant rate limiting, connection pool caps, query timeouts, and graduated isolation that auto-migrates heavy tenants.
5. Most production SaaS systems use a hybrid: pool for free/self-serve, bridge for professional, silo for enterprise, with migration tooling as a core platform capability.
6. Tenant-aware routing resolves the tenant from the request (subdomain, JWT claim, API key) in middleware, before any business logic executes.
7. In interviews, say "pool with RLS, per-tenant rate limiting, and the ability to migrate enterprise tenants to silo" to show you understand the full tradeoff spectrum.

Related Concepts

• Sharding - The pool model with heavy tenants often evolves into tenant-aware sharding. Understanding partition strategies helps you explain how tenant data is physically distributed.
• Databases - Multi-tenancy is fundamentally a database architecture decision. Knowing PostgreSQL features (RLS, schemas, connection pooling) is prerequisite knowledge.
• Security - Data leakage prevention, tenant authentication, and compliance (GDPR, HIPAA, SOC2) are the security concerns that drive isolation model choices.
• Rate Limiting - Per-tenant rate limiting is the primary noisy neighbor control. Understanding token bucket and sliding window algorithms helps you design tenant-aware limits.