Databaseadvanced

Multi-Tenant SaaS Architecture

Multi-tenancy is one of the highest-leverage architectural decisions in a SaaS, and almost impossible to fix later. This playbook is the model I use to design tenant isolation that scales from ten customers to ten thousand: shared schema with row-level isolation, tenant-scoped routing, configuration, billing, and an admin layer that lets you operate the platform without breaking customer trust.

90 min7 steps

Steps

Tools

Outcomes

advanced

Difficulty

Technologies used

PostgreSQLNext.jsPrismaVercel

The methodology

The phases, in order

Each phase below is something I actually run in a project. The descriptions are how I think about the work, not abstract definitions.

Phase

Phase 1 of 7

Choose the Tenancy Model

I default to shared schema with a tenant_id column on every tenant-scoped table, enforced by row-level security. Schema-per-tenant only makes sense at very high tenant counts with strong isolation requirements. Database-per-tenant is rarely worth it. See the SaaS starter blueprint for the reference shape.

Phase

Phase 2 of 7

Data Isolation with RLS

Postgres row-level security policies are the actual isolation layer, not application code. Every tenant-scoped table gets a policy keyed to the current_setting('app.tenant_id'), and the connection middleware sets that variable per request. Application bugs cannot leak data across tenants because the database itself refuses to return rows for the wrong tenant.

Phase

Phase 3 of 7

Tenant-aware Routing and Custom Domains

I support both subdomain routing (acme.app.com) and custom domains (app.acme.com). A middleware resolves the request host to a tenant id before any handler runs. Custom domains use a wildcard certificate plus a verification flow where the customer adds a TXT record. SSL is automated end to end.

Phase

Phase 4 of 7

Configuration and Theming

Each tenant has a settings table with branding, feature flags, and limits. The app reads tenant config once per request from a short-lived cache. Custom theming uses CSS variables set in the document root by a server component, so themes render server-side with no flash.

Phase

Phase 5 of 7

Billing and Usage Tracking

Usage events flow into a metering table with idempotency keys so retries do not double-count. Stripe handles the actual billing, and a reconciliation job runs nightly to compare metered usage with Stripe invoices. See Stripe vs Adyen for picking a billing partner.

Phase

Phase 6 of 7

Admin and Impersonation

I build a super-admin layer with explicit allowlists, audit logging on every action, and an impersonation flow that customer support can use to debug a tenant without ever seeing raw credentials. Impersonation sessions are time-boxed and visible to the tenant in their audit log.

Phase

Phase 7 of 7

Per-tenant Limits and Noisy Neighbors

I enforce per-tenant rate limits and resource quotas so a single tenant cannot degrade the others. Heavy background jobs run on a per-tenant queue with bounded concurrency. This is the difference between a SaaS that scales gracefully and one that has a bad day every time a large customer runs a bulk import.

Results

What You'll Achieve

Expected outcomes from implementing this playbook

Secure data isolation enforced at the database layer

Custom domain support with automated SSL

Tenant configuration, theming, and feature flags

Scalable SaaS architecture in the SaaS industry

Want a SaaS build partner? Contact me.

Use this playbook

Want me to run this with you?

The playbook is the public version. The private version is me running it for your team against a real deadline. If you have a project on the line, that is usually the faster path.

Start a project Just ask a question

Related insights

More on this thinking

The studio journal

Essays and notes that pair with the playbooks.

Insights in Database

Filter the journal for pieces on this topic.

Related blueprints

Reference architectures

All blueprints

Production-grade reference systems I have shipped.

Labs

Experiments where I prototype the playbooks in public.

Next up

DevOps · 60 min

Production Monitoring & Observability

Observability is not three pillars on a slide, it is the difference between knowing why your system is misbehaving and guessing. This playbook is the monitoring stack I deploy on every production system: error tracking, structured logging, performance metrics, distributed tracing, and the dashboards and alerts that turn raw data into actionable signal without paging everyone at 3 AM.

Database

Related Playbooks

Other playbooks in this category

intermediate

Building Real-time Features with Supabase

Real-time features sell products, but they also break in spectacular ways if you do not respect the limits of the underlying broker. This playbook is how I add live subscriptions, presence, and optimistic updates to a React app using Supabase, without ending up with a UI that flickers on every reconnection. It covers schema design, RLS, presence, and the patterns that keep real-time work feeling instant rather than fragile.

advanced

Managing Database Migrations

Database migrations are the part of the system where a tiny mistake creates an outage that lasts hours. This is the playbook I follow when migrating a production schema: expand-then-contract, dual writes when needed, idempotent scripts, a real rollback plan, and verification that does not depend on the migration tool reporting success. Boring on purpose, because exciting migrations are the dangerous ones.

intermediate

Choosing a Database in 2026

Database choice is one of the highest-cost, hardest-to-reverse technical decisions in a product. This playbook is the decision framework I walk teams through when they ask me to weigh in: define the workload first, pick a sensible default, evaluate hosted options on real criteria, plan for scale before you need it, prototype the hardest query, and document the choice so the next engineer does not have to relitigate it.

Building RAG Applications

Production Monitoring & Observability