@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

No-Config

If the environment variables provided by your Vercel project are all the configuration you need, you can use the config-less sql import:

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

const likes = 100;
const { rows, fields } = await sql`SELECT * FROM posts WHERE likes > ${likes};`;

This will safely substitute the JavaScript value into the query by using database parameters. The above query translates to:

await pool.query('SELECT * FROM posts WHERE likes > $1;', [100]);

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();

// The same tagged literal function as the no-config option, but attached to your pool
const likes = 100;
const { rows, fields } =
  await pool.sql`SELECT * FROM posts WHERE likes > ${likes};`;

// or use the query method from `pg`
const likes = 100;
const { rows, fields } = await pool.query(
  'SELECT * from posts WHERE likes > $1;',
  [likes],
);

To specify a connection string:

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

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

const likes = 100;
const { rows, fields } =
  await pool.sql`SELECT * FROM posts WHERE likes > ${likes};`;

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 likes = 100;
    const { rows, fields } =
      await client.sql`SELECT * FROM posts WHERE likes > ${likes};`;
  } 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.