pg-pool is a specialized connection pooling library for Node.js applications using `node-postgres` to interact with PostgreSQL databases. Currently stable at version 3.13.0, it is actively maintained as part of the `node-postgres` family, with releases typically aligning with updates to the core `pg` client. This library is designed to improve application performance and reliability by managing a set of reusable database connections, thus reducing the overhead of repeatedly establishing and tearing down connections. Key features include configurable connection limits (`max`), idle timeouts (`idleTimeoutMillis`), connection establishment timeouts (`connectionTimeoutMillis`), and the ability to replace connections after a certain number of uses (`maxUses`). A crucial differentiator from some other database clients is that `pg-pool` does not directly accept a database URL string; instead, developers must parse the URL into a configuration object before passing it to the Pool constructor. It offers a modern, promise-based API that integrates smoothly with `async/await` patterns, simplifying resource management (client acquisition and release) compared to manual connection handling. It also supports pooling both the standard `pg.Client` and `pg.native.Client` instances.
npm install pg-poolVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to initialize `pg-pool` by parsing a database URL, acquire and release clients using `async/await`, and use the convenient `pool.query` helper, along with proper error handling and pool shutdown.
Use `const { URL } = require('url');` to parse your `process.env.DATABASE_URL` into a configuration object with `user`, `password`, `host`, `port`, and `database` properties.Monitor connection metrics and client acquisition times if `maxUses` is enabled. Adjust the value based on your application's workload and desired connection lifetime.
Ensure `pg` is installed in your project: `npm install pg`. Check your `package.json` for compatible versions of `pg` as specified by `pg-pool`'s peer dependency.
Always ensure `client.release()` is called in a `finally` block when acquiring clients manually with `pool.connect()`. Consider using the `pool.query()` helper method for simple queries, as it automatically acquires and releases the client.
Configure SSL explicitly. Use `ssl: true` for default behavior, and consider `ssl: { rejectUnauthorized: false }` only when absolutely necessary for self-signed certificates in development or tightly controlled environments. For production, ensure your database provides trusted certificates and enable `rejectUnauthorized: true`.Verify that the PostgreSQL server is running and listening on the specified host and port (default 5432). Check firewall rules and ensure the database user has network access.
Ensure every `pool.connect()` call is paired with a `client.release()` call, typically within a `try...finally` block to guarantee release even if errors occur.
For CommonJS, use `const Pool = require('pg-pool')`. For ESM, use `import Pool from 'pg-pool'`.Review your `pg-pool` configuration object. Ensure all mandatory properties are present and their values are of the correct type (e.g., strings for `user`, `password`, `host`, `database`, number for `port`). Double-check your URL parsing logic if using `process.env.DATABASE_URL`.