Multi-Tenancy
Build SaaS apps that serve multiple organizations securely.
When to Use This Skill
- B2B SaaS applications
- White-label platforms
- Enterprise software
- Any app serving multiple organizations
Isolation Models
1. Shared Database, Shared Schema (Recommended for most)
┌─────────────────────────────────────────────────────┐
│ Database │
│ │
│ users: id, tenant_id, email, ... │
│ orders: id, tenant_id, user_id, ... │
│ products: id, tenant_id, name, ... │
│ │
│ All tables have tenant_id column │
└─────────────────────────────────────────────────────┘2. Shared Database, Schema per Tenant
┌─────────────────────────────────────────────────────┐
│ Database │
│ │
│ tenant_acme.users │
│ tenant_acme.orders │
│ tenant_globex.users │
│ tenant_globex.orders │
└─────────────────────────────────────────────────────┘3. Database per Tenant (Enterprise)
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ acme_db │ │ globex_db │ │ initech_db │
│ │ │ │ │ │
│ users │ │ users │ │ users │
│ orders │ │ orders │ │ orders │
└──────────────┘ └──────────────┘ └──────────────┘TypeScript Implementation
Tenant Context
// tenant-context.ts
import { AsyncLocalStorage } from 'async_hooks';
interface TenantContext {
tenantId: string;
tenantSlug: string;
plan: 'free' | 'pro' | 'enterprise';
features: string[];
}
const tenantStorage = new AsyncLocalStorage<TenantContext>();
export function getTenant(): TenantContext {
const tenant = tenantStorage.getStore();
if (!tenant) {
throw new Error('No tenant context available');
}
return tenant;
}
export function runWithTenant<T>(tenant: TenantContext, fn: () => T): T {
return tenantStorage.run(tenant, fn);
}
export { tenantStorage, TenantContext };Tenant Middleware
// tenant-middleware.ts
import { Request, Response, NextFunction } from 'express';
import { runWithTenant, TenantContext } from './tenant-context';
interface TenantMiddlewareOptions {
headerName?: string;
subdomainExtract?: boolean;
pathExtract?: boolean;
}
export function tenantMiddleware(options: TenantMiddlewareOptions = {}) {
const { headerName = 'x-tenant-id', subdomainExtract = true } = options;
return async (req: Request, res: Response, next: NextFunction) => {
let tenantId: string | undefined;
// Strategy 1: Header
tenantId = req.headers[headerName.toLowerCase()] as string;
// Strategy 2: Subdomain (acme.yourapp.com)
if (!tenantId && subdomainExtract) {
const host = req.hostname;
const subdomain = host.split('.')[0];
if (subdomain && subdomain !== 'www' && subdomain !== 'app') {
tenantId = subdomain;
}
}
// Strategy 3: Path (/t/acme/dashboard)
if (!tenantId && options.pathExtract) {
const match = req.path.match(/^\/t\/([^/]+)/);
if (match) {
tenantId = match[1];
}
}
// Strategy 4: User's default tenant (from JWT)
if (!tenantId && req.user?.defaultTenantId) {
tenantId = req.user.defaultTenantId;
}
if (!tenantId) {
return res.status(400).json({ error: 'Tenant not specified' });
}
// Load tenant from database
const tenant = await db.tenants.findUnique({
where: { id: tenantId },
select: { id: true, slug: true, plan: true, features: true },
});
if (!tenant) {
return res.status(404).json({ error: 'Tenant not found' });
}
// Check user has access to tenant
if (req.user) {
const membership = await db.tenantMemberships.findFirst({
where: { userId: req.user.id, tenantId: tenant.id },
});
if (!membership) {
return res.status(403).json({ error: 'Access denied to tenant' });
}
req.userRole = membership.role;
}
// Run request with tenant context
runWithTenant(
{
tenantId: tenant.id,
tenantSlug: tenant.slug,
plan: tenant.plan,
features: tenant.features,
},
() => next()
);
};
}Tenant-Scoped Queries
// tenant-prisma.ts
import { PrismaClient } from '@prisma/client';
import { getTenant } from './tenant-context';
// Extend Prisma with automatic tenant filtering
export function createTenantPrisma(prisma: PrismaClient) {
return prisma.$extends({
query: {
$allModels: {
async findMany({ model, operation, args, query }) {
// Auto-add tenant filter
args.where = { ...args.where, tenantId: getTenant().tenantId };
return query(args);
},
async findFirst({ model, operation, args, query }) {
args.where = { ...args.where, tenantId: getTenant().tenantId };
return query(args);
},
async findUnique({ model, operation, args, query }) {
// For unique queries, verify tenant after fetch
const result = await query(args);
if (result && result.tenantId !== getTenant().tenantId) {
return null; // Hide cross-tenant data
}
return result;
},
async create({ model, operation, args, query }) {
// Auto-set tenant on create
args.data = { ...args.data, tenantId: getTenant().tenantId };
return query(args);
},
async update({ model, operation, args, query }) {
// Ensure update is scoped to tenant
args.where = { ...args.where, tenantId: getTenant().tenantId };
return query(args);
},
async delete({ model, operation, args, query }) {
args.where = { ...args.where, tenantId: getTenant().tenantId };
return query(args);
},
},
},
});
}
// Usage
const tenantDb = createTenantPrisma(prisma);
// These are automatically scoped to current tenant
const users = await tenantDb.user.findMany();
const order = await tenantDb.order.create({ data: { ... } });Per-Tenant Configuration
// tenant-config.ts
interface TenantConfig {
branding: {
logo?: string;
primaryColor?: string;
companyName?: string;
};
features: {
maxUsers: number;
maxStorage: number;
apiAccess: boolean;
sso: boolean;
};
integrations: {
slack?: { webhookUrl: string };
stripe?: { customerId: string };
};
}
class TenantConfigService {
private cache = new Map<string, TenantConfig>();
async getConfig(tenantId: string): Promise<TenantConfig> {
if (this.cache.has(tenantId)) {
return this.cache.get(tenantId)!;
}
const tenant = await db.tenants.findUnique({
where: { id: tenantId },
include: { config: true },
});
const config = this.buildConfig(tenant);
this.cache.set(tenantId, config);
return config;
}
private buildConfig(tenant: Tenant): TenantConfig {
// Merge plan defaults with tenant overrides
const planDefaults = PLAN_CONFIGS[tenant.plan];
return {
branding: { ...tenant.config?.branding },
features: { ...planDefaults.features, ...tenant.config?.features },
integrations: { ...tenant.config?.integrations },
};
}
invalidateCache(tenantId: string) {
this.cache.delete(tenantId);
}
}Database Schema
-- Tenants table
CREATE TABLE tenants (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
slug VARCHAR(50) UNIQUE NOT NULL,
name VARCHAR(255) NOT NULL,
plan VARCHAR(50) DEFAULT 'free',
features TEXT[] DEFAULT '{}',
config JSONB DEFAULT '{}',
created_at TIMESTAMP DEFAULT NOW()
);
-- Users belong to tenants via memberships
CREATE TABLE tenant_memberships (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID REFERENCES users(id) ON DELETE CASCADE,
tenant_id UUID REFERENCES tenants(id) ON DELETE CASCADE,
role VARCHAR(50) DEFAULT 'member',
created_at TIMESTAMP DEFAULT NOW(),
UNIQUE(user_id, tenant_id)
);
-- All data tables have tenant_id
CREATE TABLE orders (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
tenant_id UUID NOT NULL REFERENCES tenants(id),
user_id UUID REFERENCES users(id),
-- ... other columns
created_at TIMESTAMP DEFAULT NOW()
);
-- Index for tenant queries
CREATE INDEX idx_orders_tenant ON orders(tenant_id);
-- Row Level Security (optional, extra protection)
ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON orders
USING (tenant_id = current_setting('app.current_tenant')::uuid);Python Implementation
# tenant_context.py
from contextvars import ContextVar
from dataclasses import dataclass
from typing import Optional
@dataclass
class TenantContext:
tenant_id: str
tenant_slug: str
plan: str
features: list[str]
_tenant_context: ContextVar[Optional[TenantContext]] = ContextVar(
"tenant_context", default=None
)
def get_tenant() -> TenantContext:
tenant = _tenant_context.get()
if not tenant:
raise RuntimeError("No tenant context")
return tenant
def set_tenant(tenant: TenantContext):
return _tenant_context.set(tenant)FastAPI Middleware
# tenant_middleware.py
from fastapi import Request, HTTPException
from starlette.middleware.base import BaseHTTPMiddleware
class TenantMiddleware(BaseHTTPMiddleware):
async def dispatch(self, request: Request, call_next):
tenant_id = request.headers.get("x-tenant-id")
if not tenant_id:
# Try subdomain
host = request.headers.get("host", "")
subdomain = host.split(".")[0]
if subdomain not in ["www", "app", "api"]:
tenant_id = subdomain
if not tenant_id:
raise HTTPException(400, "Tenant not specified")
tenant = await db.tenants.find_unique(where={"id": tenant_id})
if not tenant:
raise HTTPException(404, "Tenant not found")
token = set_tenant(TenantContext(
tenant_id=tenant.id,
tenant_slug=tenant.slug,
plan=tenant.plan,
features=tenant.features,
))
try:
response = await call_next(request)
return response
finally:
_tenant_context.reset(token)Best Practices
- Always filter by tenant_id - Never trust client-provided IDs alone
- Use middleware - Centralize tenant resolution
- Index tenant_id - Every tenant-scoped table needs this index
- Consider RLS - Extra protection layer in PostgreSQL
- Cache tenant config - Avoid repeated lookups
Common Mistakes
- Forgetting tenant filter on queries (data leak!)
- Not validating user's tenant access
- Hardcoding tenant-specific logic
- No index on tenant_id columns
- Allowing cross-tenant references