Branching Workflows on Neon

Copying databases doesn't scale. It's time to branch

Software development is built around parallel work. Engineers open pull requests, previews get generated for review, CI runs on every commit, and several versions of an application exist at the same time. Code handles all of this. Traditional databases don't.

Most teams still run one production database, a shared staging database, and sometimes a shared development database. Getting an isolated environment means copying one of them: dump, restore, wait. That is expensive in every direction. Dumps and restores take minutes or hours. Every copy duplicates storage. Long restores fail partway or drift. And a copy is already stale by the time it finishes.

So teams compromise: they test migrations against partial or outdated data, share environments and coordinate over Slack about who is running what, and avoid certain schema changes because the blast radius feels too wide. Past a few hundred gigabytes, copying stops being practical at all, and non-production databases stop resembling production.

Better scripts and faster restores only move the ceiling a little. The fix has to come from the database model itself.

"Getting realistic data into our verification environments was largely unfeasible, it was time-consuming, expensive, and a beast to maintain. You need to process hefty backups, transfer costs stack up, and there’s a lot of manual oversight required just to move that data."

The lakebase architecture that allows Postgres to branch

The key element that changes the game: database branches.

A database branch starts as a pointer. When you create one, Neon records a reference to the parent's data at a specific point in time and writes nothing. The child sees the exact schema and rows the parent had at that moment. When you run a migration, insert rows, or drop a table on the child, only those changes are written separately.

• Branch creation takes seconds no matter how large the parent is, because the amount of data copied is zero,
• Branches stays cheap until they diverge, because both branches read the same underlying pages until one of them writes.

None of this is possible on a standard Postgres instance, and the reason is architectural. In a conventional setup, the Postgres process and its disk live together on one machine. The database is a single mutable filesystem, so the only way to get a second environment is to stand up a second machine with a full copy of the data on it.

Lakebase Postgres is a lakebase, a new type of OLTP database that splits those two halves apart. Compute is the stateless Postgres process where queries run. Storage is a separate, distributed engine that keeps data on shared object storage and writes copy-on-write, versioned by WAL, so every change creates a new version instead of overwriting the old one.

Once storage is shared and versioned, starting a new compute against an existing version of the data is cheap. That single property is what branches, instant restore, and fast restarts are all built on. A branch is just another compute pointed at a version of the storage that already exists.

Branching workflows you can build today

A full walkthrough of the most popular branching patterns lives here: Mastering database branching workflows.

One branch per developer

Each engineer gets their own branch, created from production or from an anonymized copy of production when PII is involved. Nobody steps on anyone else's schema changes, and every developer works against realistic data instead of a fixtures file.

Because branches don't duplicate storage and idle compute scales to zero, this stays affordable as the team grows. If production contains PII, derive developer branches from an anonymized branch instead, and the rest of the workflow is unchanged.

One branch per pull request

A branch is created when the pull request opens and deleted when it merges or closes. Each change gets a database to run its migrations against, so migration bugs surface in review rather than in production. PR branches are usually derived from staging when a staging branch exists, and from production otherwise.

"Developers already face significant delays when working on a PR—running CI tests, ensuring everything is ready for preview, it all adds up. Time to launch is crucial for us: when we tried Neon and saw that spinning up a new branch takes seconds, we were blown away"

One branch per preview

A preview environment is supposed to show what a change looks like before it ships. That only works if the data behind it is shaped like production data. Give each preview its own branch and the schema changes and test records stay contained, then delete the branch when the preview goes away. The Vercel and Netlify integrations wire this up so a branch is created and torn down with the deployment.

One branch per test run

Instead of reusing a shared test database and running destructive cleanup between runs, create a branch at the start of the pipeline, run migrations and tests against it, and delete it at the end. Every run starts from the same baseline, so results are deterministic and no run inherits leftover rows or schema drift from the last one. Because branches are instant, this holds up when pipelines run frequently or in parallel.

"Branching saves us both money and developer time. We no longer have to set up an actual testing database instance and make sure the data is always synced with production. We now spin up an ephemeral branch when we need to and then tear it down via the create/delete Github Actions"

Branches for restore and debugging

The same mechanism works backwards. Lakebase Postgres retains history for each branch within a history window, so you can create a branch from a moment in the past and get the exact schema and data as of then, without rolling production back.

That covers most of what teams need after something goes wrong:

• Recover lost data - Branch from just before a table was dropped, pull out the rows you need, and copy them back into production
• Debug a migration - Branch from before the migration ran and compare state, or re-run it in isolation
• Audit a past state - Inspect a historical point for an incident review or compliance check while production keeps serving traffic

Delete restored branches when you're done so they don't sit in storage.

Automating branch creation and cleanup

Branching becomes a workflow once nobody has to think about it. Every operation is available through the Neon API and the CLI, so branch lifecycle can follow the same events your pipeline already reacts to:

• GitHub integration - Link a Neon project to a repository and create or delete branches from GitHub Actions
• Vercel integration - Create a branch for every preview deployment
• Branch expiration - Set a TTL so branches clean themselves up
• Scale to zero - Idle branch compute suspends automatically, so forgotten branches don't accumulate compute cost

Cleanup matters more than it sounds. Branches left running for weeks eventually fall outside the history window and start contributing to storage. Automating deletion keeps both the branch list and the bill predictable.

"Database branching is the best quality-of-life improvement to my tech stack that I can think of in recent years. Second to maybe only Copilot"

What developers are saying

"Neon’s branching gave us the last missing piece in our RISE (Robust Isolated Staging Environment): true database isolation. The services that touched schema changes or write-heavy paths could never share a database safely. Now every sandbox gets its own isolated Postgres DB whenever required"

A few examples on how branching workflows are transforming teams of all size - once you try branching, you never go back:

• Inside Bitso's branch-based workflow - Hundreds of developers and microservices, with an isolated Postgres database behind every sandbox
• How Mindvalley minimizes time-to-launch with Neon branches - Cutting the wait between opening a pull request and having an environment to test it in
• Adopting Neon branching in CI/CD pipelines: a practical story by Shepherd - Ephemeral test branches created and torn down by GitHub Actions
• From days to minutes: how Neo.Tax accelerated their development lifecycle - A branch per ticket, linked to local development and end-to-end tests
• How Dispatch speeds up development with Neon while keeping workloads on Aurora - Development and verification environments on Neon with production still on Aurora
• How Proposales integrated Neon in their Postgres development workflow - Moving development infrastructure off RDS and reducing cost along the way
• ketteQ uses Neon branching for scenario analysis - Testing hundreds of scenarios against production data with no risk to it
• From Heroku to Neon: the dev.to story - Serverless Postgres behind a platform used by millions of developers

We're now branching backends

Everything above covers the database half of an environment. For a long time that was as far as branching went - that's changing. Neon is now building backends, and the full suite of Neon backend primitives are keyed to the same branch_id. So a Neon branch now forks more than the database - one API call forks the data, the files, the users, and the code that runs against them:

• Neon Object Storage - S3-compatible buckets that fork with the branch, so a preview can accept uploads without touching production objects
• Managed Better Auth - Users, sessions, and OAuth configuration live in your Postgres database, so a branch gets its own isolated sign-up and login flows
• Neon Functions - Node.js handlers deployed onto a branch, each with its own URL and its own database state, deleted when the branch is

Start branching

Ask your agent to create a Neon and experiment with branching right away. We have a generous free plan, no credit card required.

Get startedRead the branching guide