Registry / database / sql-template-tag

sql-template-tag

JSON →
library5.2.1jsnpmunverified

An ES2015 tagged template string library for preparing SQL statements with parameterized queries. Current version 5.2.1 (stable, active). Supports PostgreSQL, MySQL, SQLite, Oracle, and MSSQL via adapters. Provides automatic parameter substitution, nested SQL embedding, join/empty/raw helpers, and bulk insert support. Ships TypeScript types. Differentiates from alternatives by supporting multiple database backends, safe nesting of SQL instances, and zero external dependencies.

npm install sql-template-tag
INSTALL
IMPORT
SIG · SQL-TEMPLATE-TAG
S
sql-template-tag
databasejavascriptv5.2.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.

default import (sql function)
import sql from 'sql-template-tag'
const sql = require('sql-template-tag')
Library is ESM-only since v5, requiring ES module import syntax.
named exports (empty, join, raw, bulk, Sql)
import { empty, join, raw, bulk, Sql } from 'sql-template-tag'
const { empty, join, raw } = require('sql-template-tag')
CommonJS require is not supported in v5+; use ESM imports.
Sql class (for TypeScript)
import { Sql } from 'sql-template-tag'
import Sql from 'sql-template-tag'
Sql is a named export, not default. In TypeScript, use { Sql } for type usage.
Helper functions (empty, join, raw, bulk)
import { join, raw, empty, bulk } from 'sql-template-tag'
import { Join, Raw, Empty, Bulk } from 'sql-template-tag'
Export names are lowercase: empty, join, raw, bulk.

Demonstrates basic usage with placeholder substitution, database-specific query properties, nesting, join/empty helpers, and bulk insert.

import sql, { join, empty, raw, bulk } from 'sql-template-tag'; const id = 42; const query = sql`SELECT * FROM books WHERE id = ${id}`; console.log(query.sql); // "SELECT * FROM books WHERE id = ?" console.log(query.text); // "SELECT * FROM books WHERE id = $1" console.log(query.values); // [42] // For PostgreSQL import pg from 'pg'; const pool = new pg.Pool(); pool.query(query.text, query.values); // For MySQL (mysql2) import mysql from 'mysql2/promise'; const conn = await mysql.createConnection('mysql://...'); await conn.execute(query.sql, query.values); // Nesting and helpers const ids = [1, 2, 3]; const nested = sql`SELECT * FROM books WHERE id IN (${join(ids)})`; const final = sql`SELECT * FROM books ${ids.length ? sql`WHERE id IN (${join(ids)})` : empty}`; // Bulk insert const users = [['Alice'], ['Bob'], ['Charlie']]; const bulkInsert = sql`INSERT INTO users (name) VALUES ${bulk(users)}`; console.log(bulkInsert.sql); // "INSERT INTO users (name) VALUES (?),(?),(?)"
Debug
Known issues
breakingv5 changed module system from CommonJS to ESM-only. require() no longer works.
fix
Use import syntax or upgrade to Node >=14 with "type": "module" in package.json.
affects: >=5.0.0
deprecatedString.concat() and direct value concatenation on SQL instances is deprecated.
fix
Use nested sql calls or join() helper instead of manual string concatenation.
affects: >=5.0.0
gotchaThe 'text' property returns Postgres-style $N placeholders; 'sql' returns ? placeholders. Using the wrong property for your database will cause query errors.
fix
For PostgreSQL use .text; for MySQL/SQLite use .sql; for Oracle use .statement.
affects: *
gotchaPassing unsanitized user input to raw() creates a SQL injection vulnerability.
fix
Only use raw() with trusted strings; never with user-supplied data.
affects: *
gotchaThe default sql function accepts unknown value types; TypeScript strict mode may require a custom sql function with a type guard.
fix
Define a custom sql function with SupportedValue union type as shown in the documentation.
affects: *
Errors
Common errors & fixes
SyntaxError: Unexpected token '?' > 1 | import sql from 'sql-template-tag' | ^^^^^^
Using ESM import syntax in a CommonJS context (no "type": "module") or Node version <14.
fix
Add "type": "module" in package.json or use .mjs extension, and ensure Node >=14.
TypeError: sql is not a function
Using CommonJS require() which returns the module's default export as object instead of the sql function.
fix
Use import sql from 'sql-template-tag' (ESM) or const sql = require('sql-template-tag').default if using v4 with require.
Property 'sql' does not exist on type 'Sql'
TypeScript can't find the property because the 'sql' property is accessed on incorrect import or version mismatch.
fix
Ensure you are using version >=5.0.0 and imported correctly: import sql from 'sql-template-tag'.
ReferenceError: require is not defined in ES module scope
Using require in an ES module context.
fix
Use import syntax instead of require().
Upgrade
Version history
5.2.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
19 hits · last 30 days
node
16
Meta
2
OpenAI (training)
1
Resources
sql-template-tag — npm install sql-template-tag · libregistry