Registry / data / sql-formatter

sql-formatter

library0.6.2pypypi✓ verified 22d ago

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.

data serialization

pip install sql-formatter

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQL-FORMATTER

sql-formatter

datapythonv0.6.2

Install

1.6s avg

Import

—

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.6.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 17.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.000s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

format_sql

✓ from sql_formatter.core import format_sql

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)

sql-formatter --version

Debug

Known issues

gotchaSQL 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.

affects: <0.6.2

gotchaLine 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.

affects: <0.6.1

gotchaThe 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+\}'}]})`.

affects: All versions

deprecatedSeveral 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`.

affects: >=0.5.4

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'sqlformatter'

The Python module for the `sql-formatter` package uses an underscore (`_`) in its name (`sql_formatter`), not a hyphen or no separator.

fix

Use `import sql_formatter` or `from sql_formatter.core import format_sql`.

sql-formatter: command not found

The `sql-formatter` command-line executable is not found in your system's PATH, or the virtual environment where it was installed is not active.

fix

Ensure your virtual environment is activated, or verify that the directory containing Python scripts (e.g., `~/.local/bin` or a virtual environment's `bin`/`Scripts` folder) is in your system's PATH.

ImportError: cannot import name 'format_sql' from 'sql_formatter' (...)

The `format_sql` function is located within the `core` submodule of the `sql_formatter` package, not directly under the main package.

fix

Correct the import statement to `from sql_formatter.core import format_sql`.

TypeError: format_sql() got an unexpected keyword argument 'indent'

The `format_sql` function uses `indent_width` as the keyword argument for specifying indentation size, not `indent`.

fix

Change the argument `indent` to `indent_width`, for example: `format_sql(my_sql_string, indent_width=2)`.

Upgrade

Version history

0.6.2latest on PyPI · released May 1, 2021

Audit

Dependencies

pythonrequiredRequired Python version for the library.

Agent activity

8 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/PabloRMira/sql_formatter ↗

packagehttps://pypi.org/project/sql-formatter/ ↗

homepagehttps://sql-formatter.readthedocs.io ↗