@vercel/postgres 🚧

A client that works with Vercel Postgres.

Quick Start

Note: If you want to use an ORM instead of writing your own queries, see @vercel/postgres-kysely.

Install

pnpm install @vercel/postgres

Create a Pool

If you need a pg Pool object, you can use the createPool function.

Automatically uses process.env.POSTGRES_URL:

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

const pool = createPool();

const { rows, fields } = await pool.query(
  'SELECT * from POSTS WHERE likes > 100;',
);

To specify a connection string:

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

const pool = createPool({
  connectionString: process.env.SOME_POSTGRES_CONNECTION_STRING,
});

const { rows, fields } = await pool.query(
  'SELECT * from POSTS WHERE likes > 100;',
);

Create a Client

If you need a pg Client object, you can use the createClient function.

Automatically uses process.env.POSTGRES_URL_NON_POOLING:

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

/**
 * Clients cannot be reused, so you have to create them, connect them, and disconnect them
 * per query. This is why you should use a pool unless you explicitly need a single client.
 */
async function queryPosts() {
  const client = createClient();

  await client.connect();

  try {
    const { rows, fields } = await client.query(
      'SELECT * from POSTS WHERE likes > 100;',
    );
  } finally {
    await client.end();
  }
}

To specify a connection string:

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

const client = createClient({
  connectionString: process.env.SOME_POSTGRES_CONNECTION_STRING,
});

Get the connection url

If you just want the connection URL, you can call postgresConnectionString(type: 'pool' | 'direct'): string;. This will read from your environment variables. For the pool type, it will look for the POSTGRES_URL environment variables. For the direct type, it will look for the POSTGRES_URL_NON_POOLING environment variables.

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

const pooledConnectionString = postgresConnectionString('pool');
const directConnectionString = postgresConnectionString('direct');

Connection Config

When using the createClient or createPool functions, you can pass in additional options alongside the connection string that conforms to VercelPostgresClientConfig or VercelPostgresPoolConfig.

Documentation

The @vercel/postgres package uses the pg package. For more detailed documentation, checkout node-postgres.