pure-sql

library1.1.0-beta5jsnpmunverified

Pure SQL (v1.1.0-beta5) is a lightweight Node.js library that enables writing SQL queries as pure SQL template files and using them directly in JavaScript. It parses SQL files containing named queries and compiles them into parameterized query strings with argument arrays. Supports PostgreSQL (pg) and other SQL dialects via configurable parameter placeholders. Key differentiators: minimal abstraction (no ORM-like layers), template-based approach similar to HugSQL, support for repeating arguments and table/column placeholders via :!table and :column** syntax. Currently in beta, with slow release cadence.

database

npm install pure-sql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PURE-SQL

pure-sql

databasejavascriptv1.1.0-beta5

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.

✓ import { PG } from 'pure-sql'

✗ const PG = require('pure-sql').PG

The package does not ship TypeScript definitions. Use require() or named import. ESM only (no default export).

pureSql

✓ import * as pureSql from 'pure-sql'

✗ const pureSql = require('pure-sql')

Import namespace to access PG, withParam, etc. CJS require works but may cause issues with ES modules.

withParam

✓ import { withParam } from 'pure-sql'

✗ const withParam = require('pure-sql').withParam

Used to customize parameter placeholder (e.g., for MySQL). Can be combined with .withRepeatingArgs().

Shows loading SQL templates from file, executing a named query with pg, and customizing parameter placeholder for MySQL.

import { PG, withParam } from 'pure-sql'; import fs from 'fs'; import path from 'path'; // Assume you have ./sql/queries.sql with: // -- name: getUser // SELECT * FROM users WHERE id = :id; const sqlDir = path.resolve(__dirname, 'sql'); const templates = PG.parseTemplateFiles(sqlDir, '.sql'); // Use with pg: import pg from 'pg'; const client = new pg.Client({ /* connection config */ }); await client.connect(); const query = templates.getUser; const res = await client.query(query.query, query.map({ id: 1 })); console.log(res.rows); // For MySQL: const mySqlParam = (idx, name) => '?'; const mysqlTemplates = withParam(mySqlParam).withRepeatingArgs().parseTemplateFiles(sqlDir, '.sql');

Debug

Known issues

breakingVersion 1.1.0-beta5 may have breaking changes from earlier versions; beta status indicates unstable API.

fix

Check CHANGELOG on GitHub before upgrading.

affects: <1.1.0-beta5

gotchaThe parseTemplateFiles method expects the extension to include dot (e.g., '.sql'), not just 'sql'.

fix

Pass '.sql' as second argument, not 'sql'.

affects: >=1.0.0

gotchaNamed placeholders like :id and :name are only supported when using map() or mapTemplate(). Raw query strings contain $1-style placeholders.

fix

Use query.map({ id: 1 }) to get { query: '...$1...', args: [1] }.

affects: >=1.0.0

deprecatedThe .mapTemplate() method appears in examples but is mentioned as older? Check current docs.

fix

Prefer .map() if available.

affects: >=1.0.0

Errors

Common errors & fixes

Cannot find module 'pure-sql'

Package not installed or name typo (it's 'pure-sql', not 'pure-sql' but often confused with 'puresql').

fix

Run 'npm install pure-sql' and verify package name in package.json.

TypeError: PG.parseTemplateFiles is not a function

Importing wrong symbol; likely using default import instead of named.

fix

Use: import { PG } from 'pure-sql' or const PG = require('pure-sql').PG

Error: parseTemplateFiles requires a directory path and file extension

Missing arguments or wrong path.

fix

Call templates = PG.parseTemplateFiles(__dirname + '/sql', '.sql'); ensure directory exists.

Upgrade

Version history

1.1.0-beta5latest on npm

Audit

Dependencies

pgoptionalRequires a db client (e.g., pg) to actually execute queries; pure-sql only generates query strings

Agent activity

13 hits · last 30 days

node

Resources

githubhttps://github.com/pesite/js-pure-sql ↗

packagepure-sql ↗

homepagehttps://github.com/pesite/js-pure-sql#readme ↗