// the find
vitaly-t/pg-promise
PostgreSQL interface for Node.js
pg-promise is a PostgreSQL client for Node.js built on top of node-postgres, adding promise-based connection management, automatic transactions, and a flexible query-formatting engine. It's been the default answer for Postgres + Node for over a decade and has the depth to show for it. The target audience is backend Node developers who want more control than an ORM but don't want to manually manage connection pooling and transactions.
The query-formatting engine is genuinely well-designed — named parameters with multiple syntax options, SQL name escaping, CSV expansion, and Custom Type Formatting via `toPostgres` let you handle nearly any query construction need without string concatenation. The result-specific methods (`one`, `none`, `oneOrNone`, `many`) turn accidental row-count mismatches into thrown errors rather than silent bugs — this alone prevents a class of runtime surprises that raw pg users hit constantly. Transaction nesting with automatic savepoint management (`sp_1_1`, `sp_1_2`, etc.) works transparently and handles partial rollbacks correctly where most hand-rolled solutions don't bother. External SQL file support via `QueryFile` with auto-reload in dev mode is a practical feature that keeps SQL maintainable in larger projects without a full ORM.
It's a wrapper around node-postgres, not a replacement — if node-postgres has a bug or a missing feature, you're waiting on two maintainers instead of one. The learning curve for the `helpers` namespace (bulk inserts/updates via `ColumnSet`) is steep and the documentation is spread across JSDoc pages that are hard to navigate without already knowing what you're looking for. No built-in migration support — you're expected to pair it with something else (node-pg-migrate, Flyway, etc.), which is a fair design choice but means the stack is incomplete out of the box. TypeScript types exist but feel bolted on; the generic typing for query methods is loose enough that you'll often need explicit casts, and complex `helpers` usage doesn't type-check cleanly.