• Welcome

node-postgres is a collection of node.js modules for interfacing with your PostgreSQL database. It has support for callbacks, promises, async/await, connection pooling, prepared statements, cursors, streaming results, C/C++ bindings, rich type parsing, and more! Just like PostgreSQL itself there are a lot of features: this documentation aims to get you up and running quickly and in the right direction. It also tries to provide guides for more advanced & edge-case topics allowing you to tap into the full power of PostgreSQL from node.js.

Install

$ npm install pg

Supporters

node-postgres continued development and support is made possible by the many supporters.

Special thanks to Medplum for sponsoring node-postgres for a whole year!

If you or your company would like to sponsor node-postgres stop by GitHub Sponsors and sign up or feel free to email me if you want to add your logo to the documentation or discuss higher tiers of sponsorship!

Version compatibility

node-postgres strives to be compatible with all recent LTS versions of node & the most recent "stable" version. At the time of this writing node-postgres is compatible with node 18.x, 20.x, 22.x, and 24.x.

Getting started

The simplest possible way to connect, query, and disconnect is with async/await:

import { Client } from 'pg'
const client = new Client()
await client.connect()
 
const res = await client.query('SELECT $1::text as message', ['Hello world!'])
console.log(res.rows[0].message) // Hello world!
await client.end()

Error Handling

For the sake of simplicity, these docs will assume that the methods are successful. In real life use, make sure to properly handle errors thrown in the methods. A try/catch block is a great way to do so:

import { Client } from 'pg'
const client = new Client()
await client.connect()
 
try {
   const res = await client.query('SELECT $1::text as message', ['Hello world!'])
   console.log(res.rows[0].message) // Hello world!
} catch (err) {
   console.error(err);
} finally {
   await client.end()
}

Pooling

In most applications you'll wannt to use a connection pool to manage your connections. This is a more advanced topic, but here's a simple example of how to use it:

import { Pool } from 'pg'
const pool = new Pool()
const res = await pool.query('SELECT $1::text as message', ['Hello world!'])
console.log(res.rows[0].message) // Hello world!

Our real-world apps are almost always more complicated than that, and I urge you to read on!