{"id":43902,"library":"sql-format","title":"SQL Formatter","description":"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.","status":"maintenance","version":"2.3.2","language":"javascript","source_language":"en","source_url":"https://github.com/apla/sql-format","tags":["javascript","sql","formatter","format","n1ql"],"install":[{"cmd":"npm install sql-format","lang":"bash","label":"npm"},{"cmd":"yarn add sql-format","lang":"bash","label":"yarn"},{"cmd":"pnpm add sql-format","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Package is ESM-only from v2? Actually CJS require works for v2. Use default import for ESM.","wrong":"const sqlFormatter = require('sql-formatter');","symbol":"default (sqlFormatter)","correct":"import sqlFormatter from 'sql-formatter';"},{"note":"In v2, default export is the format function. Named export also available.","wrong":"import { format } from 'sql-formatter'; // Actually works if exported - check the dist","symbol":"format function via named import","correct":"import { format } from 'sql-formatter';"},{"note":"Use 'language' not 'lang'. Options are part of the main export.","wrong":"sqlFormatter.format('SELECT *', { lang: 'n1ql' });","symbol":"format with options (language, indent, params)","correct":"sqlFormatter.format('SELECT *', { language: 'n1ql', indent: '  ' });"}],"quickstart":{"code":"import sqlFormatter from 'sql-formatter';\n\nconst sql = 'SELECT a, b, c FROM tbl WHERE foo = @foo ORDER BY bar DESC';\nconst formatted = sqlFormatter.format(sql, {\n  language: 'sql',\n  indent: '  ',\n  params: { foo: \"'baz'\" }\n});\nconsole.log(formatted);\n// Output:\n//   SELECT\n//     a,\n//     b,\n//     c\n//   FROM\n//     tbl\n//   WHERE\n//     foo = 'baz'\n//   ORDER BY\n//     bar DESC","lang":"javascript","description":"Demonstrates formatting SQL with parameter substitution for named placeholders."},"warnings":[{"fix":"Always pass a `params` object or array when using placeholders to avoid unformatted tokens.","message":"placeholders @foo (named) and ? (indexed) require explicit params configuration; otherwise they are left as-is.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Explicitly set `indent` option to your preference (e.g., '\\t' for tabs).","message":"Indentation defaults to 2 spaces, but may cause inconsistent formatting if mixed with tabs in existing code.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Verify formatted output for non-supported dialects; consider testing or using a more comprehensive formatter.","message":"Dialect support is limited to sql, n1ql, db2, pl/sql. Other SQL dialects or vendor-specific syntax may produce unexpected output.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Use import statement with module bundler like webpack or rollup.","message":"Usage via global window.sqlFormatter in browser is deprecated; prefer module bundlers.","severity":"deprecated","affected_versions":">=2.0.0"},{"fix":"Create a declaration file or use @ts-ignore.","message":"The library does not provide TypeScript type definitions; using in TypeScript project may require custom .d.ts file.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'2.3.2':30 'altern':62 'browser':61 'couchbas':18 'current':26 'db2':21 'depend':40 'dialect':25 'differenti':37 'e.g':64 'exist':63 'focus':77 'format':56,81 'formatt':2,4,72,80 'ibm':20 'index':46 'javascript':7,78 'key':36 'lack':47 'librari':8 'lightweight':38 'mainten':32 'n1ql':19,82 'name':44 'node.js':59 'oracl':23 'pl/sql':24 'placehold':42 'plugin':67 'pretti':11 'prettier':66 'prettier-plugin-sql':65 'pretty-print':10 'print':12 'queri':14 'releas':33 'replac':43 'simpler':74 'sql':1,3,13,17,57,68,71,79 'sql-formatt':70 'stabl':27 'standard':16 'support':15,41,49 'typescript':48 'use':54 'v2':51 'version':28 'wide':53 'year':35","created_at":"2026-06-05T17:02:01.492947+00:00","updated_at":"2026-06-05T17:02:01.492947+00:00","problems":[{"fix":"Use correct import: import sqlFormatter from 'sql-formatter' (if using ESM) or const sqlFormatter = require('sql-formatter').default (if mixing CJS/ESM).","cause":"Importing the package with default import when the module is CommonJS, or missing the .default property.","error":"TypeError: sqlFormatter.format is not a function"},{"fix":"Switch to a more appropriate dialect (e.g., 'n1ql' for Couchbase) or use a more comprehensive formatter.","cause":"The SQL contains dialect-specific syntax not supported by the specified 'language' option.","error":"SyntaxError: Unexpected token while formatting [e.g., WITH clauses]"},{"fix":"Use one of: 'sql', 'n1ql', 'db2', 'pl/sql'. For MySQL, try the default 'sql' dialect.","cause":"Attempting to use 'mysql' as language option, which is not supported.","error":"Uncaught Error: Unknown language: mysql"},{"fix":"Add params: { foo: 'value' } for named placeholders, or params: ['value'] for indexed.","cause":"Not passing the 'params' option with correct key/value or array.","error":"Placeholder replacement fails: output still contains @foo or ?"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/apla/sql-format#readme","github":"https://github.com/apla/sql-format","docs":null,"changelog":null,"pypi":null,"npm":"sql-format","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}