Neon Branch Management

Use this skill when

Use when the question is routing, not schema: which Neon branch does each Vercel environment point at, did the integration silently overwrite Production, are pooled and unpooled URLs both pointing at the same branch, is a preview branch wired to its own database fork. If the question is "is this migration safe" or "is the schema in sync", that is db-health. If the question is "does my local .env.local have everything", that is environment-bootstrap.

Workflow

Resolve current target branch with scripts/check-branch.sh before any database-touching work. Fails fast on production unless --allow-production.
For wiring questions, dump the branch map with scripts/inspect-neon-branches.sh to see which branches/endpoints exist and which Vercel env each one is wired to.
Before promotion or smoke against staging or production, run scripts/verify-deploy-branch.sh <staging|production> — wraps the deploy env parity check and confirms DATABASE_URL/DATABASE_URL_UNPOOLED resolve to the expected Neon branch.
Treat parity failure as STOP. Production must be set manually in Vercel and disabled in the Neon integration so it stops being overwritten.
For direct DB access, prefer neonctl connection-string <branch> over copying raw URLs into ad-hoc commands.

Skill graph

Read references/graph.md for routing. Related skills: db-health, vercel-deployment, environment-bootstrap, promote-deployment.

References

Neon CLI install docs: webfetch when neonctl is missing or auth/setup is unclear.
Neon CLI reference: webfetch when neonctl branches or neonctl connection-string syntax is unclear.
references/workflow.md: the full branch routing workflow.
references/graph.md: related skills and handoff boundaries.
references/branch-map.md: canonical Neon ↔ Vercel branch map for this project.
references/integration-quirk.md: the staging-as-default Neon-Vercel integration footgun.
references/pooled-vs-unpooled.md: when each URL is used and why both must point at the same branch.

Scripts

See scripts/README.md. Execute scripts when the workflow calls for deterministic inspection or validation.

Assets

See assets/README.md for templates/checklists.