node-postgres

node-postgres (published to npm as pg) is the de facto PostgreSQL client for Node.js, providing both a pure JavaScript driver and optional native libpq bindings behind a single, consistent API. It implements the PostgreSQL wire protocol directly, so connecting, querying, and streaming results require no external client library beyond Node.js itself.

The project ships as a monorepo of focused packages — pg for the core client and connection pool, pg-cursor for server-side cursors, pg-query-stream for streaming large result sets, and pg-protocol for the low-level wire-protocol parser/serializer — so applications can pull in only what they need. With roughly 36 million weekly downloads, it underpins the majority of Node.js applications, ORMs, and query builders that talk to PostgreSQL.

What You Get

• A Client and Pool implementation with automatic connection pooling and configurable overflow/timeout behavior
• A pure-JS wire-protocol implementation (pg-protocol) plus optional native libpq bindings (pg-native) behind the identical API
• Extensible type parsing so PostgreSQL types (arrays, JSON, timestamps, custom domains) coerce to native JS values
• Streaming helpers (pg-cursor, pg-query-stream) for iterating large result sets without loading them fully into memory
• Support for parameterized queries, named/prepared statements with plan caching, and async LISTEN/NOTIFY notifications

Common Use Cases

• Powering the database layer of Express/Fastify/Koa APIs that talk directly to PostgreSQL
• Serving as the underlying driver for higher-level tools like Knex, Sequelize, and Drizzle ORM
• Running on edge/serverless runtimes (Cloudflare Workers, Deno, Bun) via the pg-cloudflare transport and pure-JS client
• Streaming and paginating very large query results with pg-cursor or pg-query-stream for reporting/export jobs

Under The Hood

Architecture - node-postgres is organized as a Lerna/Yarn-workspaces monorepo split by concern: pg-protocol implements the raw PostgreSQL wire protocol (message parsing/serialization) independent of any transport; lib/connection.js wraps a TCP/TLS socket (lib/stream.js) and speaks that protocol; lib/client.js layers query/parameter handling and the DatabaseError type on top of a Connection; and pg-pool wraps Client to add pooling, exposed to consumers as the top-level Pool/Client API in lib/index.js. Companion packages (pg-cursor, pg-query-stream) subclass the same Client/Query primitives to add streaming, and the native binding (lib/native) is lazy-loaded behind a native property so the pure-JS and libpq paths share one public surface.

Tech Stack - The core pg package is plain CommonJS JavaScript (published with a matching ESM wrapper in esm/) with runtime dependencies on pg-connection-string, pg-pool, pg-protocol, pg-types, and pgpass; the optional pg-native peer dependency and pg-cloudflare optional dependency add libpq bindings and an edge-runtime transport respectively. The monorepo is built and tested with Lerna, Yarn workspaces, and Vitest/Mocha, targets Node.js >= 16, and TypeScript appears only in the dev/tooling chain, not the published library surface.

Code Quality - Test coverage is extensive and segmented by concern: test/unit, test/integration, test/native, test/cloudflare, and test/tls under packages/pg/test, plus a test/integration/gh-issues directory of regression tests tied to specific bug reports. CI runs on every push (GitHub Actions badge in the README). The codebase favors small, single-purpose modules (client.js, connection.js, query.js, result.js) with consistent naming, though the library does not ship its own TypeScript type definitions — consumers rely on the community-maintained @types/pg package.

API Design - The public API is deliberately small: new Pool(config) or new Client(config) followed by .query(text, values) covers most use cases, with the native and pure-JS clients sharing an identical interface so switching transports requires no code changes. Prepared statements, LISTEN/NOTIFY, and COPY TO/FROM are exposed through the same query-shaped API rather than bespoke methods, keeping the surface area low. Documentation is centralized at node-postgres.com with a companion GitHub wiki cataloguing community “Extras,” though the type-definition gap adds minor friction for TypeScript users.