{"id":43962,"library":"sql-template-tag","title":"SQL Template Tag","description":"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.","status":"active","version":"5.2.1","language":"javascript","source_language":"en","source_url":"git://github.com/blakeembrey/sql-template-tag","tags":["javascript","sql","template","string","tag","es2015","es6","pg","postgres","typescript"],"install":[{"cmd":"npm install sql-template-tag","lang":"bash","label":"npm"},{"cmd":"yarn add sql-template-tag","lang":"bash","label":"yarn"},{"cmd":"pnpm add sql-template-tag","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Library is ESM-only since v5, requiring ES module import syntax.","wrong":"const sql = require('sql-template-tag')","symbol":"default import (sql function)","correct":"import sql from 'sql-template-tag'"},{"note":"CommonJS require is not supported in v5+; use ESM imports.","wrong":"const { empty, join, raw } = require('sql-template-tag')","symbol":"named exports (empty, join, raw, bulk, Sql)","correct":"import { empty, join, raw, bulk, Sql } from 'sql-template-tag'"},{"note":"Sql is a named export, not default. In TypeScript, use { Sql } for type usage.","wrong":"import Sql from 'sql-template-tag'","symbol":"Sql class (for TypeScript)","correct":"import { Sql } from 'sql-template-tag'"},{"note":"Export names are lowercase: empty, join, raw, bulk.","wrong":"import { Join, Raw, Empty, Bulk } from 'sql-template-tag'","symbol":"Helper functions (empty, join, raw, bulk)","correct":"import { join, raw, empty, bulk } from 'sql-template-tag'"}],"quickstart":{"code":"import sql, { join, empty, raw, bulk } from 'sql-template-tag';\n\nconst id = 42;\nconst query = sql`SELECT * FROM books WHERE id = ${id}`;\n\nconsole.log(query.sql);    // \"SELECT * FROM books WHERE id = ?\"\nconsole.log(query.text);   // \"SELECT * FROM books WHERE id = $1\"\nconsole.log(query.values); // [42]\n\n// For PostgreSQL\nimport pg from 'pg';\nconst pool = new pg.Pool();\npool.query(query.text, query.values);\n\n// For MySQL (mysql2)\nimport mysql from 'mysql2/promise';\nconst conn = await mysql.createConnection('mysql://...');\nawait conn.execute(query.sql, query.values);\n\n// Nesting and helpers\nconst ids = [1, 2, 3];\nconst nested = sql`SELECT * FROM books WHERE id IN (${join(ids)})`;\nconst final = sql`SELECT * FROM books ${ids.length ? sql`WHERE id IN (${join(ids)})` : empty}`;\n\n// Bulk insert\nconst users = [['Alice'], ['Bob'], ['Charlie']];\nconst bulkInsert = sql`INSERT INTO users (name) VALUES ${bulk(users)}`;\nconsole.log(bulkInsert.sql); // \"INSERT INTO users (name) VALUES (?),(?),(?)\"","lang":"typescript","description":"Demonstrates basic usage with placeholder substitution, database-specific query properties, nesting, join/empty helpers, and bulk insert."},"warnings":[{"fix":"Use import syntax or upgrade to Node >=14 with \"type\": \"module\" in package.json.","message":"v5 changed module system from CommonJS to ESM-only. require() no longer works.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Use nested sql calls or join() helper instead of manual string concatenation.","message":"String.concat() and direct value concatenation on SQL instances is deprecated.","severity":"deprecated","affected_versions":">=5.0.0"},{"fix":"For PostgreSQL use .text; for MySQL/SQLite use .sql; for Oracle use .statement.","message":"The 'text' property returns Postgres-style $N placeholders; 'sql' returns ? placeholders. Using the wrong property for your database will cause query errors.","severity":"gotcha","affected_versions":"*"},{"fix":"Only use raw() with trusted strings; never with user-supplied data.","message":"Passing unsanitized user input to raw() creates a SQL injection vulnerability.","severity":"gotcha","affected_versions":"*"},{"fix":"Define a custom sql function with SupportedValue union type as shown in the documentation.","message":"The default sql function accepts unknown value types; TypeScript strict mode may require a custom sql function with a type guard.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"search_vec":"'5.2.1':19 'activ':21 'adapt':30 'altern':49 'automat':32 'backend':54 'bulk':41 'current':17 'databas':53 'depend':63 'differenti':47 'embed':37 'es2015':5,69 'es6':70 'extern':62 'helper':39 'insert':42 'instanc':59 'javascript':64 'join/empty/raw':38 'librari':9 'mssql':28 'multipl':52 'mysql':24 'nest':35,56 'oracl':26 'paramet':33 'parameter':15 'pg':71 'postgr':72 'postgresql':23 'prepar':11 'provid':31 'queri':16 'safe':55 'ship':44 'sql':1,12,36,58,65 'sqlite':25 'stabl':20 'statement':13 'string':8,67 'substitut':34 'support':22,43,51 'tag':3,6,68 'templat':2,7,66 'type':46 'typescript':45,73 'version':18 'via':29 'zero':61","created_at":"2026-06-05T17:02:19.226437+00:00","updated_at":"2026-06-05T17:02:19.226437+00:00","problems":[{"fix":"Add \"type\": \"module\" in package.json or use .mjs extension, and ensure Node >=14.","cause":"Using ESM import syntax in a CommonJS context (no \"type\": \"module\") or Node version <14.","error":"SyntaxError: Unexpected token '?'\n\n> 1 | import sql from 'sql-template-tag'\n    | ^^^^^^"},{"fix":"Use import sql from 'sql-template-tag' (ESM) or const sql = require('sql-template-tag').default if using v4 with require.","cause":"Using CommonJS require() which returns the module's default export as object instead of the sql function.","error":"TypeError: sql is not a function"},{"fix":"Ensure you are using version >=5.0.0 and imported correctly: import sql from 'sql-template-tag'.","cause":"TypeScript can't find the property because the 'sql' property is accessed on incorrect import or version mismatch.","error":"Property 'sql' does not exist on type 'Sql'"},{"fix":"Use import syntax instead of require().","cause":"Using require in an ES module context.","error":"ReferenceError: require is not defined in ES module scope"}],"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/blakeembrey/sql-template-tag","github":"git://github.com/blakeembrey/sql-template-tag","docs":null,"changelog":null,"pypi":null,"npm":"sql-template-tag","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}}