On login, connect to the tenant's database

You’ve built your product. You’ve got a few paying customers. Now you’re facing the question that every technical founder eventually has to answer:

What is multitenancy, and which architecture pattern should I actually build?

Not the textbook definition. The real question: how do I structure my data layer so customer A never sees customer B’s data, I don’t go bankrupt on infrastructure, and I can scale to a few thousand customers without rewriting everything?

This is the multitenancy problem. And there’s no single right answer — just tradeoffs. Let’s walk through them.

What Is Multitenancy?

Multitenancy is the architectural approach where a single running instance of software serves multiple customers (tenants), with each tenant’s data and configuration kept logically separate. One deployment, one codebase, shared infrastructure — but strict isolation boundaries.

It’s the opposite of single-tenancy, where each customer gets their own dedicated instance, database, and infrastructure. Single-tenant works for enterprises with regulatory requirements or massive budgets. For the vast majority of SaaS startups, multitenancy is the default.

Here’s what “multitenancy” means at each layer of your stack:

  • Application layer — a single app serves all tenants, routing requests by subdomain, path, or header
  • Database layer — tenant data is isolated (how isolation happens is the key architectural decision)
  • Infrastructure layer — shared compute, storage, and networking resources
  • UI/UX layer — tenants see only their own data and configuration, never another tenant’s

The biggest architectural decision is at the database layer. That’s where multitenancy architecture gets interesting. That’s also where most startups get it wrong on the first try.

The Three Multitenancy Architecture Patterns

There are three dominant data isolation patterns in multitenant SaaS. Each has a different cost curve, performance profile, and operational complexity.

Pattern 1: Shared Database, Shared Schema (The Discriminator Pattern)

Every tenant’s rows live in the same tables, distinguished by a tenant_id column. This is the simplest form of multitenancy. 

CREATE TABLE subscriptions ( id SERIAL PRIMARY KEY, tenant_id UUID NOT NULL, plan_id VARCHAR(50), status VARCHAR(20), created_at TIMESTAMPTZ DEFAULT now() ); CREATE INDEX idx_subscriptions_tenant ON subscriptions(tenant_id);
  • Lowest cost per tenant — you’re literally sharing everything
  • Simplest deployment — one database, one backup, one restore
  • Easiest to scale horizontally — add compute, not databases
  • Schema changes deploy instantly to all tenants in a single migration
  • Cross-tenant analytics are trivial — it’s all in one place
  • A bug in your WHERE clause leaks data across tenants — this is the single biggest risk
  • Noisy neighbor problems — one tenant’s heavy query slows everyone down
  • Compliance and data residency are harder to prove (GDPR, SOC 2, HIPAA)
  • Deleting a tenant’s data requires surgical DELETE operations across every table, cascading through foreign keys
  • You can’t point a client to their own database as a trust signal

Pattern 2: Shared Database, Separate Schema (The Schema-per-Tenant Pattern)

Rule: If you use this pattern, implement tenant isolation at the ORM/query-builder level, not just in individual queries. A missing WHERE tenant_id should be impossible, not accidental. Tools like SQLAlchemy’s scoped sessions or Prisma middleware can enforce this automatically at the framework level.

One PostgreSQL database server, but each tenant gets their own schema namespace. 

CREATE SCHEMA tenant_001; CREATE SCHEMA tenant_002; -- Each tenant's tables live in their own schema CREATE TABLE tenant_001.subscriptions (...); CREATE TABLE tenant_002.subscriptions (...);
  • Stronger isolation than the discriminator pattern — tenants are in separate schemas, a SQL-level boundary
  • Still shares the database server — lower cost than dedicated databases
  • Schema changes can be scripted per-tenant, allowing rolling upgrades one tenant at a time
  • Easier tenant deletion — DROP SCHEMA tenant_001 CASCADE and you’re done
  • You can show the tenant their schema name as a trust signal
  • Schema migrations run once per tenant — N tenants means N migration runs
  • Cross-tenant analytics are harder — you need to UNION across schemas or build an analytics warehouse
  • PostgreSQL does not have a practical limit of 1,500 schemas; it can support thousands of schemas per database, though extremely large numbers may impact backup tools and internal cache memory
  • Backup and restore are trickier — pg_dump of the whole database includes all tenants
  • Connection pooling gets complex because each schema needs its own pool context

Pattern 3: Separate Database per Tenant (The Dedicated Pattern)

Rule: Set search_path in a BEFORE LOGIN trigger or at connection initialization. Never trust application-level routing alone — a bug that forgets to set the schema is a data leak waiting to happen.

Each tenant gets their own database instance. On PostgreSQL, this could be a separate database within the same cluster or a completely separate server. 

TENANT_DB_MAP = { "tenant_001": "postgresql://host/db_tenant_001", "tenant_002": "postgresql://host/db_tenant_002", } # On login, connect to the tenant's database connection = get_connection(TENANT_DB_MAP[tenant_id])
  • Maximum isolation — physical separation at the database level
  • Easiest compliance story for SOC 2, HIPAA, and PCI-DSS audits
  • No noisy neighbor — one tenant’s heavy load doesn’t affect anyone else
  • Simple tenant deletion — just drop the database
  • You can provision a read replica for that one tenant without affecting others
  • Point the tenant to their own database as a trust signal during sales
  • Highest cost — one database per tenant, minimum
  • Schema migrations run N times (or you need automation to run across all databases)
  • Hard to scale — each new tenant is a database provisioning event
  • Cross-tenant analytics require federated queries or an ETL pipeline into a separate data warehouse
  • Operational overhead — N databases to back up, monitor, maintain, and troubleshoot
  • Connection management is complex — you need a pool per tenant or a dynamic pool manager

