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.

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 8.x, 10.x, 12.x and 14.x To use node >= 14.x you will need to install [email protected] or later due to some internal stream changes on the node 14 branch. Dropping support for an old node lts version will always be considered a breaking change in node-postgres and will be done on major version number changes only, and we will try to keep support for 8.x for as long as reasonably possible.

Getting started

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

import pg from 'pg'
const { Client } = 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 pg from 'pg'
const { Client } = 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()
}

Callbacks

If you prefer a callback-style approach to asynchronous programming, all async methods support an optional callback parameter as well:

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

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

Announcements