@stackline/pg

Maintained, dependency-reviewed PostgreSQL client compatible with pg 8.23.0.

Documentation | npm | Issues | Repository

Current package version: 1.0.4

Why this package?

A maintained, dependency-reviewed PostgreSQL client compatible with the public API of pg@8.23.0.

This package preserves node-postgres behavior while replacing the archived pg-types -> postgres-interval -> xtend branch with reviewed Stackline forks. It is an independent fork of the MIT-licensed brianc/node-postgres project and is not affiliated with or endorsed by its maintainers.

Compatibility

Item	Value
Package	`@stackline/pg@1.0.4`
Node.js runtime	`>=16`
CommonJS / primary entry	`./lib`

API baseline: pg@8.23.0.
Node.js: 16 and newer.
CommonJS, ESM, callbacks, promises, pools, notifications, COPY extensions, custom type parsers, SSL, SCRAM, and deep pg/lib/* exports are preserved.
pg-native remains available through the historical lazy pg.native API when the application installs it explicitly. It is not auto-installed.

The original package documentation is retained in UPSTREAM_README.md. See COMPATIBILITY.md and MIGRATION.md for the exact contract.

Installation

Install

Use the scoped name in new code:

Usage

npm install @stackline/pg

const { Client, Pool } = require('@stackline/pg')

Keep existing pg imports without source changes:

npm install pg@npm:@stackline/pg

const { Client, Pool } = require('pg')

Both CommonJS and ESM are supported:

import pg, { Client, Pool } from '@stackline/pg'

Quick Start

const { Pool } = require('@stackline/pg')

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
})

const result = await pool.query('select $1::text as message', ['hello'])
console.log(result.rows[0].message)
await pool.end()

Transactions must use one checked-out client:

const client = await pool.connect()
try {
  await client.query('BEGIN')
  await client.query('insert into events(name) values($1)', ['created'])
  await client.query('COMMIT')
} catch (error) {
  await client.query('ROLLBACK')
  throw error
} finally {
  client.release()
}

Security

TLS is disabled unless configured. For remote databases, enable verified TLS with ssl: true or a trusted CA in the ssl options. The explicit no-verify options disable certificate validation. Prefer server-side SCRAM-SHA-256 authentication over legacy MD5. See the connection security guidance for configuration details and vulnerability reporting.

Local Development

git clone https://github.com/alexandroit/stackline-pg.git
cd stackline-pg
npm ci
npm run verify

Release tooling uses Node.js 24.20.0 and npm 11.19.0. The consumer runtime contract remains the one documented above.

Consumer Smoke Test

Run the repository's existing consumer/package check after installing development dependencies:

npm run test:smoke

Release Checklist

Dependency Integrity

Every runtime edge is pinned and reviewed recursively. Release gates install the packed artifact in empty projects under the scoped and legacy names and require:

no npm warnings or deprecation notices;
a valid npm ls --all --omit=dev tree;
zero npm audit --omit=dev findings;
zero source-workspace audit findings;
working CommonJS and ESM imports;
the complete upstream unit and PostgreSQL integration suites.

The current closure and review rationale are recorded in DEPENDENCY_REVIEW.md. Security reports belong in GitHub private vulnerability reporting; see SECURITY.md.

Run npm run verify and inspect the package contents before release. Publish a new version through the GitHub Actions publishing workflow, using the SHA-512 digest of the reviewed tarball. Verify the exact published version, tarball integrity, and npm provenance after the run.

License

MIT. The original copyright and license are preserved in LICENSE, with attribution in NOTICE and dependency notices in THIRD_PARTY_LICENSES.md.

Dependency maintenance for this release is documented in DEPENDENCY_UPDATES.md.

Maintenance and compatibility notes

PostgreSQL protocol compatibility retains legacy MD5 authentication and configurable TLS behavior. Explicitly configure TLS verification for remote database connections; opting out of certificate verification remains a documented compatibility option.

Credits and original authors

Stackline Maintainers.
Brian M. Carlson.
Stackline maintenance: Alexandro Paixao Marques and Stackline contributors.

Original copyright, license notices and contributor acknowledgements remain part of this distribution. Stackline maintenance does not replace authorship of the original work.

Community and Links

Use this repository's issue tracker for reproducible bugs and feature requests. Join r/Stackline for examples, usage questions and release discussions.