sqlstring

library2.3.3jsnpmunverified

Simple SQL escape and format utility for MySQL, commonly used as a dependency of mysqljs/mysql and mysql2. The current stable version is 2.3.3, with a stable release cadence (last updated 2020). It provides escape() and format() methods for safe SQL value interpolation, supporting custom toSqlString for raw SQL fragments. Unlike template-based libraries, it uses placeholder substitution (?), but does NOT protect against all injection vectors (e.g., NO_BACKSLASH_ESCAPES mode). Lightweight, no dependencies, and compatible with Node >= 0.6.

database

npm install sqlstring

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQLSTRING

sqlstring

databasejavascriptv2.3.3

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.

SqlString

✓ import SqlString from 'sqlstring'

✗ const { escape } = require('sqlstring')

Default import for ESM; the package is CJS-only so ESM usage requires a bundler or Node >= 16 with --experimental-modules.

escape

✓ import SqlString from 'sqlstring'; SqlString.escape(value)

✗ import { escape } from 'sqlstring'

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

format

✓ import SqlString from 'sqlstring'; SqlString.format(sql, values)

✗ const { format } = require('sqlstring')

format is a static method; require('sqlstring') returns the same default object.

raw

✓ import SqlString from 'sqlstring'; const raw = SqlString.raw('CURRENT_TIMESTAMP()');

✗ const raw = require('sqlstring').raw('...')

raw returns an object with toSqlString method; usable as a placeholder value.

Demonstrates escape, format, and raw usage for safe SQL value interpolation and raw SQL fragments.

import SqlString from 'sqlstring'; const userId = "1' OR '1'='1"; const safeSQL = 'SELECT * FROM users WHERE id = ' + SqlString.escape(userId); console.log(safeSQL); // SELECT * FROM users WHERE id = '1\' OR \'1\'=\'1' const post = { id: 1, title: 'Hello MySQL' }; const insertSQL = SqlString.format('INSERT INTO posts SET ?', post); console.log(insertSQL); // INSERT INTO posts SET `id` = 1, `title` = 'Hello MySQL' const now = SqlString.raw('CURRENT_TIMESTAMP()'); const updateSQL = SqlString.format('UPDATE posts SET modified = ? WHERE id = ?', [now, 1]); console.log(updateSQL); // UPDATE posts SET modified = CURRENT_TIMESTAMP() WHERE id = 1

Debug

Known issues

gotchaEscape methods assume NO_BACKSLASH_ESCAPES SQL mode is OFF; if enabled, backslash escapes become invalid, leading to potential SQL injection.

fix

Ensure MySQL server runs with NO_BACKSLASH_ESCAPES disabled, or use parameterized queries with mysql2 prepared statements.

affects: >=0.0.1

gotchaPlaceholder '?' replacement happens even inside SQL comments and string literals, which can break queries if placeholders appear in those contexts.

fix

Avoid using '?' inside comment blocks or string literals; escape literal '?' or use alternative methods.

affects: >=0.0.1

deprecatedPackage is stable but rarely updated; last release was in 2020. Consider using mysql2's built-in escape or an ORM for active maintenance.

fix

Use mysql2's escape() or migrate to a maintained alternative like @mysql2/promise.

affects: 2.3.3

gotchaNaN and Infinity values are left as-is and passed to MySQL, causing runtime errors as MySQL does not support these literals.

fix

Validate numeric inputs to reject NaN/Infinity before passing to escape/format.

affects: >=0.0.1

gotchaObject properties with function values are silently skipped, which may lead to unexpected omissions when escaping objects.

fix

Ensure objects used with escape/format have only serializable values.

affects: >=0.0.1

Errors

Common errors & fixes

TypeError: SqlString.escape is not a function

Named import instead of default import: `import { escape } from 'sqlstring'`

fix

Use default import: `import SqlString from 'sqlstring'` then call `SqlString.escape(value)`.

Cannot read properties of undefined (reading 'escape')

Calling `SqlString.escape()` after importing the module incorrectly (e.g., destructuring) or without initialization.

fix

Require correctly: `const SqlString = require('sqlstring');` or default import in ESM.

TypeError: (value).toSqlString is not a function

Passing a raw object without toSqlString method to format placeholder; misusing SqlString.raw.

fix

Use `SqlString.raw('...')` to create an object with toSqlString method.

Upgrade

Version history

2.3.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node