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