The Isolation Spectrum: Choose by Maturity

Rule: Use a connection pooler like PgBouncer in transaction mode, one pool per tenant. Without pooling, each request opens a new connection and you’ll exhaust PostgreSQL’s max_connections setting long before you exhaust your patience.

The smartest approach: start with shared schema, migrate to separate schema or database as specific tenants demand it. Don’t overbuild. You’ll know when it’s time — an enterprise customer will tell you.

The Hybrid Approach

The most flexible multitenancy architecture is a hybrid: default to shared schema for most tenants, but allow elevation to separate schema or dedicated database for enterprise customers who demand it.

This means:

  1. Build your data access layer to abstract away the physical isolation strategy — the rest of your code shouldn’t care which pattern is in use
  2. Add a tenant.isolation_level flag: shared , schema , or dedicated
  3. Route queries based on that flag at the connection layer
  4. Let customer requirements drive infrastructure spending, not the other way around
  5. Build migration tooling that can move a tenant from shared to dedicated isolation with a single operation

Many platforms start with shared isolation and gradually adopt hybrid models as enterprise customers demand stronger guarantees. You can follow a similar path.

Common Multitenancy Mistakes (and How to Avoid Them)

Never put tenant_id in the URL path. Use subdomains ( acme.yourapp.com ) or HTTP headers ( X-Tenant-ID ). URL paths are shared in browser history, server logs, and referer headers — they’re not safe for tenant routing. An engineer bookmarking a debug URL can leak tenant context to another user.

A background worker doesn’t have a login session or request headers. Every job must carry the tenant_id in its payload. If a worker processes a job and doesn’t know which tenant it belongs to, it either leaks data across tenants or fails silently. Queue every job with tenant context baked in.

Add a dedicated test suite that specifically verifies Tenant A cannot read Tenant B’s data through every endpoint. Run it on every deploy. This isn’t optional — it’s the difference between “we have a security model” and “we had a security model.” Automate this in CI/CD so a regression is caught before it reaches production.

When you’re running migrations across N tenants, one flaky tenant can block everyone. Run migrations asynchronously with a per-tenant lease or lock. If Tenant X’s migration fails, retry it later — don’t block the entire system. Use a tool like Alembic for PostgreSQL or Liquibase for other databases.

How does a new tenant get provisioned? Manual? Self-service? The answer affects your signup flow, your database provisioning, and your support SLA. Decide this before you write code. Self-service works for shared schema. Dedicated databases require manual or automated provisioning — you need a decision.

In shared-schema and shared-database patterns, a single large tenant with millions of rows can slow down queries for smaller tenants. Implement row limits, pagination caps, and query timeouts per tenant. Consider rate-limiting API calls based on the tenant’s plan tier.

Multitenancy and Billing: Where It Gets Real

Here’s what most architecture articles won’t tell you: multitenancy isn’t just a database problem. It’s a billing problem.

When you’re charging per-seat, per-usage, or per-tenant, your billing system needs tenant context in every transaction. Stripe doesn’t care about tenant_id — you build that mapping. Chargebee doesn’t know about your schema separation — you build that too.

Your billing layer needs:

  • Tenant-scoped usage tracking (metered per tenant, billed per agreement)
  • Tenant-scoped proration (Tenant A upgrades mid-cycle, Tenant B is unaffected)
  • Tenant-scoped downgrades and cancellations (isolate the blast radius)
  • Cross-tenant aggregation for enterprise contracts (parent company bills for 50 sub-tenants)
  • Webhook reconciliation that maps payment events back to the correct tenant

This is where tools like Serial Subscriptions matter — they handle tenant-scoped billing, usage metering, and subscription lifecycle management as a single integration, so you don’t have to wire Stripe webhooks through your tenant isolation layer yourself.

Multitenancy Architecture: The Decision Framework

Don’t pick a pattern based on what feels architecturally pure. Pick based on your current customer profile and revenue stage:

FAQ

What is multitenancy in simple terms?

Multitenancy means one application serves multiple customers, with each customer’s data kept separate. Think of it like an apartment building: one structure, multiple units, each with their own lock.

Which multitenancy pattern should I start with?

Start with shared schema (the discriminator pattern). It’s the cheapest, simplest, and most flexible. You can always migrate to stronger isolation later as customer needs change.

How do I handle tenant data deletion in multitenant SaaS?

In shared-schema, you need cascading DELETE queries for every table with a tenant_id . In separate-schema, you DROP SCHEMA . In separate-database, you DROP DATABASE . Make this process auditable — compliance requires a paper trail of data deletion.

Can I use multitenancy with usage-based billing?

Yes. In fact, multitenancy is the most common architecture for usage-based billing because metering is easier when all tenant usage flows through a single application. Track usage per tenant_id , aggregate at billing boundaries, and invoice per agreement.

Fact Check

  1. PostgreSQL does not have a practical limit of 1,500 schemas; it can support thousands of schemas per database, though extremely large numbers may impact backup tools and internal cache memory.