Branch Your Database

Database migrations are scary. Not the “add a nullable column” kind — those are fine. I mean the ones where you’re reshaping data, backfilling columns, or merging tables. The kind where you stare at the migration script, convince yourself it’s correct, run it against prod, and immediately alt-tab to your monitoring dashboard with your heart rate slightly elevated.

Coding agents make this worse. They’re fast and confident, which is exactly the combination you don’t want near a production database. An agent will happily write a migration that looks plausible, and if you let it run against prod without verification you’re going to have a bad time.

Here’s a pattern I’ve been using: branch the database, let the agent iterate on the branch, verify, then run against prod.

Neon (and a few other providers) support instant copy-on-write database branching. You create a branch and get a full copy of your production database — schema and data — in seconds, regardless of size. It’s a metadata operation, no data is actually copied until something diverges.

The workflow:

1. Branch off prod. Create a database branch. You now have a perfect replica of production that you can freely destroy.
2. Point the agent at the branch. Give it the branch’s connection string and let it write and run the migration. It’ll probably get it wrong the first time. That’s fine — it’s a throwaway copy.
3. Iterate. The agent runs the migration, you inspect the results. Something’s off? Delete the branch, create a new one, try again. Each attempt starts from a clean copy of prod.
4. Verify. Once the migration looks right, sanity check it. Query the branch database, spot check edge cases, make sure row counts add up.
5. Run on prod. Take the final migration script and run it against the real database.
6. Delete the branch. It served its purpose. Clean up.

The key insight is that step 3 is free. Branching is instant and costs nothing until data diverges. You can throw away as many attempts as you need without ever touching production. This is what makes agents viable for migration work — their tendency to iterate through trial and error stops being a liability when the environment is disposable.

Neon is what I use, but there are alternatives. Xata offers similar copy-on-write branching with built-in PII masking. Amazon Aurora has fast database cloning (limited to 15 clones). DBLab Engine is a self-hosted open-source option that uses ZFS for thin cloning. Note that some services like PlanetScale and Supabase offer “branching” that only copies the schema, not the data — that’s useful for schema migrations but won’t help you if you need to test against real data.

- omegastick