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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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:
