Database branching is one of the best ideas serverless Postgres brought to the mainstream. Fork the database at a point in time, get an isolated copy with all the data, run something risky against it, throw it away. It made preview databases and safe migrations feel routine.
But a real application is not just a database. It is a database, plus the files it stores in object storage, plus the backend code that serves it, plus, increasingly, the model and gateway config it calls for AI. When you branch only the database, those other three stay shared. Your "branch" points at the same S3 bucket, the same deployed backend, and the same AI configuration as everything else. So it is half a copy, and the half it leaves out is where a lot of the interesting bugs and the scary migrations live.
Neon's platform preview changes what a branch contains. A branch now forks the database and its data, the object storage and its files, the functions that run your backend, and the AI gateway config, all at the same point in time, all isolated. A branch stops being a database copy and becomes a whole environment. To make sure that is a real claim and not a diagram, I took a full-stack project, branched it, and checked every layer. Here is what happened.
main
untouched, and deleting the branch removed all of it.us-east-2
)npm i -g neon
, then neon login
)Database branching is now common. What is not common is branching everything around the database. In a typical stack:
Teams paper over this with scripts: a bucket-prefix-per-branch convention, a bespoke deploy step, a separate set of keys. It works, sort of, and it is a pile of glue nobody wants to own.
On Neon's platform preview, one branch carries the whole stack:
The database and storage are copy-on-write, so the branch starts as a reference to the parent's state and only stores what you change. The function redeploys onto the branch with its own URL. The gateway config comes along. Delete the branch and every layer goes with it.
I used a small AI image-agent project that exercises all four services: a Postgres table, an images
object-storage bucket with real files in it, an imagegen
function, and the AI gateway. Then I branched it and inspected each layer. Every line below is from the real run.
The parts that matter: the deploy reported Utilized services: Postgres, Object Storage, Functions, AI Gateway
, so all four came along. The branch got a separate storage endpoint from main
(not the same bucket with a prefix, an actual isolated endpoint) carrying a copy of the files. It got its own function URL. And the file I wrote to the branch never appeared on main
, the same isolation the rows get. Deleting the branch took the whole environment with it.
I used the AWS CLI shape above for readability; in the actual run I drove object storage with the S3 SDK against the branch-scoped AWS_ENDPOINT_URL_S3
that neon deploy
writes into .env.local
. The credentials and endpoint are per branch.
Once a branch is the whole stack, a few things that used to need real infrastructure become one command:
The useful reframe is to stop thinking of a branch as "a copy of my database" and start thinking of it as "a copy of my environment." Because storage and database are copy-on-write, that environment does not duplicate anything on disk until it diverges, and because functions scale to zero, an idle branch costs almost nothing. That combination is what makes it reasonable to spin up a full environment per pull request, per experiment, or per agent task and delete it without a second thought.
This is Neon's platform preview: object storage, functions, and the AI gateway are available on new
us-east-2
projects. The database-branching half works everywhere; the "everything else branches too" half is what the preview adds.
The full-stack demo used here (Postgres + object storage + function + AI gateway, from one CLI) is the companion to the earlier flagship in this series:
https://github.com/The-DevOps-Daily/neon-ai-agent
Branching taught us to treat a database as something you can fork and throw away. The catch was always that the database was only part of the application, so a branch was only part of a copy. When the branch also carries the files, the backend, and the model config, it becomes a real, disposable environment, and the workflows that used to justify a pile of staging infrastructure, preview stacks, safe migrations, faithful bug repro, agent sandboxes, collapse into create a branch
and delete a branch
. That is the shift worth paying attention to: not a better database copy, but a forkable environment.