sql-escaper

SQL Escaper

Motivation

SQL Escaper is a rework of sqlstring (created by Douglas Wilson), by using an AST-based approach to parse and format SQL queries while maintaining its same API.

Rework includes:

• TypeScript by default.
• Support for Uint8Array, BigInt, and Temporal.
• Support for both CJS and ESM exports.
• Up to ~40% faster compared to sqlstring.
• Distinguishes when a keyword is used as value.
• Distinguishes when a column has a keyword name.
• Distinguishes between multiple clauses/keywords in the same query.
• Reasonable conservative support for Node.js v12 (sqlstring supports Node.js v0.6).

SQL Escaper has the same API as the original sqlstring, so it can be used as a drop-in replacement. If SQL Escaper breaks any API usage compared to sqlstring, please, report it as a bug. Pull Requests are welcome.

SQL Escaper is intended to fix a potential SQL Injection vulnerability reported in 2022. By combining the original sqlstring with mysqljs/mysql or MySQL2, objects passed as values could be expanded into SQL fragments, potentially allowing attackers to manipulate query structure. See sidorares/node-mysql2#4051 for details.

Regardless of the stringifyObjects value, objects used outside of SET or ON DUPLICATE KEY UPDATE contexts are always stringified as '[object Object]'. This is a security measure to prevent SQL Injection and is not interpreted as a breaking change for sqlstring usage.

---

Install

# Node.js
npm i sql-escaper

# Bun
bun add sql-escaper

# Deno
deno add npm:sql-escaper

---

MySQL2

For MySQL2, it already uses SQL Escaper as its default escaping library since version 3.17.0, so you just need to update it to the latest version:

npm i mysql2@latest

mysqljs/mysql

You can use an overrides in your package.json:

"dependencies": {
  "mysql": "^2.18.1"
},
"overrides": {
  "sqlstring": "npm:sql-escaper"
}

• Next, clean the node_modules and reinstall the dependencies (npm i).
• Please, note the minimum supported version of Node.js is 12.

---

Usage

For up-to-date documentation, always follow the README.md in the GitHub repository.

Quickstart

import { escape, escapeId, format, raw } from 'sql-escaper';

escape("Hello 'World'", true);
// => "'Hello \\'World\\''"

escapeId('table.column');
// => '`table`.`column`'

format('SELECT * FROM ?? WHERE id = ?', ['users', 42]);
// => 'SELECT * FROM `users` WHERE id = 42'

format('INSERT INTO users SET ?', [{ name: 'foo', email: 'bar@test.com' }]);
// => "INSERT INTO users SET `name` = 'foo', `email` = 'bar@test.com'"

escape(raw('NOW()'), true);
// => 'NOW()'

Import

ES Modules

import { escape, escapeId, format, raw } from 'sql-escaper';

CommonJS

const { escape, escapeId, format, raw } = require('sql-escaper');

---

API

escape

Escapes a value for safe use in SQL queries.

escape(value: SqlValue, stringifyObjects?: boolean, timezone?: Timezone): string

escape(undefined, true); // 'NULL'
escape(null, true); // 'NULL'
escape(true, true); // 'true'
escape(false, true); // 'false'
escape(5, true); // '5'
escape("Hello 'World", true); // "'Hello \\'World'"

Dates

Dates are converted to YYYY-MM-DD HH:mm:ss.sss format:

escape(new Date(2012, 4, 7, 11, 42, 3, 2), true);
// => "'2012-05-07 11:42:03.002'"

Invalid dates return NULL:

escape(new Date(NaN), true); // 'NULL'

You can specify a timezone:

const date = new Date(Date.UTC(2012, 4, 7, 11, 42, 3, 2));

escape(date, true, 'Z'); // "'2012-05-07 11:42:03.002'"
escape(date, true, '+01'); // "'2012-05-07 12:42:03.002'"
escape(date, true, '-05:00'); // "'2012-05-07 06:42:03.002'"

Temporal

Temporal values are supported too. Temporal.Instant and Temporal.ZonedDateTime are absolute points in time and honor the timezone argument exactly like Date (millisecond precision):

const instant = Temporal.Instant.from('2012-05-07T11:42:03.002Z');

escape(instant, true, 'Z'); // "'2012-05-07 11:42:03.002'"
escape(instant, true, '+0200'); // "'2012-05-07 13:42:03.002'"

