Repository files navigation

SQL Formatter is a JavaScript library for pretty-printing SQL queries.

It started as a port of aPHP Library, but has since considerably diverged.

It supports various SQL dialects:GCP BigQuery, IBM DB2, DuckDB, Apache Hive, MariaDB, MySQL, TiDB, Couchbase N1QL, Oracle PL/SQL, PostgreSQL, Amazon Redshift, SingleStoreDB, Snowflake, Spark, SQL Server Transact-SQL, Trino (and Presto).Seelanguage option docs for more details.

It does not support:

• Stored procedures.
• Changing of the delimiter type to something else than;.

→Try the demo.

Get the latest version from NPM:

npm install sql-formatter

Also available with yarn:

yarn add sql-formatter

import{format}from'sql-formatter';console.log(format('SELECT * FROM tbl',{language:'mysql'}));

This will output:

SELECT*FROM  tbl

You can also pass in configuration options:

format('SELECT * FROM tbl',{language:'spark',tabWidth:2,keywordCase:'upper',linesBetweenQueries:2,});

You can disable the formatter for a section of SQL by surrounding it with disable/enable comments:

/* sql-formatter-disable*/SELECT*FROM tbl1;/* sql-formatter-enable*/SELECT*FROM tbl2;

which produces:

/* sql-formatter-disable*/SELECT*FROM tbl1;/* sql-formatter-enable*/SELECT*FROM  tbl2;

The formatter doesn't even parse the code between these comments.So in case there's some SQL that happens to crash SQL Formatter,you can comment the culprit out (at least until the issue getsfixed in SQL Formatter).

In addition to formatting, this library can also perform placeholder replacement in prepared SQL statements:

format('SELECT * FROM tbl WHERE foo = ?',{params:["'bar'"],});

Results in:

SELECT*FROM  tblWHERE  foo='bar'

For more details seedocs of params option.

The CLI tool will be installed undersql-formatterand may be invoked vianpx sql-formatter:

sql-formatter -h

usage: sql-formatter [-h] [-o OUTPUT] \[-l {bigquery,db2,db2i,hive,mariadb,mysql,n1ql,plsql,postgresql,redshift,singlestoredb,snowflake,spark,sql,sqlite,tidb,transactsql,trino,tsql}] [-c CONFIG] [--version] [FILE]SQL Formatterpositional arguments:  FILE            Input SQL file (defaults to stdin)optional arguments:  -h, --help      show this help message and exit  -o, --output    OUTPUT                    File to write SQL output (defaults to stdout)  --fix           Update the file in-place  -l, --language  {bigquery,db2,db2i,hive,mariadb,mysql,n1ql,plsql,postgresql,redshift,singlestoredb,snowflake,spark,sql,sqlite,tidb,trino,tsql}                    SQL dialect (defaults to basic sql)  -c, --config    CONFIG                    Path to config JSON file or json string (will find a file named '.sql-formatter.json' or use default configs if unspecified)  --version       show program's version number and exit

By default, the tool takes queries from stdin and processes them to stdout butone can also name an input file name or use the--output option.

echo'select * from tbl where id = 3'| sql-formatter

select*from  tblwhere  id=3

The tool also accepts a JSON config file named .sql-formatter.json in the current or any parent directory, or with the--config option that takes this form:

{"language":"spark","tabWidth":2,"keywordCase":"upper","linesBetweenQueries":2}

All fields are optional and all fields that are not specified will be filled with their default values.

• language the SQL dialect to use (when usingformat()).
• dialect the SQL dialect to use (when usingformatDialect() since version 12).
• tabWidth amount of indentation to use.
• useTabs to use tabs for indentation.
• keywordCase uppercases or lowercases keywords.
• dataTypeCase uppercases or lowercases data types.
• functionCase uppercases or lowercases function names.
• identifierCase uppercases or lowercases identifiers. (experimental!)
• indentStyle defines overall indentation style. (deprecated!)
• logicalOperatorNewline newline before or after boolean operator (AND, OR, XOR).
• expressionWidth maximum number of characters in parenthesized expressions to be kept on single line.
• linesBetweenQueries how many newlines to insert between queries.
• denseOperators packs operators densely without spaces.
• newlineBeforeSemicolon places semicolon on separate line.
• params collection of values for placeholder replacement.
• paramTypes specifies parameter placeholders types to support.

If you don't use a module bundler, clone the repository, runnpm install and grab a file from/dist directory to use inside a<script> tag.This makes SQL Formatter available as a global variablewindow.sqlFormatter.

• VSCode extension
  • Repo
• Vim extension
• Prettier plugin

We provideJSON Schema for.sql-formatter.json configuration file, enabling autocompletion and IntelliSense support in editors.

• JSON Schema link
• Usage Guides:
  • Using the schema in VSCode
  • Using the schema in Zed

• Insideeslint-plugin-sql by using the ruleeslint-plugin-sql#format.

The most common cause is that you haven't specified an SQL dialect.Instead of calling the library simply:

format('select [col] from tbl');// Throws: Parse error: Unexpected "[col] from" at line 1 column 8

pick the proper dialect, like:

format('select [col] from tbl',{language:'transactsql'});

Or when using the VSCode extension: Settings -> SQL-Formatter-VSCode -> Dialect.

This typically happens when bundling an application with Webpack.The cause is that Babel (throughbabel-loader) is not configuredto support class properties syntax:

    | export default class ExpressionFormatter {    >   inline = false;

This syntax is widely supported in all major browsers (except old IE)and support for it is included to the default@babel/preset-env.

Possible fixes:

• Update to newer Babel / Webpack
• Switch to@babel/preset-env
• Include plugin@babel/plugin-proposal-class-properties

ThePrettier SQL VSCodeextension is no more maintained by its author.

Please use the officialSQL Formatter VSCodeextension to get the latest fixes from SQL Formatter library.

For example, you might have an SQL like:

SELECT {col1}, {col2}FROM {tablename}

While templating is not directly supported by SQL Formatter, the workaroundis to useparamTypes config option to treat theseoccurrences of templating constructs as prepared-statement parameter-placeholders:

format('SELECT {col1}, {col2} FROM {tablename};',{paramTypes:{custom:[{regex:String.raw`\{\w+\}`}]},});

This won't work for all possible templating constructs,but should solve the most common use cases.

The development of this formatter is currently in maintenance mode.Bugs will get fixed if feasible, but new features will likely not be added.

I have started a new SQL formatting tool:prettier-plugin-sql-cst.

• It solves several problems which can't be fixed in SQL Formatter becauseof fundamental problems in its architecture.
• It makes use of the Prettier layout algorithm,doing a better job of splitting long expressions to multiple lines.
• It takes much more opinionated approach to SQL formatting,giving only a very limited set of options to adjust the code style.
• It already has full support for SQLite and BigQuery syntax.It should work for the most common SQL code in various other dialects.

Give it a try if you'd like to take your SQL auto-formatting to the next level.

Please seeCONTRIBUTING.md

MIT