pg-format

library1.0.4jsnpmunverified

A Node.js implementation of PostgreSQL's format() function for safely creating dynamic SQL queries. Version 1.0.4, stable and minimal, with no dependencies. It escapes SQL identifiers (%I), literals (%L), and simple strings (%s) to help prevent SQL injection. Supports Node buffers, arrays, and objects, including nested arrays for bulk inserts. Unlike other SQL escaping libraries, it mimics PostgreSQL's built-in format() exactly, making it ideal for building queries in Node.js that mirror PL/pgSQL logic. Released under MIT license, maintained on GitHub.

database

npm install pg-format

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PG-FORMAT

pg-format

databasejavascriptv1.0.4

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.

format

✓ const format = require('pg-format');

✗ import format from 'pg-format';

This package is CJS-only and does not support ESM imports. Using ES import syntax will fail.

format.ident

✓ const { ident } = require('pg-format');

✗ const ident = require('pg-format').ident;

Destructuring works; the package exports a single function with methods attached.

format.withArray

✓ const { withArray } = require('pg-format');

✗ const withArray = require('pg-format/withArray');

No subpath exports; use destructuring from the main module.

Shows how to safely build a SELECT query with identifier, literal, and string placeholders.

const format = require('pg-format'); const sql = format('SELECT * FROM %I WHERE age > %L ORDER BY %I LIMIT %s', 'users', 18, 'name', 10); console.log(sql); // Output: SELECT * FROM "users" WHERE age > '18' ORDER BY "name" LIMIT 10

Debug

Known issues

gotchaIdentifier (%I) placeholders do not support arrays or objects; using them will throw an error.

fix

Use %L or %s for arrays/objects, or iterate manually.

affects: >=1.0.0

gotchaformat.config changes are global and affect all subsequent calls; reset with format.config() to defaults.

fix

Call format.config() with no arguments to restore defaults, or use a fresh require if isolation is needed.

affects: >=1.0.0

deprecatedThe package does not support ESM imports and has no TypeScript definitions.

fix

Use a dynamic import() with createRequire or switch to an ESM-compatible alternative like 'pg-escape'.

affects: >=1.0.0

gotchaPassing undefined or null as argument for %I throws an error; for %L they become 'NULL'; for %s they become empty string.

fix

Check for null/undefined before passing to %I, or use %L or %s accordingly.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: format is not a function

Using ES import syntax: `import format from 'pg-format'`

fix

Use CommonJS require: `const format = require('pg-format')`

Error: Expected a string or number for %I

Passing an array or object to an %I placeholder

fix

Use %L or %s for arrays/objects, or convert to string first.

Error: %L value must be a string, number, boolean, null, undefined, Buffer, or array

Passing a function or symbol to %L

fix

Ensure only supported types are passed; convert complex types to string beforehand.

Upgrade

Version history

1.0.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/datalanche/node-pg-format ↗

packagepg-format ↗

homepagehttps://github.com/datalanche/node-pg-format ↗