---
name: neon-serverless-postgres-branching
description: "Neon serverless Postgres — copy-on-write branches, the @neondatabase/serverless HTTP driver, scale-to-zero, per-tenant DBs. Production Neon: instant copy-on-write branches for preview/CI environments and the neonctl/branch API, the @neondatabase/serverless HTTP and WebSocket driver for edge runtimes (Vercel, Cloudflare Workers), connection pooling via PgBouncer (-pooler endpoints), scale-to-zero autosuspend cost control, point-in-time restore via branch reset, and database-per-tenant/ephemeral provisioning patterns. Covers branch reset/rebase from parent, Drizzle/Prisma over the serverless driver, and the Neon API for agent-driven provisioning."
license: MIT
---

# 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
```bash
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
```

```ts
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.