3. Row-level tenancy
- Status: superseded by ADR 0035
- Date: 2026-10-29
Context and problem statement
Section titled “Context and problem statement”One installation serves several tenants (companies), and one user may belong to more than one of them. Data of different tenants must never mix, and a forgotten condition in a query must not leak rows.
Decision drivers
Section titled “Decision drivers”- Isolation by default, not by developer discipline.
- One database and one schema to operate and back up.
- A user working in one tenant at a time, chosen explicitly.
Considered options
Section titled “Considered options”- Row-level tenancy: a
tenant_idcolumn on every tenant-owned table, enforced by a Doctrine SQL filter - One schema per tenant
- One database per tenant
Decision outcome
Section titled “Decision outcome”Chosen option: “row-level tenancy”, because it keeps operations simple and lets one enforcement point cover all queries.
- Every tenant-owned entity implements
TenantOwnedand has a non-null, indexedtenant_idcolumn. - A Doctrine filter adds the active tenant to every ORM and DQL query. It is enabled by default and fails closed: reading without an active tenant throws instead of returning everything.
TenantContextholds the active tenant. The tenant is stamped on new entities at persist time, and writing an entity of another tenant is rejected.- The active tenant is never guessed: a user with a single membership has it selected automatically, and a user with several memberships has no active tenant (so no tenant-owned data is reachable) until one is chosen. Switching is implemented as the
SwitchTenantapplication service, which refuses tenants the user is not a member of. The user interface has a tenant chooser (/organisation/choose), which callsSwitchTenant. Actions never run in more than one tenant at once. - Cross-tenant lookups (for example listing a user’s memberships) go through
TenantFilterBypass, which returns scalar values only and never entities. - Raw DBAL access is forbidden in
ApplicationandDomain(enforced by Deptrac), because it would bypass the filter. - Database-level row-level security (for example PostgreSQL policies) is not implemented. Isolation relies on the Doctrine filter, on the check at write time, and on references across tenants being refused. A second layer in the database is possible future work and would not work on SQLite.
- A tenant can hold several firms (legal entities) that share its users and contacts; see ADR 10. Firms are not isolated from each other by the tenant filter.
Consequences
Section titled “Consequences”- Good: a missing condition cannot leak data across tenants.
- Good: a single schema and a single backup.
- Bad: tenants share tables, so noisy-neighbour effects and a database-wide incident affect all tenants.
- Bad: every new tenant-owned table must follow the rules, which tests and the quality gate check.