Neon

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.