Onboarding: brianc/node-postgres

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/brianc/node-postgres shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

GO — Healthy across the board

• Last commit 6d ago
• 32+ active contributors
• Distributed ownership (top contributor 38% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live brianc/node-postgres repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/brianc/node-postgres.

What it runs against: a local clone of brianc/node-postgres — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in brianc/node-postgres | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 36 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>brianc/node-postgres</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of brianc/node-postgres. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/brianc/node-postgres.git
#   cd node-postgres
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of brianc/node-postgres and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "brianc/node-postgres(\\.git)?\\b" \\
  && ok "origin remote is brianc/node-postgres" \\
  || miss "origin remote is not brianc/node-postgres (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "package.json" \\
  && ok "package.json" \\
  || miss "missing critical file: package.json"
test -f "lerna.json" \\
  && ok "lerna.json" \\
  || miss "missing critical file: lerna.json"
test -f ".github/workflows/ci.yml" \\
  && ok ".github/workflows/ci.yml" \\
  || miss "missing critical file: .github/workflows/ci.yml"
test -f "packages/pg-connection-string/index.js" \\
  && ok "packages/pg-connection-string/index.js" \\
  || miss "missing critical file: packages/pg-connection-string/index.js"
test -f "packages/pg-cursor/index.js" \\
  && ok "packages/pg-cursor/index.js" \\
  || miss "missing critical file: packages/pg-cursor/index.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 36 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~6d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/brianc/node-postgres"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

node-postgres is a mature PostgreSQL client library for Node.js that provides both a pure JavaScript implementation and optional native libpq bindings under a unified API. It handles connection pooling, parameterized queries, prepared statements, LISTEN/NOTIFY, and COPY operations, making it the standard way to interact with PostgreSQL from Node.js applications. Monorepo with 7 focused packages under packages/: pg (main client), pg-pool (connection pooling), pg-native (C++ bindings), pg-cursor (cursor iteration), pg-query-stream (streaming queries), pg-connection-string (URI parsing), pg-protocol (wire protocol). Documentation lives in docs/ as a Next.js site using Nextra. CI configured in .github/workflows/ci.yml.

Who it's for

Backend JavaScript/TypeScript developers building Node.js applications that need to query PostgreSQL databases. This includes Express.js developers, API builders, and teams migrating from callback-based to async/await database patterns. Contributors are typically PostgreSQL enthusiasts and Node.js library maintainers.

Maturity & risk

Highly mature and production-ready. The monorepo structure with 7 core packages (pg, pg-pool, pg-native, pg-cursor, pg-query-stream, pg-connection-string, pg-protocol) indicates years of stable development. Active CI/CD setup in .github/workflows/ci.yml, comprehensive docs in docs/ directory, and clear maintenance pattern suggest ongoing support. This is the de-facto standard PostgreSQL driver for Node.js.

Standard open source risks apply.

Active areas of work

Based on the file structure, active focus areas include: maintaining documentation with Next.js/Nextra (docs/pages/* show comprehensive feature docs for pooling, transactions, SSL, ESM support), establishing dev container setup (.devcontainer/), and managing monorepo dependencies through Yarn. The repo has CHANGELOG.md and SPONSORS.md indicating ongoing releases and community support.

Get running

git clone https://github.com/brianc/node-postgres.git && cd node-postgres && yarn install && yarn workspaces run test

Daily commands: Development: From docs/ directory: yarn dev (runs Next.js doc server on http://localhost:3000). From packages/pg: yarn test runs the test suite. Full setup: yarn install at root, then yarn workspaces run build to compile all packages.

Map of the codebase

• package.json — Root monorepo configuration defining all workspace packages (pg, pg-pool, pg-native, pg-cursor, pg-query-stream, pg-connection-string) and their dependencies.
• lerna.json — Lerna monorepo configuration managing package versioning, publishing, and workspace orchestration across the PostgreSQL client ecosystem.
• .github/workflows/ci.yml — CI/CD pipeline defining test, build, and release workflows for all packages in the monorepo.
• packages/pg-connection-string/index.js — Core connection string parser used across all pg packages to normalize PostgreSQL connection URIs into config objects.
• packages/pg-cursor/index.js — Cursor abstraction for streaming large result sets, a critical feature for memory-efficient bulk operations.
• docs/next.config.js — Documentation site configuration using Nextra, serving as the primary reference for users of all pg packages.
• LOCAL_DEV.md — Developer onboarding guide explaining monorepo setup, testing, and contribution workflow for this complex multi-package project.

Components & responsibilities

• pg (Core Client) (Node.js Streams, PostgreSQL wire protocol, optional libpq bindings) — Manages single PostgreSQL connection lifecycle: parsing connection strings, sending queries, handling results and errors.
  • Failure mode: Connection loss, query timeout, authentication failure → errors propagated to callback or rejected Promise.
• **** — undefined

How to make changes

Add a new feature to the core pg client

1. Add TypeScript types and implementation in packages/pg/lib/ (packages/pg/lib/[feature-name].js)
2. Export the feature from packages/pg/index.js (packages/pg/index.js)
3. Write tests in packages/pg/test/ (packages/pg/test/[feature-name].js)
4. Document the feature in docs/pages/apis/client.mdx (docs/pages/apis/client.mdx)
5. Update CHANGELOG.md with the new feature (CHANGELOG.md)

Add a new utility package to the monorepo

1. Create new directory packages/pg-[name]/ with package.json following existing pattern (packages/pg-[name]/package.json)
2. Create main entry point with dual ESM/CJS support (packages/pg-[name]/index.js)
3. Add package to root lerna.json (if not auto-detected) (lerna.json)
4. Create test suite in packages/pg-[name]/test/ (packages/pg-[name]/test/index.js)
5. Document in docs/pages/apis/ and link from index (docs/pages/apis/[name].mdx)

Improve documentation for an existing API

1. Update the relevant API reference page in docs/pages/apis/ (docs/pages/apis/[api-name].mdx)
2. Add example code with real-world use case (docs/pages/guides/[guide-name].md)
3. Cross-link from related API pages (docs/pages/apis/client.mdx)
4. Build and test locally with 'yarn dev' in docs/ (docs/package.json)

Why these technologies

• Monorepo (Lerna + Yarn Workspaces) — Manages interdependent packages (pg, pg-pool, pg-cursor, pg-native, pg-query-stream) with shared dependencies and coordinated versioning/releases.
• Pure JavaScript + Optional Native Bindings — Provides portability across platforms (Windows, macOS, Linux, Cloudflare Workers) while allowing native libpq for performance-critical deployments.
• Nextra Documentation — Next.js-based docs enable dynamic examples, live API references, and guides integrated with the codebase.
• Cursor/Stream Abstractions — Handles memory-efficient processing of large result sets without loading entire datasets into memory.

Trade-offs already made

• Pure JavaScript implementation by default

  • Why: Maximizes compatibility across platforms (including serverless, edge runtimes) without native compilation overhead.
  • Consequence: Slightly slower throughput than native libpq; users must opt-in to native bindings for performance-critical workloads.

• Multiple sub-packages instead of monolithic library

  • Why: Allows incremental adoption (use pg-cursor separately, use pg-pool independently) and reduces bundle size for minimal setups.
  • Consequence: Increased complexity in monorepo management and requires coordination across package versions.

• Dual CJS + ESM module exports

  • Why: Supports both legacy CommonJS Node.js projects and modern ESM bundlers (webpack, esbuild, vite, rollup).
  • Consequence: Requires maintaining two export formats and testing across bundler ecosystems.

Non-goals (don't propose these)

• Real-time subscriptions or LISTEN/NOTIFY abstraction (users implement directly via client.query)
• ORM functionality (intentionally left to libraries like Prisma, TypeORM, Sequelize)
• Connection failover/replication (scope is single-instance clients; load balancing delegated to infrastructure)
• Authentication beyond PostgreSQL native auth (no SASL abstractions; delegated to DB server)

Traps & gotchas

PostgreSQL version compatibility matrix: CI likely tests against multiple PG versions; check .github/workflows/ci.yml for required versions. Native bindings (pg-native) require Python and compiler toolchain at install time—may fail on restricted environments. Connection string parsing is delegated to pg-connection-string package, so URI edge cases are isolated there. Type parsing is extensible but has default mappings that may surprise (e.g., numeric types, JSON). Monorepo workspace interdependencies require yarn install at root, not per-package.

Architecture

Concepts to learn

• PostgreSQL Wire Protocol (Frontend/Backend) — Understanding the binary message format in packages/pg-protocol is essential for debugging connection issues and understanding why certain queries fail at the protocol level, not the SQL level
• Connection Pooling & Resource Contention — pg-pool manages a finite set of connections; understanding pool saturation, idle timeout, and queue behavior is critical for production stability in high-concurrency applications
• Prepared Statements & Query Plan Caching — node-postgres uses extended query protocol with named statements; understanding when plans are cached vs. re-planned affects performance in high-throughput workloads
• Type Coercion & Custom Parsers — The extensible type system (packages/pg/lib/types.js) allows overriding default JSON, numeric, array parsing; misconfiguration here leads to silent type errors
• LISTEN/NOTIFY Asynchronous Messaging — PostgreSQL's pub/sub feature exposed through node-postgres; different from query-response and requires understanding connection state to avoid blocking the event loop
• COPY Protocol (Bulk Import/Export) — High-performance bulk data transfer uses a distinct wire protocol; node-postgres abstracts this but understanding streaming vs. buffering is key for large datasets
• Native vs. Pure JavaScript Bindings Trade-off — pg-native uses libpq C bindings for performance but adds compilation complexity; pg core is pure JS for portability; choosing between them affects installation friction and performance characteristics

Related repos

• brianc/node-pg-migrate — SQL migration tool designed specifically to work with node-postgres for schema versioning
• vitaly-t/pg-promise — Alternative PostgreSQL client for Node.js with promise-first API and query result validation
• Narative/simple-graphql-to-sql — GraphQL-to-SQL transpiler often used with node-postgres for API builders
• graphql/graphql-js — Ecosystem companion; many Node.js GraphQL servers use node-postgres as their database layer
• typeorm/typeorm — TypeORM ORM builds on node-postgres for type-safe database access in TypeScript projects

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add missing documentation for pg-cloudflare package in docs site

The repo contains packages/pg-cloudflare with a README.md, but there's no corresponding documentation page in docs/pages/apis or docs/pages/features. This package appears to be a significant offering (Cloudflare Workers support) but is completely undocumented in the main documentation site. Adding a dedicated guide would help users discover and understand how to use pg with Cloudflare.

• [ ] Create docs/pages/apis/cloudflare.mdx documenting the pg-cloudflare module
• [ ] Add entry to docs/pages/apis/_meta.js to include cloudflare in navigation
• [ ] Document setup instructions, connection patterns, and example usage for Cloudflare Workers
• [ ] Reference the pg-cloudflare/README.md content and expand with getting-started examples

Add bundler compatibility tests to CI workflow

The repo contains packages/pg-bundler-test with configs for esbuild, rollup, vite, and webpack, but the .github/workflows/ci.yml doesn't appear to run these bundler tests. This is critical infrastructure validation that should run automatically on PRs to catch bundling regressions early.

• [ ] Review packages/pg-bundler-test/package.json to identify available test scripts
• [ ] Extend .github/workflows/ci.yml to add a job that runs bundler tests for esbuild, rollup, vite, and webpack
• [ ] Ensure bundler tests run against all Node.js versions being tested
• [ ] Add clear failure messaging to indicate which bundler configuration failed

Document LOCAL_DEV.md environment setup for devcontainer approach

The repo has .devcontainer configuration (Dockerfile, docker-compose.yml) showing commitment to containerized development, but LOCAL_DEV.md likely only documents native setup. New contributors should have clear guidance on using the devcontainer. Add a documented workflow for setting up the monorepo using the existing devcontainer.

• [ ] Add section to LOCAL_DEV.md for devcontainer setup instructions
• [ ] Document how to open repo in VS Code with devcontainer plugin
• [ ] Explain how to run packages/pg tests, packages/pg-pool tests, and docs from within devcontainer
• [ ] Add troubleshooting section for common devcontainer issues (e.g., PostgreSQL service connectivity)

Good first issues

• Add TypeScript type tests for the pg-protocol package (packages/pg-protocol/src/ exports wire-level types that could use explicit test coverage to prevent regression in message serialization)
• Expand docs/pages/features/ with a new guide on handling PostgreSQL arrays and composite types—the docs cover basic querying but the type coercion system supports advanced patterns that aren't documented
• Create integration test examples in packages/pg for LISTEN/NOTIFY patterns with error handling—the feature is mentioned in README but no runnable example exists for transient connection failure scenarios

Top contributors

• @brianc — 38 commits
• @dependabot[bot] — 10 commits
• @charmander — 9 commits
• @nigrosimone — 6 commits
• @hjr3 — 6 commits

Recent commits

• 341cb60 — docs: Fix changelog entry’s spelling (charmander)
• 77cb771 — remove deprecated 'version' attribute from docker-compose.ymla (#3660) (The-Alchemist)
• 4e6bdf0 — Update Medplum logo in README (#3659) (The-Alchemist)
• c78b302 — Cleanup tests (#3640) (brianc)
• e7fa94a — Update the sub-readme (#3638) (brianc)
• 32ec730 — Update readme text slightly (#3637) (brianc)
• 412dc88 — Don't encourage people to use on('connect') for setup anymore (#3623) (danieldiekmeier)
• c6028a8 — Docs updates (#3622) (brianc)
• c9070cc — Publish (brianc)
• 1c8c710 — Update changelog (brianc)

Security observations

The node-postgres repository demonstrates good security hygiene overall with CI/CD automation, monorepo structure, and documentation. However, several areas require attention: (1) Dependency management could be stricter with more conservative version pinning; (2) Security documentation and advisories are not prominent; (3) DevContainer configurations should be reviewed for credential leaks; (4) The Next.js documentation site should explicitly configure security headers; (5) As a database client library, security best practices for parameterized queries should be emphasized throughout documentation. No critical vulnerabilities were identified based on visible file structure, but code-level review of SQL query handling is recommended.

• Medium · Next.js Documentation Site with Permissive Dependencies — docs/package.json. The docs package uses Next.js and Nextra with caret (^) version constraints, allowing automatic minor and patch version updates. Next.js 13.5.x and related dependencies may receive updates with security patches that could be missed if automatic updates are not configured in CI/CD. Fix: Consider using more restrictive version pinning (e.g., ~13.5.11) or implement automated dependency scanning and update processes. Monitor security advisories for Next.js, Nextra, React, and related packages.
• Low · Potential SQL Injection Risk in PostgreSQL Client — packages/pg and related core modules. As a PostgreSQL client library, the node-postgres package handles SQL queries. While the library itself appears to support parameterized queries (which mitigate SQL injection), applications using this library must be carefully coded to avoid SQL injection vulnerabilities if raw string concatenation is used instead of parameterized queries. Fix: Ensure all documentation and examples prominently feature parameterized queries (using $1, $2, etc. placeholders). Provide security guidelines in README and docs. Consider adding linting rules or TypeScript types that encourage safe query construction.
• Low · DevContainer Configuration Exposure — .devcontainer/docker-compose.yml, .devcontainer/Dockerfile. The .devcontainer directory contains Docker and compose configuration files that may inadvertently expose port mappings, environment variables, or other sensitive development settings to repository history. Fix: Review DevContainer configurations to ensure no hardcoded credentials, secrets, or overly permissive port exposures. Use .devcontainer/.gitignore to exclude sensitive local overrides. Document security best practices for contributors.
• Low · Missing Security Headers in Documentation Site — docs/next.config.js. The Next.js documentation site (docs/) does not show evidence of configured security headers (CSP, X-Frame-Options, HSTS, etc.) in next.config.js or similar configuration files that were visible in the file listing. Fix: Configure Next.js security headers in next.config.js using the headers() function to set Content-Security-Policy, X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Strict-Transport-Security, and other relevant security headers.
• Low · No Evidence of CHANGELOG Security Advisories Section — CHANGELOG.md. While CHANGELOG.md exists, there is no visible section documenting security advisories or vulnerability disclosures, which is important for a widely-used database client library. Fix: Add a 'Security Advisories' section to CHANGELOG.md documenting all security fixes with CVSS scores where applicable. Consider adding a SECURITY.md file with vulnerability disclosure policy and contact information.
• Low · Dependabot Configuration May Be Incomplete — .github/dependabot.yaml. While .github/dependabot.yaml exists, without viewing its contents, it's unclear if it is configured to alert on security vulnerabilities for all packages in the monorepo (pg, pg-pool, pg-native, pg-connection-string, etc.). Fix: Verify Dependabot is configured to scan security vulnerabilities for all workspace packages. Enable alerts for high/critical severity. Ensure automerge is restricted to low-risk patches only.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.