pg-extra

library3.0.0jsnpmunverified

pg-extra v3.0.0 provides helpful extensions and helpers for node-postgres (pg) without mutating the pg module. It adds a `pg.extra` namespace with extended Pool and Client classes that include convenient methods like `many`, `one`, `withTransaction`, `stream`, and `prepared` statement support. It also includes `sql` and `_raw` template literal tags to enforce parameterized queries and prevent SQL injection. Requires Node 8+ and pg 7.3+. Release cadence is low; stable, maintained project with no recent updates.

database

npm install pg-extra

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PG-EXTRA

pg-extra

databasejavascriptv3.0.0

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.

extend

✓ import { extend } from 'pg-extra'

✗ const extend = require('pg-extra').extend

ESM import works; also available as default import but named is recommended.

sql

✓ import { sql } from 'pg-extra'

✗ import { sql } from 'pg-extra/sql'

sql is exported from the main package, not a subpath.

_raw

✓ import { _raw } from 'pg-extra'

✗ import { raw } from 'pg-extra'

The tag is named _raw (underscore) to indicate unsafe usage. Do not forget underscore.

Pool (extended)

✓ const pg = extend(require('pg')); const pool = new pg.extra.Pool({})

✗ const { Pool } = require('pg-extra')

Pool is not directly exported; you must call extend(pg) first and then use pg.extra.Pool.

Shows basic usage: import extend, sql, _raw; extend pg; create pool; use many/one/withTransaction methods with template tags.

import { extend, sql, _raw } from 'pg-extra' import pg from 'pg' const extendedPg = extend(pg) const pool = new extendedPg.extra.Pool({ connectionString: process.env.DATABASE_URL ?? 'postgres://localhost/mydb' }) async function main() { const users = await pool.many(sql`SELECT * FROM users`) console.log(users) const user = await pool.one(sql`SELECT * FROM users WHERE id = ${1}`) console.log(user) await pool.withTransaction(async (client) => { await client.query(sql`UPDATE users SET name = ${'Alice'} WHERE id = ${1}`) }) await pool.end() } main().catch(console.error)

Debug

Known issues

breakingRequires Node >=8 and pg >=7.3. Older Node or pg versions will cause errors.

fix

Upgrade Node to 8+ and pg to 7.3+.

affects: >=3.0.0

gotchaAll query methods (query, many, one) reject queries that are not tagged with `sql` or `_raw`. Plain template literals will throw.

fix

Always use sql`...` for parameterized queries or _raw`...` for unsafe interpolation.

affects: >=3.0.0

gotchaThe `_raw` tag is unsafe and allows SQL injection if user input is interpolated. Use only for dynamic identifiers or keywords that cannot be parameterized.

fix

Prefersql`...` over _raw`...`. If you must use _raw, validate/sanitize inputs.

affects: >=3.0.0

gotchaThe `extend` function mutates the pg object's prototype? It actually adds an `extra` namespace but does not mutate existing prototypes. However, the extended classes have additional methods.

fix

Call extend only once per pg instance to avoid multiple wrapping.

affects: >=3.0.0

gotcha`pool.stream()` returns a Promise<Readable>, not a Readable directly. Await it before using the stream.

fix

Use `const stream = await pool.stream(...)`

affects: >=3.0.0

gotcha`pool.prepared('funcName').query()` etc. require that the prepared statement name does not conflict with existing ones in the same session.

fix

Use unique names for prepared statements, or avoid reusing names across queries.

affects: >=3.0.0

Errors

Common errors & fixes

Error: Query must be built with sql tag or _raw tag (e.g. sql`...` or _raw`...`)

Passing a regular template literal or string to query/many/one methods.

fix

Wrap the query with sql`...` or _raw`...` accordingly.

TypeError: pg.extra.Pool is not a constructor

Forgot to call extend(require('pg')) before accessing pg.extra.Pool.

fix

Call `const pg = extend(require('pg'))` and then use `new pg.extra.Pool(...)`.

ReferenceError: sql is not defined

sql tag not imported from pg-extra.

fix

Add `import { sql } from 'pg-extra'` or `const { sql } = require('pg-extra')`.

Error: Cannot find module 'pg-extra'

pg-extra not installed or not in node_modules.

fix

Run `npm install pg-extra` (and ensure pg is installed as a peer dependency).

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

pgrequiredPeer dependency: pg-extra extends pg module classes and requires pg >= 7.3.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/danneu/pg-extra ↗

packagepg-extra ↗

homepagehttps://github.com/danneu/pg-extra#readme ↗