The Architect's Guide: Building Scalable Multi-Tenant SaaS Applications

Pick your isolation model before you write a line of code

The decision that haunts every multi-tenant SaaS is the one you make on day one and almost never revisit: do tenants share a database, or do they each get their own? Get it wrong and you'll either be paying for thousands of idle Postgres instances or untangling a data leak at 2am because someone forgot a WHERE clause. I've shipped both kinds. Neither is "correct" in the abstract, but the costs land at very different points in your company's life.

So let's skip the dictionary definition. Multi-tenancy means one running application serving many customers (tenants) off shared infrastructure, with each tenant's data walled off from the rest. The reason you'd bother: you patch a bug once and every tenant gets the fix, you onboard a new customer with an INSERT instead of a Terraform run, and you stop paying for a server per logo on your homepage. The reason you'd hesitate: every one of those shared resources is now a place where tenant A can accidentally see tenant B's invoices.

The three isolation models, and when each one actually makes sense

Database per tenant

Each tenant gets a dedicated database. Shared app code, fully siloed data.

This is the model enterprise procurement teams love, because "your data lives in its own database" is an easy sentence to put in a security questionnaire. Isolation is close to airtight, you can restore a single customer without touching anyone else, and you can even fork a schema for that one whale client who needs a custom field. I've used it for exactly that: a handful of large contracts where each was paying enough to justify the overhead.

The overhead is real. Migrations now run N times, and N grows every time sales closes a deal. A schema change that's a five-second ALTER TABLE in dev becomes a fan-out job with retry logic and a dashboard tracking which of your 800 databases are still on the old version. Provisioning a fresh database on signup also adds latency and a new failure mode to your registration flow. Don't reach for this model until a customer is paying you to.

Shared database, schema per tenant

One database, but each tenant lives in its own schema (the Postgres kind: tenant_4271.orders).

It looks like a tidy compromise and occasionally it is. You cut the number of databases way down while keeping data in separate namespaces. But you've mostly relocated the pain, not removed it. Migrations still run per schema. Cross-tenant analytics turn into ugly UNION gymnastics or a separate warehouse. And once you're past a few thousand schemas, the system catalog itself gets heavy and tools like pg_dump start to crawl. I treat this as a niche choice, not a default.

Shared database, shared schema

Everyone shares the same tables. A tenant_id column on nearly every row says who owns what.

This is what I reach for first, and what I'd tell most people to start with. It's the cheapest, it scales to thousands of tenants on one database, onboarding is a single insert, and analytics across your whole customer base is just a normal query. The catch is the one that matters: your application is now the only thing standing between tenant A and tenant B's data. Every query needs to be scoped to a tenant, and a single forgotten filter is a breach, not a bug.

That trade is worth making, but only if you stop relying on humans to remember the filter. More on that below.

The thing people over-engineer first

Here's the opinionated part. Most teams I've talked to pick database-per-tenant way too early, usually because a single prospect waved a security checklist around in a sales call. Then they spend their first year — the year they should be finding product-market fit — building migration orchestration and per-tenant backup tooling for forty customers, half of whom churn.

Start with shared schema. Add Postgres row-level security so the isolation is enforced in the database, not just in your code. When a real enterprise deal needs physical separation, you graduate that one tenant to its own database while everyone else stays shared. A hybrid where 99% of tenants share and your top three are isolated is not a compromise you settled for, it's the architecture you wanted. Don't pay the per-tenant-database tax across your whole book of business to satisfy three contracts.

Figuring out which tenant is asking

Your app has to resolve the tenant on every request. The usual options:

• Subdomain — acme.yourapp.com
• Custom domain — the tenant points their own domain at you
• URL path — yourapp.com/acme/... (workable, but it leaks tenant identity into every link and complicates cookies)
• JWT / session claim — after login, tenant_id rides inside the token on every API call

For APIs I default to the JWT claim. It's stateless, it survives horizontal scaling without sticky sessions, and it drops cleanly into the request lifecycle. On a Next.js app I'll resolve the tenant in middleware and stash it where the data layer can read it without every route handler re-deriving it. If you're tuning that path, the patterns in my Next.js 14 performance notes on middleware and caching are worth a look — middleware runs on every request, so it's an easy place to quietly add latency.

A subdomain or custom domain on the frontend pairs well with this: it's what the customer sees and bookmarks, while the JWT is what your backend actually trusts.

Enforcing isolation so a forgotten WHERE can't sink you

In a shared-schema setup, "we'll be careful" is not a strategy. You will hire someone who writes a raw query for a one-off report, forgets the tenant filter, and now a support ticket includes another company's data. You need isolation that survives a tired engineer on a Friday. Two layers, and use both.

