# @wmfs/hl-pg-client

> Provides a slightly higher level PostgreSQL client, that builds on pg-pool

Latest version **1.46.1** (published 2026-08-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install @wmfs/hl-pg-client
pnpm add @wmfs/hl-pg-client
yarn add @wmfs/hl-pg-client
bun add @wmfs/hl-pg-client
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 1.46.1 |
| Published | 2026-08-13 |
| First published | 2018-06-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 64.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | West Midlands Fire Service |
| Maintainers | wmfsbot |
| Keywords | tymly, package, postgresql |

## Links

- npm: https://www.npmjs.com/package/@wmfs/hl-pg-client
- Repository: https://github.com/wmfs/hl-pg-client
- Homepage: https://github.com/wmfs/hl-pg-client#readme
- Issues: https://github.com/wmfs/hl-pg-client/issues
- npm.io page: https://npm.io/package/@wmfs/hl-pg-client

## Dependencies (2)

- [pg](https://npm.io/package/pg.md) 8.16.3
- [debug](https://npm.io/package/debug.md) 4.4.1

## Alternatives

- [monaco-yaml](https://npm.io/package/monaco-yaml.md) — 420.1K weekly downloads
- [@crewx/workflow](https://npm.io/package/@crewx/workflow.md) — 3.1K weekly downloads
- [yaml-cat](https://npm.io/package/yaml-cat.md) — 38 weekly downloads
- [nunjucks-in-yaml](https://npm.io/package/nunjucks-in-yaml.md) — 9 weekly downloads
- [shopify-symlinks](https://npm.io/package/shopify-symlinks.md) — 3 weekly downloads

## Recent versions

- 1.46.1 (latest) — 2026-08-13
- 1.46.0 — 2025-10-21
- 1.45.0 — 2025-06-30
- 1.44.0 — 2025-06-20
- 1.43.0 — 2025-05-14
- 1.42.0 — 2025-05-13
- 1.41.0 — 2025-04-28
- 1.40.0 — 2025-04-25
- 1.39.0 — 2025-04-23
- 1.38.0 — 2025-03-18
- 1.37.0 — 2025-03-12
- 1.36.0 — 2025-02-14
- 1.35.0 — 2025-02-12
- 1.34.0 — 2024-12-09
- 1.33.0 — 2024-11-04
- … 37 more at https://npm.io/package/@wmfs/hl-pg-client/versions

## README

# hl-pg-client
[![Tymly Package](https://img.shields.io/badge/tymly-package-blue.svg)](https://tymly.io/)
[![npm (scoped)](https://img.shields.io/npm/v/@wmfs/hl-pg-client.svg)](https://www.npmjs.com/package/@wmfs/hl-pg-client)
[![CircleCI](https://circleci.com/gh/wmfs/hl-pg-client.svg?style=svg)](https://circleci.com/gh/wmfs/hl-pg-client)
[![codecov](https://codecov.io/gh/wmfs/hl-pg-client/branch/master/graph/badge.svg)](https://codecov.io/gh/wmfs/hl-pg-client)
[![CodeFactor](https://www.codefactor.io/repository/github/wmfs/hl-pg-client/badge)](https://www.codefactor.io/repository/github/wmfs/hl-pg-client)
[![Dependabot badge](https://img.shields.io/badge/Dependabot-active-brightgreen.svg)](https://dependabot.com/)
[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
[![license](https://img.shields.io/github/license/mashape/apistatus.svg)](https://github.com/wmfs/tymly/blob/master/packages/pg-concat/LICENSE)


> Provides a slightly higher level PostgreSQL client, that builds on pg-pool

## Usage

### Create
```
const HlPgClient = require('@hl-pg-client')

const client = new HlPgClient(connectionString)
```

### Query
To just run a simple query, just use the ```query``` method:

```
const time = await client.query('SELECT NOW()')
const name = await client.query('select $1::text as name', ['brianc'])
console.log(name.rows[0].name, 'says hello at', time.rows[0].name)
```

You can also use a callback here if you'd like:

```
client.query('SELECT $1::text as name', ['brianc'], function (err, res) {
  console.log(res.rows[0].name) // brianc 
})
```

Internally, ```query``` uses pg-pool.query which ensures that a connection is acquired from the pool
beforehand, and then properly released again afterwards.

### Larger Transactions
To run multiple SQL statements within the same transaction, use the ```run``` method:
```
await client.run(statementArray)
```
or using callbacks
```
client.run(statementArray, (err, res) => { ... })
```

Each item in the statement array should be an object with the form 
```
{
  sql: 'SQL statement to execute',
  params: parameter array
    // optional
  preStatementHook: (item, ctx) => { ... },
    // optional, called before the SQL is executed
  postStatementHook: (result, ctx) => { ... },
    // optional, called after the SQL is executed
  action: (sql, params, client) => { ... }
    // alternative action to perform instead of calling query
}
```

In the above the ```ctx``` parameter is initially the empty object, ```{}```, 
and it is passed to each postStatementHook in turn. 

The return value of ```run``` is ```ctx.returnValue```.

The run method ensures that a client is properly acquired from and released back to the pool, whether the transaction 
succeeds or fails.  In the event of a statement failure, it will attempt to rollback the transaction.

#### Run example

```
const statements = [
  { "sql": "BEGIN;" },
  { "sql": "CREATE TEMP TABLE delete_supercopy_test_adults ON COMMIT DROP AS SELECT * FROM supercopy_test.adults WITH NO DATA;" },
  { 
    "sql": "COPY delete_supercopy_test_adults(adult_no) FROM '/some/path/to/the/deletes/adults.csv' CSV HEADER;",
    "action": copyStream
  },
  { "sql": "DELETE FROM supercopy_test.adults WHERE (adult_no) IN (SELECT adult_no FROM delete_supercopy_test_adults);" },
  { "sql": "DROP TABLE delete_supercopy_test_adults;" }
  { "sql": "COMMIT;" }
]
await client.run(statements)

...

function copyStream(statement, params, client) {
  // use pg-copy-stream to send local file to remote PostgreSQL server
  return new Promise((resolve, reject) => {
    const components = statement.match(/COPY (.*?) FROM '([^']*)'/)
    const tableAndCols = components[1]
    const filename = components[2]
    const newStatement = `COPY ${tableAndCols} FROM STDIN CSV HEADER;`

    const stream = client.query(
      copyFrom(newStatement)
    )
    stream.on('end', function () {
      resolve()
    }).on('error', function (err) {
      reject(err)
    })

    const fileStream = fs.createReadStream(filename)
    fileStream.on('error', function (err) {
      reject(err)
    })

    fileStream.pipe(stream)
  })
} // copyStream
```

### SQL Files

The ```runFile``` method reads a file of SQL statements and executes them within a single transaction.

### Testing

Ensure a PostgreSQL database is setup for testing and add a PG_CONNECTION_STRING environment variable when establishing a pool of PostgreSQL connections, for example:

```
PG_CONNECTION_STRING=postgres://postgres:postgres@localhost:5432/my_test_db
```

---
_Source: https://npm.io/package/@wmfs/hl-pg-client · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._