Tenant on every row, enforced in every query, cross-tenant tests.
Spec — Multi-tenant data isolation
Status: draft · Created: 2026-11-10
1. Context and goal
Many customers share one database, and no customer may ever read or change another customer's data, even through a bug in a single query.
2. Functional requirements (EARS)
- FR-1: THE SYSTEM SHALL store a non-null tenant id on every row of every tenant-owned table, and include it in every unique constraint of such a table.
- FR-2: THE SYSTEM SHALL take the tenant id only from the authenticated session, never from the request body, path or query string.
- FR-3: THE SYSTEM SHALL add the tenant filter to every read, update and delete on a tenant-owned table, and IF a query runs with no tenant in context, THEN it SHALL fail instead of returning rows.
- FR-4: THE SYSTEM SHALL enforce the same rule in the database with row-level security, so a query that bypasses the data access layer returns 0 rows of other tenants.
- FR-5: IF a request names a record of another tenant, THEN THE SYSTEM SHALL answer 404, exactly as for a record that does not exist.
- FR-6: THE SYSTEM SHALL scope cache keys, search indexes, file storage paths and background jobs by tenant id.
- FR-7: THE SYSTEM SHALL have, for every endpoint, a test where tenant A tries to read, list, change and delete tenant B's records, and the build SHALL fail if any attempt succeeds.
- FR-8: WHEN an operator opens a tenant's data for support, THE SYSTEM SHALL require a reason and write an audit entry with the operator, the reason and the time that the tenant's admins can see.
3. Out of scope
- A separate database per tenant.
- Moving a tenant to another region.