The Cheapest Database Migration Is the One You Do Before Production Exists
There's a species of infrastructure decision that gets more expensive every day you don't make it, and database migrations are its apex example. I moved my portfolio's Postgres database from Neon to Supabase in a single evening — schema, data, connection strings, and a Payload CMS adapter swap — and the honest reason it was that easy has less to do with tooling than with timing. My rebuild was still on staging. Production didn't exist yet. Nobody was reading the database I was about to move.
That's the thesis of this post, and I want to defend it properly: the cheapest migration window for any stateful dependency is the stretch of time after your architecture is real but before production traffic makes your data precious. Miss that window and the same migration acquires cutover plans, freshness deadlines, rollback rehearsals, and a maintenance page. Hit it, and a database migration is a build artifact you regenerate — not a liability you carry.
Here's the timing argument, the actual mechanics (including the two mistakes worth stealing lessons from), and how to recognize this window in your own projects while it's still open.
Why the window exists at all
Think about what makes a production database migration hard. It's almost never the schema — schema travels in a dump file. It's everything that accumulates around a database once real users depend on it:
Data freshness. In production, the data changes under you. Every migration plan needs a story for the writes that happen between your dump and your cutover — replication, a write freeze, dual-writing, or accepting loss. On a staging database, you are the write traffic. I stopped typing, took the dump, and freshness was solved.
Coordination surface. Production cutover touches DNS TTLs, environment promotion, cache invalidation, and anybody else who deploys. Pre-production, the coordination surface is one person changing environment variables in one dashboard.
Rollback stakes. If a production migration goes sideways, rolling back means reconciling whatever happened during the attempt. If a staging migration goes sideways, rolling back means pointing an environment variable at the old database, which is still sitting there untouched.
The audience. This is the quiet one. A production migration has stakeholders who need notice, status pages, and postmortems. A staging migration has an audience of exactly one, and he was the one holding the keyboard.
None of these costs announce themselves when you defer a migration. They accrue silently, and the bill arrives precisely when you finally decide to move — which is why "we'll migrate after launch" so often becomes "we're still on the old thing three years later." The window doesn't feel like it's closing, until it has.
What I was moving, and why
The concrete situation: my portfolio rebuild runs Next.js with Payload CMS as the content engine, storing everything in Postgres through Drizzle ORM. The database lived on Neon, provisioned through Vercel's storage integration back when that was the path of least resistance. It worked fine. Like the email vendor in my last post, nothing was broken.
But two of the four inertia signals I wrote about were already lit. I had chosen Supabase as the strategic direction — my other projects were consolidating there, and its tooling (including a first-class MCP server that lets my AI agents inspect the database directly) fit the platform stack I'm building on. And the migration window was demonstrably open: staging only, production weeks away, meaning production would be born on Supabase and there would never be a production database cutover in this project's history. Two signals plus an open window was enough. I had the drive-in initiative, as I put it that evening, and the whole thing was done before I went to bed.
The mechanics: an adapter, a dump, and an ordering decision
The migration had three moving parts, and each one taught me something worth writing down.
Part one: the adapter swap was configuration, not surgery
Payload's database layer is pluggable, and the plug matters here. The site used @payloadcms/db-vercel-postgres, which speaks Neon's serverless driver. Supabase needs the general-purpose @payloadcms/db-postgres adapter, which speaks standard node-postgres. Both are thin shells around the same Drizzle core — same schema representation, same migration format, same query building.
That shared core is what made the swap boring in the best way. My project carries a chain of migration files — every schema change since the rebuild began. Those files import types from the adapter package, so the swap was: install @payloadcms/db-postgres, update one import per migration file (a one-line sed), and change the config from the Neon-driver adapter to:
postgresAdapter({
pool: {
connectionString: process.env.DATABASE_URI || '',
},
})
The entire migration chain survived the adapter change untouched. If your CMS or ORM offers this kind of adapter interchangeability, it's worth knowing before you need it — it converts "database migration" from a rewrite risk into a dependency swap.
Just as important is what the swap didn't touch. My media files live in Vercel Blob, not in Postgres, and they stayed exactly where they were — the database migration moved the database, full stop. Keeping state stores separable (content in Postgres, files in object storage, cache in the framework) is what lets you migrate them one at a time instead of facing a single entangled everything-move. If your architecture can't move one state store without dragging the others along, that coupling is the first thing worth fixing — before any migration.
Part two: dump and restore, with pooler modes as the plot twist
Moving the data was classic pg_dump and restore — with one modern wrinkle worth understanding: connection pooler modes. Managed Postgres providers put a connection pooler in front of your database, and the pooler's mode changes what your connection can do.
Supabase's pooler (Supavisor) offers two flavors. Transaction mode (port 6543) hands your connection to a pooled backend per-transaction — ideal for serverless apps that open many short-lived connections, which is exactly what a Next.js app on Vercel does. Session mode (port 5432) gives you a dedicated backend for the life of the connection — which is what long-running administrative work like a restore needs. The connection docs spell out the split, but the practical rule is simple: apps through the transaction pooler, restores and migrations through session mode.
On the dump side there's a mirror-image rule: dump from the direct, non-pooled connection string. Vercel's Neon integration exposes both a pooled URL and a POSTGRES_URL_NON_POOLING variant; the non-pooling one is the correct source for pg_dump, because a pooler that juggles backends mid-dump is a recipe for confusing failures.
One small habit that prevented a whole category of problems: when I reset the Supabase database password, I generated a plain hex string (openssl rand -hex 32). Passwords with special characters have to be percent-encoded inside connection URLs, and a % mishap in an env var is one of those bugs that costs an hour and teaches nothing. Hex sidesteps the entire class.
Part three: restore order is a real decision
Here's the piece I'd call genuinely non-obvious: restore the data before the first deploy against the new database.
Payload runs migrations on deploy. The migration runner checks a bookkeeping table to see which migrations have already been applied. If I had deployed against an empty Supabase database first, the runner would have executed the entire migration chain against a bare schema, and my restored data would then have collided with freshly created tables. By restoring first, the dump arrived carrying both the data and the migration bookkeeping — so when the first deploy ran, the migration runner looked at the ledger, saw every migration already recorded, and did nothing. A no-op is exactly what you want your first deploy to be.
This generalizes past Payload: any framework that auto-runs migrations has an opinion about whether it's meeting a fresh database or a populated one. Decide which story your first deploy will encounter, on purpose, before you deploy.
The one failure, and what it taught
I promised the mistakes. The deploy after the cutover failed with password authentication failed for user "postgres" — while the password was verifiably correct.
The cause is a pooler detail that reads like trivia until it burns you: connections through Supavisor use a project-qualified username. You don't connect as postgres; you connect as postgres.<your-project-ref>, because the pooler serves many projects and routes by that suffix. My connection string carried the direct-connection form of the username with the pooler's host and port — a franken-string assembled from two different tabs of the connection dialog. The error message says "password," the actual problem is "username," and nothing in the string looks wrong.
The fix was thirty seconds once diagnosed. The lesson is durable: connection strings are format-sensitive in provider-specific ways, so copy each one whole from the provider's dialog for the exact mode you're using — never assemble one from remembered parts. If I'd been in a production cutover window, that failed deploy would have been minutes of downtime and a spike of adrenaline. On staging, it was a two-line diagnosis and a redeploy.
Second, smaller lesson: after the restore, I disabled Supabase's auto-generated Data API. Supabase exposes your tables over a REST interface by default, secured by row-level security (RLS) policies — per-row access rules that live in the database itself. But my hundred-plus tables are owned by Drizzle and Payload, which enforce access in the application layer, so none of them carry RLS policies. An API surface I don't use, over tables that don't carry the security model it expects, is pure attack surface. Turning it off cost nothing. The general habit: when you migrate onto a platform that does more than your last one, audit what it turned on for you — the features you didn't ask for are the ones you haven't secured.
Same category, opposite direction: know what your new tier turns off. Supabase's free tier pauses projects after about a week without activity, which is harmless for an actively developed staging site and exactly the kind of surprise you want to have read about before your demo goes down. Platform defaults — both the ones switched on and the ones that lapse — are part of the migration's real scope.
What "done" looked like
A migration you haven't verified end-to-end is a migration you've assumed. The checklist that closed the evening: the deploy went green with the migration runner reporting nothing to do; every article, page, and media item rendered from the new database; the Payload admin could create, edit, and publish; and the on-demand revalidation path — CMS edit propagating to the live page — round-tripped correctly. Each of those exercised a different path to the database (build-time queries, runtime queries, admin writes, cache invalidation), which is the point: verification should cover paths, not pages.
Total elapsed time, adapter swap to green deploy: one evening, alongside other work. The failed deploy was the only hiccup.
Recognizing your own window
The generalizable skill isn't "how to move Neon to Supabase" — it's noticing when a stateful migration is temporarily cheap. The tells:
Your data is regenerable or low-stakes. Staging content, seed data, or anything you could rebuild from a source of truth. The moment real user data lands, the window narrows.
No production traffic depends on the thing moving. Not "low traffic" — none. The difference between zero and epsilon is the difference between an env-var change and a cutover plan.
You've already made the strategic choice. If you know where you're consolidating, every week on the old provider is rent on a building you've decided to leave — and unlike rent, the moving cost compounds.
A forcing function is approaching. Mine was production promotion. A launch, a contract renewal, a pricing change — anything that will soon convert "we should migrate" into "we can't easily migrate anymore."
When three of those line up, the move that looks deferrable is actually urgent — not because anything is on fire, but because the price is about to go up and stay up. Inertia reads as safety; before production, it's actually the risky choice, because you're spending down a window you can't reopen.
The counter-case deserves its sentence: if you have no strategic reason to move — no consolidation story, no capability gap, no approaching forcing function — then an open window alone isn't a reason to churn infrastructure. Cheap isn't the same as worthwhile. The window makes a justified migration nearly free; it doesn't justify the migration.
The takeaway
Databases are where migration dread concentrates, because state is where risk concentrates. But dread is a function of timing, not of databases. Before production, a database move is an adapter swap, a dump piped through the right pooler mode, a deliberately ordered restore, and one evening — with every mistake costing minutes instead of downtime.
Your next action: list your stateful dependencies — database, file storage, search index — and for each one, ask whether you're currently inside a cheap migration window that production traffic will close. If you find one you've been deferring on vibes, price it honestly: count the touchpoints, check whether your framework's storage layer is adapter-swappable, and look at what a dump-and-restore actually involves on your providers. Mine priced out at one evening. The window was the whole reason why.