postgres-pool

library11.0.4jsnpmunverified

postgres-pool is a robust connection pooling library for Node.js applications designed to interact with PostgreSQL databases via the `node-pg` client. As of its current stable version, 11.0.4, it offers an actively maintained and feature-rich alternative to the original `pg-pool`, addressing specific reliability concerns such as connection timeouts that were observed in its predecessor. The library features enhanced error handling, graceful cluster failover mechanisms, and streamlined integration with AWS RDS through a simplified `ssl='aws-rds'` configuration option for secure connections. It adheres to a modern development paradigm, being built with TypeScript to enforce type safety and primarily utilizing Promises, moving away from callback-based patterns. The project typically sees frequent patch releases and major version increments roughly annually, with a significant v11 update in late 2025 transitioning `pg` to a peer dependency. It strives for API compatibility with `pg-pool` to ease migration for existing users.

database http-networking aws type-stubs

npm install postgres-pool

github ↗package ↗

INSTALL

IMPORT

SIG · POSTGRES-POOL

postgres-pool

databasejavascriptv11.0.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Pool

✓ import { Pool } from 'postgres-pool';

✗ const { Pool } = require('postgres-pool');

The library primarily uses ES Modules. For CommonJS environments, ensure proper transpilation or use dynamic import.

PoolClient

✓ import { Pool, PoolClient } from 'postgres-pool';

✗ import { Client } from 'pg';

PoolClient is the type returned by `pool.connect()`. Do not confuse it with `pg`'s raw `Client` type, though they are compatible.

QueryResult

✓ import { QueryResult } from 'pg';

✗ import { QueryResult } from 'postgres-pool';

While `postgres-pool` returns `QueryResult`, the type definition is re-exported from the underlying `pg` package.

Demonstrates initializing a PostgreSQL connection pool and executing a simple SELECT query with automatic connection release, including error handling and graceful shutdown.

import { Pool } from 'postgres-pool'; // Use environment variables for sensitive connection details in production. // For local development, replace with your actual database credentials. const pool = new Pool({ connectionString: process.env.DATABASE_URL ?? 'postgres://username:pwd@127.0.0.1/db_name', max: 20, // max number of clients in the pool idleTimeoutMillis: 30000, // how long a client is allowed to remain idle before being closed }); async function getUser(userId: number) { try { const results = await pool.query('SELECT id, name, email FROM "users" WHERE id=$1', [userId]); if (results.rows.length > 0) { console.log('User found:', results.rows[0]); return results.rows[0]; } else { console.log('User not found.'); return null; } } catch (err) { console.error('Error executing query', err); throw err; } } // Example usage: getUser(42); // Ensure the pool is gracefully shut down when the application exits process.on('SIGINT', async () => { console.log('Shutting down database pool...'); await pool.end(); console.log('Database pool shut down.'); process.exit(0); });

Debug

Known issues

breakingStarting with v11.0.0, `pg` is no longer a direct runtime dependency but a peer dependency. Users must explicitly install `pg` alongside `postgres-pool`.

fix

Run `npm install pg postgres-pool` (or `yarn add pg postgres-pool`) to ensure `pg` is installed.

affects: >=11.0.0

gotchaWhen manually acquiring a client using `await pool.connect()`, it is crucial to call `await client.release()` in a `finally` block to return the client to the pool. Failure to do so will exhaust the pool and lead to application freezes.

fix

Always wrap `pool.connect()` usage in a `try...finally` block to guarantee `client.release()` is called: `const client = await pool.connect(); try { /* ... */ } finally { await client.release(); }`

affects: >=1.0.0

gotchaThe library explicitly states a Node.js engine requirement of `>=20.11.0`. Running on older Node.js versions may lead to unexpected behavior or compatibility issues.

fix

Ensure your Node.js environment meets the minimum version requirement. Upgrade Node.js if necessary.

affects: >=11.0.0

gotchaThis library was created to address specific connection timeout and stability issues found in the `pg-pool` library. If you are experiencing such issues with `pg-pool`, consider migrating to `postgres-pool`.

fix

Review the documentation and examples for `postgres-pool` and adapt your application's database interaction layer. The API is designed to be largely compatible with `pg-pool` options.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'pg' or its corresponding type declarations.

The `pg` package, which provides the underlying PostgreSQL client, is a peer dependency of `postgres-pool` since v11.0.0 and must be installed separately.

fix

Run `npm install pg` (or `yarn add pg`) in your project directory.

Error: self-signed certificate in certificate chain

This error typically indicates an issue with SSL/TLS configuration, often when connecting to a database that uses a custom or self-signed certificate, or when the client does not trust the server's certificate authority.

fix

For AWS RDS, use `ssl: 'aws-rds'` in your pool configuration. For other custom setups, provide `ssl` options like `rejectUnauthorized: false` (for testing, not recommended for production) or `ca: fs.readFileSync('/path/to/ca.pem')` for custom CAs.

Error: Client has already been released.

You are attempting to use a `PoolClient` instance after it has been explicitly returned to the connection pool via `client.release()`.

fix

Ensure that any operations performed with a `PoolClient` are completed before `client.release()` is called. Structure your code with `try...finally` to guarantee release and avoid using the client outside that block.

Upgrade

Version history

11.0.4latest on npm

Audit

Dependencies

pgrequiredRequired runtime dependency for PostgreSQL client functionality. Made a peer dependency in v11.0.0.

Agent activity

19 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/postgres-pool/postgres-pool ↗

packagehttps://www.npmjs.com/package/postgres-pool ↗