Alexandro.Net

Version 1.0.4

@stackline/pg

Maintained, dependency-reviewed PostgreSQL client compatible with pg 8.23.0

Installation

npm install @stackline/pg@1.0.4

Node.js: >=16. Read the compatibility and maintenance notes before migrating.

Usage and API

@stackline/pg

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

npm version license GitHub repository Docs Reddit community

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

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:

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

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.

Migration

Migration

No Source Changes

Replace the dependency with an npm alias:

npm install pg@npm:@stackline/pg

Existing imports remain unchanged:

const { Pool } = require('pg')

import { Pool } from 'pg'

Scoped Imports

New applications may install and import the scoped package directly:

npm install @stackline/pg

import { Pool } from '@stackline/pg'

Optional Native Adapter

The default package is pure JavaScript. Applications that deliberately use pg.native must install a compatible pg-native themselves. This keeps the native adapter and its separate dependency graph outside the default install.

Compatibility

Compatibility

Baseline

@stackline/pg@1.0.0 tracks the public runtime contract of pg@8.23.0 from upstream source commit c9e57617bc92c2ded23a75345f50eadc527bd131.

The lib and esm runtime implementation is unchanged. Stackline changes are limited to dependency routing, package metadata, tests, documentation, and release controls.

Preserved Contracts

Runtime Support

Node.js 16 and newer are release-gated. PostgreSQL integration tests run against PostgreSQL 18. Applications may use older supported PostgreSQL server versions according to the upstream protocol compatibility contract.

No TypeScript declarations were exposed by pg@8.23.0, so this fork does not invent a competing declaration surface. Existing applications can continue using the community @types/pg package.

Security review

PostgreSQL authentication and TLS review

Reviewed on 2026-09-28 for the 1.0.2 dependency-maintenance release. Runtime authentication and TLS code is unchanged from the preceding release. The maintainer approved the specific dispositions below; this document does not claim that disabling certificate validation or MD5 authentication is secure.

Alerts 4 and 5: explicitly disabled certificate validation

lib/connection-parameters.js constructs {rejectUnauthorized: false} only after the application supplies ssl: 'no-verify', a connection-string equivalent, or the deployment environment supplies PGSSLMODE=no-verify. These are explicit insecure compatibility settings. The parsed options pass through Connection.upgradeToSSL into stream.getSecureStream, which calls Node's tls.connect.

With ssl: true, a normal SSL options object, or environment modes prefer, require, verify-ca, and verify-full, these branches do not turn validation off. Node's rejectUnauthorized default remains true. TLS itself is off when no setting enables it; this client does not claim encrypted connections by default. Untrusted connection strings or environment configuration must not be accepted as application input.