Scope it in the data layer. Don't let route handlers build queries from a bare tenant id. Pass a tenant-bound client into your repositories so the filter is structural, not something a developer remembers to type.

// One scoped client per request. Repositories can't see "all tenants".
class TenantContext {
  constructor(private readonly tenantId: string) {}

  products() {
    return {
      list: () =>
        db.select().from(products).where(eq(products.tenantId, this.tenantId)),
      create: (data: NewProduct) =>
        db.insert(products).values({ ...data, tenantId: this.tenantId }),
    };
  }
}

The win is that there's no code path in your app that fetches products without a tenant id, because the only way to reach products() is through a context that already has one.

Back it with Postgres row-level security. App-layer scoping is your first line; RLS is the seatbelt for when something slips past it. You set the current tenant per connection and let the database refuse to return anything else:

ALTER TABLE products ENABLE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON products
  USING (tenant_id = current_setting('app.current_tenant')::uuid);

Then each request sets app.current_tenant after grabbing its connection (SET LOCAL inside the transaction so it doesn't leak across a pooled connection). Now even a hand-written SELECT * FROM products with no WHERE returns only the current tenant's rows. A bug becomes "you saw nothing" instead of "you saw everything." That difference is the whole ballgame.

One caveat with connection poolers like PgBouncer in transaction mode: SET LOCAL is the safe form because it's scoped to the transaction. A plain SET can bleed into the next request that reuses the connection, which is exactly the failure you were trying to prevent.

If you ever scope by something richer than a flat id — plans, regions, feature flags per tenant — get comfortable inspecting those JWT claims directly. I keep a JSON formatter open whenever I'm debugging what's actually inside a token versus what I assumed was there.

Scaling and the noisy neighbor

The downside of sharing is that one heavy tenant can drag everyone down. A customer who runs a 50,000-row export every five minutes is now your whole platform's problem. How I keep it contained:

• Scale web tiers horizontally. Keep request handling stateless (the JWT-claim approach helps here) so adding instances is trivial and no tenant is pinned to one box.
• Rate-limit per tenant, not just per IP. The point is to stop one account from eating the shared pool, and a single tenant can come from many IPs.
• Index `tenant_id`, and index it as part of composite keys. Most of your queries filter on it, so a (tenant_id, created_at) index usually beats a lone tenant_id one. Watch out for skew: one tenant with millions of rows next to thousands with a handful can wreck the planner's row estimates.
• Cache per tenant, and key the cache by tenant. A cache key that forgets the tenant id is the same data-leak bug wearing a different hat.

If a single tenant's workload still dominates after all that, it's a signal — not that your architecture failed, but that this specific customer has outgrown the shared pool and is a candidate for the isolated-database path from earlier.

A lot of the noisy-neighbor work is operational toil that's a good fit for automation: watching per-tenant query volume, flagging the account that suddenly 10x'd its API calls, kicking off the migration to a dedicated database. I've wired up a fair amount of that kind of glue and wrote about the approach in automating workflows with AI.

A note on tenant-aware AI features

If you're bolting AI onto a multi-tenant product — a chatbot over each customer's own docs, say — tenant isolation doesn't stop at your SQL. Your vector store needs the same discipline. Tag every embedding with its tenant_id and filter on it at query time, or tenant A's search will happily surface chunks from tenant B's knowledge base. It's the noisy-neighbor and data-leak problems again, just in a vector index instead of a table. I went deep on scoping retrieval in implementing RAG for a custom AI knowledge base.

FAQ

Should I start with shared or isolated databases? Shared schema with row-level security, unless you already have a signed contract that requires physical separation. You can always graduate a specific tenant to its own database later. Going the other direction — collapsing a thousand databases back into one — is the migration nobody wants.

Is row-level security enough on its own? It's a strong backstop, not a replacement for scoping queries in your application. Run both. RLS catches the query that slipped through your data layer; the data layer keeps you from leaning on the database for logic it shouldn't own. And mind connection pooling — set the tenant with SET LOCAL inside the transaction.

How do I handle a tenant that needs a custom schema? Resist customizing the shared tables for one customer. Use a metadata or JSONB column for per-tenant custom fields, or if the requirements are genuinely heavy, move that tenant to a dedicated database where they can diverge without dragging the shared schema along.

When does noisy neighbor actually become a problem? Later than you'd expect, and almost always traceable to one or two specific tenants rather than general load. Per-tenant rate limits and good composite indexes handle most of it. When they don't, that tenant has earned its own database.