sql-format

library2.3.2jsnpmunverified

SQL Formatter is a JavaScript library for pretty-printing SQL queries, supporting Standard SQL, Couchbase N1QL, IBM DB2, and Oracle PL/SQL dialects. Current stable version is 2.3.2, with maintenance releases over years. Key differentiator: lightweight, no dependencies, supports placeholder replacement (named and indexed). Lacks TypeScript support in v2 but widely used for formatting SQL in Node.js and browser. Alternatives exist (e.g., prettier-plugin-sql) but sql-formatter is simpler and more focused.

devops

npm install sql-format

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQL-FORMAT

sql-format

devopsjavascriptv2.3.2

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 (sqlFormatter)

✓ import sqlFormatter from 'sql-formatter';

✗ const sqlFormatter = require('sql-formatter');

Package is ESM-only from v2? Actually CJS require works for v2. Use default import for ESM.

format function via named import

✓ import { format } from 'sql-formatter';

✗ import { format } from 'sql-formatter'; // Actually works if exported - check the dist

In v2, default export is the format function. Named export also available.

format with options (language, indent, params)

✓ sqlFormatter.format('SELECT *', { language: 'n1ql', indent: ' ' });

✗ sqlFormatter.format('SELECT *', { lang: 'n1ql' });

Use 'language' not 'lang'. Options are part of the main export.

Demonstrates formatting SQL with parameter substitution for named placeholders.

import sqlFormatter from 'sql-formatter'; const sql = 'SELECT a, b, c FROM tbl WHERE foo = @foo ORDER BY bar DESC'; const formatted = sqlFormatter.format(sql, { language: 'sql', indent: ' ', params: { foo: "'baz'" } }); console.log(formatted); // Output: // SELECT // a, // b, // c // FROM // tbl // WHERE // foo = 'baz' // ORDER BY // bar DESC

Debug

Known issues

gotchaplaceholders @foo (named) and ? (indexed) require explicit params configuration; otherwise they are left as-is.

fix

Always pass a `params` object or array when using placeholders to avoid unformatted tokens.

affects: >=2.0.0

gotchaIndentation defaults to 2 spaces, but may cause inconsistent formatting if mixed with tabs in existing code.

fix

Explicitly set `indent` option to your preference (e.g., '\t' for tabs).

affects: >=1.0.0

gotchaDialect support is limited to sql, n1ql, db2, pl/sql. Other SQL dialects or vendor-specific syntax may produce unexpected output.

fix

Verify formatted output for non-supported dialects; consider testing or using a more comprehensive formatter.

affects: >=2.0.0

deprecatedUsage via global window.sqlFormatter in browser is deprecated; prefer module bundlers.

fix

Use import statement with module bundler like webpack or rollup.

affects: >=2.0.0

gotchaThe library does not provide TypeScript type definitions; using in TypeScript project may require custom .d.ts file.

fix

Create a declaration file or use @ts-ignore.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: sqlFormatter.format is not a function

Importing the package with default import when the module is CommonJS, or missing the .default property.

fix

Use correct import: import sqlFormatter from 'sql-formatter' (if using ESM) or const sqlFormatter = require('sql-formatter').default (if mixing CJS/ESM).

SyntaxError: Unexpected token while formatting [e.g., WITH clauses]

The SQL contains dialect-specific syntax not supported by the specified 'language' option.

fix

Switch to a more appropriate dialect (e.g., 'n1ql' for Couchbase) or use a more comprehensive formatter.

Uncaught Error: Unknown language: mysql

Attempting to use 'mysql' as language option, which is not supported.

fix

Use one of: 'sql', 'n1ql', 'db2', 'pl/sql'. For MySQL, try the default 'sql' dialect.

Placeholder replacement fails: output still contains @foo or ?

Not passing the 'params' option with correct key/value or array.

fix

Add params: { foo: 'value' } for named placeholders, or params: ['value'] for indexed.

Upgrade

Version history

2.3.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/apla/sql-format ↗

packagesql-format ↗

homepagehttps://github.com/apla/sql-format#readme ↗