Every schema change is now fifteen migrations, run by hand, on fifteen deployments, and last Thursday one of them failed halfway and nobody noticed until a customer did. Or the other version: you built one system for one client, it worked well enough that you want to sell it to the whole market, and you have just discovered that tenant_id is not a column you can add on a Tuesday.
Both roads lead to the same week. Somebody, possibly an agency, has told you this needs a rewrite. You half believe them and you are dreading what comes attached to that word.
It is usually not a rewrite. It is a well-defined migration with an unusually long list of small parts, and the reason it feels unbounded is that the assumption you are removing was never written down anywhere. Nobody ever typed a line that said there is only one customer. They just wrote every query, every cache key and every background job as though that were true, and now the assumption has to be found and removed one place at a time.
This page is the list. It is written for the retrofit, not for a blank page. If you are designing a multi-tenant system from scratch, our companion piece on multi-tenant architecture for white-label platforms is the better starting point, because greenfield lets you make choices this page has to work around.
How Do You Know You Are Actually Single-Tenant?
The test is not what the architecture diagram says. It is what happens when you add a customer. If that means a new deployment, a new database, a new config file or a subdomain someone wires up by hand, you are single-tenant, whatever the diagram claims.
There is a sharper test in the code. Open your data access layer and find a query that reads a table without filtering by customer. If you find one quickly, look for the next. In a genuinely single-tenant codebase almost every query looks like this, because filtering by customer would have been meaningless when the code was written. That is the real shape of the problem, and it is why the estimate people give you is always wrong. The work is not concentrated in a module. It is smeared across the whole application in the form of an assumption nobody declared.
It is worth separating two situations that look alike and cost differently.
Deployment-per-customer. One codebase, many running copies, each with its own database. This is the more common accident and the more tractable one, because the code already has a notion of configuration varying per customer. The pain is operational rather than architectural, and it grows linearly with every deal your sales team closes.
One bespoke system you now want to productise. Harder, because the code frequently contains that one client's rules in places that are not configuration. A workflow that assumes their approval chain. A report shaped around their fiscal calendar. Those are not tenancy problems, they are product problems wearing tenancy clothing, and finding them is a separate exercise from anything in this article.
Knowing which one you are matters more than any technical decision further down this page, because the second one has a discovery phase and the first does not.
Why Does Adding a tenant_id Column Not Make You Multi-Tenant?
Because the column is the easy afternoon and everything that depends on it is the quarter. A tenant_id that exists but is not enforced is genuinely worse than not having one, because it looks like isolation in code review and provides none at runtime.
Here is what that means in practice, and the stakes are not abstract. Every item below is a way one customer sees another customer's data.
Your unique constraints are now wrong. A UNIQUE constraint on an email column was correct when there was one customer. The moment there are two, it means a person cannot exist as a user at two of your customers, which is common in any market where people work with more than one supplier. This surfaces weeks later as a signup bug that nobody can reproduce, because reproducing it requires two tenants and a shared email address. Every such constraint has to become composite, on the tenant and the column together.
Your foreign keys do not check tenancy. A standard foreign key guarantees the parent row exists. It does not guarantee the parent belongs to the same tenant as the child. Nothing in a conventional schema stops an invoice in tenant A from referencing a customer record in tenant B, and no error is raised when it happens. Closing that properly means composite keys carrying the tenant on both sides, which is more schema churn than most people expect and is the reason this section exists before the one on choosing a model.
Your indexes are the wrong shape. They stay valid, which is the problem. An index built for single-tenant access remains perfectly usable and quietly stops being selective once every query also filters by tenant. Nothing fails. Query times drift upward as you add customers, and the cause is not obvious from any error.
The stakes. The failure mode here is not downtime, which would at least be loud. It is a customer seeing another customer's data. That is the one incident class in business software that does not get forgiven, that has to be disclosed, and that ends enterprise contracts on the spot. It also tends to be discovered by the affected customer rather than by you, because your monitoring has no concept of a query returning the wrong tenant's rows successfully.
This is the reason the rest of the migration is worth doing carefully rather than quickly, and it is why the enforcement mechanism matters more than the column.
Database Per Tenant, Schema Per Tenant, or Shared Tables?
Choose based on how you will be audited and how you sell, not on which is technically cleaner. All three work. They fail in different directions, and the direction matters more than the merits.
Shared tables with a tenant column. One database, one schema, every table carrying the tenant, isolation enforced by database policy. Cheapest to operate by a wide margin. A schema change is one migration. Adding a customer is a row. Reporting across tenants is a query rather than a project. The costs are real too: a mistake is a cross-tenant leak rather than a contained error, one tenant running an expensive report degrades everyone unless you plan for it, and deleting a single customer's data on request becomes a careful cascade rather than a single command.
Database per tenant. The strongest isolation story and the easiest one to explain to a security reviewer. Per-tenant backup and restore is trivial. Erasure is trivial. Noisy neighbours mostly disappear. What you buy in exchange is a migration that now runs once per customer and has to be orchestrated and monitored, a connection count that grows with your sales pipeline until pooling becomes its own project, and the loss of easy cross-tenant reporting. Notice that this is the model you are already in if you arrived here from deployment-per-customer, so treat this option honestly as staying put with better tooling.
Schema per tenant. One database, a named schema per customer. It looks like a compromise and often behaves like the worst of both. You keep the per-tenant migration cost of the isolated model, since every schema needs the change, and you do not get the clean per-tenant restore story that makes the isolated model worth its price. Postgres also starts to feel the object count in the thousands of schemas. It is a reasonable choice at a few dozen tenants and a poor one at a few thousand.
The practical rule. If your buyers are mid-market and your differentiator is shipping quickly, pool into shared tables. If your buyers are regulated enterprises whose procurement asks where exactly their data lives, or if you have already signed contracts promising a dedicated database, you cannot pool without renegotiating something. Plenty of mature platforms end up running both: pooled by default, isolated for the small number of customers who pay for the difference. That is a legitimate destination, and it is much easier to reach from a pooled architecture than from an isolated one.
One thing worth saying because it is rarely said: this decision is reversible, at a cost. Going from pooled to isolated is mechanical once tenancy is enforced. Going from fifteen deployments to pooled is the hard direction, and it is the one you are on.
How Does Row-Level Security Actually Enforce Isolation?
Row-level security moves the tenant filter out of your application and into the database, so that a query a developer forgot to scope still cannot cross a tenant boundary. You enable it on a table and write a policy whose USING clause compares the row's tenant column against a value the application sets for the current transaction. Postgres then applies that predicate to every statement against the table, without the application asking.
That is the mechanism, and it is the right one, because it changes the question from whether every developer remembered to filter to whether the database is capable of returning the row at all. Two details decide whether you actually get that guarantee or only the appearance of it. Both are common and neither is loud.
Enabling row-level security does not apply it to the table owner. This is the single most important sentence on this page. In Postgres, the role that owns a table bypasses that table's policies by default, and any role holding the BYPASSRLS attribute ignores policies regardless of ownership. A great many applications connect as the schema owner because that is what the setup guide did. In that configuration you can enable row-level security, write correct policies, review them, and have precisely nothing enforced at runtime. FORCE ROW LEVEL SECURITY is what makes policies apply to the owner as well. Better still, have the application connect as a role that owns nothing and holds no bypass, so the guarantee does not depend on remembering a setting.
Session-level configuration leaks through a transaction pooler. The usual way to tell the database which tenant is active is to set a configuration parameter that the policy reads. If you set it at session level and you run a connection pooler in transaction pooling mode, you have a cross-tenant read waiting to happen. In transaction pooling a connection returns to the pool at the end of every transaction and is handed to whichever request comes next, so a session-level value survives into a different tenant's work on the same connection. The reason this reaches production rather than being caught in testing is that it behaves correctly under low concurrency, when a connection is usually reused by the same request. Setting the value with SET LOCAL scopes it to the transaction and removes the problem entirely.
How to verify rather than assume. Connect to the database as the role your application actually uses, set the tenant context to one customer, and select a row belonging to another. If you get the row, you have no isolation, whatever the policy definitions say. Write that as a test and run it in continuous integration, because this is exactly the kind of guarantee that gets switched off by an unrelated change to a role grant and stays off silently. Our notes on Postgres in production cover the surrounding operational side of this.
Row-level security is not a substitute for filtering in your queries. Keep the filters, because they carry the index behaviour and make intent obvious to the next reader. Treat the policy as the thing that catches you the day somebody forgets.
What Breaks That Is Not the Database?
This is the part that turns a two-month estimate into six, because a database policy protects the database and nothing else. Everything below sits outside that boundary and every item has produced a real cross-tenant incident somewhere.
Cache keys built from a record id. A key like invoice:4821 was unambiguous when there was one customer. It is now a way to serve tenant A's invoice to tenant B, and it will do so faster than your database ever could. Every key needs the tenant in it, and the cache needs flushing on the day you make that change, because the old keys are still sitting there.
Background jobs that carry an id and no context. Jobs are enqueued during a request, when the tenant is known, and run later outside any request, when it is not. If the job payload has an id and the worker looks it up, the worker is running with whatever tenant context it happens to have, which is usually none. Under row-level security this fails closed and you get a mysteriously empty result. Without it, the job reads across tenants and succeeds. The fix is to put the tenant in the payload and to establish context as the first thing every worker does, which is a small change repeated in a lot of files.
File storage paths. Uploads written to a path built from a record id have the same problem as cache keys, with the added difficulty that renaming existing objects is a migration of its own and any stored URL pointing at the old path has to keep working.
Search indexes. If you run a separate search engine, it has no idea what a tenant is. Documents need a tenant field, every query needs a filter on it, and that filter is application-enforced with no database policy behind it. In a pooled architecture this is often the weakest link in the whole system, precisely because it sits outside the mechanism everyone trusts.
Webhooks and outbound integrations. Payloads assembled from a record often include more context than the receiving tenant should see, and a single signing secret shared across tenants means one customer can verify and read another's payloads.
Reporting and admin paths. Internal dashboards are usually written against a privileged connection, which is the exact configuration that bypasses row-level security. It is common to migrate the customer-facing application correctly and leave an internal tool as an unlogged, unscoped read of everything.
A specific note from our own work. The EdTech platform we run at 250,000+ daily users is white-label and multi-tenant, and the parts that needed the most care during scaling were not the schema. They were the cache layer and the background processing, for exactly the reasons above. You can read the detail in our case study on scaling that platform.
How Do You Migrate Live Customer Data Without Downtime?
In stages, with the application tolerating both shapes while you are in the middle. The instinct is to write one migration that adds the column, backfills it, makes it required and enables the policies. That migration takes a lock on a live table for as long as the backfill runs, and on a table of any size it is an outage.
The staged version looks like this, and the ordering is the whole trick.
Add the column nullable. In Postgres 11 and later, adding a column with a default that is not volatile does not rewrite the table, so this step is fast on tables where it used to be dangerous. Do not add the constraint yet.
Backfill in batches. Update in bounded chunks with a pause between them rather than in a single statement. A single statement holds one long transaction, accumulates dead tuples, and blocks autovacuum from doing anything useful for the duration. Batches let the database keep up and let you stop halfway without losing the work.
Write the tenant on every insert, tolerate null on read. Deploy the application change while the backfill is still running. From this moment nothing new is created without a tenant, so the backfill has a fixed finish line rather than a moving one.
Add the constraint in two steps. Once nothing is null, do not simply set the column not null, because that form scans the whole table while holding a lock that blocks writes. Add a check constraint with NOT VALID, which takes effect for new rows immediately and does not scan, then run VALIDATE CONSTRAINT, which scans under a weaker lock that readers and writers can work around.
Fix constraints and indexes before policies, not after. Composite unique constraints and tenant-leading indexes should be in place and building concurrently before you turn on enforcement.
Enable row-level security last. Turn the policies on only once you can prove the data is right. Enable them early and every remaining data bug presents as rows vanishing, which sends the team hunting for data loss that never happened. Turning them on at the end converts a confusing failure mode into an obvious one.
Through all of this, keep the old shape working. The ability to stop halfway is worth more than the speed of any individual step, because the one certainty in a migration this wide is that something in the list of things that break outside the database will surface at an inconvenient moment.
Does This Mean Rewriting the Application?
Almost never. This deserves saying plainly, because it is the point at which teams get sold the most unnecessary work, and because you arrived here having already been told otherwise by somebody.
Look at what actually changes. Your domain logic does not care how many customers the database holds. Your screens do not. Your business rules, your validation, your workflows and the large majority of your code are indifferent to tenancy. What changes is the data access layer, the constraint and index definitions, how context reaches background work, and key naming in anything cached. That is a serious piece of engineering with a real cost and it is not the same activity as starting again.
Be suspicious of a specific pattern. If the answer to a tenancy question arrives as a proposal to rebuild the product on a new stack, notice that the proposal is larger than the problem and that the person making it benefits from that. There are genuine reasons to rebuild a system. Needing a tenant boundary is rarely one of them, because a rewrite does not remove any of the work on this page. You still have to find every place the old code assumed one customer, and now you have to do it while reimplementing everything else at the same time.
The case where the rewrite argument holds is narrower and worth naming honestly. If the code is one client's business rules rather than a product, if there is no test coverage to tell you when a change breaks something, and if the people who wrote it are gone, then you are not doing a tenancy migration. You are extracting a product from a bespoke system, and that is a different and larger project which happens to include this one. Anyone who cannot tell you which of the two you are in has not read your code.
The cheap way to find out is to have somebody audit the schema and the data access layer before committing to anything. That work is measured in days and it is the only step that can change the plan.
Who Should Not Do This Migration Yet?
Plenty of teams read a page like this, conclude they are behind, and spend a quarter on architecture their business does not need. That is a real cost with nothing on the other side of it, so here is the honest list of people who should close this tab.
Anyone with a handful of customers and working automation. Three deployments, a scripted release and a schema change you run three times is an inconvenience, not an architecture problem. The migration on this page costs you a quarter of product work. Spend it on the product.
Anyone still finding out whether the market wants this. If you are validating demand, the deployment model is not what is standing between you and growth. Multi-tenancy is an efficiency gain on a business that is already working.
Anyone who has promised a dedicated database in a signed contract. Pooling would put you in breach. That is a commercial conversation before it is a technical one, and the technical answer changes completely depending on how it goes.
Anyone whose real problem is per-customer code. If each customer has a different workflow implemented in code, tenancy is not your bottleneck, configurability is. Doing this migration first means porting all that divergence into a shared schema, which makes it more expensive to remove later, not less.
And the group who should be honest in the other direction. If every sale adds operational load, if you are declining deals because onboarding takes weeks, or if a security review has already asked a question you could not answer, this is not premature and delaying it makes it larger. Every customer you add before the migration is another dataset that has to move during it.
What Does an Enterprise Security Review Ask?
This section is here because tenancy decisions are usually forced by a buyer rather than by an engineer, and knowing the questions in advance changes which model you pick.
How do you prevent cross-tenant access? Reviewers want a mechanism, not a policy. Answering that every query filters by tenant is a statement about developer discipline, and an experienced reviewer will hear it that way. A database-enforced predicate is a mechanism. Being able to demonstrate it live, by connecting as the application role and failing to read another tenant's data, ends the question rather than extending it.
How is one customer's data deleted? Trivial when a tenant is a database. Genuinely hard when a tenant is a set of rows spread across tables, caches, a search index and a rolling backup window. Erasure obligations under privacy regimes make this a contractual matter rather than a nice-to-have, and the backup question in particular has no comfortable answer in a pooled model unless it was designed for.
How is one customer restored without touching anyone else? The question behind it is what happens when their data is corrupted by a bug on your side. In an isolated model you restore one database. In a pooled model, restoring one tenant from a backup that contains everybody is a real engineering task, and if you have not built it, the honest answer is that you cannot, which reviewers notice.
Where does the data live? Data residency splits tenants by geography whether you wanted it to or not. If a European customer requires their data in the region, you are running at least two of something, and the pooled model has to become pooled-per-region.
The pattern across all four is that they are answered by architecture, not by documentation, and they are far cheaper to answer during a migration than after one. Teams that build erasure and per-tenant restore into the migration pass these reviews. Teams that treat them as later work usually end up rebuilding a part of the migration to accommodate them.
What Order Should the Migration Be Done In?
The sequence matters more than the speed, because two of these steps can change the plan and both are cheap to run.
First, audit the schema and the data access layer. Count the tables, find the unique constraints that need to become composite, find the foreign keys that cross what will become tenant boundaries, and find every query that reads without scoping. This is days of work and it is the only step that can tell you the job is bigger or smaller than you thought.
Second, decide the isolation model against your sales motion. Not against a technical preference. Ask who you are selling to in eighteen months and what their procurement will ask. This decision constrains everything after it.
Third, inventory what sits outside the database. Cache keys, background jobs, file paths, search indexes, webhooks, internal dashboards. Do this before you write any migration, because the length of this list, not the schema, is what determines the timeline.
Fourth, fix constraints and indexes. Composite uniqueness, composite foreign keys, tenant-leading indexes built concurrently.
Fifth, migrate the data in stages. Nullable column, batched backfill, application writing tenants, then the constraint in two steps.
Sixth, enforce at the database. Policies on, forced for the owner, application connecting as a role that owns nothing, and a test in continuous integration that tries to read across tenants and expects to fail.
Seventh, close the gaps outside the database in the order the inventory ranked them, most exposed first.
Eighth, build erasure and per-tenant restore while the context is fresh and before a buyer asks.
Doing the audit last is the most expensive sequencing mistake available here. Doing the outside-the-database inventory last is a close second, because it is the part that makes the estimate wrong and it is the part everybody defers.
If you want a second opinion on the shape of your own system before committing to any of this, that is what the review below is for. Where the answer is that your team can carry this unaided, we will say so, and there is nothing to buy. If you would rather talk about the build itself, our SaaS product development work is where that conversation starts.
