Vercel

What it does

Connect a CapyDB project to a Vercel project and CapyDB will:

• validate the token and bind to the Vercel project
• push DATABASE_URL (pooled) and DATABASE_URL_UNPOOLED (direct) into the Vercel project's environment
• re-push automatically after credential rotation, restores, and imports — the env vars never go stale
• register a deployment webhook on the Vercel side (when preview branches are enabled)
• create a preview database per git branch: clone mode, named branch-<slug> from the branch name, with the connection strings pushed as branch-scoped env vars
• refresh the preview's TTL on every deployment of that branch, so active branches keep their database and abandoned ones expire on their own

Setup

Dashboard → project → Settings → Integrations → Vercel:

1. Create a Vercel API token (Vercel → Account Settings → Tokens) with access to the team that owns the project.
2. Enter the Vercel project (name or prj_... id), the team id if it is a team project, and the token. The token is stored encrypted and never returned.
3. Optionally enable preview branches.

CapyDB validates the token against the Vercel API before saving, then runs an immediate env sync.

Branch previews in practice

Push a branch, open a preview deployment, and the deployment webhook (deployment.created) makes CapyDB ensure a clone-mode preview named branch-<slug> exists and its URLs are set as env vars scoped to that git branch. Production deployments are ignored — production always points at the project database.

Cleanup is TTL-driven: branch previews expire like any other preview (TTL refreshed on each deployment), so merged and deleted branches clean themselves up without anyone wiring a deletion hook.

The first-deployment caveat

Env vars land when the deployment webhook fires, which is after the build of a brand-new branch's first deployment has started. That first build may not see the branch-scoped DATABASE_URL yet; the second deployment (or a redeploy) will.

If you need exact ordering — database ready, env var present, then build — use the GitHub Action in the same repo: it creates the preview synchronously before your checks run. The two compose fine; the Action and the integration reuse a preview with the same name rather than fighting.

CLI escape hatch

capydb integrations env prints the same payloads if you want to push env vars yourself:

capydb integrations env --target vercel --branch feature/checkout