postgres

Postgres.js (published to npm as postgres) is a PostgreSQL client that implements the Postgres wire protocol directly in JavaScript, with no runtime dependencies at all. Queries are written as ES6 tagged template literals, so parameters are automatically extracted and sent to the server separately from the SQL text — safe by construction rather than by convention, with no separate escaping step to remember.

Beyond basic querying, it ships connection pooling, prepared statements, transactions with savepoints, LISTEN/NOTIFY, a subscribe() API that speaks Postgres’s logical replication protocol for real-time row-level change feeds, large object support, and a full custom-type system. A single source tree is transpiled to separate builds for Node (ESM and CommonJS), Deno, and Cloudflare Workers, so the same API works across all four runtimes.

It’s widely used as the low-level driver underneath higher-level tools — Drizzle ORM ships a first-class postgres-js adapter, for example — as well as directly in application code that wants raw SQL without an ORM in between.

What You Get

• A connection pool with automatic reconnection, idle timeouts, and configurable max lifetime per connection
• Tagged-template queries (sql\…`) with automatic parameterization, plus .unsafe()` for raw SQL and dynamic query building helpers
• Transactions via sql.begin() with nested savepoint support and automatic rollback on thrown errors
• LISTEN/NOTIFY support and a subscribe() API implementing logical replication for real-time insert/update/delete streams
• Prepared statements, large object (largeObject) support, and a custom-type registration system for user-defined Postgres types
• Single codebase transpiled to Node.js (ESM + CJS), Deno, Bun, and Cloudflare Workers builds via transpile.*.js scripts

Common Use Cases

• Direct SQL in application code - teams that want typed, parameterized SQL without adopting a full ORM’s abstraction layer
• Driver underneath an ORM or query builder - projects using Drizzle ORM’s postgres-js adapter or similar tools that need a fast, dependency-free Postgres transport
• Real-time change feeds - services using sql.subscribe() against logical replication to react to row-level inserts/updates/deletes without polling
• Edge and serverless deployments - Cloudflare Workers or other constrained runtimes where a zero-dependency, small-footprint driver avoids bundling a large dependency tree
• Multi-runtime libraries - packages that need one Postgres client that behaves identically across Node.js, Deno, and Bun

Under The Hood

Architecture The library is organized around a small set of focused modules: index.js builds the sql tagged-template function and owns the connection-pool state machine (queues for connecting/open/busy/full/closed/reserved/ended connections, each a Queue from queue.js), connection.js (over 1,000 lines) implements the actual wire-protocol state machine — parsing and writing the Postgres binary message format via the tiny binary-builder in bytes.js — and dispatches to query.js, types.js, and subscribe.js for query lifecycle, type encode/decode, and logical-replication parsing respectively. Pool state transitions (move(c, queue)) are explicit and centralized, and higher-level features like begin() (transactions/savepoints) and reserve() (dedicated connections) are built as thin orchestration on top of the same connection/queue primitives rather than separate subsystems, which keeps one mental model for how a query ultimately reaches a socket.

Tech Stack Runtime dependencies are zero — the package.json declares no dependencies at all, only Node’s built-in net, tls, crypto, fs, os, and perf_hooks modules are used, meaning the wire protocol (startup, auth including SCRAM and MD5, simple/extended query, COPY, logical replication) is hand-implemented rather than delegated to a lower-level driver. Publishing is multi-target: transpile.cjs, transpile.deno.js, and transpile.cf.js each rewrite the ESM src/ tree into a CommonJS build, a Deno-compatible build, and a Cloudflare Workers (workerd) build, wired up via package.json’s exports map so consumers get the right build per runtime automatically. TypeScript users get hand-maintained .d.ts definitions under types/ rather than generated ones.

Code Quality Tests live in tests/index.js, a large single-file suite exercising real behavior against live Postgres instances (started via tests/bootstrap.js) rather than mocks, covering connection edge cases, all three auth methods, transactions/savepoints, LISTEN/NOTIFY, and type coercion; the same suite is re-run against the ESM, CJS, and Deno builds in CI. GitHub Actions runs the full matrix across nine Node versions (12 through 24) and six PostgreSQL versions (12 through 17) on every push, which is unusually thorough dependency-compatibility coverage for a library of this size. ESLint is configured and run as part of prepublishOnly, and error handling is explicit throughout — Postgres wire-level error fields are parsed into structured PostgresError objects with named properties (severity, code, detail, hint, position, etc.) rather than opaque strings.

What Makes It Unique Most Postgres clients in the Node ecosystem wrap libpq bindings or build on top of node-postgres; Postgres.js instead implements the wire protocol itself in plain JavaScript over raw sockets, which is what lets it ship with zero dependencies and run unmodified (after transpilation) on Deno, Bun, and Cloudflare Workers — runtimes where native bindings or node-postgres’s Node-specific assumptions don’t work. Combining that with first-class tagged-template query syntax, built-in logical-replication subscriptions, and savepoint-aware nested transactions in one cohesive API, rather than layering these as separate add-on packages, is the project’s distinguishing design choice.