sql-syntax

library2.0.1jsnpmunverified

SQLSyntax is a JavaScript/TypeScript library for composing SQL queries using tagged template literals, ported from ScalikeJDBC. Version 2.0.1 is the latest stable release. It provides a SQLSyntax class and sqls template tag that automatically escapes interpolated values and generates parameterized queries, preventing SQL injection for safe values. Key differentiators include the ability to merge SQLSyntax instances directly into queries, a custom toQuery function for adapting to different databases (default PostgreSQL), and a createUnsafely method for dynamic identifiers with explicit safety warnings. The library is ESM-only since v2.0.0 and requires Node.js >=18. It ships TypeScript types and is published on npm.

database

npm install sql-syntax

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQL-SYNTAX

sql-syntax

databasejavascriptv2.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.

SQLSyntax

✓ import SQLSyntax from 'sql-syntax'

✗ const SQLSyntax = require('sql-syntax')

ESM-only since v2.0.0; CommonJS require is not supported.

sqls

✓ import { sqls } from 'sql-syntax'

✗ import sqls from 'sql-syntax'

sqls is a named export, not default.

SQLSyntax type

✓ import type { SQLSyntax } from 'sql-syntax'

For TypeScript type-only import when using as a type.

Creates a parameterized SELECT query using sqls tag and executes it with pg client.

import SQLSyntax, { sqls } from 'sql-syntax'; import { Client } from 'pg'; const client = new Client(); await client.connect(); const userId = 'my-id'; const number = 4; const query = sqls`SELECT * FROM users WHERE user_id = ${userId} AND number = ${number}`; const [sql, parameters] = query.toQuery(); const res = await client.query(sql, parameters); console.log(res.rows); await client.end();

Debug

Known issues

breakingv2.0.0+ is pure ESM; CommonJS require() throws an error. Node.js >=18 is required.

fix

Switch to ESM (use import) or upgrade to Node.js >=18. Alternatively, stay on v1.x if CommonJS is needed.

affects: >=2.0.0

deprecatedCustom toQuery function via SQLSyntax.customToQueryFunc is available but may be removed in future versions.

fix

Consider extending the SQLSyntax class instead: class CustomSQLSyntax extends SQLSyntax { toQuery() {...} }.

affects: >=1.0.0

gotchaString values are always parameterized by default; dynamic identifiers require createUnsafely, which bypasses escaping and can cause SQL injection.

fix

Do not use createUnsafely with untrusted input. Always validate and sanitize identifier strings manually.

affects: all

gotchaDefault toQuery generates PostgreSQL-style $1, $2 parameters. For other databases like MySQL (?), you must replace SQLSyntax.customToQueryFunc.

fix

Set SQLSyntax.customToQueryFunc to a function that produces the correct placeholder style for your database.

affects: all

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

Using ESM import in a CommonJS project or Node.js version <18.

fix

Add "type": "module" to package.json or rename file to .mjs. Upgrade to Node.js >=18.

SQLSyntax is not a constructor

Trying to use require('sql-syntax') on ESM-only version >=2.0.0.

fix

Change to dynamic import: const { default: SQLSyntax } = await import('sql-syntax'); or switch to ESM.

Cannot find module 'sql-syntax' or its corresponding type declarations

Package not installed or TypeScript version not compatible with ESM.

fix

Run npm install sql-syntax. Ensure tsconfig.json has "moduleResolution": "node16" or "nodenext".

Property 'toQuery' does not exist on type 'string'

Calling toQuery on a regular string instead of a SQLSyntax instance.

fix

Use the sqls tagged template literal: const query = sqls`SELECT * FROM users`; then query.toQuery().

Upgrade

Version history

2.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node