neon-vercel-postgres

# Neon & Vercel Serverless Postgres

**Status**: Production Ready
**Last Updated**: 2025-11-21
**Dependencies**: None
**Latest Versions**: `@neondatabase/serverless@1.0.2`, `@vercel/postgres@0.10.0`, `drizzle-orm@0.44.7`, `neonctl@2.16.1`

---

## Quick Start (5 Minutes)

### 1. Choose Your Platform

**Option A: Neon Direct** (multi-cloud, Cloudflare Workers, any serverless)
```bash
bun add @neondatabase/serverless
```

**Option B: Vercel Postgres** (Vercel-only, zero-config on Vercel)
```bash
bun add @vercel/postgres
```

**Why this matters:**
- Neon direct gives you multi-cloud flexibility and access to branching API
- Vercel Postgres gives you zero-config on Vercel with automatic environment variables
- Both are HTTP-based (no TCP), perfect for serverless/edge environments

### 2. Get Your Connection String

**For Neon Direct:**
```bash
# Sign up at https://neon.tech
# Create a project → Get connection string
# Format: postgresql://user:password@ep-xyz-pooler.region.aws.neon.tech/dbname?sslmode=require
```

**For Vercel Postgres:**
```bash
# In your Vercel project
vercel postgres create
vercel env pull .env.local  # Automatically creates POSTGRES_URL and other vars
```

**CRITICAL:**
- Use **pooled connection string** for serverless (ends with `-pooler.region.aws.neon.tech`)
- Non-pooled connections will exhaust quickly in serverless environments
- Always include `?sslmode=require` parameter

### 3. Query Your Database

**Neon Direct:**
```typescript
import { neon } from '@neondatabase/serverless';

const sql = neon(process.env.DATABASE_URL!);

// Simple query
const users = await sql`SELECT * FROM users WHERE id = ${userId}`;

// Transactions
const result = await sql.transaction([
  sql`INSERT INTO users (name) VALUES (${name})`,
  sql`SELECT * FROM users WHERE name = ${name}`
]);
```

**Vercel Postgres:**
```typescript
import { sql } from '@vercel/postgres';

// Simple query
const { rows } = await sql`SELECT * FROM users WHERE id = ${userId}`;

// Transactions
c