{"id":19223626,"url":"https://github.com/wmfs/hl-pg-client","last_synced_at":"2025-05-13T10:47:46.898Z","repository":{"id":33119534,"uuid":"136909047","full_name":"wmfs/hl-pg-client","owner":"wmfs","description":"Provides a slightly higher level PostgreSQL client, that builds on pg-pool","archived":false,"fork":false,"pushed_at":"2025-05-13T08:18:14.000Z","size":392,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-05-13T08:18:54.212Z","etag":null,"topics":["package","postgresql","tymly"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wmfs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-06-11T10:10:16.000Z","updated_at":"2025-05-13T08:18:16.000Z","dependencies_parsed_at":"2023-09-25T02:02:15.102Z","dependency_job_id":"58f8cad8-8e07-4e06-b601-3b5ec5c51760","html_url":"https://github.com/wmfs/hl-pg-client","commit_stats":null,"previous_names":[],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wmfs%2Fhl-pg-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wmfs%2Fhl-pg-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wmfs%2Fhl-pg-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wmfs%2Fhl-pg-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wmfs","download_url":"https://codeload.github.com/wmfs/hl-pg-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253928184,"owners_count":21985790,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["package","postgresql","tymly"],"created_at":"2024-11-09T15:09:06.840Z","updated_at":"2025-05-13T10:47:46.876Z","avatar_url":"https://github.com/wmfs.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hl-pg-client\n[![Tymly Package](https://img.shields.io/badge/tymly-package-blue.svg)](https://tymly.io/)\n[![npm (scoped)](https://img.shields.io/npm/v/@wmfs/hl-pg-client.svg)](https://www.npmjs.com/package/@wmfs/hl-pg-client)\n[![CircleCI](https://circleci.com/gh/wmfs/hl-pg-client.svg?style=svg)](https://circleci.com/gh/wmfs/hl-pg-client)\n[![codecov](https://codecov.io/gh/wmfs/hl-pg-client/branch/master/graph/badge.svg)](https://codecov.io/gh/wmfs/hl-pg-client)\n[![CodeFactor](https://www.codefactor.io/repository/github/wmfs/hl-pg-client/badge)](https://www.codefactor.io/repository/github/wmfs/hl-pg-client)\n[![Dependabot badge](https://img.shields.io/badge/Dependabot-active-brightgreen.svg)](https://dependabot.com/)\n[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)\n[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)\n[![license](https://img.shields.io/github/license/mashape/apistatus.svg)](https://github.com/wmfs/tymly/blob/master/packages/pg-concat/LICENSE)\n\n\n\u003e Provides a slightly higher level PostgreSQL client, that builds on pg-pool\n\n## Usage\n\n### Create\n```\nconst HlPgClient = require('@hl-pg-client')\n\nconst client = new HlPgClient(connectionString)\n```\n\n### Query\nTo just run a simple query, just use the ```query``` method:\n\n```\nconst time = await client.query('SELECT NOW()')\nconst name = await client.query('select $1::text as name', ['brianc'])\nconsole.log(name.rows[0].name, 'says hello at', time.rows[0].name)\n```\n\nYou can also use a callback here if you'd like:\n\n```\nclient.query('SELECT $1::text as name', ['brianc'], function (err, res) {\n  console.log(res.rows[0].name) // brianc \n})\n```\n\nInternally, ```query``` uses pg-pool.query which ensures that a connection is acquired from the pool\nbeforehand, and then properly released again afterwards.\n\n### Larger Transactions\nTo run multiple SQL statements within the same transaction, use the ```run``` method:\n```\nawait client.run(statementArray)\n```\nor using callbacks\n```\nclient.run(statementArray, (err, res) =\u003e { ... })\n```\n\nEach item in the statement array should be an object with the form \n```\n{\n  sql: 'SQL statement to execute',\n  params: parameter array\n    // optional\n  preStatementHook: (item, ctx) =\u003e { ... },\n    // optional, called before the SQL is executed\n  postStatementHook: (result, ctx) =\u003e { ... },\n    // optional, called after the SQL is executed\n  action: (sql, params, client) =\u003e { ... }\n    // alternative action to perform instead of calling query\n}\n```\n\nIn the above the ```ctx``` parameter is initially the empty object, ```{}```, \nand it is passed to each postStatementHook in turn. \n\nThe return value of ```run``` is ```ctx.returnValue```.\n\nThe run method ensures that a client is properly acquired from and released back to the pool, whether the transaction \nsucceeds or fails.  In the event of a statement failure, it will attempt to rollback the transaction.\n\n#### Run example\n\n```\nconst statements = [\n  { \"sql\": \"BEGIN;\" },\n  { \"sql\": \"CREATE TEMP TABLE delete_supercopy_test_adults ON COMMIT DROP AS SELECT * FROM supercopy_test.adults WITH NO DATA;\" },\n  { \n    \"sql\": \"COPY delete_supercopy_test_adults(adult_no) FROM '/some/path/to/the/deletes/adults.csv' CSV HEADER;\",\n    \"action\": copyStream\n  },\n  { \"sql\": \"DELETE FROM supercopy_test.adults WHERE (adult_no) IN (SELECT adult_no FROM delete_supercopy_test_adults);\" },\n  { \"sql\": \"DROP TABLE delete_supercopy_test_adults;\" }\n  { \"sql\": \"COMMIT;\" }\n]\nawait client.run(statements)\n\n...\n\nfunction copyStream(statement, params, client) {\n  // use pg-copy-stream to send local file to remote PostgreSQL server\n  return new Promise((resolve, reject) =\u003e {\n    const components = statement.match(/COPY (.*?) FROM '([^']*)'/)\n    const tableAndCols = components[1]\n    const filename = components[2]\n    const newStatement = `COPY ${tableAndCols} FROM STDIN CSV HEADER;`\n\n    const stream = client.query(\n      copyFrom(newStatement)\n    )\n    stream.on('end', function () {\n      resolve()\n    }).on('error', function (err) {\n      reject(err)\n    })\n\n    const fileStream = fs.createReadStream(filename)\n    fileStream.on('error', function (err) {\n      reject(err)\n    })\n\n    fileStream.pipe(stream)\n  })\n} // copyStream\n```\n\n### SQL Files\n\nThe ```runFile``` method reads a file of SQL statements and executes them within a single transaction.\n\n### Testing\n\nEnsure a PostgreSQL database is setup for testing and add a PG_CONNECTION_STRING environment variable when establishing a pool of PostgreSQL connections, for example:\n\n```\nPG_CONNECTION_STRING=postgres://postgres:postgres@localhost:5432/my_test_db\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwmfs%2Fhl-pg-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwmfs%2Fhl-pg-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwmfs%2Fhl-pg-client/lists"}