Guide · Open source
How to use node-postgres: install pg and query PostgreSQL from Node.js
Updated · written with AI from the project's own documentation and checked against our catalogue data
node-postgres, published on npm as the pg package, is a non-blocking PostgreSQL client for Node.js. It lets your server code or scripts send queries to a PostgreSQL database without freezing the rest of the program while it waits for answers. This guide shows you how to install it, what features it provides, and where it fits compared with heavier tools.
node-postgresbrianc/node-postgres · ★ 13.2k · MIT Install options & downloads Quick start
- 1Install the package. Run npm install pg in your project folder to add node-postgres to your project.
- 2Confirm your runtime. Make sure Node.js is installed. The README excerpt does not state a minimum version, so check node-postgres.com.
- 3Set up a PostgreSQL database. You need a PostgreSQL database to connect to. The README points to the standard PG* environment variables such as PGUSER and PGPASSWORD for connection settings.
- 4Create a pool for connections. Use the built-in connection pooling for server code that runs many queries, rather than opening a fresh connection for each one.
- 5Run parameterized queries. Send queries with parameters so values are passed separately from SQL text, as the library supports parameterized queries.
- 6Use LISTEN/NOTIFY or COPY if needed. Add async notifications with LISTEN/NOTIFY or bulk import and export with COPY TO/COPY FROM when your project needs them.
Install node-postgres with npm
node-postgres is installed as the pg package from npm. You need Node.js installed; the README excerpt does not specify a minimum Node.js version, so check the documentation at node-postgres.com for requirements.
Run the install command from your project folder.
npm install pgUnderstand what node-postgres gives you
node-postgres is a client library, not a database or a visual tool. It is non-blocking, so database calls do not stop other work in your program while they wait. The README says it works with Node.js and also with bun, deno and cloudflare, and that it offers a pure JavaScript client plus optional native libpq bindings that share the same API.
- Connection pooling built in
- Parameterized queries
- Named statements with query plan caching
- Async notifications with LISTEN/NOTIFY
- Bulk import and export with COPY TO/COPY FROM
- Extensible JS to PostgreSQL data-type coercion
Use the related modules when you need them
The repository is a monorepo containing the core pg module and related modules, including pg-pool, pg-cursor, pg-query-stream and pg-connection-string. The pg-native module is the one tied to the native libpq bindings. The README describes node-postgres as light on abstractions, and lists handy extras on its wiki rather than building them in.
- pg: the core client module
- pg-pool: pooling
- pg-cursor and pg-query-stream: streaming results
- pg-native: native libpq bindings
Find documentation and get help
Full project documentation lives at node-postgres.com. Common errors and their causes are covered in the project FAQ on the GitHub wiki. If the documentation does not answer your question, the README asks you to open an issue on the GitHub repo that describes what was unclear.
When you report a problem, the README asks for your Node.js version, your PostgreSQL version and the smallest code snippet that reproduces the issue.
Check whether node-postgres fits your project
node-postgres suits Node.js developers who need to query PostgreSQL from a server or script, especially teams that want pooling in their database layer, or projects that use LISTEN/NOTIFY or COPY. The README is clear that it is not an ORM or query builder, so if you want models, migrations or a query builder, look at tools such as Prisma, Knex.js or Sequelize, or at Postgres.js as another PostgreSQL client.
What people use it for
- A Node.js API server that runs SQL queries against a PostgreSQL database through a connection pool
- A script that bulk loads a CSV-style dataset into PostgreSQL using COPY FROM
- A service that listens for database events with LISTEN/NOTIFY and reacts in JavaScript
- A serverless or edge project using a runtime such as cloudflare, bun or deno, as the README says the library works there
Frequently asked questions
How do I install node-postgres?
Install the pg package from npm with npm install pg. The README lists this as the install method, and you need Node.js installed first.
Is node-postgres free to use?
Yes. The README says node-postgres is free software and is released under the MIT licence. The copyright notice is held by Brian Carlson.
Is node-postgres an ORM?
No. The README says the library is by design light on abstractions. If you want an ORM or query builder, tools such as Prisma, Knex.js or Sequelize are comparable projects.
Does node-postgres work with Bun, Deno or Cloudflare?
The README says it works with bun, deno and cloudflare as well as Node.js. Check the documentation for details on your specific setup.
What is the difference between pg and pg-native?
The pg package is the core module with a pure JavaScript client. pg-native is a related module in the same repo, and the README says the library offers optional native libpq bindings that share the same API.
Where do I get help if something breaks?
Check the FAQ on the GitHub wiki for common errors, then open an issue on the GitHub repo if needed. Include your Node.js version, PostgreSQL version and a minimal code snippet.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
node-postgres is a good choice for Node.js developers who want a light, non-blocking PostgreSQL client with pooling, parameterized queries, LISTEN/NOTIFY and COPY built in. If you want an ORM, a query builder or a visual database tool, pick a different project such as Prisma, Knex.js, Sequelize or a GUI client.
Install options & downloads