Vercel

What it doesCopy Anchor Link

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
• push CAPYKV_REST_URL when the project has a K/V store - the URL only. The K/V token is shown once when you create or rotate it and is never retrievable, so set CAPYKV_REST_TOKEN yourself
• 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

SetupCopy Anchor Link

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.

Or from the repo, after vercel link:

VERCEL_TOKEN=... capydb env sync vercel --preview-branches

It reads the project and team from .vercel/project.json (or --vercel-project / --team), connects the same integration, and waits for the first push. Run it again to re-push or to replace the token.

Branch previews in practiceCopy Anchor Link

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 caveatCopy Anchor Link

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.

Re-push on demandCopy Anchor Link

If DATABASE_URL was deleted or edited on the Vercel side, or a push failed, push the current values again without reconnecting:

curl -X POST https://capydb.dev/api/capydb/v1/projects/$PROJECT_ID/integrations/vercel/sync \
  -H "Authorization: Bearer $CAPYDB_API_KEY"

It queues a job (202) that pushes the same variables connecting pushed, with the token stored when you connected. 404 means the project has no Vercel integration; 409 means a push for it is already queued or running - wait for that one. Needs projects:write. Recorded in the audit log as project.integration.env_synced.

CLI escape hatchCopy Anchor Link

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

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