Home

Awesome

<a href='https://github.com/sql-formatter-org/sql-formatter'><img src="static/prettier-sql-clean.svg" width="128"/></a>

SQL Formatter NPM version Build status Coverage Status

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

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

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

It does not support:

→ Try the demo.

Install

Get the latest version from NPM:

npm install sql-formatter

Also available with yarn:

yarn add sql-formatter

Usage

Usage as library

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,
});

Disabling the formatter

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 at comment the culprit out (at least until the issue gets fixed in SQL Formatter).

Placeholders replacement

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
  tbl
WHERE
  foo = 'bar'

For more details see docs of params option.

Usage from command line

The CLI tool will be installed under sql-formatter and may be invoked via npx 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 Formatter

positional 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 but one can also name an input file name or use the --output option.

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

select
  *
from
  tbl
where
  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.

Configuration options

Usage without NPM

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

Usage in editors

Usage as ESLint plugin

Frequently Asked Questions

Parse error: Unexpected ... at line ...

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: SQLFlavourOverride.

Module parse failed: Unexpected token

This typically happens when bundling an appication with Webpack. The cause is that Babel (through babel-loader) is not configured to 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:

I'm having a problem with Prettier SQL VSCode extension

The Prettier SQL VSCode extension is no more maintained by its author.

Please use the official SQL Formatter VSCode extension to get the latest fixes from SQL Formatter library.

My SQL contains templating syntax which SQL Formatter fails to parse

For example, you might have an SQL like:

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

While templating is not directly supported by SQL Formatter, the workaround is to use paramTypes config option to treat these occurances 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 future

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.

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

Contributing

Please see CONTRIBUTING.md

License

MIT