{"id":43552,"library":"pg-essential","title":"pg-essential","description":"Lightweight Node.js library on top of pg-spice that patches pg.Client with helper methods: fetchOne, fetchAll, execute, executeBulkInsertion, and executeTransaction. Version 1.0.2 is stable with no recent updates. It does not manage connection pooling, leaving that to the developer. Differentiators: bulk insertion and transaction handling without SQL injection via pg-promise internals.","status":"active","version":"1.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/ZiaDev/Pg-essential-dev","tags":["javascript","pg-essential","pg","pg-spice","postgres","bulk insert","bulk-insert","postgres node","postgres transaction"],"install":[{"cmd":"npm install pg-essential","lang":"bash","label":"npm"},{"cmd":"yarn add pg-essential","lang":"bash","label":"yarn"},{"cmd":"pnpm add pg-essential","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency – library patches pg.Client prototype","package":"pg","optional":false},{"reason":"internal dependency for bulk insertion and SQL injection prevention","package":"pg-spice","optional":false}],"imports":[{"note":"pg-essential is CJS-only. ESM import requires dynamic import().","wrong":"import { patch } from 'pg-essential';","symbol":"patch","correct":"const { patch } = require('pg-essential'); patch(pg);"},{"note":"fetchOne is a prototype method on client instance, not a static export.","wrong":"const row = await pg.fetchOne('SELECT * FROM users WHERE id=$1', [1]);","symbol":"pg.Client.prototype.fetchOne","correct":"const client = new pg.Client(); // then patch first\nconst row = await client.fetchOne('SELECT * FROM users WHERE id=$1', [1]);"},{"note":"Order of arguments: bulkData, columns, tableName.","wrong":"await client.executeBulkInsertion('users', [{id:1,name:'a'}], ['id','name']);","symbol":"executeBulkInsertion","correct":"await client.executeBulkInsertion([{id:1,name:'a'}], ['id','name'], 'users');"}],"quickstart":{"code":"const pg = require('pg');\nrequire('pg-essential').patch(pg);\n\nasync function main() {\n  const client = new pg.Client({ connectionString: process.env.DATABASE_URL ?? 'postgres://localhost/mydb' });\n  await client.connect();\n\n  // fetchOne\n  const user = await client.fetchOne('SELECT * FROM users WHERE id = $1', [1]);\n  console.log('User:', user);\n\n  // fetchAll\n  const allUsers = await client.fetchAll('SELECT * FROM users');\n  console.log('All users:', allUsers);\n\n  // execute\n  const result = await client.execute('UPDATE users SET name = $1 WHERE id = $2', ['John', 1]);\n  console.log('Updated rows:', result.rowCount);\n\n  // executeBulkInsertion\n  const bulkData = [\n    { id: 2, name: 'Alice' },\n    { id: 3, name: 'Bob' }\n  ];\n  await client.executeBulkInsertion(bulkData, ['id', 'name'], 'users');\n\n  // executeTransaction\n  await client.executeTransaction(async (txClient) => {\n    await txClient.execute('INSERT INTO logs (msg) VALUES ($1)', ['start']);\n    await txClient.execute('UPDATE users SET name = $1 WHERE id = $2', ['Updated', 2]);\n  });\n\n  await client.end();\n}\n\nmain().catch(console.error);","lang":"javascript","description":"Demonstrates patching pg, connecting a client, and using fetchOne, fetchAll, execute, executeBulkInsertion, and executeTransaction."},"warnings":[{"fix":"Call require('pg-essential').patch(pg) at app startup before any new pg.Client().","message":"Must call patch(pg) before creating any clients; otherwise prototype methods are undefined.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Split bulk data into chunks of ~500 rows to avoid parameter limit errors.","message":"executeBulkInsertion uses pg-promise internally, but its options are not configurable. Large bulk inserts may exceed PostgreSQL parameter limit.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Wrap executeTransaction inside getPool().then(...) as shown in the README examples.","message":"executeTransaction does not expose the connection from pool; it expects you to call p.getClient() yourself as shown in examples.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Consider using pg-promise or knex directly for bulk operations and transactions.","message":"pg-spice on which this depends is no longer actively maintained. Future compatibility with newer pg versions is uncertain.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Always check const row = await client.fetchOne(...); if (row === null) { ... }","message":"fetchOne returns null if no rows found, not undefined or throws. Check for null to handle empty results.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1.0.2':26 'bulk':45,67,70 'bulk-insert':69 'connect':37 'develop':43 'differenti':44 'essenti':3,61 'execut':21 'executebulkinsert':22 'executetransact':24 'fetchal':20 'fetchon':19 'handl':49 'helper':17 'inject':52 'insert':46,68,71 'intern':57 'javascript':58 'leav':39 'librari':6 'lightweight':4 'manag':36 'method':18 'node':73 'node.js':5 'patch':14 'pg':2,11,55,60,62,64 'pg-essenti':1,59 'pg-promis':54 'pg-spice':10,63 'pg.client':15 'pool':38 'postgr':66,72,74 'promis':56 'recent':31 'spice':12,65 'sql':51 'stabl':28 'top':8 'transact':48,75 'updat':32 'version':25 'via':53 'without':50","created_at":"2026-06-05T17:00:20.883326+00:00","updated_at":"2026-06-05T17:00:20.883326+00:00","problems":[{"fix":"Call require('pg-essential').patch(pg) before any new pg.Client() instantiation.","cause":"patch(pg) was not called before creating the client.","error":"TypeError: client.fetchOne is not a function"},{"fix":"Ensure columns array matches actual table column names, including case sensitivity.","cause":"executeBulkInsertion column names array contains a column that does not exist in the table.","error":"error: column \"id\" of relation \"test\" does not exist"},{"fix":"Ensure connection.done() is called exactly once per getClient block, and catch errors to avoid double call.","cause":"Calling done() multiple times or handling errors incorrectly in connection callback.","error":"Error: Can't set headers after they are sent."},{"fix":"Run npm install pg-spice or use --legacy-peer-deps if using npm v7+.","cause":"pg-essential depends on pg-spice which may not be installed automatically if peer dependencies are not resolved.","error":"Cannot find module 'pg-spice'"}],"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://github.com/ZiaDev/Pg-essential-dev#readme","github":"https://github.com/ZiaDev/Pg-essential-dev","docs":null,"changelog":null,"pypi":null,"npm":"pg-essential","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}}