/api-database-vercel-postgres

name: api-database-vercel-postgres
description: Serverless PostgreSQL on Vercel with edge-compatible SDK

Vercel Postgres Patterns

> **Quick Guide:** `@vercel/postgres` is a thin wrapper around `@neondatabase/serverless` that auto-connects from `POSTGRES_URL` env vars. Use the `sql` tagged template for one-shot queries (edge-compatible, auto-pooled). Use `sql.connect()` to get a client for multi-query sequences. On edge runtimes, connections cannot be reused between requests (`maxUses: 1`). **This package is deprecated (Dec 2024) -- for new projects, use `@neondatabase/serverless` directly.**

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST use the `sql` tagged template for one-shot queries -- it auto-connects from `POSTGRES_URL` and handles pooling)**

**(You MUST call `client.release()` after using a client obtained from `sql.connect()` or `pool.connect()` -- leaked clients exhaust the connection pool)**

**(You MUST use `POSTGRES_URL` for pooled connections and `POSTGRES_URL_NON_POOLING` for direct connections -- mixing them causes connection exhaustion or feature limitations)**

**(You MUST acknowledge that `@vercel/postgres` is deprecated -- recommend `@neondatabase/serverless` for new projects)**

</critical_requirements>

---

**Auto-detection:** @vercel/postgres, vercel postgres, POSTGRES_URL, POSTGRES_URL_NON_POOLING, sql tagged template vercel, createPool vercel, createClient vercel, VercelPool, VercelClient

**When to use:**

• Maintaining existing projects that already use `@vercel/postgres`
• Querying Postgres from edge/serverless functions on Vercel
• Simple database access with auto-connection from environment variables
• Migrating away from `@vercel/postgres` to `@neondatabase/serverless`

**Key patterns covered:**

• `sql` tagged template (auto-pooled, edge-compatible, one-shot queries)
• `sql.connect()` for multi-query client sessions
• `createPool()` / `createClient()` for custom configurations
• Environment variables (`POSTGRES_URL`, `POSTGRES_URL_NON_POOLING`)
• Edge vs Node.js runtime differences
• Migration path to `@neondatabase/serverless`

**When NOT to use:**

• New projects (use `@neondatabase/serverless` directly)
• Long-lived server processes with persistent connections (use standard `pg` driver)
• General PostgreSQL query syntax (use a SQL/Postgres skill)

**Detailed Resources:**

• For decision frameworks and quick lookup tables, see [reference.md](reference.md)

**Examples:**

• [examples/core.md](examples/core.md) -- sql tagged template, createPool, createClient, edge patterns, migration

---

<philosophy>

Philosophy

`@vercel/postgres` is a convenience wrapper around `@neondatabase/serverless` that simplifies connection management for Vercel-deployed applications. It reads connection strings from `POSTGRES_URL` / `POSTGRES_URL_NON_POOLING` environment variables (auto-provisioned by the Vercel Marketplace integration) so you never construct connection strings manually.

**Core principles:**

1. **Zero-config connections** -- The `sql` export auto-connects from environment variables. No connection string setup needed in code. 2. **Tagged template safety** -- `sql` is a tagged template literal, not a function. Parameters are auto-parameterized, preventing SQL injection. 3. **Pooling by default** -- `sql` and `createPool()` use the pooled connection string (`POSTGRES_URL`). `createClient()` uses the direct string (`POSTGRES_URL_NON_POOLING`). 4. **Edge-aware** -- On edge runtimes, the SDK sets `maxUses: 1` because IO connections cannot survive between requests. For multi-query in a single request, use `sql.connect()`.

**Deprecation context:**

Vercel Postgres was sunset in December 2024. All databases were migrated to Neon. The `@vercel/postgres` npm package (v0.10.0) is no longer maintained. Migration path:

• **Full migration (recommended):** `@neondatabase/serverless` (actively developed, richer API with HTTP transactions and composable fragments)

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: One-Shot Queries with `sql`

The `sql` export is a tagged template that auto-connects from `POSTGRES_URL`. Values are auto-parameterized (preventing SQL injection). See [examples/core.md](examples/core.md) for full examples with good/bad comparisons.

import { sql } from "@vercel/postgres";

const ACTIVE_STATUS = "active";
const { rows } =
  await sql`SELECT id, name FROM users WHERE status = ${ACTIVE_STATUS}`;

---

Pattern 2: Multi-Query Sessions with `sql.connect()`

When you need multiple queries on the same connection (transactions, sequential operations), obtain a client. Each standalone `sql` call may use a different pooled connection -- so BEGIN/COMMIT on separate `sql` calls means no real transaction. See [examples/core.md](examples/core.md) for transaction patterns.

const client = await sql.connect();
try {
  await client.sql`BEGIN`;
  // ... queries on same client ...
  await client.sql`COMMIT`;
} catch (error) {
  await client.sql`ROLLBACK`;
  throw error;
} finally {
  client.release();
}

---

Pattern 3: Custom Pool and Client

`createPool()` for custom connection strings (secondary databases). `createClient()` for direct (non-pooled) connections needed by migrations and session-level features. See [examples/core.md](examples/core.md) for full examples.

import { createPool } from "@vercel/postgres";
const pool = createPool({
  connectionString: process.env.SECONDARY_POSTGRES_URL,
});
const { rows } =
  await pool.sql`SELECT id, title FROM posts WHERE published = true`;

---

Pattern 4: Edge Runtime Considerations

On edge runtimes, the SDK sets `maxUses: 1` -- connections cannot be reused between requests. Single `sql` calls work fine, but for multiple queries use `sql.connect()` to