The databasePart 5 of 6

Deploy is a branch promotion, not a migration

Shipping to production normally means moving data: dump dev, restore into a separate prod database, run the migrations, hope nothing drifted. On copy-on-write Postgres timelines it's a different shape — production is a branch, and going live is a promotion. No bytes move when prod forks from dev's head (and by default prod keeps only the schema), re-deploys keep prod's data and apply only the pending migrations, a rollback re-deploys a pinned commit with an optional point-in-time data restore, and each environment scales to zero independently. Here's the model and the mechanics.

Deploy is a branch promotion, not a migration

The usual path to production moves data. You snapshot dev, restore it into a separate production database, run the migrations there, and hope the two schemas haven't drifted in the meantime. You now operate two databases that are supposed to be the same and slowly aren't, and the copy step gets slower as your data grows.

If your databases are copy-on-write timelines on a shared page store, deploy has a different shape entirely. Production isn't a separate database you copy into — it's a branch. Going live is a promotion: a metadata operation that moves a pointer, not bytes. This post is the model the platform's timeline architecture is built around, and the mechanics underneath it.

It builds on two primitives covered elsewhere: copy-on-write branching at an LSN and scale-to-zero compute. If those are new, skim them first — this post composes them.


The model: prod is a durable branch forked from dev

A project's database is a timeline. Day to day that timeline is the dev environment — where the agent builds and iterates. Production is a second timeline: a durable branch that customer traffic hits.

The first deploy forks dev's current head into a new, durable prod timeline. From that point prod is its own timeline that will carry real users' data, and dev keeps running on its own timeline, untouched. Because branching is O(1) copy-on-write, the fork copies no data. The database side of a deploy costs the same whether the database holds a kilobyte or a hundred gigabytes.

What prod starts with is a separate choice. A dev database is full of demo and faker rows that don't belong in a live app, so by default production starts with the schema only. A copy-on-write fork can't be created empty, so the release forks and then truncates the app's tables once the prod compute is up. The deployer can opt into keeping dev's rows instead (copyDevData). The platform's own verification accounts are still removed before the app goes live.

first deploy: fork dev head → prod

shared history up to the fork

dev timeline
agent builds here · keeps running

prod timeline
durable · customer traffic

One consequence falls straight out of "prod and dev are the same engine, one branch apart": no provisioning drift. Prod isn't a separately stood-up database you dump-and-restore into. It's a fork that inherited dev's migration ledger at the split. A deploy applies only the genuinely pending migrations (the DDL dev ran that prod hasn't), so there's no "works on dev, breaks on prod" gap from two databases provisioned and migrated independently.


The promotion mechanics

The first promotion is a single metadata move: fork the dev head into a durable prod timeline. The decision is pure — given the current branches, what becomes prod — and the execution is a branch operation with no data copy:

pageserverneon-conn-proxybackend (promotion)deploy triggerpageserverneon-conn-proxybackend (promotion)deploy triggerpromoteToProduction(project)planPromotion(branches) %% pick the dev-serving timelinefork dev head → prod timeline (O(1), CoW)create_timeline(ancestor=dev head)record prod branchprovision prod compute credentials (Vault + proxy cache)setServingBranch("prod")release flip step: neon-compute-prod in proj-{id}-prod

The promotion logic is a small pure function, planPromotion, that looks at the project's branches and decides which timeline becomes prod (and is a no-op if dev already equals prod). The execution layer, promoteToProduction, forks the dev head, records the new prod branch, provisions prod compute credentials for it, and only then marks it serving prod, so prod never serves a timeline nothing can connect to. The prod compute itself lives in its own namespace, proj-{id}-prod. The release's flip step creates that namespace and its quota, and applies neon-compute-prod there.

That's the first promotion. A re-deploy doesn't re-fork: it keeps the live prod timeline, so real users' data persists across releases. It tags a pre-deploy LSN checkpoint on prod's head as a rollback anchor (anchorProdRedeploy; a re-deploy without an anchor is refused), pins the newly released commit, and applies each app's pending db/migrations to prod as forward-only DDL (migrateProduction → runPendingMigrations(…, { env: "prod" })). So a deploy does run schema migrations against prod; what it never does is copy data. Overwriting prod data with dev's takes an explicit owner choice, never a side effect of shipping. There are two such choices: a data reset, or starting fresh from dev when deploying again after an undeploy kept the old data. Each takes a restore point on the data it replaces first.

Rolling back a bad deploy re-deploys an earlier release's pinned commit. The release ledger is append-only and every release is pinned to a git commit, so the old code is exact. Restoring data is optional and rides on the same branch-at-LSN primitive as time-travel. The restore point is the pre-deploy checkpoint of the release that superseded the target. The rollback forks prod from it and repoints the prod compute at the fork. No restore-from-backup, and the data is restored before the old code goes back on, so old code never serves new-era data.


Separate compute per environment — and both scale to zero

Prod and dev have to be live at the same time: customers hit prod while the agent keeps iterating on dev. A single Postgres process is bound to one timeline at boot, so the environments get separate computes — neon-compute for dev, neon-compute-prod for prod — each pointed at its own timeline.

That sounds like double the cost, and it would be, except both computes scale to zero independently (the scale-to-zero proxy routes per-environment by database name and wakes each on demand):

  • App with no visitors and nobody building → both at zero.
  • A customer visits → prod wakes; dev stays at zero.
  • The agent iterates → dev wakes; prod stays at zero.

You pay per environment accessed, not per environment provisioned. The manifests are generated per environment from a single template (generateNeonComputeManifests(projectId, { env })), so a prod compute is the same resource set as dev with a distinct name, namespace and timeline.

The materialization is lazy: a project that hasn't deployed has exactly one compute (dev). The prod timeline and its compute come into existence at the first promotion — so the long tail of never-deployed experiments carries no prod overhead at all.


What this gives you

  • The database side of a deploy is instant and data-size-independent. It's a fork + a pointer move, not a dump/restore. A 50 GB database promotes as fast as an empty one.
  • Prod data is durable. The first deploy starts prod clean by default; re-deploys keep it and only migrate it forward. Dev data reaches a live prod only on an explicit, restore-point-backed owner choice.
  • No provisioning drift. Same engine, one branch apart — prod was forked from dev and inherited its migration ledger, so a deploy applies only the pending DDL, never a blind full re-run against a separately-built database.
  • Rollback is exact, data included on request. Re-deploy the pinned commit; optionally restore prod data to that release's era with the same branch-at-LSN operation as code+data time-travel — applied to prod.
  • Idle is free, per environment. Scale-to-zero on each compute means the second environment isn't a standing cost; it's there when accessed and gone when not.

The shape of it

Stop thinking of production as a place you copy your database to, and start thinking of it as a branch you promote. On separated storage/compute Postgres, "deploy" stops being a data-migration event with a copy step and a drift risk, and becomes what it should be: moving a pointer to say "this version is the one customers get." The storage was already there — shared, copy-on-write, one branch away from every environment.

Build on the platform these posts describe.

Describe your app in plain English — igentik writes the code, sets up the database, and ships it live.

Start building free