@vercel/postgres

Connect to Vercel Postgres databases on the Edge

weekly downloads204K

versionv0.10.0

licenseApache-2.0

categorydatabase

Overview

@vercel/postgres is a PostgreSQL client library built specifically for serverless and edge environments, particularly optimized for Vercel's infrastructure. It wraps the standard node-postgres (pg) driver with WebSocket support, enabling TCP-less database connections in environments like Vercel Edge Functions and Cloudflare Workers. The package provides a zero-configuration experience when deployed on Vercel, automatically consuming environment variables for connection management.

The library centers around a simple sql template literal API that handles parameterized queries automatically, preventing SQL injection while maintaining the expressiveness of raw SQL. Unlike traditional database clients that require manual connection string configuration and pool management, @vercel/postgres abstracts these concerns in Vercel environments while still exposing lower-level primitives like createPool() and createClient() for advanced use cases.

With over 200,000 weekly downloads, @vercel/postgres has become the default choice for JavaScript developers building serverless applications on Vercel that need direct SQL access. It bridges the gap between raw SQL control and the convenience of ORMs, making it suitable for applications that need performance-critical queries without the overhead of full schema abstraction layers. The package integrates seamlessly with popular ORMs like Drizzle, Kysely, and Prisma when more structured data access patterns are needed.

The serverless optimization is its key differentiator—connections are pooled and reused across invocations, and the WebSocket-based protocol allows database access in environments where traditional TCP connections aren't available. This makes it fundamentally different from standard pg usage patterns where connection lifecycle management is a primary concern.

Quick Start

typescript

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

// Simple parameterized query - prevents SQL injection
async function getUserById(userId: number) {
  const result = await sql`
    SELECT id, email, created_at 
    FROM users 
    WHERE id = ${userId}
  `;
  return result.rows[0];
}

// Transaction with multiple queries using a shared connection
async function transferCredits(fromUserId: number, toUserId: number, amount: number) {
  const client = await sql.connect();
  
  try {
    await client.sql`BEGIN`;
    
    await client.sql`
      UPDATE accounts 
      SET credits = credits - ${amount} 
      WHERE user_id = ${fromUserId}
    `;
    
    await client.sql`
      UPDATE accounts 
      SET credits = credits + ${amount} 
      WHERE user_id = ${toUserId}
    `;
    
    await client.sql`COMMIT`;
  } catch (error) {
    await client.sql`ROLLBACK`;
    throw error;
  } finally {
    client.release();
  }
}

// Using createPool for advanced configuration
import { createPool } from '@vercel/postgres';

const pool = createPool({
  connectionString: process.env.POSTGRES_URL,
  max: 20,
  idleTimeoutMillis: 30000
});

async function getRecentOrders(limit: number = 10) {
  const result = await pool.sql`
    SELECT o.id, o.total, u.email
    FROM orders o
    JOIN users u ON o.user_id = u.id
    ORDER BY o.created_at DESC
    LIMIT ${limit}
  `;
  return result.rows;
}

Use Cases

Serverless API routes with direct SQL access: When building Next.js API routes or Vercel Functions that need quick database queries without ORM overhead, @vercel/postgres provides instant connectivity with parameterized query support. A user authentication endpoint can execute await sqlSELECT * FROM users WHERE email = ${email}`` without connection string management.

Edge-deployed data fetching: Applications using Vercel Edge Runtime or Cloudflare Workers can connect to PostgreSQL databases despite TCP limitations. A middleware layer authenticating requests at the edge can validate API keys against a centralized database using WebSocket-based connections.

Migration from traditional Node.js Postgres apps: Teams moving existing pg-based applications to serverless infrastructure can adopt @vercel/postgres with minimal refactoring since it exposes the same underlying pg client interfaces through createClient() and createPool(), just with automatic serverless optimization.

Hybrid ORM architectures: Projects using Drizzle or Kysely for most queries but needing raw SQL for complex analytics or performance-critical operations can use @vercel/postgres as the underlying driver while switching to template literals for specific queries that benefit from hand-tuned SQL.

Rapid prototyping with Vercel Postgres: Developers spinning up MVPs or proof-of-concepts on Vercel can create a Postgres database through the Vercel dashboard and immediately start querying with zero manual configuration—no connection strings, no pool setup, just import and query.

Pros & Cons

Pros

