Home › Neon Postgres › Neon serverless Postgres CLAUDE.md

Neon serverless Postgres CLAUDE.md

CLAUDE.md for apps on Neon serverless Postgres: pooled connections, the serverless driver, branches, and migrations.

Claude Code (CLAUDE.md)Neon Postgres

Copy CLAUDE.md

How to use

Save this as CLAUDE.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

# CLAUDE.md: Neon Postgres

## Connections
- `DATABASE_URL` uses the pooled host (`...-pooler...neon.tech`) for the app; `DATABASE_URL_UNPOOLED` (direct) for migrations and long sessions. Both come from env, never hard-coded.
- Serverless/edge runtimes use `@neondatabase/serverless`: `neon(url)` for one-shot HTTP queries, `Pool`/`Client` over WebSockets when you need transactions or sessions.
- Long-running servers can use regular `pg`/`postgres`/`psycopg` with the pooled URL; keep pool sizes small.
- With an ORM (Drizzle `drizzle-orm/neon-http`, Prisma with the Neon adapter), follow its Neon setup instead of mixing drivers.
- Expect cold starts after scale-to-zero: set connect timeouts and one retry for the first query.

## Branches
- Never run experiments or destructive SQL on the `main`/production branch.
- Create a branch for risky work: `neonctl branches create --name <feature> --parent main`, then get its URL with `neonctl connection-string <feature>`. Delete it when done (ask first).
- Preview deployments get their own branch through the CI integration if configured.

## Migrations
- Use the repo's migration tool against the direct (unpooled) URL. Test on a branch first, then apply to main through CI.
- Follow zero-downtime rules: concurrent indexes, nullable columns first, batched backfills.

## Queries
Parameterized only. The serverless driver's tagged template (sql`...${id}...`) sends `id` as a parameter; building SQL by string concatenation does not.