handy-postgres

library1.3.2jsnpmunverified

A lightweight wrapper around node-postgres that provides a simplified promise-based API for common PostgreSQL operations such as querying, inserts, updates, transactions, streaming, and schema management. Version 1.3.2 is the latest stable release; the project is in maintenance mode with infrequent updates. Key differentiators include automatic loading and caching of SQL files from a folder, support for multiple database connections via separate config paths, and explicit transaction helpers with isolation level control. Compared to raw pg or knex, it reduces boilerplate for CRUD and transactions but lacks active development or TypeScript support.

database

npm install handy-postgres

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · HANDY-POSTGRES

handy-postgres

databasejavascriptv1.3.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

default

✓ import HandyPg from 'handy-postgres'

✗ const HandyPg = require('handy-postgres')

ESM default import; library is CJS but bundlers support this syntax.

HandyPg

✓ const HandyPg = require('handy-postgres')

✗ import { HandyPg } from 'handy-postgres'

CommonJS require for default export; named import not supported.

✓ import pg from 'pg'

✗ import { pg } from 'pg'

pg is a peer dependency and must be installed separately.

Initialize handy-postgres with a config object and execute a simple query using promises.

Debug

Known issues

gotchaSQL file location is relative to the configuration object's 'sql' property, not the project root. If not provided, shorthand queries (e.g., 'myQuery' instead of raw SQL) will fail silently.

fix

Set the 'sql' config path to the folder containing .sql files, and reference them by filename without extension.

affects: >=1.0

deprecatedThe library uses callbacks internally and is not actively maintained. Consider migrating to a more modern alternative like slonik or knex.

fix

Migrate to a library that supports async/await natively and has TypeScript definitions.

affects: >=1.0

gotchaMultiple queries in a single streamQuery or formattedStreamQuery call will throw an error. Only one query per stream is allowed.

fix

Use separate stream queries for each statement, or use query() for multiple statements.

affects: >=1.0

breakingThe module syntax changed from require to import in version 1.2.0. Old require('.') syntax no longer works.

fix

Use require('handy-postgres') or default import with bundler.

affects: >=1.2.0

Errors

Common errors & fixes

Cannot find module 'handy-postgres'

Package not installed or wrong import syntax.

fix

Run 'npm install handy-postgres' and use const HandyPg = require('handy-postgres');

Error: connect ECONNREFUSED 127.0.0.1:5432

PostgreSQL server is not running or config is incorrect.

fix

Ensure PostgreSQL is running on localhost:5432 and config matches.

TypeError: Cannot read property 'query' of undefined

HandyPg was called without proper configuration object.

fix

Pass a valid config object or config path to HandyPg({...}).

Error: query() expects a string or a known SQL shorthand

The first argument to query() is neither a raw SQL string nor a .sql filename (without extension).

fix

Ensure the sql config path is set and the SQL file exists, or provide a raw SQL string.

Upgrade

Version history

1.3.2latest on npm

Audit

Dependencies

pgrequiredCore PostgreSQL driver for all database communication

lodashoptionalUsed for utility functions like merging configuration

Agent activity

15 hits · last 30 days

node

Resources

githubhttps://github.com/guidesmiths/handy-postgres ↗

packagehandy-postgres ↗

homepagehttps://guidesmiths.github.io/handy-postgres/ ↗