Neon Postgres Branching

Neon is serverless Postgres that separates storage from compute, which makes database branches as cheap and fast as Git branches. This skill helps you wire Neon into a real app: spin up copy-on-write branches for every PR or CI run, connect from edge runtimes with the @neondatabase/serverless driver, and keep idle compute at zero. It is aimed at developers running Postgres on Vercel, Cloudflare Workers, or any environment where cold starts and per-environment data isolation matter.

When to use it

• You want an isolated database per pull request or per CI job, seeded with production-like data, torn down when the branch closes.
• You're deploying to an edge or serverless function and a normal TCP pg pool won't survive the runtime.
• You need per-tenant databases without paying for idle compute around the clock.
• You're debugging a data issue and want a writable, throwaway copy of production as of a point in time.

How it works

Branches are created from a parent via neonctl branches create --parent <branch> (or the /branches REST API / GitHub Action). A branch shares the parent's storage copy-on-write, so creation is near-instant and only diverging pages cost storage. Each branch exposes its own connection string.

For app code, install @neondatabase/serverless. Use the neon() HTTP function for one-shot queries (lowest latency on edge), or Pool/Client over WebSockets when you need transactions or session state. For pooled connections, target the -pooler host (PgBouncer in transaction mode). Compute autosuspends after the inactivity window and resumes on the next connection.

Example

curl -fsSL --create-dirs -o ~/.claude/skills/neon-serverless-postgres-branching/SKILL.md https://claudeskil.com/skills/neon-serverless-postgres-branching/SKILL.md

# create a preview branch off main
neonctl branches create --name pr-142 --parent main
neonctl connection-string pr-142 --pooled   # use this as DATABASE_URL

import { neon } from '@neondatabase/serverless';
const sql = neon(process.env.DATABASE_URL!);
const rows = await sql`SELECT id FROM users WHERE email = ${email}`;

Tips & gotchas

• For HTTP neon(), each query is its own request — no BEGIN/COMMIT. Use the WebSocket Pool for multi-statement transactions.
• The -pooler endpoint runs PgBouncer in transaction mode: session-level features like SET, advisory locks, and LISTEN/NOTIFY won't behave as expected. Use the direct (non-pooler) host for migrations.
• Run schema migrations on the direct endpoint, not the pooled one, to avoid prepared-statement issues.
• Autosuspend adds a small cold-start latency to the first query after idle. Tune the suspend timeout per project if that hurts UX.

FAQ

Does a branch copy all the data? No. It's copy-on-write — you pay storage only for pages that change after branching, so a fresh branch is effectively free.

HTTP or WebSocket driver? HTTP for stateless single queries on edge; WebSocket when you need transactions, LISTEN/NOTIFY, or a persistent session.

How do I auto-create branches per PR? Use the Neon GitHub Action or call the branch API in CI, set the output as DATABASE_URL, and delete the branch on PR close.