Registry / database / puresql

puresql

JSON →
library1.10.0jsnpmunverified

puresql is a Node.js SQL library inspired by Clojure's yesql that lets you define SQL queries in .sql files with named parameters and modifiers, then loads them as async functions. The current stable version is 1.10.0. It supports MySQL, MariaDB, PostgreSQL, MS SQL Server, and SQLite via adapters. Unlike ORMs or query builders, puresql keeps SQL raw and separate from JS logic, and supports parameter modifiers for safe interpolation, object insertion/update, dynamic conditions, and conditional clauses. Ships TypeScript definitions. Requires Node >= 6.0.0. Maintained but infrequent releases.

database
npm install puresql
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · PURESQL
P
puresql
databasejavascriptv1.10.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.

puresql
✓ const puresql = require('puresql')
✗ import puresql from 'puresql'
puresql is CommonJS-only; ESM import not supported without bundler interop. TypeScript users should use `import puresql = require('puresql')` or `import * as puresql from 'puresql'` with esModuleInterop: true.
adapters
✓ const adapter = puresql.adapters.mysql(connection)
✗ const adapter = puresql.mysqlAdapter(connection)
Adapters are nested under puresql.adapters; available adapters: mysql, mariadb, pg, mssql, sqlite.
loadQueries
✓ const queries = puresql.loadQueries('path/to/queries.sql')
loadQueries reads a .sql file and returns an object with functions named after the -- name: declarations.
defineQuery
✓ const query = puresql.defineQuery('SELECT * FROM user WHERE id = :id')
✗ const query = puresql.defineQuery('SELECT * FROM user WHERE id = :id', adapter)
defineQuery returns a raw query function that still needs adapter as second argument at call time.

Demonstrates loading SQL queries from a .sql file, creating a MySQL adapter, and calling queries as async functions with parameter binding.

const mysql = require('mysql'); const puresql = require('puresql'); const connection = mysql.createConnection({ host: process.env.DB_HOST ?? 'localhost', user: process.env.DB_USER ?? 'test', password: process.env.DB_PASS ?? '', database: process.env.DB_NAME ?? 'test', }); const adapter = puresql.adapters.mysql(connection); // Load queries from a .sql file // File: user.sql // -- name: get_by_id // SELECT * FROM user WHERE id = :id // -- name: get_all // SELECT * FROM user const queries = puresql.loadQueries('user.sql'); async function main() { const rows = await queries.get_all({}, adapter); rows.forEach(row => console.log('Name:', row.name)); const user = await queries.get_by_id({ id: 1 }, adapter); console.log('User:', user); } main().catch(console.error);
Debug
Known issues
gotchaNamed parameters require an exact match; missing parameters throw at runtime, not parse time.
fix
Ensure all named parameters in the SQL are provided in the parameters object, or use optional parameters with modifiers like :*limit.
affects: >=1.0.0
breakingGenerator-based workflow removed in v1.0.0; only async/await supported in Node 8+.
fix
Use async/await or Promises instead of generators. See README_OLD.md for generator examples.
affects: >=1.0.0
gotchaSQL injection possible with ! (dangerous) modifier; values passed to :!param are not escaped.
fix
Only use :! for trusted values like column names or ORDER BY clauses; prefer named parameters for user input.
affects: >=1.0.0
deprecatedNode version requirement might be too low; puresql 1.x may break on newer Node (e.g., 18+) due to engine restriction >=6.0.0.
fix
If using Node 16+, verify compatibility; consider pinning Node version if issues arise.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: puresql.loadQueries is not a function
Using ES module import syntax `import puresql from 'puresql'` with a CommonJS-only package.
fix
Use `const puresql = require('puresql')` or configure bundler with `esModuleInterop: true` for TypeScript.
Error: Parameter 'id' not provided
Missing required named parameter in the query call.
fix
Pass all required parameters as an object, e.g., `queries.get_by_id({ id: 1 }, adapter)`.
TypeError: adapter.query is not a function
Using an invalid adapter or not passing an adapter at all.
fix
Create an adapter via `puresql.adapters.mysql(connection)` (or other database adapter) and pass it as second argument to query functions.
Upgrade
Version history
1.10.0latest on npm
Audit
Dependencies
mysqloptionalRequired for MySQL adapter example, but adapter is optional if using other databases or custom adapters
Agent activity
11 hits · last 30 days
node
8
Resources
githubhttps://github.com/neonerd/puresql ↗
packagepuresql ↗
homepagehttps://github.com/neonerd/puresql#readme ↗
puresql — npm install puresql · libregistry