Registry / database / sql-template-strings

sql-template-strings

library2.2.2jsnpmunverified

sql-template-strings (v2.2.2) is a mature, stable library that enables ES6 tagged template literals for building prepared SQL statements. It supports mysql, mysql2, pg (PostgreSQL), and Sequelize, automatically generating the correct placeholder syntax ($1, ?) and extracting values into arrays. Unlike raw template strings or manual concatenation, it prevents SQL injection by separating query text and values. Ships TypeScript definitions. Minimal API surface (SQL tag and append method). Last updated 2020; no active development but widely used and bug-free for its scope.

database

npm install sql-template-strings

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQL-TEMPLATE-STRIN

sql-template-strings

databasejavascriptv2.2.2

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 (SQL)

✓ import SQL from 'sql-template-strings'

✗ import { SQL } from 'sql-template-strings'

Module is ESM with default export. Named import will fail.

SQL (CommonJS)

✓ const SQL = require('sql-template-strings')

✗ const { SQL } = require('sql-template-strings')

CommonJS uses default export, not named destructuring.

Statement class

✓ import { Statement } from 'sql-template-strings'

✗ import Statement from 'sql-template-strings'

Statement is a named export, not default. For TypeScript type annotations.

Shows how to use the SQL tagged template to create a prepared statement and execute it with mysql2 using async/await.

import SQL from 'sql-template-strings'; import { createConnection } from 'mysql2/promise'; async function main() { const conn = await createConnection({ host: 'localhost', user: 'root', database: 'test' }); const name = 'harry potter'; const author = 'J. K. Rowling'; const query = SQL`SELECT author FROM books WHERE name = ${name} AND author = ${author}`; const [rows] = await conn.execute(query.sql, query.values); console.log(rows); await conn.end(); } main().catch(console.error);

Debug

Known issues

gotchaDo not use `${value}` inside string literals inside the template – the tag only escapes top-level interpolations.

fix

Keep all dynamic values as direct template interpolations, not inside quoted substrings.

affects: >=1.0.0

gotchaThe SQL tag returns an object, not a string. Passing it directly to db.query(..., callback) may not work in all drivers.

fix

Use query.sql or query.text for the query string and query.values for the parameters, or use compatible drivers (mysql, mysql2, pg) that accept the object directly.

affects: >=1.0.0

gotchaDo not mix SQL tagged templates with string concatenation inside the same template – it breaks escaping.

fix

Use the append() method to build queries dynamically instead of concatenating strings.

affects: >=1.0.0

deprecatedThe .query property is deprecated in favor of .sql and .text for clarity.

fix

Use query.sql for MySQL-style (?) placeholders and query.text for PostgreSQL-style ($1) placeholders.

affects: >=2.0.0

Errors

Common errors & fixes

Cannot read properties of undefined (reading 'sql')

Using SQL tag as a regular function instead of a tagged template: SQL(...)

fix

Use the backtick syntax: SQL`...`

TypeError: (intermediate value) is not iterable

Forgetting to call .append() on a Statement object before using it as a query.

fix

Chain .append() correctly: query.append(SQL`...`)

ReferenceError: SQL is not defined

Importing incorrectly (named instead of default) or using in an environment without ES module support.

fix

Use default import: import SQL from 'sql-template-strings' or require: const SQL = require('sql-template-strings')

Upgrade

Version history

2.2.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node