Temporal.PlainDateTime, Temporal.PlainDate and Temporal.PlainTime are wall-clock values and are emitted verbatim as DATETIME / DATE / TIME literals, ignoring timezone:

escape(Temporal.PlainDate.from('2012-05-07')); // "'2012-05-07'"
escape(Temporal.PlainTime.from('11:42:03')); // "'11:42:03'"

Buffers

Buffers are converted to hex strings:

escape(Buffer.from([0, 1, 254, 255]), true);
// => "X'0001feff'"

Objects

When stringifyObjects is set to a non-nullish value (recommended), objects are stringified instead of being expanded into key-value pairs:

escape({ a: 'b' }, true);
// => "'[object Object]'"

Objects with a toSqlString method will have that method called:

escape({ toSqlString: () => 'NOW()' }, true);
// => 'NOW()'

Plain objects are converted to key = value pairs (discouraged):

escape({ a: 'b', c: 'd' });
// => "`a` = 'b', `c` = 'd'"

Function properties in objects are ignored (discouraged):

escape({ a: 'b', c: () => {} });
// => "`a` = 'b'"

Without stringifyObjects, plain objects are converted to key = value pairs, so an object reaching escape where a value is expected reshapes the query, for example:

const userInput = { id: true }; // e.g. JSON.parse('{"id":true}')

/** Unsafe 🔓 (value position) */
'DELETE FROM entries WHERE id = ' + escape(userInput);
// => "DELETE FROM entries WHERE id = `id` = true"
// `id` = `id` is always true, so every row is deleted ❗️

/** Valid ✅ (SET assignment) */
'UPDATE users SET ' + escape({ name: 'foo', role: 'admin' });
// => "UPDATE users SET `name` = 'foo', `role` = 'admin'"

Instead, format only expands an object where it is safe (e.g., a SET assignment) and stringifies it everywhere else, so the same input cannot reshape the query:

const userInput = { id: true }; // e.g. JSON.parse('{"id":true}')

/** Unsafe 🔐 (value position) */
format('DELETE FROM entries WHERE id = ?', [userInput]);
// => "DELETE FROM entries WHERE id = '[object Object]'"
// stringified to an inert value

/** Valid ✅ (SET assignment) */
format('UPDATE users SET ?', [{ name: 'foo', role: 'admin' }]);
// => "UPDATE users SET `name` = 'foo', `role` = 'admin'"
// expanded on purpose

Arrays

Arrays are turned into comma-separated lists:

escape([1, 2, 'c'], true);
// => "1, 2, 'c'"

Nested arrays are turned into grouped lists (useful for bulk inserts):

escape(
  [
    [1, 2, 3],
    [4, 5, 6],
  ],
  true
);
// => '(1, 2, 3), (4, 5, 6)'

Sets

Sets are treated like arrays, turning into comma-separated lists with natural deduplication:

escape(new Set([1, 2, 3]), true);
// => '1, 2, 3'

---

escapeId

Escapes an identifier (database, table, or column name).

escapeId(value: SqlValue, forbidQualified?: boolean): string

escapeId('id');
// => '`id`'

escapeId('table.column');
// => '`table`.`column`'

escapeId('i`d');
// => '`i``d`'

Qualified identifiers (with .) can be forbidden:

escapeId('id1.id2', true);
// => '`id1.id2`'

Arrays are turned into comma-separated identifier lists:

escapeId(['a', 'b', 't.c']);
// => '`a`, `b`, `t`.`c`'

---

format

Formats a SQL query by replacing ? placeholders with escaped values and ?? with escaped identifiers.

format(sql: string, values?: SqlValue | SqlValue[], stringifyObjects?: boolean, timezone?: Timezone): string

format('SELECT * FROM ?? WHERE id = ?', ['users', 42]);
// => 'SELECT * FROM `users` WHERE id = 42'

format('? and ?', ['a', 'b']);
// => "'a' and 'b'"

Triple (or more) question marks are ignored:

format('? or ??? and ?', ['foo', 'bar', 'fizz', 'buzz']);
// => "'foo' or ??? and 'bar'"

If no values are provided, the SQL is returned unchanged:

format('SELECT ??');
// => 'SELECT ??'

Objects in SET clauses

When stringifyObjects is falsy, objects used in SET or ON DUPLICATE KEY UPDATE contexts are automatically expanded into key = value pairs:

format('UPDATE users SET ?', [{ name: 'foo', email: 'bar@test.com' }]);
// => "UPDATE users SET `name` = 'foo', `email` = 'bar@test.com'"

