{"id":43712,"library":"pure-sql","title":"Pure SQL","description":"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.","status":"active","version":"1.1.0-beta5","language":"javascript","source_language":"en","source_url":"https://github.com/pesite/js-pure-sql","tags":["javascript","sql","pure","template","postgresql"],"install":[{"cmd":"npm install pure-sql","lang":"bash","label":"npm"},{"cmd":"yarn add pure-sql","lang":"bash","label":"yarn"},{"cmd":"pnpm add pure-sql","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Requires a db client (e.g., pg) to actually execute queries; pure-sql only generates query strings","package":"pg","optional":true}],"imports":[{"note":"The package does not ship TypeScript definitions. Use require() or named import. ESM only (no default export).","wrong":"const PG = require('pure-sql').PG","symbol":"PG","correct":"import { PG } from 'pure-sql'"},{"note":"Import namespace to access PG, withParam, etc. CJS require works but may cause issues with ES modules.","wrong":"const pureSql = require('pure-sql')","symbol":"pureSql","correct":"import * as pureSql from 'pure-sql'"},{"note":"Used to customize parameter placeholder (e.g., for MySQL). Can be combined with .withRepeatingArgs().","wrong":"const withParam = require('pure-sql').withParam","symbol":"withParam","correct":"import { withParam } from 'pure-sql'"}],"quickstart":{"code":"import { PG, withParam } from 'pure-sql';\nimport fs from 'fs';\nimport path from 'path';\n\n// Assume you have ./sql/queries.sql with:\n// -- name: getUser\n// SELECT * FROM users WHERE id = :id;\n\nconst sqlDir = path.resolve(__dirname, 'sql');\nconst templates = PG.parseTemplateFiles(sqlDir, '.sql');\n\n// Use with pg:\nimport pg from 'pg';\nconst client = new pg.Client({ /* connection config */ });\nawait client.connect();\n\nconst query = templates.getUser;\nconst res = await client.query(query.query, query.map({ id: 1 }));\nconsole.log(res.rows);\n\n// For MySQL:\nconst mySqlParam = (idx, name) => '?';\nconst mysqlTemplates = withParam(mySqlParam).withRepeatingArgs().parseTemplateFiles(sqlDir, '.sql');","lang":"typescript","description":"Shows loading SQL templates from file, executing a named query with pg, and customizing parameter placeholder for MySQL."},"warnings":[{"fix":"Check CHANGELOG on GitHub before upgrading.","message":"Version 1.1.0-beta5 may have breaking changes from earlier versions; beta status indicates unstable API.","severity":"breaking","affected_versions":"<1.1.0-beta5"},{"fix":"Pass '.sql' as second argument, not 'sql'.","message":"The parseTemplateFiles method expects the extension to include dot (e.g., '.sql'), not just 'sql'.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use query.map({ id: 1 }) to get { query: '...$1...', args: [1] }.","message":"Named placeholders like :id and :name are only supported when using map() or mapTemplate(). Raw query strings contain $1-style placeholders.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Prefer .map() if available.","message":"The .mapTemplate() method appears in examples but is mentioned as older? Check current docs.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'abstract':58 'approach':67 'argument':42,74 'array':43 'base':66 'beta':85 'cadenc':89 'column':81 'compil':35 'configur':52 'contain':31 'current':83 'dialect':50 'differenti':56 'direct':24 'enabl':12 'file':20,30 'hugsql':70 'javascript':26,90 'key':55 'layer':63 'librari':10 'lightweight':8 'like':62 'minim':57 'name':32 'node.js':9 'orm':61 'orm-lik':60 'paramet':53 'parameter':38 'pars':28 'pg':46 'placehold':54,77 'postgresql':45,94 'pure':1,3,17,92 'queri':15,33,39 'releas':88 'repeat':73 'similar':68 'slow':87 'sql':2,4,14,18,29,49,91 'string':40 'support':44,71 'syntax':82 'tabl':79 'table/column':76 'templat':19,65,93 'template-bas':64 'use':22 'v1.1.0-beta5':5 'via':51,78 'write':13","created_at":"2026-06-05T17:01:07.042444+00:00","updated_at":"2026-06-05T17:01:07.042444+00:00","problems":[{"fix":"Run 'npm install pure-sql' and verify package name in package.json.","cause":"Package not installed or name typo (it's 'pure-sql', not 'pure-sql' but often confused with 'puresql').","error":"Cannot find module 'pure-sql'"},{"fix":"Use: import { PG } from 'pure-sql' or const PG = require('pure-sql').PG","cause":"Importing wrong symbol; likely using default import instead of named.","error":"TypeError: PG.parseTemplateFiles is not a function"},{"fix":"Call templates = PG.parseTemplateFiles(__dirname + '/sql', '.sql'); ensure directory exists.","cause":"Missing arguments or wrong path.","error":"Error: parseTemplateFiles requires a directory path and file extension"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/pesite/js-pure-sql#readme","github":"https://github.com/pesite/js-pure-sql","docs":null,"changelog":null,"pypi":null,"npm":"pure-sql","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}