node-postgres

Non-blocking PostgreSQL client for Node.js with pure JavaScript and native libpq bindings.

Library
npm
v8.23.1
13,230 stars
MIT License

Repository Health

Pre-computed score based on development activity, maintenance, community, maturity, and trend momentum. How we score it →
77 /100 Good
Development Activity 80
Maintenance 44
Community 84
Maturity 60
Momentum 40

Technical Analysis

AI-assessed by reading the actual repository — architecture, code quality, innovation, and documentation. How we score it →
82 /100 Excellent
Architecture 85
Code Quality 82
Innovation 80
Learning Curve 82

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.

Used by 145 apps in this directory

Rust
68%
Apache 2.0

Temps

Analytics · Devops · Monitoring

904

A self-hosted Rust PaaS that replaces Vercel, Sentry, PostHog, Pingdom, Resend, and E2B with one binary — plus 440+ CLI operations agents like Claude Code can drive directly.

View details
81
Repo Health
86
Technical
66
Dependency
Built with
Rust 68%
TypeScript 31%
Updated 1 weeks ago
TypeScript
98%
Apache 2.0

Tianji

Analytics · Monitoring

3,119

Replace Google Analytics, UptimeKuma, and Prometheus with one self-hosted platform that tracks websites, monitors uptime, and reports server health.

View details
85
Repo Health
76
Technical
65
Dependency
Built with
TypeScript 98%
Updated 2 weeks ago
HTML
65%
AGPL 3.0

ToolJet

AI Agents · Low Code Platforms · No Code Platforms

41,204

Open-source AI-native platform to build and deploy internal tools, workflows, and AI agents with a visual drag-and-drop builder and 80+ data source integrations.

View details
94
Repo Health
81
Technical
63
Dependency
Built with
HTML 65%
JavaScript 21%
TypeScript 11%
Updated 1 weeks ago
TypeScript
99%
Apache 2.0

Trigger.dev

AI Development · Automation · Developer Tools

16,725

Build and deploy fully-managed AI agents and background jobs in TypeScript — with no timeouts, durable retries, real-time observability, and elastic scaling built in.

View details
89
Repo Health
9
Technical
63
Dependency
Built with
TypeScript 99%
Updated 2 weeks ago
TypeScript
81%
Other

twenty

CRM

60,566

The open-source CRM you build, ship, and version like the rest of your stack — with customizable objects, AI agents, and a TypeScript SDK.

View details
92
Repo Health
82
Technical
64
Dependency
Built with
TypeScript 81%
MDX 17%
Updated 1 weeks ago
TypeScript
99%
MIT

Umami

Analytics

39,958

Privacy-first web analytics that respects your users — self-hosted, cookieless, and GDPR compliant out of the box.

View details
94
Repo Health
83
Technical
67
Dependency
Built with
TypeScript 99%
Updated 2 weeks ago
TypeScript
97%
Apache 2.0

Unleash

Ab Testing Experimentation · Developer Tools · Devops

14,123

The open-source feature management platform that lets you ship code to production and control who sees it — without redeploying.

View details
91
Repo Health
84
Technical
69
Dependency
Built with
TypeScript 97%
Updated 1 weeks ago
TypeScript
97%
Apache 2.0

Unleash

Ab Testing Experimentation · Developer Tools · Devops

14,123

The open-source feature management platform that lets you ship code to production and control who sees it — without redeploying.

View details
91
Repo Health
84
Technical
69
Dependency
Built with
TypeScript 97%
Updated 1 weeks ago
JavaScript
51%
MIT

Uptime Kuma

Monitoring

93,330

Self-hosted monitoring for every service you run — 23 monitor types, 95 notification channels, live dashboards, and public status pages with no vendor lock-in.

View details
92
Repo Health
81
Technical
62
Dependency
Built with
JavaScript 51%
Vue 37%
TypeScript 11%
Updated 1 weeks ago

Join founders buildingwith open source

Opinionated takes, migration guides, cost-saving tips, and insights from the open source ecosystem.

Subscribe on Substack
Join 750+ subscribers