@neondatabase/serverless

# @neondatabase/serverless: agent guide

Neon's Postgres driver for serverless/edge. HTTP via `neon()`, WebSocket via `Pool`/`Client`. Only works against Neon (or your own Neon WS proxy), not plain localhost Postgres: use `pg` for that.

## Install
```bash
npm install @neondatabase/serverless server-only
npm install drizzle-orm && npm install -D drizzle-kit   # only if you want an ORM
```

## Env
- `DATABASE_URL`: Neon connection string. Sources, in order:
  1. Already set (Vercel Marketplace Neon integration sets it; `vercel env pull .env.local`).
  2. Neon console -> Connection details.
  3. No account: README 'No account?' section (POST https://neon.new/api/v1/database). Give the user the `claim_url`.
- Commit `.env.example` with a placeholder. Never commit `.env.local`.

## Next.js App Router: the one path
```ts
// src/db/index.ts
import 'server-only';
import { neon } from '@neondatabase/serverless';
import { drizzle } from 'drizzle-orm/neon-http';

export function getDb() {            // lazy: do NOT connect or throw at import time
  const url = process.env.DATABASE_URL;
  if (!url) throw new Error('DATABASE_URL is not set');
  return drizzle(neon(url));
}
```
Call `getDb()` inside server actions and route handlers or server components, and mark pages `export const dynamic = 'force-dynamic'` if they query at render. Without an ORM: `const sql = neon(url); await sql`SELECT * FROM t WHERE id = ${id}`;`

## Three mistakes
1. Throwing or creating the client at module top level. `next build` imports the module and fails without DATABASE_URL.
2. Using `Pool`/`Client` at module scope in serverless, or not closing them. Create, use and end them in one request. Node 21 and below also need `neonConfig.webSocketConstructor = ws`. Default to `neon()` unless you need sessions or interactive transactions.
3. Expecting `neon()` to hold a session. Each call is one HTTP request, so BEGIN/COMMIT across calls does nothing. Use `sql.transaction([...])` or `Pool`.

## Verify
- `npm run build` passes with and without DATABASE_URL.
- With DATABASE_URL set: run the migration, then hit a route that executes sql`SELECT 1` and returns 200.
- If no DATABASE_URL exists, say so. Do not claim the database works.

### Next.js (App Router)

```bash
npm install @neondatabase/serverless server-only
```

```ts
// src/db/index.ts
import 'server-only';
import { neon } from '@neondatabase/serverless';

// Lazy on purpose: `next build` imports this file. Never throw or query at import time.
export function getSql() {
  const url = process.env.DATABASE_URL;
  if (!url) throw new Error('DATABASE_URL is not set');
  return neon(url);
}
```

```ts
// src/app/actions.ts
'use server';
import { getSql } from '@/db';

export async function createUser(formData: FormData) {
  const email = String(formData.get('email') ?? '').trim();
  if (!email) return;
  const sql = getSql();
  await sql`INSERT INTO users (email) VALUES (${email}) ON CONFLICT DO NOTHING`;
}
```

```tsx
// src/app/page.tsx (query at render)
import { getSql } from '@/db';
export const dynamic = 'force-dynamic';

export default async function Page() {
  const users = await getSql()`SELECT id, email FROM users ORDER BY id DESC LIMIT 20`;
  return <ul>{users.map((u) => <li key={u.id}>{u.email}</li>)}</ul>;
}
```

With Drizzle: `import { drizzle } from 'drizzle-orm/neon-http'; const db = drizzle(neon(url));`

No `DATABASE_URL` yet? See 'No account? Provision a claimable database' above.

# @neondatabase/serverless

> Neon's Postgres driver for JavaScript/TypeScript: node-postgres compatible, uses HTTP (`neon()`) or WebSockets (`Pool`/`Client`) so it works in serverless and edge runtimes such as Vercel and Cloudflare Workers. Connects to Neon databases. For plain local Postgres use `pg`.

## Get a database (do this first)

- [No account? Provision a claimable Neon database](https://neon.com/auth.md): create a Postgres project without signup; a human claims it later via `claim_url`
- [Neon console connection string](https://neon.com/docs/connect/choose-connection.md): which connection string and driver to use
- [Vercel Marketplace integration](https://neon.com/docs/guides/vercel-managed-integration.md): sets DATABASE_URL automatically

## Use the driver

- [README: install, neon(), transaction(), Pool, Client](https://github.com/neondatabase/serverless/blob/main/README.md)
- [Serverless driver docs](https://neon.com/docs/serverless/serverless-driver.md): HTTP vs WebSocket, limits
- [Config options (neonConfig)](https://github.com/neondatabase/serverless/blob/main/CONFIG.md)
- [AGENTS.md: Next.js App Router path and common mistakes](https://github.com/neondatabase/serverless/blob/main/AGENTS.md)

## Optional

- [Run your own WebSocket proxy for non-Neon Postgres](https://github.com/neondatabase/serverless/blob/main/DEPLOY.md)
- [Connection errors and timeouts](https://neon.com/docs/connect/connection-errors.md)
- [Neon MCP server](https://neon.com/docs/ai/neon-mcp-server.md)