🛡️ Faster SQL escape and format for JavaScript (Node.js, Bun, and Deno).
npm install sql-escaper
🛡️ Up to ~40% faster SQL escape and format for JavaScript (Node.js, Bun, and Deno).
``bash`Node.js
npm i sql-escaper
`bash`Bun
bun add sql-escaper
`bash`Deno
deno add npm:sql-escaper
> [!NOTE]
>
> 🔐 SQL Escaper fixes a potential SQL Injection vulnerability discovered in 2022 in the original sqlstring, where objects passed as values could be expanded into SQL fragments, potentially allowing attackers to manipulate query structure. See sidorares/node-mysql2#4051 for details.
---
💡 SQL Escaper has the same API as the original sqlstring, so it can be used as a drop-in replacement.
`js
import { escape, escapeId, format, raw } from 'sql-escaper';
escape("Hello 'World'");
// => "'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()'));
// => 'NOW()'
`
> For _up-to-date_ documentation, always follow the README.md in the GitHub repository.
#### ES Modules
`js`
import { escape, escapeId, format, raw } from 'sql-escaper';
#### CommonJS
`js`
const { escape, escapeId, format, raw } = require('sql-escaper');
---
Escapes a value for safe use in SQL queries.
`ts`
escape(value: SqlValue, stringifyObjects?: boolean, timezone?: Timezone): string
`js`
escape(undefined); // 'NULL'
escape(null); // 'NULL'
escape(true); // 'true'
escape(false); // 'false'
escape(5); // '5'
escape("Hello 'World"); // "'Hello \\'World'"
#### Dates
Dates are converted to YYYY-MM-DD HH:mm:ss.sss format:
`js`
escape(new Date(2012, 4, 7, 11, 42, 3, 2));
// => "'2012-05-07 11:42:03.002'"
Invalid dates return NULL:
`js`
escape(new Date(NaN)); // 'NULL'
You can specify a timezone:
`js
const date = new Date(Date.UTC(2012, 4, 7, 11, 42, 3, 2));
escape(date, false, 'Z'); // "'2012-05-07 11:42:03.002'"
escape(date, false, '+01'); // "'2012-05-07 12:42:03.002'"
escape(date, false, '-05:00'); // "'2012-05-07 06:42:03.002'"
`
#### Buffers
Buffers are converted to hex strings:
`js`
escape(Buffer.from([0, 1, 254, 255]));
// => "X'0001feff'"
#### Objects
Objects with a toSqlString method will have that method called:
`js`
escape({ toSqlString: () => 'NOW()' });
// => 'NOW()'
Plain objects are converted to key = value pairs:
`jsa
escape({ a: 'b', c: 'd' });
// => " = 'b', c = 'd'"`
Function properties in objects are ignored:
`jsa
escape({ a: 'b', c: () => {} });
// => " = 'b'"`
When stringifyObjects is set to a non-nullish value, objects are stringified instead of being expanded into key-value pairs:
`js`
escape({ a: 'b' }, true);
// => "'[object Object]'"
#### Arrays
Arrays are turned into comma-separated lists:
`js`
escape([1, 2, 'c']);
// => "1, 2, 'c'"
Nested arrays are turned into grouped lists (useful for bulk inserts):
`js`
escape([
[1, 2, 3],
[4, 5, 6],
]);
// => '(1, 2, 3), (4, 5, 6)'
---
Escapes an identifier (database, table, or column name).
`ts`
escapeId(value: SqlValue, forbidQualified?: boolean): string
`jsid
escapeId('id');
// => ''
escapeId('table.column');
// => 'table.column'
escapeId('id');
// => 'id'
``
Qualified identifiers (with .) can be forbidden:
`jsid1.id2
escapeId('id1.id2', true);
// => ''`
Arrays are turned into comma-separated identifier lists:
`jsa
escapeId(['a', 'b', 't.c']);
// => ', b, t.c'`
---
Formats a SQL query by replacing ? placeholders with escaped values and ?? with escaped identifiers.
`ts`
format(sql: string, values?: SqlValue | SqlValue[], stringifyObjects?: boolean, timezone?: Timezone): string
`jsusers
format('SELECT * FROM ?? WHERE id = ?', ['users', 42]);
// => 'SELECT * FROM WHERE id = 42'
format('? and ?', ['a', 'b']);
// => "'a' and 'b'"
`
Triple (or more) question marks are ignored:
`js`
format('? or ??? and ?', ['foo', 'bar', 'fizz', 'buzz']);
// => "'foo' or ??? and 'bar'"
If no values are provided, the SQL is returned unchanged:
`js`
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:
`jsname
format('UPDATE users SET ?', [{ name: 'foo', email: 'bar@test.com' }]);
// => "UPDATE users SET = '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:
`js`
format('UPDATE users SET ?', [{ name: 'foo' }], true);
// => "UPDATE users SET '[object Object]'"
> [!IMPORTANT]
>
> 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.
---
Creates a raw SQL value that will not be escaped.
`ts`
raw(sql: string): Raw
`js
escape(raw('NOW()'));
// => 'NOW()'
escape({ id: raw('LAST_INSERT_ID()') });
// => 'id = LAST_INSERT_ID()'`
Only accepts strings:
`js`
raw(42); // throws TypeError
---
You can import the available types:
`ts`
import type { Raw, SqlValue, Timezone } from 'sql-escaper';
---
Each benchmark formats 10,000 queries using format with 100 mixed values (numbers, strings, null, and dates), comparing SQL Escaper against the original sqlstring through hyperfine:
| Benchmark | sqlstring | SQL Escaper | Difference |
| ---------------------------------------- | --------: | ----------: | ---------------: |
| Select 100 values | 248.8 ms | 178.7 ms | 1.39x faster |
| Insert 100 values | 247.5 ms | 196.2 ms | 1.26x faster |
| SET with 100 values | 257.5 ms | 205.2 ms | 1.26x faster |
| SET with 100 objects | 348.3 ms | 250.5 ms | 1.39x faster |
| ON DUPLICATE KEY UPDATE with 100 values | 466.2 ms | 394.6 ms | 1.18x faster |
| ON DUPLICATE KEY UPDATE with 100 objects | 558.2 ms | 433.9 ms | 1.29x faster |
- See detailed results and how the benchmarks are run in the benchmark directory.
> [!NOTE]
>
> Benchmarks ran on GitHub Actions (ubuntu-latest) using Node.js LTS.
> Results may vary depending on runner hardware and runtime version.
---
- TypeScript by default.
- Ships both CJS and ESM exports.
- Support multi lines, spaces and tables.
- Support SQL comments, including multi line comments.
- Distinguish when a keyword is used in a value.
- Distinguish between SET, KEY UPDATE, and WHERE clauses in the same queries.
- Distinguish when a column has a keyword name.
---
- Requires Node.js 12+ (the original sqlstring supports Node.js 0.6+)
> [!TIP]
>
> The Node.js 12+ requirement is what allows SQL Escaper to leverage modern engine optimizations and achieve the performance gains over the original.
---
> 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.
---
Please check the SECURITY.md.
---
See the Contributing Guide and please follow our Code of Conduct 🚀
---
- 
- 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.
---
SQL Escaper is under the MIT License.
Copyright © 2026-present Weslley Araújo and SQL Escaper contributors.