Imported from ericrisco/rsc-harness (skills/neon/SKILL.md). Install upstream with npx skills add ericrisco/rsc-harness --skill neon. Copyright stays with the author.

Neon — serverless Postgres as a platform

Neon is Postgres with three platform features the engine doesn't have: a serverless driver that talks over HTTP/WebSocket (so you can query from edge runtimes), built-in connection pooling, and copy-on-write branching that makes a fork of production data appear instantly. This skill owns that platform layer. The Postgres engine underneath — schema, indexes, EXPLAIN, RLS, zero-downtime DDL — is identical to any Postgres 16 and belongs to ../postgresdb/SKILL.md. Don't re-derive engine craft here; connect correctly and branch correctly.

When to use / When NOT to use

When to use:

• Code imports @neondatabase/serverless, or DATABASE_URL points at *.neon.tech / *.aws.neon.tech.
• Connecting from Vercel (Edge/Node), Cloudflare Workers, AWS Lambda, or any serverless/edge function — choosing HTTP neon() vs WebSocket Pool.
• Setting up branching: dev branch off production, a branch per PR in CI, neonctl usage, the Neon + Vercel preview integration.
• Neon-specific symptoms: cold start after scale-to-zero, "too many connections" despite being serverless, pooled-vs-direct string confusion, autoscaling CU sizing/cost.
• Picking the connection string for migrations (direct) vs app queries (pooled).

When NOT to use — route to the sibling:

• Schema design, index choice, EXPLAIN/ANALYZE, query tuning, RLS, VACUUM, partitioning, expand-contract migrations → ../postgresdb/SKILL.md. Neon adds nothing to the engine; defer.
• Drizzle schema/migrations → ../drizzle-orm/SKILL.md; Prisma → prisma-orm. Neon supplies only the driver adapter line.
• A different managed Postgres/BaaS: Supabase (auth + storage + realtime) → supabase; PlanetScale → planetscale; Turso/libSQL → sqlite-turso.
• Where to deploy the app talking to Neon → ../vercel/SKILL.md / cloudflare / railway.
• Backup/PITR strategy as a discipline → backups (Neon branch-as-restore is mentioned here, not owned).

Non-negotiables

1. A WebSocket Pool/Client is created and closed inside one request handler — never at module scope in a serverless function. Module scope = a connection that outlives the invocation and leaks.
2. App queries use the pooled string (host contains -pooler). Migrations / DDL / advisory locks / session features use the direct string (no -pooler). Mixing them is the #1 Neon foot-gun.
3. The HTTP neon() driver always uses the pooled endpoint — don't hand it a direct string and expect session state.
4. HTTP neon() has no interactive transactions. Need BEGIN ... COMMIT across round-trips? Use sql.transaction([...]) (batched, non-interactive) or a WebSocket Pool.
5. On Node.js ≤ 21 you must set neonConfig.webSocketConstructor = ws before opening a Pool/Client. Node 22+ and edge runtimes have a global WebSocket; don't set it there.
6. Pin the driver: @neondatabase/serverless is at v1.1.0 (npm latest, 2026-04-17). It is a drop-in replacement for pg.

Pick your connection method

Keyed by runtime and what the query needs. Pick the lightest transport that satisfies the need.

If you're behind Drizzle or Prisma, you don't call these directly — you pass the driver to the adapter. See the ORM pointers below.

Connection strings: pooled vs direct

Neon gives every branch two connection strings that differ in one thing: the host of the pooled one contains -pooler.

pooled:  postgresql://user:pass@ep-cool-name-123456-pooler.us-east-2.aws.neon.tech/db?sslmode=require
direct:  postgresql://user:pass@ep-cool-name-123456.us-east-2.aws.neon.tech/db?sslmode=require

Bad → Good for a typical setup:

# Bad: one string everywhere — migrations sporadically fail under PgBouncer.
DATABASE_URL="postgresql://...-pooler.../db?sslmode=require"

# Good: split them. App uses the pooled one; the migration tool uses DIRECT.
DATABASE_URL="postgresql://...-pooler.../db?sslmode=require"          # app runtime
DIRECT_URL="postgresql://....../db?sslmode=require"                    # migrations/DDL

Serverless driver patterns

All examples assume @neondatabase/serverless@1.1.0.

HTTP one-shot — the default for edge/serverless reads and writes:

import { neon } from "@neondatabase/serverless";

const sql = neon(process.env.DATABASE_URL!); // pooled endpoint, no socket to manage
export async function getUser(id: string) {
  const [row] = await sql`select id, email from users where id = ${id}`;
  return row; // parameterized; ${id} is bound, not interpolated
}

