sql-formatter

What is sql-formatter?

The sql-formatter npm package is a library for formatting SQL queries. It supports various SQL dialects and provides a clean and readable output for SQL statements.

What are sql-formatter's main functionalities?

Basic SQL Formatting

This feature allows you to format a basic SQL query into a more readable format.

const sqlFormatter = require('sql-formatter');
const formattedSQL = sqlFormatter.format('SELECT * FROM table WHERE column = value');
console.log(formattedSQL);

Dialect-Specific Formatting

This feature allows you to format SQL queries according to specific SQL dialects like MySQL, PostgreSQL, etc.

const sqlFormatter = require('sql-formatter');
const formattedSQL = sqlFormatter.format('SELECT * FROM table WHERE column = value', { language: 'mysql' });
console.log(formattedSQL);

Custom Indentation

This feature allows you to customize the indentation used in the formatted SQL output.

const sqlFormatter = require('sql-formatter');
const formattedSQL = sqlFormatter.format('SELECT * FROM table WHERE column = value', { indent: '    ' });
console.log(formattedSQL);

Other packages similar to sql-formatter

sql-formatter-plus

sql-formatter-plus is another SQL formatter that offers similar functionality to sql-formatter. It also supports multiple SQL dialects and provides options for customizing the output format. However, it may have different default formatting styles and additional configuration options.

prettier-plugin-sql

prettier-plugin-sql is a plugin for the Prettier code formatter that adds support for formatting SQL queries. It integrates with Prettier's ecosystem, allowing you to format SQL queries alongside other code formats supported by Prettier. This can be useful if you are already using Prettier for other parts of your codebase.

README

SQL Formatter

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

Note. The docs here are for the latest dev version. For the latest release, see v4.0.2.

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, Couchbase N1QL, Oracle PL/SQL, PostgreSQL, Amazon Redshift, Spark, SQL Server Transact-SQL. See language option docs for more details.

It does not support:

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

→ 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'));

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

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: sqlfmt.js [-h] [-o OUTPUT] \
[-l {bigquery,db2,hive,mariadb,mysql,n1ql,plsql,postgresql,redshift,spark,sql,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)
  -l, --language  {bigquery,db2,hive,mariadb,mysql,n1ql,plsql,postgresql,redshift,spark,sql,tsql}
                    SQL dialect (defaults to standard sql)
  -c, --config    CONFIG
                    Path to config json file (will 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 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

• language the SQL dialect to use.
• tabWidth amount of indentation to use.
• useTabs to use tabs for indentation.
• keywordCase uppercases or lowercases keywords.
• indentStyle defines overall indentation style.
• multilineLists determines when to break lists of items to multiple lines.
• logicalOperatorNewline newline before or after boolean operator (AND, OR, XOR).
• aliasAs enforces or forbids use of AS keyword for aliases.
• tabulateAlias aligns column aliases vertically.
• commaPosition where to place the comma in column lists.
• newlineBeforeOpenParen placement of opening parenthesis.
• newlineBeforeCloseParen placement of closing parenthesis.
• 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.

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

• VSCode extension
• Vim extension

Contributing

Please see CONTRIBUTING.md

You can read more about how the library works in DOC.md

License

MIT