{"id":42834,"library":"handy-postgres","title":"handy-postgres","description":"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.","status":"maintenance","version":"1.3.2","language":"javascript","source_language":"en","source_url":"https://github.com/guidesmiths/handy-postgres","tags":["javascript"],"install":[{"cmd":"npm install handy-postgres","lang":"bash","label":"npm"},{"cmd":"yarn add handy-postgres","lang":"bash","label":"yarn"},{"cmd":"pnpm add handy-postgres","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core PostgreSQL driver for all database communication","package":"pg","optional":false},{"reason":"Used for utility functions like merging configuration","package":"lodash","optional":true}],"imports":[{"note":"ESM default import; library is CJS but bundlers support this syntax.","wrong":"const HandyPg = require('handy-postgres')","symbol":"default","correct":"import HandyPg from 'handy-postgres'"},{"note":"CommonJS require for default export; named import not supported.","wrong":"import { HandyPg } from 'handy-postgres'","symbol":"HandyPg","correct":"const HandyPg = require('handy-postgres')"},{"note":"pg is a peer dependency and must be installed separately.","wrong":"import { pg } from 'pg'","symbol":"pg","correct":"import pg from 'pg'"}],"quickstart":{"code":"const HandyPg = require('handy-postgres');\nconst pg = require('pg');\n\nconst config = {\n  user: 'postgres',\n  database: 'test',\n  password: 'password',\n  host: 'localhost',\n  port: 5432,\n  max: 10,\n  idleTimeoutMillis: 30000\n};\n\nconst handypg = HandyPg({ config });\n\nhandypg.query('SELECT NOW()')\n  .then(result => {\n    console.log(result.rows);\n  })\n  .catch(err => {\n    console.error(err);\n  });","lang":"javascript","description":"Initialize handy-postgres with a config object and execute a simple query using promises."},"warnings":[{"fix":"Set the 'sql' config path to the folder containing .sql files, and reference them by filename without extension.","message":"SQL 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.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Migrate to a library that supports async/await natively and has TypeScript definitions.","message":"The library uses callbacks internally and is not actively maintained. Consider migrating to a more modern alternative like slonik or knex.","severity":"deprecated","affected_versions":">=1.0"},{"fix":"Use separate stream queries for each statement, or use query() for multiple statements.","message":"Multiple queries in a single streamQuery or formattedStreamQuery call will throw an error. Only one query per stream is allowed.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Use require('handy-postgres') or default import with bundler.","message":"The module syntax changed from require to import in version 1.2.0. Old require('.') syntax no longer works.","severity":"breaking","affected_versions":">=1.2.0"}],"env_vars":null,"search_vec":"'1.3.2':34 'activ':94 'api':18 'around':7 'automat':52 'base':17 'boilerpl':87 'cach':55 'common':20 'compar':79 'config':69 'connect':66 'control':78 'crud':89 'databas':65 'develop':95 'differenti':50 'explicit':72 'file':58 'folder':61 'handi':2 'handy-postgr':1 'helper':74 'includ':51 'infrequ':47 'insert':26 'isol':76 'javascript':99 'key':49 'knex':84 'lack':93 'latest':37 'level':77 'lightweight':5 'load':53 'mainten':44 'manag':32 'mode':45 'multipl':64 'node':9 'node-postgr':8 'oper':22 'path':70 'pg':82 'postgr':3,10 'postgresql':21 'project':41 'promis':16 'promise-bas':15 'provid':12 'queri':25 'raw':81 'reduc':86 'releas':39 'schema':31 'separ':68 'simplifi':14 'sql':57 'stabl':38 'stream':29 'support':62,98 'transact':28,73,91 'typescript':97 'updat':27,48 'version':33 'via':67 'wrapper':6","created_at":"2026-06-05T16:56:53.663252+00:00","updated_at":"2026-06-05T16:56:53.663252+00:00","problems":[{"fix":"Run 'npm install handy-postgres' and use const HandyPg = require('handy-postgres');","cause":"Package not installed or wrong import syntax.","error":"Cannot find module 'handy-postgres'"},{"fix":"Ensure PostgreSQL is running on localhost:5432 and config matches.","cause":"PostgreSQL server is not running or config is incorrect.","error":"Error: connect ECONNREFUSED 127.0.0.1:5432"},{"fix":"Pass a valid config object or config path to HandyPg({...}).","cause":"HandyPg was called without proper configuration object.","error":"TypeError: Cannot read property 'query' of undefined"},{"fix":"Ensure the sql config path is set and the SQL file exists, or provide a raw SQL string.","cause":"The first argument to query() is neither a raw SQL string nor a .sql filename (without extension).","error":"Error: query() expects a string or a known SQL shorthand"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://guidesmiths.github.io/handy-postgres/","github":"https://github.com/guidesmiths/handy-postgres","docs":null,"changelog":null,"pypi":null,"npm":"handy-postgres","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}