Batched atomic writes over HTTP — atomicity without a WebSocket and without interactivity:

import { neon } from "@neondatabase/serverless";

const sql = neon(process.env.DATABASE_URL!);
await sql.transaction([
  sql`insert into orders (id, total) values (${id}, ${total})`,
  sql`update inventory set qty = qty - 1 where sku = ${sku}`,
]); // one round-trip, both succeed or both roll back

Interactive transaction — WebSocket Pool, opened and closed inside the handler:

import { Pool, neonConfig } from "@neondatabase/serverless";
import ws from "ws"; // Node ≤21 only; omit on edge / Node 22+

neonConfig.webSocketConstructor = ws; // required on Node ≤21; do NOT set on edge runtimes

export async function transfer(from: string, to: string, cents: number) {
  const pool = new Pool({ connectionString: process.env.DATABASE_URL }); // inside the handler
  const client = await pool.connect();
  try {
    await client.query("begin");
    const { rows } = await client.query("select balance from accounts where id=$1 for update", [from]);
    if (rows[0].balance < cents) throw new Error("insufficient");
    await client.query("update accounts set balance=balance-$1 where id=$2", [cents, from]);
    await client.query("update accounts set balance=balance+$1 where id=$2", [cents, to]);
    await client.query("commit");
  } catch (e) {
    await client.query("rollback");
    throw e;
  } finally {
    client.release();
    await pool.end(); // close before the function returns — no leaked connection
  }
}

Edge runtime (Vercel Edge, Cloudflare Workers): use HTTP neon(); the global WebSocket exists, so a Pool works without ws, but prefer HTTP unless you truly need an interactive transaction.

ORM adapters — you wire the driver, the ORM owns the query API:

• Drizzle: pass neon()/Pool into drizzle-orm/neon-http or neon-serverless → ../drizzle-orm/SKILL.md.
• Prisma: use the @prisma/adapter-neon driver adapter → prisma-orm.

Branching for dev / preview / CI

A Neon branch is copy-on-write: created instantly with no data copied, it forks production at a point in time, gets its own compute endpoint, and scales to zero independently. That makes a branch a cheap, isolated, full-data environment — not a backup substitute (test the restore).

neonctl (alias neon) drives create/connect/teardown:

neonctl branches create --name pr-$PR_NUMBER --parent main
neonctl connection-string pr-$PR_NUMBER --pooled   # feed to the preview app
neonctl branches delete pr-$PR_NUMBER              # on PR merge/close

Vercel preview integration: with the Neon + Vercel integration, each preview deployment gets its own branch forked from production, auto-deleted when the PR merges or closes — zero CI code. If you're not on Vercel, replicate it in CI: create branch on PR open → run migrations (direct string) → seed → expose the pooled connection string to the app → delete on PR close. Full GitHub Actions workflow, neonctl reference, and the Neon API endpoints: branching-ci.

Branch-as-restore (PITR): to recover, branch from an earlier point in time and either read from it or promote it. It's a fast undo, not a tested backup discipline — own that in backups.

Autoscaling & scale-to-zero

Each branch's compute endpoint autoscales between a min and max CU (vCPU/RAM) on its own, with no noisy neighbors across branches. Idle compute scales to zero after 5 minutes of inactivity (default), then resumes on the next connection with a millisecond-to-sub-second cold start.

Cost mental model: non-prod branches sit at zero almost always, so a dozen PR branches cost close to nothing. The cold start is the price.

Prod endpoint sizing checklist:

• Set a sane min/max CU for the prod branch — not maxed "just in case" (you pay for the max headroom you actually use).
• Latency-sensitive prod with sparse traffic? Disable scale-to-zero or set min CU > 0 so there's no cold start in p99.
• Treat the cold start as real: warm the connection on deploy, or accept it on non-prod and account for it in latency SLOs.
• Keep non-prod branches on scale-to-zero — that's where the near-free economics come from.

Anti-patterns

Cross-references

• Engine craft (schema, indexes, EXPLAIN, RLS, zero-downtime DDL): ../postgresdb/SKILL.md.
• Next.js App Router data layer that calls Neon: ../nextjs/SKILL.md.
• ORM query APIs over the Neon driver: ../drizzle-orm/SKILL.md, prisma-orm.
• Deployment targets: ../vercel/SKILL.md, cloudflare, railway. Backups discipline: backups.
• Other managed DBs (route away): supabase, planetscale, sqlite-turso.