5 min read
Multi-tenancy explained: shared database, schema or database per tenant
What a tenant is, the three ways to keep tenants apart, what multi-tenancy saves you and what it costs, and how to tell whether your product needs it.
- Architecture
- SaaS
Multi-tenancy means one application serving many customers at once, where each customer sees only their own data. Think of an apartment building: everyone shares the walls, the plumbing and the lift, but each family has its own locked door. The building is the application, and each apartment is a tenant.
Most SaaS products work this way. When two companies sign up for the same CRM, they use the same code on the same servers, and neither can ever see the other’s customers.
A tenant is not a user
A tenant is the customer you sell to: usually a company, a shop or a team. A tenant has many users. In an ERP, the paving company is the tenant, and its estimators, crew leads and accountants are users inside it. Permissions decide what a user may do; the tenant decides which data they can see at all.
How a request finds its tenant
Every request has to answer one question before anything else: which tenant is this for? The common answers:
- A subdomain: acme.example.com.
- A custom domain the customer points at you: crm.acme.com.
- A path: example.com/acme/orders.
- A claim inside the login token, for APIs and mobile apps.
Whichever you choose, resolve the tenant once, early, and keep it in one place for the rest of the request. Code that has to work out the tenant again deep in a query is where leaks begin.
- Requestacme.example.com/orders
- Resolve the tenantsubdomain “acme” → Acme
- Tenant contextset once, read everywhere after
- Acme’s data onlyqueries, cache, files and jobs
// Resolve once, at the edge of the request.const host = request.headers.get('host') ?? '';const subdomain = host.split('.')[0];const tenant = await tenants.findBySubdomain(subdomain); if (!tenant) return notFound(); // Everything after this reads the tenant from the request context.return runWithTenant(tenant, () => handle(request));Three ways to keep the data apart
The real design decision is where each tenant’s data lives. There are three common models, from most shared to most separate:
- Shared database, shared tables. Every table has a tenant_id column, and every query filters on it. One database to run, back up and migrate. On PostgreSQL, row-level security can enforce the filter inside the database, so a forgotten WHERE clause cannot leak another tenant’s rows.
- A schema per tenant. One database server, but each tenant gets its own set of tables (a PostgreSQL schema). The app switches schema for each request.
- A database per tenant. Each tenant has a database of its own, sometimes on its own server. The strongest separation, and the most to operate.
Shared tables
app_db
orders · tenant_id
- A
- B
- A
- C
- B
One database. Every row carries a tenant_id, and every query filters on it.
A schema per tenant
app_db
- schema tenant_a
- schema tenant_b
- schema tenant_c
One database server, with a separate set of tables for each tenant.
A database per tenant
tenant_a_db
tenant_b_db
tenant_c_db
Each tenant has a database of its own, sometimes on a server of its own.
More shared: cheaper, one thing to run and migrate
More separate: stronger isolation, more to operate
Tenant ATenant BTenant C
-- Shared tables: the tenant is part of every query and every index.CREATE INDEX orders_tenant_created ON orders (tenant_id, created_at); SELECT * FROM ordersWHERE tenant_id = :tenantORDER BY created_at DESCLIMIT 20;I have shipped all three. PotholeDoctor, an ERP for paving contractors, gives every company its own PostgreSQL schema and subdomain. Phytopian gives each nursery its own database. PerfectBillboard started with a database per tenant and moved to one shared database with a tenant ID, at the client’s request, because hundreds of small tenants were easier to run in one place.
What it gives you
- One codebase and one deployment for every customer. A fix or a feature ships to everyone at once.
- Lower cost per customer: servers, databases and monitoring are shared instead of copied for each one.
- Fast onboarding. A new customer is a new row, schema or database created by the app, not a new server set up by hand.
- Usage across all customers in one place, which helps with billing, support and product decisions.
What it costs you
- One missed filter can show one customer another customer’s data. With shared tables, isolation depends on every query being right.
- Noisy neighbours: one tenant’s heavy report can slow everyone else down unless you limit it.
- Migrations get harder as isolation grows. With a schema or database per tenant, one change runs hundreds of times and must be safe to retry halfway.
- Restoring or exporting a single customer is easy with separate databases and painful with shared tables.
- The tenant has to reach everything, not just the database: cache keys, queued jobs, uploaded files, search indexes, logs and emails.
- Pressure to customize. When one big customer wants different behavior, you need settings and feature flags, not a fork of the code.
The bugs that leak data are rarely in the main queries. They hide in the places people forget: a cache key without the tenant, or a background job that runs without one.
// Without the tenant, two companies share one cached dashboard.cache.get(`dashboard:${tenant.id}:${userId}`); // A queued job has no request, so it must carry the tenant itself.queue.push('send-invoice', { tenantId: tenant.id, invoiceId });Where to use it
- B2B SaaS, where many companies use the same product: CRMs, ERPs, helpdesks, booking systems.
- White-label platforms, where each customer gets their own domain, branding and storefront.
- Marketplaces, where each seller runs their own space but the platform still sees across all of them.
- Any product you expect to sell to more customers than you could ever run separate copies for.
Where not to
- An internal tool or a product built for exactly one client. There is nobody to keep apart.
- Consumer apps where users share one world, like a social network. Users and permissions are enough.
- Customers who must, by contract or regulation, run on infrastructure of their own. Give them a separate deployment instead.
- Customers who need very different features. Multi-tenancy pays off when everyone runs the same product.
How to choose a model
A few questions decide most of it:
- How many tenants will you have? Thousands of small ones fit shared tables; dozens of large ones fit separate databases.
- How strictly must data be separated? If a customer will ask where exactly their data lives, isolate more.
- Will customers need their own backups, exports or restores? That points to a schema or database per tenant.
- Who will run it? Every step toward separation is more migrations, monitoring and upgrades for your team.
My rule: start with the simplest model that meets the isolation your customers really need, and make the tenant explicit everywhere from day one. Moving data between models later is possible, as PerfectBillboard showed, but adding the tenant to code that never had it is the expensive part.