pgsqwell

library6.0.1jsnpmunverified

pgsqwell is an immutable SQL template tag library for PostgreSQL, currently at version 6.0.1. It provides tagged template literals (sql, sqlPart) and helpers (escapeSQLIdentifier, joinSQLValues) for safe SQL construction without risk of injection. Unlike alternatives (e.g., node-postgres template libraries), it emphasizes immutability and separation of concerns: use `sql` for full statements and `sqlPart` for subparts. It ships TypeScript declarations and requires Node >=24.14.0. The library is actively maintained with a focus on correctness and composability.

database

npm install pgsqwell

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PGSQWELL

pgsqwell

databasejavascriptv6.0.1

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.

default export (sql)

✓ import sql from 'pgsqwell'

✗ const sql = require('pgsqwell')

ESM-only; no CommonJS support.

escapeSQLIdentifier

✓ import { escapeSQLIdentifier } from 'pgsqwell'

✗ import escapeSQLIdentifier from 'pgsqwell'

Named export, not default.

sqlPart

✓ import { sqlPart } from 'pgsqwell'

✗ import sqlPart from 'pgsqwell'

Named export for partial SQL fragments.

joinSQLValues

✓ import { joinSQLValues } from 'pgsqwell'

Named export for joining values into SQL lists.

emptySQLPart

✓ import { emptySQLPart } from 'pgsqwell'

Named export for an empty SQL part to use in conditional expressions.

Demonstrates building a SELECT query with parameterized value, conditional LIMIT using sqlPart, identifier escaping, IN-list via joinSQLValues, and query composition via UNION.

import sql, { escapeSQLIdentifier, sqlPart, emptySQLPart, joinSQLValues } from 'pgsqwell'; const limit = 10; const query = sql`SELECT id FROM users WHERE name=${'toto'} ${ limit ? sqlPart`LIMIT ${limit}` : emptySQLPart }`; const query2 = sql`SELECT id FROM ${escapeSQLIdentifier('table')}`; const query3 = sql`SELECT id FROM users WHERE id IN ${joinSQLValues([1, 2])}`; const mergedQuery = sql` ${query} UNION ${query2} UNION ${query3} `; console.log(query.text, query.values); console.log(query2.text, query2.values); console.log(query3.text, query3.values); console.log(mergedQuery.text, mergedQuery.values);

Debug

Known issues

breakingMinimum Node.js version increased to >=24.14.0

fix

Upgrade Node.js to 24.14.0 or later, or pin to pgsqwell 5.x if using older Node.

affects: >=6.0.0

breakingNo CommonJS support; ESM-only

fix

Use import syntax or dynamic import() in CommonJS projects. Switch to pgsqwell@5 if CJS required.

affects: >=6.0.0

gotchaUsing sqlPart with full statements may produce invalid SQL when composed

fix

Use sql for full statements, sqlPart only for subparts (e.g., conditions, clauses).

affects: all

gotchavscode-sql-tagged-template-literal plugin does not validate composed queries

fix

Test generated query strings manually or use pgsqwell-mock for testing.

affects: all

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

Using ESM import in a CommonJS environment

fix

Add "type": "module" to package.json or use dynamic import().

TypeError: pgsqwell__WEBPACK_IMPORTED_MODULE_0___default(...) is not a function

Wrong import: using default import for named export

fix

Use import { sql, sqlPart } from 'pgsqwell' instead of import sql from 'pgsqwell'.

Error: Invalid identifier: ... (escaping needed)

Using sql directly with user-provided table/column names without escapeSQLIdentifier

fix

Use escapeSQLIdentifier('tablename') inside the template literal.

Upgrade

Version history

6.0.1latest on npm

Audit

Dependencies

pgrequiredRuntime peer dependency for executing queries built with pgsqwell; pgsqwell itself only builds query strings.

Agent activity

4 hits · last 30 days

node

Resources

githubssh://git@github.com/nfroidure/pgsqwell ↗

packagepgsqwell ↗

homepagehttps://github.com/nfroidure/pgsqwell#readme ↗