Next.js boilerplate with Neon

Database access goes through src/db - getSql(), getPool(), withTransaction(), batchTransaction(). Nothing else in the repo constructs a client.

Required

• Import from @/db (or the ORM client bound to getPool()). Never call neon() or new Pool() in a route handler, a server action, a component or a script; every extra instance is another set of sockets against the same pooler.
• Default to getSql(). The HTTP driver has no connection to establish, which is why it wins on a cold serverless instance. One statement per call.
• Use getPool() / withTransaction() only when a single request genuinely needs a shared session: an interactive transaction, set local, an advisory lock, a cursor. Keep the transaction body free of HTTP calls - it holds a connection for its whole duration.
• Use batchTransaction() when several statements must commit together but none of them reads a previous statement's result. It is one round trip and holds nothing.
• Parameterise everything. The tagged template (sql`select * from users where id = ${id}`) sends values out of band; string concatenation into SQL is an injection bug even when the value "comes from our own code".

Forbidden

• DATABASE_URL in client components, NEXT_PUBLIC_* anything database-shaped, or a connection string in a log line, an error message returned to the browser, or a commit. The env-leak hook catches the obvious shapes; do not rely on it.
• Long-lived state assumed across requests. Neon branches scale to zero and serverless instances are recycled, so treat every request as if the connection is new. Nothing may be cached on the pool object.
• select * in a hot path, and unbounded select without limit. Egress and row-parse time are the two costs you notice on a serverless database.
• Swallowing connection errors. A Connection terminated or too many connections must surface - it is the signal that the pool policy is wrong, and hiding it turns a 30-second incident into a week of mystery latency.

Reads that can be stale

Wrap them in unstable_cache or a route segment revalidate before reaching for a read replica. Most "we need a replica" traffic is the same three queries running on every request.

Local Postgres

• Local development runs the same Neon driver through bun run db:proxy and NEON_LOCAL_PROXY. databaseUrl() in src/db/client.ts applies it before the first query, so no code path forks. Never swap in pg, postgres or drizzle-orm/node-postgres "just for local": that client can run db.transaction() and the HTTP driver in production cannot, so local runs would pass code that breaks on deploy.
• NEON_LOCAL_PROXY never goes into a Vercel environment. The app throws on a production deployment that has it set.

Every schema change in this repo is a migration file produced by the ORM, applied with the ORM's own command, against DATABASE_URL_UNPOOLED.

Required

• Generate the migration (bun run db:generate for Drizzle, prisma migrate dev --name <change> for Prisma), read the emitted SQL, then apply it. The generated file is the reviewable artefact - a schema change with no file in the diff did not happen.
• Apply migrations with bun run db:migrate. It has to reach the direct endpoint, never the -pooler one. How it gets there is the ORM's business - Prisma's prisma.config.ts reads DIRECT_URL, then DATABASE_URL_UNPOOLED; Drizzle derives the direct host from DATABASE_URL - so set every direct-connection key .env.example lists to the same string and let the ORM pick.
• In a script you write, resolve the direct string with directDatabaseUrl() from src/db/client.ts rather than re-reading process.env: it refuses to hand back a pooler host instead of letting the migration discover that itself.
• Edit table definitions only in the ORM schema file - src/db/schema.ts under Drizzle, prisma/schema.prisma under Prisma. That file is owned by the ORM battery.
• Test destructive migrations on a Neon branch first: bun run db:branch, apply there, check the row counts, then apply to main.

Forbidden

• Raw DDL from application code, a script, psql -c, neonctl or the Neon SQL editor. create table, alter table, drop, truncate and create index outside a migration file put the database and the schema file out of sync, and the next generated migration will try to "fix" the drift by dropping your column.
• Pointing any migration at the pooled URL. PgBouncer in transaction mode hands each statement to a different backend, so create index concurrently fails, advisory locks silently do nothing, and multi-statement DDL half-applies. The guard-neon-sql hook blocks the obvious cases; do not work around it by inlining the string.
• drizzle-kit push or prisma db push against anything but your own throwaway branch. Both skip the migration history, so the change exists in the database and nowhere in git.
• Hand-editing a migration that has already been applied to main. Write a new one.

Data migrations

Keep DDL and backfills in separate migrations. Add the nullable column, deploy, backfill in batches, then a second migration adds the not null. A single migration that adds a column and rewrites ten million rows holds a lock for the length of the rewrite, and on a serverless host the request that triggered it times out first.