pg-sql

library1.1.0jsnpmunverified

A safe and composable SQL string builder for Postgres using template strings. Current stable version: 1.1.0. The library exposes a `sql` template tag and helper functions (`sql.ident`, `sql.raw`, `sql.join`) that produce `{ text, values }` objects compatible with the `pg` npm package. It prevents SQL injection by treating all interpolated values as parameters unless explicitly escaped via `sql.ident` or `sql.raw`. Unlike ORMs or raw query building, `pg-sql` keeps full control of SQL while ensuring safety and composability. It is released on an as-needed basis and ships TypeScript definitions.

database

npm install pg-sql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PG-SQL

pg-sql

databasejavascriptv1.1.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.

sql

✓ import { sql } from 'pg-sql'

✗ import sql from 'pg-sql'

Must use named import, not default import.

sql.ident

✓ import { sql } from 'pg-sql'; sql.ident('table')

✗ import { sqlIdent } from 'pg-sql'

`sql.ident` is a method on the `sql` object, not a separate named export.

sql.raw

✓ import { sql } from 'pg-sql'; sql.raw('text')

✗ import { raw } from 'pg-sql'

`sql.raw` is a method on the `sql` object, not a separate named export.

sql.join

✓ import { sql } from 'pg-sql'; sql.join(queries, separator)

✗ import { join } from 'pg-sql'

`sql.join` is a method on the `sql` object, not a separate named export.

Demonstrates safe query building with template strings, identifiers, and execution with the pg client.

import { sql } from 'pg-sql'; import { Pool } from 'pg'; const pool = new Pool(); const id = 10; const tableName = 'user'; const query = sql`select * from ${sql.ident(tableName)} where id = ${id}`; pool.query(query).then(({ rows }) => { console.log(rows); });

Debug

Known issues

gotchaUsing `sql.raw` with user input introduces SQL injection vulnerability.

fix

Avoid `sql.raw` unless you fully trust the input. Use `sql.ident` for identifiers and parameters for values.

affects: >=1.0.0

gotchaThe `sql` template tag returns an object, not a string. It must be passed directly to pg's query method.

fix

Use `pg.query(sql\`...\`)` instead of trying to stringify the result.

affects: >=1.0.0

gotchaOnly named export `sql` is available; there is no default export.

fix

Use `import { sql } from 'pg-sql'`.

affects: >=1.0.0

gotchaThe `sql.ident` function can generate local identifiers when passed a non-string (e.g., Symbol). This is unexpected for users who only pass strings.

fix

Always pass strings to `sql.ident` unless you intentionally need local identifiers.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: template is not a function

Importing `sql` as default instead of named import.

fix

Use `import { sql } from 'pg-sql'` instead of `import sql from 'pg-sql'`.

Cannot read properties of undefined (reading 'ident')

Attempting to use `sql.ident` after importing `sql` as default (which is undefined).

fix

Ensure you use `import { sql } from 'pg-sql'`.

Expected result to be a string but got an object

Treating the result of `sql\`...\`` as a plain string instead of an object.

fix

Pass the result directly to `pg.query()`; do not call `.toString()` or concatenate.

pg.query: expected a query object with text and values properties

Passing an incorrect object or string to pg.query.

fix

Ensure you use `sql` template tag directly: `pg.query(sql\`select...\`)`.

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/calebmer/pg-sql ↗

packagepg-sql ↗

homepagehttps://github.com/calebmer/pg-sql#readme ↗