+Zero-configuration deployment on Vercel with automatic environment variable consumption eliminates connection management boilerplate
+SQL template literal syntax provides parameterized query safety with the expressiveness of raw SQL, avoiding ORM query builder limitations
+WebSocket-based protocol enables PostgreSQL access in edge runtimes and serverless environments where TCP connections are unavailable
+Built on battle-tested node-postgres (pg) library, ensuring protocol compatibility and reliability while adding serverless optimizations
+Connection pooling happens automatically across serverless function invocations, improving cold start performance compared to per-invocation connections

Cons

−Tightly coupled to Vercel ecosystem with limited documentation for non-Vercel deployments or competing platforms like Supabase (requires connection string workarounds)
−No built-in schema validation, type generation, or migration tooling—developers must manage database schemas separately or integrate external tools
−Manual connection cleanup required when using sql.connect() for multi-query sessions, creating potential connection leak risks if not properly released
−Lacks advanced ORM features like eager loading, relationship mapping, or automatic JOIN generation that libraries like Prisma provide
−WebSocket fallback adds latency overhead compared to direct TCP connections in traditional Node.js environments where TCP is available

Alternatives

drizzle-ormv0.45.1

Drizzle ORM package for SQL databases

databasedrizzleorm

4.6M / week

kyselyv0.28.11

Type safe SQL query builder

databasequerybuilder

2.5M / week

@neondatabase/serverlessv1.0.2

node-postgres for serverless environments from neon.com

databaseNeonserverless

1.0M / week

prismav7.4.0

Prisma is an open-source database toolkit. It includes a JavaScript/TypeScript ORM for Node.js, migrations and a modern GUI to view and edit the data in your database. You can use Prisma in new projects or add it to an existing one.

databaseCLIORM

7.8M / week

Install

bash

npm install @vercel/postgres

bash

pnpm add @vercel/postgres

bash

bun add @vercel/postgres

Overview

Quick Start

typescript

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

// Simple parameterized query - prevents SQL injection
async function getUserById(userId: number) {
  const result = await sql`
    SELECT id, email, created_at 
    FROM users 
    WHERE id = ${userId}
  `;
  return result.rows[0];
}

// Transaction with multiple queries using a shared connection
async function transferCredits(fromUserId: number, toUserId: number, amount: number) {
  const client = await sql.connect();
  
  try {
    await client.sql`BEGIN`;
    
    await client.sql`
      UPDATE accounts 
      SET credits = credits - ${amount} 
      WHERE user_id = ${fromUserId}
    `;
    
    await client.sql`
      UPDATE accounts 
      SET credits = credits + ${amount} 
      WHERE user_id = ${toUserId}
    `;
    
    await client.sql`COMMIT`;
  } catch (error) {
    await client.sql`ROLLBACK`;
    throw error;
  } finally {
    client.release();
  }
}

// Using createPool for advanced configuration
import { createPool } from '@vercel/postgres';

const pool = createPool({
  connectionString: process.env.POSTGRES_URL,
  max: 20,
  idleTimeoutMillis: 30000
});

async function getRecentOrders(limit: number = 10) {
  const result = await pool.sql`
    SELECT o.id, o.total, u.email
    FROM orders o
    JOIN users u ON o.user_id = u.id
    ORDER BY o.created_at DESC
    LIMIT ${limit}
  `;
  return result.rows;
}

Use Cases

Pros & Cons

Pros

+Zero-configuration deployment on Vercel with automatic environment variable consumption eliminates connection management boilerplate
+SQL template literal syntax provides parameterized query safety with the expressiveness of raw SQL, avoiding ORM query builder limitations
+WebSocket-based protocol enables PostgreSQL access in edge runtimes and serverless environments where TCP connections are unavailable
+Built on battle-tested node-postgres (pg) library, ensuring protocol compatibility and reliability while adding serverless optimizations
+Connection pooling happens automatically across serverless function invocations, improving cold start performance compared to per-invocation connections

Cons

−Tightly coupled to Vercel ecosystem with limited documentation for non-Vercel deployments or competing platforms like Supabase (requires connection string workarounds)
−No built-in schema validation, type generation, or migration tooling—developers must manage database schemas separately or integrate external tools
−Manual connection cleanup required when using sql.connect() for multi-query sessions, creating potential connection leak risks if not properly released
−Lacks advanced ORM features like eager loading, relationship mapping, or automatic JOIN generation that libraries like Prisma provide
−WebSocket fallback adds latency overhead compared to direct TCP connections in traditional Node.js environments where TCP is available