How Tenancy Works
Multi-tenancy runs several separate organisations on one installation, each seeing only its own data.
Where to find it
Architect Panel → Configuration:
- Multitenancy — the tenants themselves
- Custom Tenant Information Fields — your own fields on a tenant
- Instance Configuration Fields — settings held per tenant
Architect Panel → Integration & Connections:
- Database Hosts — where tenant databases live
What a tenant is
A record with a code, a name, the database host holding its data, a count of active clients, an optional parent, and whether it may share records with others.
Everything else — users, data, configuration — hangs off that, scoped by the tenant it belongs to.
The switches that shape it
- Tenancy enabled — the master switch. Off, the installation is single-organisation.
- Database mode — shared or separate. The largest decision, covered in its own subcategory.
- Sharding — whether tenant databases are spread across several database hosts.
- A tenant per user — whether signing up creates an organisation.
- Copy data to new tenants — whether a new tenant starts populated.
These are application configuration rather than screens, and several are effectively decided once.
Decide the database mode first
Because it is the one that is genuinely hard to change later. Shared means every tenant’s rows live in one database, separated by a tenant column. Separate means each has its own database.
Both are legitimate. Choosing between them is a data-isolation and operations question, not a technical preference.
Tenants can have parents
A tenant names an optional parent, which allows a hierarchy — a group with subsidiaries, a franchise with branches, a reseller with customers. That is a genuine capability and worth knowing about before you model your customers as a flat list.
Some things are shared deliberately
A datastore can be marked as holding shared data, in which case every tenant sees the same rows. Reference data — country lists, product catalogues, category structures — usually belongs there rather than being copied into each tenant.
Tenancy tightens what custom code may do
Two older custom-PHP paths are refused automatically whenever tenancy is on, because unreviewed code authored in one tenant would run in a process shared with every other. That is a security boundary rather than a limitation to work around.
Isolation is the whole product
One tenant seeing another’s data is the failure that ends the arrangement. Test it deliberately and repeatedly — with a test tenant, from a real session, trying to reach things it should not.
Worked example
A platform runs sixty customer organisations in shared database mode, with country and product reference data marked as shared datastores. Two customers with subsidiaries use parent tenants. A test tenant is used after every permission change to confirm isolation still holds.
Recommendations
- Settle the database mode before onboarding anybody.
- Use shared datastores for reference data.
- Consider the hierarchy before modelling customers flat.
- Test isolation from a real tenant session, regularly.