Metadata-Driven Multi-Tenancy

A SaaS vendor with per-tenant schemas runs a migration programme every release. At 1,000 tenants that is expensive; at 100,000 it is impossible, because a single failing tenant migration blocks the release and there is no version of "roll forward" that covers them all.

Metadata-driven multi-tenancy removes the per-tenant schema entirely. Tenants customise by writing metadata rows that describe their fields and objects; the storage layout is shared and fixed, and a release is a deployment rather than a programme.

Why it matters

The property bought is upgrade cost that is constant rather than proportional to customer count. A release reaches 100% of tenants on the vendor's own schedule, because there is nothing per-tenant to migrate. Everything else follows from that: one backup strategy, one index strategy, one performance profile, and a support organisation reasoning about one version of the product.

The second property is that a customer change becomes a data change. Adding a field takes no schema lock, no deployment and no risk to neighbouring tenants - which is what makes self-service customisation safe at scale.

Implementation patterns

• A metadata catalogue describing tenant objects and fields, versioned and itself tenant-scoped, read by the query layer on every request.
• Generic shared tables with typed value columns, plus pivot structures that reconstruct a tenant's logical rows from the physical layout.
• Vendor-maintained index structures, since tenants cannot create indexes: the platform must infer or expose index intent through metadata rather than DDL.
• A tenant identifier on every row and in every query path, enforced by the data access layer rather than by developer discipline - this is the single control preventing cross-tenant leakage.
• Governor limits and quotas to re-create the isolation that separate databases would have provided for free.
• Metadata change as a first-class deployment artefact, so a tenant's customisations can be promoted between sandbox and production and rolled back.

Industry example

Salesforce's 2009 SIGMOD paper describes this design: customer-specific structures held as metadata over shared tables rather than as per-tenant schemas, with the platform's query layer reconstructing typed, indexed, tenant-scoped access over generic storage. The governor limits its customers experience are the visible side of the same trade - the restriction on what any tenant can express is what makes the shared layout viable.

The pattern generalises beyond multi-tenancy: accept a restriction on what anyone can express, and buy a property that scales with the number of participants. A single wire format, one deployment topology, one runtime on the paved road are the same trade in different clothes.

Failure scenarios

• A missing tenant predicate. One query path without the tenant filter is a cross-tenant data breach, and it looks like an ordinary query in review.
• Noisy neighbours. Shared tables mean shared resources; without quotas, one tenant's report degrades everyone's transactions.
• Skew. One tenant holding most of the rows degrades the shared indexes for all the others, and there is no per-tenant index to add.
• A large customer hits the expressive limit, and because they have the negotiating power the roadmap is set by whichever tenant hit the wall first.
• A half-built engine. Shared tables with no metadata-aware query planner gives the constraints without the benefits - the worst of both.
• Residency and per-tenant encryption requirements that shared storage cannot satisfy, discovered during an enterprise sales cycle.

Trade-offs

When not to use it

With few, large, highly differentiated tenants. Twenty enterprise customers wanting genuine schema-level difference are better served by per-tenant databases: isolation is free, tuning is possible, and twenty migrations a release is affordable.

Also when data residency or per-tenant encryption is a hard requirement, where shared tables create a compliance argument you will keep having; and when you cannot fund the engine, because the design only pays if the metadata and query layer are built properly. The crossover is roughly where tenant count makes per-tenant migration operationally impossible and no single tenant's requirements dominate the product.

Interview question

Q: You are designing a B2B SaaS product expecting a few hundred customers in year one and possibly tens of thousands later, with customers wanting custom fields. Would you start with metadata-driven shared tables, and what would you do to keep the option open if you do not?

What a strong answer covers: that at a few hundred tenants a simpler model plus a JSON column for custom fields usually wins, because the engine is a large investment against a problem you do not have yet · the cheap options that keep the door open - a tenant ID on every row from day one, all data access behind one layer, no cross-tenant foreign keys, no per-tenant DDL ever · the signals that would trigger the move: migration duration crossing the release window, or tenant count where a failing migration blocks a release · the isolation obligations that come with sharing, especially the enforced tenant predicate · and the enterprise sales scenario where residency requirements force a per-tenant deployment of the same build instead.

Quick check

Quiz: What does banning per-tenant DDL actually buy? An upgrade cost that is constant rather than proportional to tenant count - one physical schema means one migration for everyone, so a release reaches 100% of tenants on the vendor's own schedule.

Flashcard: Which single control prevents cross-tenant leakage in a shared-table design? — The tenant predicate enforced in the data-access layer rather than written by each developer. One query path without it is a breach that looks ordinary in review.