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

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
TypeScript
72%
Apache 2.0

Valmis

AI Agents

107

A security-focused, self-hostable AI agent platform for production work — agents run in isolated containers that access credentials only through a host-side proxy, so the AI itself never sees API keys or plaintext credentials.

View details
50
Repo Health
69
Technical
70
Dependency
Built with
TypeScript 72%
Svelte 27%
Updated 2 months ago
Rust
83%
AGPL 3.0

Vaultwarden

Password Manager · Security

70,347

Unofficial Bitwarden-compatible server in Rust — run the full Bitwarden ecosystem on a Raspberry Pi using every official client you already have, without the multi-container overhead.

View details
89
Repo Health
69
Technical
69
Dependency
Built with
Rust 83%
Updated 2 weeks ago
TypeScript
79%
AGPL 3.0

VoidAuth

Authentication · Security

2,905

Self-hosted SSO with OIDC, LDAP, passkeys, and proxy auth for your entire self-hosted stack

View details
83
Repo Health
77
Technical
72
Dependency
Built with
TypeScript 79%
HTML 15%
Updated 1 weeks ago
TypeScript
88%
Other

Webiny JS

Blogging · CMS · Ecommerce

8,049

Open-source, self-hosted CMS on AWS serverless — a TypeScript framework you extend with code, not a product you configure through a UI.

View details
90
Repo Health
86
Technical
61
Dependency
Built with
TypeScript 88%
JavaScript 11%
Updated 1 weeks ago
TypeScript
42%
AGPL 3.0

Wiki.js

Collaboration · Knowledge Management

29,200

A modern, self-hosted wiki platform built on Node.js with a rich plugin ecosystem for authentication, search, storage, and rendering that adapts to any team's infrastructure.

View details
95
Repo Health
67
Technical
60
Dependency
Built with
TypeScript 42%
Vue 38%
JavaScript 17%
Updated 1 weeks ago
TypeScript
42%
AGPL 3.0

Wiki.js

Collaboration · Knowledge Management

29,200

A modern, self-hosted wiki platform built on Node.js with a rich plugin ecosystem for authentication, search, storage, and rendering that adapts to any team's infrastructure.

View details
95
Repo Health
67
Technical
60
Dependency
Built with
TypeScript 42%
Vue 38%
JavaScript 17%
Updated 1 weeks ago
TypeScript
72%
AGPL 3.0

Worklenz

Collaboration · Product Management · Project Management

3,296

All-in-one open source project management for teams who want full control — plan projects, track tasks, manage resources, and monitor finances without the SaaS lock-in.

View details
87
Repo Health
7
Technical
64
Dependency
Built with
TypeScript 72%
JavaScript 21%
Updated 1 weeks ago
TypeScript
50%
Other

World Monitor

Analytics · Monitoring

90,281

Real-time global intelligence dashboard that fuses AI-synthesized news, geopolitical risk scoring, and infrastructure tracking into one open-source situational awareness platform.

View details
87
Repo Health
89
Technical
68
Dependency
Built with
TypeScript 50%
JavaScript 48%
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