Chooses and creates Neon Postgres branches (normal vs schema-only) via Neon CLI, MCP, or REST, including reset-from-parent and ephemeral expiry. Use when testing migrations against production-like data or isolating PR/dev databases. Not for picking Neon vs Blob/Redis/Supabase on Vercel (vercel-storage) or writing application SQL.
Chooses and creates Neon Postgres branches (normal vs schema-only) via Neon CLI, MCP, or REST, including reset-from-parent and ephemeral expiry. Use when testing migrations against production-like data or isolating PR/dev databases. Not for picking Neon vs Blob/Redis/Supabase on Vercel (vercel-storage) or writing application SQL.
Use this skill when you need to choose and create the right Neon branch type for testing and development. Trigger keywords and scenarios include:
"Create a Neon branch" / "branch my database"
Migration testing against production-like data
Isolated test or staging environments
Schema-only branch workflows for sensitive or compliant data
Reset-from-parent to refresh a drifted child branch
Branch creation via Neon CLI, Neon MCP server, or Neon REST API
Per-PR, per-test-run, or per-developer branching patterns
Ephemeral branch lifecycle and expiration management
The outcome of this skill should be a created Neon branch (or a clear, actionable next step if creation cannot proceed). Choose the correct branch type, then execute branch creation via MCP or CLI.
Normal branch — for realistic migration and query testing with real data.
Schema-only branch (Beta) — for sensitive data workflows where structure is needed without copying rows.
Prerequisites
Neon account and project — A Neon project must exist. Create one at https://console.neon.tech if needed.
Authentication — At least one of the following must be available and authenticated:
Choose normal vs schema-only based on data sensitivity and migration-testing goals.
Use branch tools (e.g., create_branch) to create the branch.
Validate with read tools (e.g., describe_branch).
For migration workflows, prefer branch-based migration flows before applying to main.
Step 2 — Create a Normal Branch (Preferred for Real-Data Migration Testing)
Use this when the user needs realistic testing conditions. Real production-like data can expose edge cases your seed or data migration scripts miss, which helps catch migration issues before going live.
--preserve-under-name keeps the pre-reset state as a backup branch for rollback, but adds one extra branch to clean up later.
Optional context setup to avoid repeating --project-id:
neon set-context --project-id <project-id>
Console and API usage:
Console: Open the target child branch, then select Reset from parent from Actions.
API: Use the restore endpoint for the branch and set source_branch_id to the parent branch ID.
Step 5 — Post-Creation Environment Update
After branch creation, ask whether the user wants to update local environment credentials to point at the new branch.
Ask: "Do you want me to update your .envDATABASE_URL to this new branch connection string?"
If yes, write the new branch connection string to the requested env file/key.
If no, leave credentials unchanged and share the connection string for manual use.
Never overwrite an existing env key without explicit confirmation.
Step 6 (Optional) — Declarative Configuration with neon.ts
Beyond creating branches imperatively (CLI / MCP / API above), you can program what configuration new branches receive declaratively in neon.ts — Neon's infrastructure-as-code file. See the neon skill for the full reference.
The closure receives a read-only descriptor of the target branch — name, exists, isDefault, parentId, and more — and returns the tuning to apply: parent, ttl (auto-expiry), protected, and postgres.computeSettings. This is the declarative complement to ephemeral lifecycle hygiene and per-PR / per-test patterns: instead of remembering --expires-at on every neon branches create, the TTL and compute profile live in version control and apply to every matching branch.
Because neon checkout applies this policy when it creates a branch, a fresh preview/* or dev-* branch comes up already expiring and scaled-to-zero. Checking out an existing branch doesn't reconcile it — run neon deploy (alias for neon config apply) to apply changes to a branch that already exists.
Pitfalls
Schema-only branches are independent root branches — they have no parent branch and no shared history, so reset-from-parent does not apply to them.
Root branches cannot be reset from parent — only child branches support reset-from-parent.
Reset blocked by child branches — if the target branch has children, reset is blocked until those child branches are removed.
Reset unavailable after parent restore — after a parent branch is restored from snapshot, reset-from-parent may be unavailable for up to 24 hours.
Reset is not a merge — local changes on the child branch are lost. Use --preserve-under-name to keep a backup.
Branch quota limits — root branch allowances and per-branch storage limits can cap how many schema-only branches users can create.
Never overwrite env keys without confirmation — always ask before writing a new connection string to an existing .env key.
Schema-only is Beta — expect possible breaking changes or missing capabilities; direct users to Console feedback and Discord for issues.
neon checkout does not reconcile existing branches — run neon deploy to apply neon.ts policy changes to branches that already exist.
TTL max is 30 days — the ttl field in neon.ts supports a maximum of 30d.
Verify before destructive actions — always verify commands, API behavior, pricing, quotas, credentials, and deployment effects against current official documentation before making changes.
Verification
After branch creation, verify the branch exists and is accessible:
List branches to confirm creation:
neon branches list
Expected: the new branch name appears in the output with the correct parent.
Describe the branch for details:
neon branches describe <branch-name>
Expected: branch ID, parent branch, creation timestamp, and expiration (if set) are shown.
Fetch and test the connection string:
neon connection-string <branch-name>
Expected: a valid PostgreSQL connection string is returned. Test connectivity with psql or your application's DB client.
For MCP flows, use describe_branch read tools to confirm the branch exists and has the expected parent and schema state.
For schema-only branches, verify that tables exist but rows are not copied:
If the user asks for process recommendations (not just a single command), suggest these:
One branch per PR: Create branch when PR opens, delete when merged/closed, keep migration tests isolated.
One branch per test run: Create branch at pipeline start, run migrations/tests, delete at end for deterministic CI.
One branch per developer: Isolated dev environments with production-like shape; avoid team collisions on shared test data.
PII-aware branching: If production has sensitive data, derive dev/PR branches from an anonymized branch or use schema-only branches.
Ephemeral lifecycle hygiene: Set branch expiration and automate cleanup so old branches do not accumulate avoidable storage/history cost.
Branching in CI/CD
Common CI/CD use cases for Neon branches:
Per-PR preview deployments: Branch on PR open, deploy the preview against it, delete on close. Each PR gets an isolated database branch. Injecting the branch's DATABASE_URL into the deployed app is hosting-provider-specific — see:
