Multi-Tenancy
Running several customer organisations on one installation — what a tenant is, and the decisions taken once.
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.
Tenant Hierarchies
A tenant can name a parent, so customers can be modelled as a structure rather than a flat list.
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
What it is for
- A group with subsidiaries, where the parent needs a view across them.
- A franchise, where branches operate independently under one brand.
- A reseller, whose customers are tenants of yours but belong to them.
- Regions or divisions within one large customer.
Model the real relationship
The hierarchy should reflect how the organisations actually relate, not how you would like your reporting to work. A structure invented for convenience becomes wrong the first time a subsidiary is sold.
It is not automatically an access grant
The important caution. A parent tenant does not, by existing, see its children’s data — nor should it be assumed to. Whether a group can see a subsidiary’s records is a decision about permissions and record sharing, made explicitly.
Treating the hierarchy as an access model is how a subsidiary’s confidential data reaches its parent company’s staff without anybody deciding that should happen.
Ask the customer
Whether a parent should see a child’s data is frequently contentious inside the customer’s own business. Subsidiaries often have good reasons for separation — a pending sale, a regulated activity, a works council.
Get it in writing rather than inferring it from the org chart.
Keep it shallow
Two levels covers nearly every real case. Deeper hierarchies are usually modelling an internal structure that changes annually, and every change means restructuring tenants.
Restructuring happens
Companies are bought, sold and merged. Know what moving a tenant from one parent to another does — to reporting, to sharing, to anybody who had access because of the old position.
Billing usually follows the parent
But not always. Decide explicitly whether the subscription sits with the group or with each subsidiary, because it determines who gets suspended when a payment fails.
Worked example
A platform models a customer group as a parent tenant with four subsidiary tenants. The parent sees consolidated reporting through explicitly shared records, not through the hierarchy itself — which mattered when one subsidiary was sold and the sharing was simply revoked.
Recommendations
- Never treat the hierarchy as an access grant.
- Get parent visibility agreed in writing.
- Two levels is usually enough.
- Decide where billing sits before onboarding.
Sharding Across Hosts
Sharding places tenant databases across several database hosts rather than one.
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 it does
Each tenant names the host holding its data. With sharding on, new tenants can be placed on different hosts, so the installation is not limited by one server’s capacity.
When it is worth it
- Capacity — one host cannot hold or serve everything.
- Isolation of load — one heavy tenant should not slow everybody.
- Jurisdiction — some tenants’ data must stay in a particular country.
- A very large customer who has asked for, and pays for, their own infrastructure.
The last two are usually better reasons than the first. Capacity problems are frequently a query or an index rather than a server.
Solve the actual problem
Sharding is a substantial operational commitment. Before taking it on, be confident the constraint is genuinely the database host and not something cheaper to fix — because afterwards you have several hosts with the same problem.
What it complicates
- Backups — several to take, several to test.
- Schema changes — applied everywhere, and partial application is now possible.
- Monitoring — a problem on one host affects some tenants and not others, which is confusing to diagnose.
- Anything crossing tenants — reporting across hosts is a different exercise.
Placement needs a rule
Otherwise tenants land wherever the last one did, and hosts drift into wildly different sizes. Decide how a new tenant is placed — round robin, by region, by size — and write it down.
Record which tenant is where
The tenant record holds it, and you also want it somewhere findable during an incident when the platform is the thing that is down.
Moving a tenant between hosts
Should be a rehearsed procedure, not a first attempt during an emergency. You will need it — for capacity, for a customer request, or for a failing host.
Worked example
A platform shards by region so European customers’ data stays in Europe, with placement decided at onboarding by a written rule. Schema changes are applied host by host with a check after each, and a tenant move has been rehearsed on a test tenant.
Recommendations
- Confirm the constraint is the host before sharding.
- Write down the placement rule.
- Check every host after a schema change.
- Rehearse moving a tenant.
A Tenant Per User
The installation can create a tenant automatically for each new user signing up under the master tenant.
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
What it produces
Self-service sign-up where every account is its own isolated organisation. That is the right model for a product sold to individuals and small businesses who arrive without a conversation.
When it fits
- A product with a free tier or trial.
- Customers who are individuals or sole traders.
- A sales model with no onboarding conversation.
When it does not
Where customers are organisations with several users. Then the first person to sign up creates a tenant, the second creates another, and you have two organisations that should have been one — which is unpicked by hand, repeatedly.
If your customers are companies, invite users into an existing tenant instead.
It creates tenants indefinitely
Including for people who sign up once and never return, and for anybody testing your sign-up form. Most will be empty forever.
Have a policy: how long an empty, inactive tenant is kept, and what removing one does. Without it the tenant list grows without limit and every operation across tenants gets slower.
Separate database mode changes the arithmetic
Considerably. A tenant per user in separate mode means a database per user, and the operational cost of thousands of databases is not the same as thousands of rows.
If you expect volume sign-up, shared mode is almost certainly the right pairing.
Consider what a new tenant starts with
An empty tenant is a poor first experience. The data-copying setting decides whether a new tenant starts populated from the master, which for a self-service product is often what makes it usable in the first five minutes.
Guard the sign-up
Automatic tenant creation on an open form is an unbounded resource. Rate limiting, e-mail verification and abuse monitoring matter more here than on an ordinary sign-up form.
Worked example
A self-service product creates a tenant per sign-up in shared database mode, populated from the master so a new user sees a working example. Verification is required before the tenant becomes usable, and empty unverified tenants are removed after ninety days.
Recommendations
- Only for individual customers, not for companies.
- Pair with shared database mode.
- Have a policy for empty inactive tenants.
- Rate-limit and verify the sign-up.
Starting a Tenant Populated
A new tenant can start populated from the master tenant rather than empty.
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 → Data:
- Datastores — the initialisation mode and shared-data flag on each
What gets copied
Not everything. Data is copied for datastores whose initialisation mode marks them as eligible and which are not flagged as holding shared data.
That second condition matters: shared datastores are already visible to every tenant, so copying them would create a second, divergent copy of data that was meant to be common.
Curate the master tenant
The consequence of this feature is that your master tenant is a template. Whatever is in an eligible datastore is what every new customer starts with, including test records somebody left there.
Review it before enabling this, and again periodically.
What is worth copying
- Example records that show what the product does.
- Starter configuration — categories, statuses, templates.
- Reference lists a tenant will edit for itself.
Reference data a tenant will not edit belongs in a shared datastore instead, so it is maintained once.
What is not
Anything with real names in it. The master tenant is where somebody demonstrated the product to a real prospect, and copying that into every new customer’s account is a data breach delivered automatically.
Empty is a bad first impression
A new customer signing in to nothing has to imagine what the product does. A tenant with three example records and a configured workflow shows them, and the difference in whether they come back is substantial.
Make examples obviously examples
Named so nobody mistakes them for real, and easy to delete in one action. Sample data that looks real ends up quoted in a meeting.
Test what a new tenant actually gets
By creating one and looking, rather than by reasoning about the settings. The eligible-datastore rule is easy to get wrong in either direction, and the symptom — a new customer with the wrong starting data — is one your customers report rather than your monitoring.
Worked example
A platform copies example records and starter configuration into every new tenant, with country and currency lists held as shared datastores instead. Examples are prefixed so they are unmistakable. A test tenant is created after any change to the master, and the copy is checked.
Recommendations
- Treat the master tenant as a template and curate it.
- Never copy real customer data — check before enabling.
- Shared datastores for data tenants will not edit.
- Create a test tenant and look at what it got.