format(
  'INSERT INTO users (name, email) VALUES (?, ?) ON DUPLICATE KEY UPDATE ?',
  ['foo', 'bar@test.com', { name: 'foo', email: 'bar@test.com' }]
);
// => "INSERT INTO users (name, email) VALUES ('foo', 'bar@test.com') ON DUPLICATE KEY UPDATE `name` = 'foo', `email` = 'bar@test.com'"

When stringifyObjects is truthy, objects are always stringified:

format('UPDATE users SET ?', [{ name: 'foo' }], true);
// => "UPDATE users SET '[object Object]'"

Maps in SET clauses

Maps are treated like plain objects, preserving insertion order. In SET or ON DUPLICATE KEY UPDATE contexts, they are expanded into key = value pairs:

format('UPDATE users SET ?', [
  new Map([
    ['name', 'foo'],
    ['email', 'bar@test.com'],
  ]),
]);
// => "UPDATE users SET `name` = 'foo', `email` = 'bar@test.com'"

Outside of SET or ON DUPLICATE KEY UPDATE, a Map is stringified as '[object Map]', the same security measure applied to objects:

format('SELECT * FROM users WHERE data = ?', [new Map([['id', 1]])]);
// => "SELECT * FROM users WHERE data = '[object Map]'"

---

raw

Creates a raw SQL value that will not be escaped.

raw(sql: string): Raw

escape(raw('NOW()'), true);
// => 'NOW()'

Inside an expanded object, raw values are preserved (discouraged):

escape({ id: raw('LAST_INSERT_ID()') });
// => '`id` = LAST_INSERT_ID()'

Only accepts strings:

raw(42); // throws TypeError

---

TypeScript

You can import the available types:

import type { Raw, SqlValue, Timezone } from 'sql-escaper';

---

Performance

Each benchmark formats 10,000 queries using format with 100 values, comparing SQL Escaper against the original sqlstring through hyperfine:

#	Benchmark	sqlstring	SQL Escaper	Difference
1	Select 100 values	249.0 ms	177.8 ms	1.40x faster
2	Insert 100 values	247.7 ms	185.3 ms	1.34x faster
3	Insert 100 strings requiring escape	436.9 ms	257.5 ms	1.70x faster
4	Insert 100 dates	611.9 ms	415.1 ms	1.47x faster
5	SET with 100 values	258.8 ms	207.4 ms	1.25x faster
6	SET with 100 objects	344.8 ms	241.0 ms	1.43x faster
7	ON DUPLICATE KEY UPDATE with 100 values	462.0 ms	362.7 ms	1.27x faster
8	ON DUPLICATE KEY UPDATE with 100 objects	559.4 ms	437.8 ms	1.28x faster
9	Multi-statement SET with 100 objects	348.7 ms	243.4 ms	1.43x faster

• See detailed results and how the benchmarks are run in the benchmark directory.

Benchmarks ran on GitHub Actions (ubuntu-latest) using Node.js LTS. Results may vary depending on runner hardware and runtime version.

---

Differences from sqlstring

• Requires Node.js 12+ (the original sqlstring supports Node.js 0.6+)

The Node.js 12+ requirement is what allows SQL Escaper to leverage modern engine optimizations and achieve the performance gains over the original.

---

Caution

Based on the original sqlstring documentation.

• The escaping methods in this library only work when the NO_BACKSLASH_ESCAPES SQL mode is disabled (which is the default state for MySQL servers).
• This library performs client-side escaping to generate SQL strings. The syntax for format may look similar to a prepared statement, but it is not — the escaping rules from this module are used to produce the resulting SQL string.
• When using format, all ? placeholders are replaced, including those contained in comments and strings.
• When structured user input is provided as the value to escape, care should be taken to validate the shape of the input, as the resulting escaped string may contain more than a single value.
• NaN and Infinity are left as-is. MySQL does not support these values, and trying to insert them will trigger MySQL errors.
• The string provided to raw() will skip all escaping, so be careful when passing in unvalidated input.

---

Security Policy

Please check the SECURITY.md.

---

Contributing

See the Contributing Guide and please follow our Code of Conduct

---

Acknowledgements

• 
• SQL Escaper is adapted from sqlstring (MIT), modernizing it with high performance, TypeScript support and multi-runtime compatibility.
• Special thanks to Douglas Wilson for the original sqlstring project and its contributors.

---

License

SQL Escaper is under the MIT License.