sql-fmt

library2.1.0jsnpmunverified

A MySQL query builder and SQL string formatting library that provides template literal-based SQL escaping and object-to-SQL conversion. Current stable version is 2.1.0. It wraps sqlstring for escaping and offers helper functions like insert, where, set, and values to safely build SQL from JavaScript objects. Key differentiators include automatic detection of template usage (e.g., objects become WHERE or SET clauses) and a prefix '#' to bypass escaping for trusted strings. Release cadence is low; the package is maintained primarily for personal use with notable limitations in documentation consistency.

database

npm install sql-fmt

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQL-FMT

sql-fmt

databasejavascriptv2.1.0

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 from 'sql-fmt'

✗ const sql = require('sql-fmt').default

ESM default import works; CommonJS require('sql-fmt') returns the default export directly.

sql.escape

✓ import sql from 'sql-fmt'; sql.escape(value)

✗ import { escape } from 'sql-fmt'

escape is a method on the default export, not a named export.

sql.escapeId

✓ import sql from 'sql-fmt'; sql.escapeId(identifier)

✗ const sql = require('sql-fmt'); const { escapeId } = sql;

escapeId is not a standalone export; it is only accessible via the default export object.

Demonstrates template literal SQL building with auto-escape, object handling for WHERE/INSERT/SET, and direct escape/escapeId functions.

import sql from 'sql-fmt'; // Template literal with auto-escape const name = "hello"; const query = sql`SELECT * FROM users WHERE name=${name};`; console.log(query); // SELECT * FROM users WHERE name='hello' // Object to WHERE clause const condition = { age: [20, 30] }; console.log(sql`SELECT * FROM users WHERE ${condition};`); // SELECT * FROM users WHERE (age=20 OR age=30) // Object to INSERT const data = { dog: "ff", age: 20 }; console.log(sql`INSERT INTO users ${data};`); // INSERT INTO users (dog,age) VALUES ('ff',20) // Object to SET const setData = { dog: "ff", age: 20 }; const whereData = { name: "apple" }; console.log(sql`UPDATE users SET ${setData} WHERE ${whereData};`); // UPDATE users SET dog='ff',age=20 WHERE (name='apple') // Using raw escape function console.log(`SELECT * FROM users WHERE name=${sql.escape("hello")};`); // SELECT * FROM users WHERE name='hello' // Escape identifier console.log(`SELECT * FROM users WHERE ${sql.escapeId("name")}='hello';`); // SELECT * FROM users WHERE `name`='hello'

Debug

Known issues

gotchaThe '#' prefix to skip escaping can introduce SQL injection if used with untrusted input.

fix

Avoid using '#' with user-supplied data; always prefer automatic escaping.

affects: >=2.0.0

gotchaTemplate literal automatically detects object types; passing an array to WHERE produces OR conditions incorrectly if mixed with AND.

fix

Use explicit sql.where() if you need precise control over condition grouping.

affects: >=2.0.0

deprecatedThe sql.values() function may duplicate sql.insert() behavior for single objects; check documentation.

fix

Use sql.insert() for INSERT queries; sql.values() is intended for VALUES portion only.

affects: >=2.0.0

gotchaTypeScript types are shipped but not fully comprehensive; some helper functions may have loose typing.

fix

Cast query strings as needed or supplement with your own type definitions.

affects: >=2.0.0

Errors

Common errors & fixes

Cannot find module 'sqlstring' when using sql-fmt in a browser environment

sql-fmt depends on sqlstring, which uses Node.js Buffer and is not natively available in browsers.

fix

Use a bundler who provides Buffer polyfill (e.g., webpack with Buffer plugin) or avoid runtime usage in browser.

TypeError: sql.escape is not a function

Importing named export instead of default: import { escape } from 'sql-fmt' does not work.

fix

Use the default import: import sql from 'sql-fmt', then call sql.escape().

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

sqlstringrequiredCore escaping functionality is delegated to sqlstring.

Agent activity

16 hits · last 30 days

node