multi-tenancy

Multi-Tenancy

Treat tenant identity as an authorization boundary, not a query convenience.

Choose an isolation model

Database per tenant: strongest isolation and highest operational cost.
Schema per tenant: strong logical isolation with shared infrastructure.
Shared schema with tenant_id: simplest operations, but every access path must enforce scope.
Document the selected model and prohibit repositories from bypassing it.

Derive the tenant from a verified token claim, trusted host mapping, or authenticated API key.
Reject missing, unknown, disabled, or conflicting tenant identifiers.
Never trust a public X-Tenant-Id header by itself.
Clear servlet thread-local context in finally; use Reactor Context for reactive flows.

Apply tenant selection before opening the persistence session or transaction.
Include tenant identity in unique constraints, cache keys, idempotency keys, and object storage paths.
Prevent cross-tenant joins and unrestricted administrative repositories.
Authorize support impersonation explicitly and audit every use.

Run migrations per database/schema with resumable progress and version reporting.
Propagate tenant identity into scheduled jobs, messages, and async tasks explicitly.
Limit noisy tenants with quotas and per-tenant observability using bounded identifiers.
Test negative cross-tenant access, not only successful tenant queries.

Agent trusts a tenant header supplied by the caller - derive tenant from authenticated context.
Agent forgets to clear a servlet ThreadLocal - pooled threads can leak one tenant into another request.
Agent scopes database queries but not cache keys - cached data can cross tenants.
Agent starts a transaction before selecting the tenant - routing may choose the wrong database.
Agent runs background jobs without tenant context - make tenant an explicit job parameter.