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. Once branching is on, a branch is created in seconds, not by a slow byte copy, so a preview gets its own data almost immediately. 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 has to be turned on for the database, which is a one-click toggle (next step).
1. Turn on Instant branches
Open the database on Layerbase Cloud, go to its Settings tab, and turn on Instant branches. New databases on branchable engines usually have it on already, in which case the setting simply reads Enabled. If it is off, turning it on prepares the database for branching: that takes a few minutes once, and the database is briefly unreachable while it runs. Your connection string stays the same either way.
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?sslmode=verify-full
# Preview deployments on the "staging" branch
DATABASE_URL=postgresql://user:pass@your-db-staging.cloud.layerbase.dev/app?sslmode=verify-fullThe variables Layerbase writes carry sslmode=verify-full rather than the sslmode=require shown in the dashboard. Your Vercel app runs on Node, where verify-full verifies the certificate chain and hostname against the system trust store with no extra configuration, and it keeps doing so after a future pg major changes what require means. Connection strings you copy from the dashboard stay on require, which is the value every client accepts, including psql and GUI clients.
Existing environment variables
Layerbase never silently overwrites a variable you set by hand. When you pick a project in the wizard, it checks whether that variable name is already set on the scope it would write (production, or preview), and if so it warns you and leaves the toggle off. Turning the toggle on is your confirmation that Layerbase should take over that variable, replacing its value and managing (and eventually deleting) it. In per-branch mode, if a git branch already has that variable configured manually on Vercel, Layerbase skips creating a preview database for that branch rather than clobber your value; remove the manual variable, or change the integration's variable name, to let the automation take over.
Renaming the environment variable
Open Edit on a mapping and change the Environment variable name. Layerbase rewrites every variable it manages for that project under the new name (staging, preview, and any per-branch variables), then removes the old ones. Your database branches are untouched, so the rename costs nothing: no re-fork, no data loss. The Production variable is set once and never re-managed, so it only moves when Layerbase was the one that set it; otherwise it is left exactly as it is and the result message says so. Make sure your app reads the new name before you rename - deployments pick it up on their next build, not retroactively.
Reset 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.