Guide
Vercel preview branches
Wire a Vercel project's git branches to Layerbase databases. Your production branch points at your main database, and every preview deployment gets an instant, copy-on-write database branch forked from production, so previews run against real, isolated data instead of a shared dev database. The branch's pooled connection string is written to the environment variable you choose, so previews work with zero setup.
How it works
A Layerbase database branch is a full, writable copy of its parent. On branch-ready (ZFS) storage a branch is an instant copy-on-write fork, not a slow byte copy, so a preview gets its own data in seconds. You connect Vercel once, map a project, and Layerbase keeps the wiring in sync:
- The production git branch uses your main database.
- The staging git branch uses a database branch forked from production.
- The connection string is set on the Vercel environment variable you name (default
DATABASE_URL), scoped to the right deployment.
Preview branching is available on PostgreSQL today, with more engines to follow.
Before you start
You need a PostgreSQL database on Layerbase Cloud and a Vercel project with a linked git repository. Branching also requires branch-ready storage, which is a one-click toggle (next step).
1. Enable branching storage
In Cloud Settings, turn on Branching storage. This moves your databases onto ZFS so branches are instant. If you already have data, it runs a brief one-time migration (a few minutes, once); enabling it while a database is small keeps that move fast. New databases created afterward land on branch-ready storage from the start.
2. Connect Vercel
Go to Integrations and click Connect Vercel. You will be sent to Vercel to authorize Layerbase, then returned to the dashboard. The connection is shared with your team, so any member can wire up a project against it. You can also start from a database's Settings tab via Connect to Vercel, which deep-links straight into the wizard for that database.
3. Map a project
Click New mapping and fill in:
- Database — the production database to fork from.
- Vercel project — Layerbase reads its production branch for you.
- Environment variable name — defaults to
DATABASE_URL; change it to whatever your app reads. - Staging git branch and the name for the Layerbase staging branch to create.
- Optional toggles to write the env var on the production deployment and on the staging branch's preview deployments for you, instead of copying the value yourself.
On Create mapping, Layerbase ensures the database is branchable, forks the staging branch, and (if you opted in) writes the connection strings to Vercel. A production variable is set once and then left for you to manage; a staging variable is a Preview variable scoped to the staging git branch:
# Production deployment
DATABASE_URL=postgresql://user:pass@your-db.cloud.layerbase.dev/app
# Preview deployments on the "staging" branch
DATABASE_URL=postgresql://user:pass@your-db-staging.cloud.layerbase.dev/appReset staging on every deploy (optional)
Turn on Reset staging on merge to re-fork the staging branch from production whenever the staging branch deploys. This keeps staging close to production, and is destructive: it discards whatever was in the staging branch. The connection string does not change, so nothing downstream needs re-wiring. It is off by default.
Removing a mapping
Delete a mapping from the Integrations page. Layerbase removes the preview environment variable it created. Your production variable and the Layerbase staging branch are left untouched; delete the branch from its dashboard page if you want it gone. Mark any database or branch as persistent on its Settings tab to protect it from automated cleanup entirely.
Other ways to set up
Prefer to wire it yourself? The same database-branch API powers two other paths: a drop-in GitHub Actions workflow that creates and tears down a branch per pull request, and a paste-able AI-agent prompt that sets it up against the API for you. Both converge on the same primitive (a parent database plus the branch API), so you can move between them without re-architecting.