Approved classification: accepted, explicit insecure compatibility option (won't fix). The warning describes a real risk if the option is selected, so neither “used in tests” nor a blanket “false positive” would describe these runtime branches accurately. Removing the option would break the retained pg API. SECURITY.md already explains the impersonation risk and recommends a trusted CA with certificate verification enabled.

Alert 6: PostgreSQL MD5 challenge response

Client._handleAuthMD5Password runs in response to the server's authenticationMD5Password message. It calls postgresMd5PasswordHash(user, password, salt) and sends the result using connection.password. This is the legacy PostgreSQL wire-protocol response, not a password-storage KDF. The calculation is dictated by the server challenge and cannot be replaced unilaterally by a slower digest or another algorithm. The SASL/SCRAM path is separate.

Approved classification: false positive for insufficient password-storage hashing. This does not dismiss the limitations of the legacy protocol: PostgreSQL deprecates MD5 authentication and recommends migration to SCRAM-SHA-256. The client retains interoperable legacy behavior while SECURITY.md recommends server-side migration. No password database is created by this helper.

Verification

npm run test:security-contract checks the actual option path into the TLS stream factory for normal and explicit no-verify configurations, environment/config precedence, hostname forwarding, and an independent fixed MD5 challenge vector. These tests do not make a live database TLS connection; the supported PostgreSQL/Node integration matrix and existing upstream SSL/authentication tests run separately in CI. The test restores all process environment and stream hooks. Source and runtime files remain in CodeQL analysis; no rule/path exclusions, hidden warnings, or runtime rewrites were introduced to silence the scanner.

Release changes

Changelog

1.0.2 - 2026-09-28

[1.0.1] - 2026-09-28

@stackline/pg 1.0.0 - 2026-08-30

Upstream History

All major and minor upstream releases are briefly explained below.

For richer information consult the commit log on github with referenced pull requests.

We do not include break-fix version release in this file.

pg@8.23.0

pg@8.22.0

pg@8.21.0

pg@8.20.0

pg@8.19.0

pg@8.18.0

pg@8.17.0

pg@8.16.0

pg@8.15.0

pg@8.14.0

pg@8.13.0

pg@8.12.0

pg-pool@8.10.0

pg@8.9.0

pg@8.8.0

pg-pool@3.5.0

pg@8.7.0

pg-cursor@2.7.0

pg@8.6.0

pg-query-stream@4.0.0

pg@8.5.0

pg@8.4.0

pg@8.3.0

pg@8.2.0

pg-cursor@2.2.0

pg-query-stream@3.1.0

pg@8.1.0

pg-pool@3.2.0

pg-pool@3.1.0

pg@8.0.0

note: for detailed release notes please check here

pg@7.18.0

pg-query-stream@3.0.0

pg@7.17.0

7.16.0

7.15.0

7.14.0

7.13.0

7.12.0

7.11.0

7.10.0

7.9.0

7.8.0

7.7.0

7.6.0

7.5.0

7.4.0

7.3.0

7.2.0

7.1.0

Enhancements

7.0.0

Breaking Changes

Please see here for a migration guide

Enhancements

v6.2.0

v6.1.0

v6.0.0

Breaking Changes

New features

You can now create an instance of a pool and don't have to rely on the pg singleton for anything:

var pg = require('pg')

var pool = new pg.Pool()

// your friendly neighborhood pool interface, without the singleton
pool.connect(function(err, client, done) {
  // ...
})

Promise support & other goodness lives now in pg-pool.

Please read the readme at pg-pool for the full api.

var client = new Client({ keepAlive: true })

This should help with backends incorrectly considering idle clients to be dead and prematurely disconnecting them.

v5.1.0

Example:

var client = new Client()
client.connect()
client.query('SELECT $1::text as name', ['brianc']).then(function (res) {
  console.log('hello from', res.rows[0])
  client.end()
})

v5.0.0

Breaking Changes

New Features

v4.5.0

v4.4.0

v4.3.0

v4.2.0

v4.1.0

v4.0.0

v3.6.0

v3.5.0

v3.4.0

v3.2.0

v3.1.0

v3.0.0

Breaking changes

After some discussion it was decided node-postgres was non-compliant in how it was handling DATE results. They were being converted to UTC, but the PostgreSQL documentation specifies they should be returned in the client timezone. This is a breaking change, and if you use the date type you might want to examine your code and make sure nothing is impacted.

pg@v2.0 included changes to not convert large integers into their JavaScript number representation because of possibility for numeric precision loss. The same types in arrays were not taken into account. This fix applies the same type of type-coercion rules to arrays of those types, so there will be no more possible numeric loss on an array of very large int8s for example. This is a breaking change because now a return type from a query of int8[] will contain string representations of the integers. Use your favorite JavaScript bignum module to represent them without precision loss, or punch over the type converter to return the old style arrays again.

Single date parameters were properly sent to the PostgreSQL server properly in local time, but an input array of dates was being changed into utc dates. This is a violation of what PostgreSQL expects. Small breaking change, but none-the-less something you should check out if you are inserting an array of dates.

This is a small change to bring the semantics of query more in line with other EventEmitters. The tests all passed after this change, but I suppose it could still be a breaking change in certain use cases. If you are doing clever things with the end and error events of a query object you might want to check to make sure its still behaving normally, though it is most likely not an issue.

New features

The long & short of it is now any object you supply in the list of query values will be inspected for a .toPostgres method. If the method is present it will be called and its result used as the raw text value sent to PostgreSQL for that value. This allows the same type of custom type coercion on query parameters as was previously afforded to query result values.

If domains are active node-postgres will honor them and do everything it can to ensure all callbacks are properly fired in the active domain. If you have tried to use domains with node-postgres (or many other modules which pool long lived event emitters) you may have run into an issue where the active domain changes before and after a callback. This has been a longstanding footgun within node-postgres and I am happy to get it fixed.

Avoids a scenario where your pool could fill up with disconnected & unusable clients.

To provide better documentation and a clearer explanation of how to override the query result parsing system we broke the type converters into their own module. There is still work around removing the 'global-ness' of the type converters so each query or connection can return types differently, but this is a good first step and allow a lot more obvious way to return int8 results as JavaScript numbers, for example

v2.11.0

v2.10.0

v2.9.0

v2.8.0

v2.7.0

v2.6.0

v2.5.0

v2.4.0

v2.3.0

v2.2.0

v2.1.0

v2.0.0

PostgreSQL | pg@v2.0 JavaScript | pg@v1.0 JavaScript
--------------------------------|----------------
float4     | number (float)     | string
float8     | number (float)     | string
int8       | string             | number (int)
numeric    | string             | number (float)
decimal    | string             | number (float)

For more information see https://github.com/brianc/node-postgres/pull/353 If you are unhappy with these changes you can always override the built in type parsing fairly easily.

v1.3.0

v1.2.0

v1.1.0

v1.0.0

v0.15.0

v0.14.0

Release files and references

Package bytes, npm provenance and the immutable GitHub release were verified for this version. Security checks describe the reviewed release; documented compatibility risks and upstream reports are not blanket claims of resolution.