pg-promise is a PostgreSQL interface for Node.js that wraps the base node-postgres driver with promise-based abstractions and advanced query handling.
The library solves the problem of managing database connections and transactions in Node.js applications by providing automatic connection pooling and transaction handling on top of node-postgres. It adds a powerful query-formatting engine that supports index variables, named parameters, nested parameters, and custom type formatting. The approach emphasizes result-specific methods named according to expected row counts—such as one, many, oneOrNone, and manyOrNone—to protect code from unexpected query results by automatically rejecting mismatches. Tasks and transactions are the core abstractions: tasks provide shared connections for multiple queries, while transactions handle nested transactions with configurable behavior. The library also supports external SQL files, global event reporting for centralized error handling, and streaming for large result sets.
Developers should choose this tool when building Node.js applications that need reliable PostgreSQL access with strong guarantees around result cardinality and transaction safety. It suits projects where query formatting flexibility matters—particularly those using external SQL files or complex parameter binding. The declarative approach to result handling makes it valuable for teams wanting to catch data shape mismatches early rather than discovering them in production. The library is not positioned against alternatives in its documentation, so no comparative guidance is available.
The project maintains comprehensive documentation including an official guide, contribution notes, and a beginner's tutorial with examples. The codebase includes extensive support for customization through events and extensible protocols. The library's scope has grown significantly beyond its original purpose of adding promises to the base driver, now encompassing connection management, transaction control, and sophisticated query generation as core features.
