SQL Formatter

0.6.2 · active · verified Sun Apr 12

sql-formatter is a Python library designed to format SQL queries, enhancing readability and quick understanding through consistent indentation and casing. It aims to standardize SQL query writing, similar to how 'black' formats Python code. The library provides both a command-line interface and a Python API, and is actively maintained with frequent bug fixes and feature enhancements.

Warnings

gotcha SQL keywords embedded within table or variable names (e.g., 'select', 'and') could lead to incorrect formatting due to misinterpretation. [cite: Bugfixes in 0.6.2 release notes]
Fix: Upgrade to version 0.6.2 or later, which includes specific fixes to address these parsing issues.
gotcha Line comments starting with `--` might prematurely terminate formatting for subsequent SQL statements on the same line or block. [cite: Bugfixes in 0.6.1 release notes]
Fix: Ensure you are using version 0.6.1 or newer. If issues persist, consider using block comments (`/* ... */`) or utilizing the `/* sql-formatter-disable */` comments to explicitly exclude problematic sections from formatting.
gotcha The library does not inherently understand or format templating syntax (e.g., `SELECT {col} FROM {tablename}`). Such constructs might break formatting or be ignored.
Fix: For SQL containing templating, use the `paramTypes` configuration option to define custom regular expressions that treat these patterns as parameter placeholders during formatting. Example: `format(sql, paramTypes={'custom': [{'regex': r'\{\w+\}'}]})`.
deprecated Several older command-line interface (CLI) commands were deprecated and subsequently removed, potentially causing 'command not found' errors if older scripts are used. [cite: Maintenance in 0.5.4 release notes]
Fix: Refer to the latest documentation or use `sql-formatter --help` for the current CLI usage. The primary command is `sql-formatter <sql_file(s)>` with options like `--max-line-length`.

Install

pip install sql-formatter Install with pip

Imports

format_sql

from sql_formatter.core import format_sql

Quickstart

This quickstart demonstrates how to import the `format_sql` function and use it to format a multi-line SQL string.

from sql_formatter.core import format_sql

example_sql = """
create or replace table mytable as -- mytable example
seLecT a.asdf, b.qwer, -- some comment here
c.asdf, -- some comment there
b.asdf2
frOm table1 as a
leFt join table2 as b -- and here a comment
on a.asdf = b.asdf -- join this way 
"""

formatted_sql = format_sql(example_sql)
print(formatted_sql)

view raw JSON →