explaingit

brianc/node-postgres

13,126JavaScriptAudience · developerComplexity · 2/5LicenseSetup · easy

TLDR

node-postgres (pg) is the standard Node.js library for connecting to a PostgreSQL database, supporting parameterized queries, connection pooling, async notifications, and large data streaming.

Mindmap

mindmap
  root((repo))
    What it does
      PostgreSQL client
      Connection pooling
      Safe queries
    Features
      Parameterized queries
      LISTEN and NOTIFY
      COPY bulk transfer
    Sub-packages
      pg core
      pg-pool
      pg-cursor
      pg-native
    Usage
      npm install
      No system deps
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Connect a Node.js API server to PostgreSQL with a connection pool for efficient, reusable database access

USE CASE 2

Run parameterized SQL queries safely, preventing SQL injection from user-supplied input

USE CASE 3

Listen for real-time database events using PostgreSQL LISTEN/NOTIFY without polling

USE CASE 4

Stream large query result sets row-by-row with pg-cursor to avoid loading everything into memory at once

Tech stack

JavaScriptNode.jsPostgreSQL

Getting it running

Difficulty · easy Time to first run · 5min

Requires a running PostgreSQL instance to connect to.

Free to use in personal and commercial projects, just keep the copyright notice.

In plain English

node-postgres (published on npm as the package "pg") is the standard library Node.js developers use to talk to a PostgreSQL database. PostgreSQL is an open-source relational database, the kind where you store data in tables and query it with SQL. node-postgres handles the connection between your JavaScript code and that database. The library supports the full range of things you would typically need: running queries with parameters (so that user input is passed safely without SQL injection risk), connection pooling (reusing a shared set of database connections instead of opening a new one for every request, which is much more efficient in a server environment), and PostgreSQL-specific features like async notifications via LISTEN/NOTIFY and bulk data transfers via COPY. Installing it is a single npm command. The library is written in plain JavaScript, so no additional system dependencies are required for basic use. There is an optional companion package (pg-native) that uses a lower-level C library called libpq instead, which can be faster in certain situations but requires that library to be installed on the machine. The repository also contains several smaller related packages in the same codebase: a pool manager, a cursor for reading large result sets row by row, a streaming query interface, a connection string parser, and an implementation of the PostgreSQL wire protocol. Each is published to npm separately but developed together here. The project is MIT licensed and maintained on GitHub through community contributions. A detailed documentation site is available at node-postgres.com.

Copy-paste prompts

Prompt 1
Show me how to set up a pg connection pool in a Node.js Express app and run a safe parameterized SELECT query
Prompt 2
Write a Node.js script using node-postgres that listens for NOTIFY events on a PostgreSQL channel and logs each message
Prompt 3
How do I use the pg-cursor package to read a large PostgreSQL table row by row without running out of memory?
Prompt 4
I'm getting SSL connection errors with node-postgres connecting to a Heroku Postgres database, show me the correct client config to fix this
Open on GitHub → Explain another repo

← brianc on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.