saas-multitenancy

SaaS Multi-Tenancy

Capability

Implement robust multi-tenant architecture for SaaS applications with proper data isolation, tenant context management, and scalable patterns. Covers shared database with row-level security, tenant-scoped queries, and organization/team hierarchies.

Use Cases

• Data isolation between tenants (organizations/workspaces)
• Team/organization hierarchy with roles
• Tenant-scoped API endpoints
• Subdomain or path-based tenant routing
• Tenant provisioning and onboarding
• Cross-tenant admin operations

Patterns

Row-Level Security (RLS) Pattern

When to use: Shared database with multiple tenants needing data isolation

Implementation: Use database-level RLS policies to enforce tenant isolation. Every query automatically filters by tenant.

-- Enable RLS on tenant tables
ALTER TABLE projects ENABLE ROW LEVEL SECURITY;

-- Create tenant isolation policy
CREATE POLICY tenant_isolation ON projects
  USING (tenant_id = current_setting('app.current_tenant_id')::uuid);

-- Create policy for insert
CREATE POLICY tenant_insert ON projects
  FOR INSERT
  WITH CHECK (tenant_id = current_setting('app.current_tenant_id')::uuid);

-- Create policy for update/delete
CREATE POLICY tenant_modify ON projects
  FOR ALL
  USING (tenant_id = current_setting('app.current_tenant_id')::uuid);

// Middleware to set tenant context
async function setTenantContext(tenantId: string) {
  // Set session variable for RLS
  await db.execute(
    sql`SELECT set_config('app.current_tenant_id', ${tenantId}, true)`
  );
}

// Usage in API route
async function handleRequest(req: Request) {
  const tenantId = await getTenantFromSession(req);
  await setTenantContext(tenantId);

  // All subsequent queries automatically filtered
  const projects = await db.query.projects.findMany();
  return projects; // Only returns tenant's projects
}

Tenant Context Middleware

When to use: Every request needs tenant context for data access