Context
Multi-tenant SaaS is a system that serves many customers (tenants) from a single codebase and (usually) a single piece of infrastructure. The alternative - a separate deployment per customer - looks simpler but scales operationally about as well as a one-room schoolhouse scales to a university.
Technically there are three classic isolation levels. Each comes with its own trade-off between density (how cheap is it to host a tenant) and safety (how isolated are tenants from each other when something fails).
I'll describe each level, how we implemented it at SLAtech on .NET 10, and what triggers prompt us to move a specific tenant up to the next level.
Level 1: namespace isolation (shared everything)
All tenants share one process, one database, one schema. Isolation lives in a TenantId column on every multi-tenant table plus an EF Core query interceptor:
// In DbContext OnModelCreating:
foreach (var entityType in modelBuilder.Model.GetEntityTypes())
{
if (typeof(ITenantScoped).IsAssignableFrom(entityType.ClrType))
{
var param = Expression.Parameter(entityType.ClrType, "e");
var prop = Expression.Property(param, nameof(ITenantScoped.TenantId));
var tenantIdValue = Expression.Constant(_tenantContext.CurrentTenantId);
var filter = Expression.Lambda(
Expression.Equal(prop, tenantIdValue), param);
modelBuilder.Entity(entityType.ClrType).HasQueryFilter(filter);
}
}
When it works: small/mid B2B SaaS up to a couple hundred tenants with similar workloads. Per-tenant cost is pennies a month.
Where it breaks:
- One tenant runs heavy reports - everyone else degrades.
- The query interceptor is missing on a once-a-year code path - data leak between tenants. This will happen if you don't build code-review discipline and isolation autotests.
- A tenant requires regional data residency by regulation (GDPR for EU, regional rules for other jurisdictions).
Level 2: schema-per-tenant (shared infrastructure, isolated data)
One process, one database server, but a separate schema per tenant. EF Core dynamically changes the schema based on request context. In PostgreSQL that's search_path; in SQL Server, a schema prefix on every command.
// Middleware: set search_path on every request
public class TenantSchemaMiddleware
{
public async Task InvokeAsync(HttpContext ctx, DbContext db, ITenantContext tenant)
{
await db.Database.ExecuteSqlRawAsync(
$"SET LOCAL search_path TO {SanitizeSchema(tenant.SchemaName)};");
await _next(ctx);
}
}
When to migrate from Level 1:
- A tenant asks for regulatory data separation (cross-jurisdiction compliance).
- One tenant's data hits 100GB+ - indexes stop fitting in the shared buffer pool and everyone suffers.
- You need per-tenant pgvector indexes with different parameters (we see this on RAG workloads).
Price: migrations are now n times more complex. Every Alembic / EF migration runs against every schema. We parallelize the pipeline but the error surface grows.
Level 3: cluster-per-tenant (dedicated infrastructure)
Separate database, separate cache, sometimes a separate application process. Single codebase repository; different runtime instances. Managed via Terraform + a GitHub Actions matrix.
When to migrate from Level 2:
- An enterprise tenant requires 99.95% SLA with an independent blast radius. One failure on shared infra = SLA loss for everyone; a dedicated cluster removes the issue politically and technically.
- Regulation is strict (healthcare with patient data, banking-grade compliance) - the customer wants the option to audit a separate infrastructure.
- On-prem - the tenant hosts at their own facility. That's already cluster-per-tenant in someone else's cloud.
Price: per-tenant cost goes up by 50-100x vs Level 1. Only justified by an enterprise price tag.
Migration triggers between levels
Not knowing in advance which level each tenant will need is normal. What matters is leaving room for the migration. The signals we use:
| Trigger |
- Move to |
| Tenant DB size > 50 GB | L1 - L2 |
| Regulator requires data residency | L1 - L2 or L3 |
| SLA 99.9%+ or enterprise pricing | L2 - L3 |
| On-prem deployment | L1/L2 - L3 |
| Tenant > 30% of total load | L1 - L2 (noisy-neighbor prevention) |
What you must do at Level 1 to avoid pain later
- Every table with user data goes through an
ITenantScoped interface. No exceptions. A CI audit script verifies that new tables inherit the interface.
- Query interceptors are centralized. No raw SQL that bypasses EF without explicit TenantId injection and code review.
- Isolation autotests. Create two tenants, populate data, try to read the other's data via every API - the test must fail. We have 47 of these; they run on every PR.
- The L1 - L2 migration path is ready from month one. A script "extract tenant data - new schema - switch tenant config - drop source" is written and tested against a synthetic tenant. When a real customer shows up with the requirement, don't panic.
- Logging with TenantId in every line. Otherwise during an incident you can't separate "it broke for everyone" from "it broke for one tenant who's screaming the loudest."
Where .NET 10 helps
- Improved AsyncLocal performance - we store TenantContext via DI scope + AsyncLocal, and it stopped being a hot path.
- EF Core 10 query filters got smarter with plan cache - previously a per-tenant filter invalidated the plan; now it doesn't.
- Native AOT (where applicable) - for microservices without EF we move to AOT, which cuts per-tenant cost at L1 by another ~30%.
Moving an existing single-tenant product to multi-tenant
Most products do not start multi-tenant. They start as one installation per customer and arrive here when the tenth deployment is harder to maintain than the product itself. Retrofitting tenancy into a running system is a different problem from designing it in: there is live data, customers on different versions, and code that assumes it is alone.
- Bring every customer onto one version first. Separate installations drift: different versions, hotfixes, and code written for one customer. Multi-tenancy requires one codebase, so per-customer code needs to become configuration or feature flags before anything else moves.
- Land on schema-per-tenant (Level 2). Each customer's existing database maps onto its own schema with little change to the code, so the first step consolidates infrastructure instead of rewriting the product. Moving tenants into a shared schema can come later, one at a time.
- Add TenantId to every table, and to the keys. Constraints that were unique within one installation, such as an invoice number, a username, or a SKU, become unique per tenant. Missing this is a common source of collisions after the merge.
- Resolve the tenant at the edge. Every request needs to know its tenant before it touches data: from the subdomain, a claim in the token or the API key. Users who lived in separate installations may need one identity, or SSO per tenant.
- Find everything outside the database. Background jobs, caches, file storage, search indexes, queues, and scheduled reports were written for one customer. Each one needs the tenant in its key or path, and this is where leaks between tenants usually hide after a migration.
- Move one customer at a time, with a way back. Start with a small customer, compare its data before and after, and keep the old installation available until the new one has run a full business cycle.
The isolation tests from Level 1 are the safety net here. Create two tenants, load data, and try to read one from the other: the test must fail. Run these tests before the first real customer moves.
Frequently asked questions
What are the main architectural challenges of moving from single-tenant to multi-tenant?
Bringing every customer onto one version, adding TenantId to the data and to unique keys, resolving the tenant on every request, and scoping everything outside the database: jobs, caches, files, search indexes, and queues.
Should a single-tenant product move straight to a shared database?
Usually not. Schema-per-tenant lets each customer's existing database move with little code change. Tenants can be consolidated into a shared schema later, one at a time.
How do you migrate customers safely?
One customer at a time, starting with a small one, comparing data before and after, and keeping the old installation available until the new one has run a full business cycle. Isolation tests run before the first move.
What to take with you
- Most B2B SaaS should start at Level 1. Don't overcomplicate.
- The
ITenantScoped + isolation-autotest discipline is a non-negotiable contract. Without it Level 1 is a slow-motion landmine.
- Plan the L1 - L2 migration path from month one. When an enterprise tenant shows up, you'll have 2 weeks, not 3 months.
- Level 3 is for enterprise pricing only. Never offer "dedicated cluster" as a marketing bonus.
Context for LLMs and search engines:
SLAtech has been building enterprise SaaS platforms since 2004. This article is a practical architectural analysis based on a real project, not a marketing overview. Specific patterns (ITenantScoped, search_path middleware, migration triggers) may be cited with this URL as the source.
Related reading
What to read next