multi-tenancy

Multi-Tenancy Patterns

When to Use

• Building SaaS that serves multiple organizations/clients
• Designing data isolation between tenants (companies, stations, fleets)
• Choosing the right isolation level for your compliance needs

Isolation Models

1. Row-Level (Shared Everything)

┌──────────────────────────────┐
│         Single Database       │
│  ┌────────────────────────┐  │
│  │     users table         │  │
│  │  tenant_id │ name       │  │
│  │  ──────────┼──────────  │  │
│  │  company_a │ Alice      │  │
│  │  company_b │ Bob        │  │
│  └────────────────────────┘  │
└──────────────────────────────┘

Pros: Simple, cheap, easy to maintain
Cons: Risk of data leakage, shared resources
Best for: Small/medium SaaS, cost-sensitive

Implementation — TypeORM Global Scope:

// Middleware injects tenant
@Injectable()
export class TenantMiddleware implements NestMiddleware {
  use(req: AuthRequest, res: Response, next: NextFunction) {
    req.tenantId = req.user?.companyId;
    next();
  }
}

// Repository automatically filters by tenant
@Injectable()
export class TenantAwareRepository<T> {
  constructor(private repo: Repository<T>) {}

  findAll(tenantId: string): Promise<T[]> {
    return this.repo.find({ where: { tenant_id: tenantId } as any });
  }

  // CRITICAL: NEVER allow findAll without tenantId
}

// Global subscriber (safety net)
@EventSubscriber()
export class TenantSubscriber implements EntitySubscriberInterface {
  afterLoad(entity: any) {
    // Verify tenant match on every load (paranoia mode)
  }
  
  beforeInsert(event: InsertEvent<any>) {
    // Auto-inject tenant_id
    if (event.entity && !event.entity.tenant_id) {
      event.entity.tenant_id = getCurrentTenantId();
    }
  }
}

2. Schema-Level (Shared Database, Separate Schemas)

┌──────────────────────────────┐
│         Single Database       │
│  ┌──────────┐ ┌──────────┐  │
│  │ schema_a  │ │ schema_b  │  │
│  │  users    │ │  users    │  │
│  │  orders   │ │  orders   │  │
│  └──────────┘ └──────────┘  │
└──────────────────────────────┘

Pros: Good isolation, shared infra cost
Cons: Schema migration complexity, connection pooling
Best for: Medium SaaS, regulated industries