SQLFluff

4.1.0 · active · verified Thu Apr 09

SQLFluff is an SQL linter and auto-formatter designed for humans, with a focus on configurability and extensibility. It helps enforce coding styles and catch common errors in SQL queries across various dialects. The current version, 4.1.0, continues to expand its Rust-backed execution, improve performance, and enhance dialect support. It maintains an active release cadence with minor versions often introducing performance gains and bug fixes, and major versions bringing significant architectural shifts.

Warnings

breaking SQLFluff version 4.0.0 dropped support for Python 3.8. Users on Python 3.8 or older must upgrade to Python 3.9+ or remain on a SQLFluff 3.x release.
Fix: Upgrade your Python environment to 3.9 or higher. If unable to upgrade, pin your `sqlfluff` dependency to `<4.0.0` (e.g., `sqlfluff<4.0.0`).
breaking Version 4.1.0 introduced recursion protection via the `max_parse_depth` configuration setting. Extremely complex or deeply nested queries that previously parsed successfully might now fail with a recursion limit error if they exceed the default depth. This is a security feature to prevent resource exhaustion.
Fix: If legitimate queries are failing due to recursion depth, explicitly increase the `max_parse_depth` in your `.sqlfluff` configuration file (e.g., `[sqlfluff] max_parse_depth = 200`). Exercise caution when increasing this value significantly.
gotcha The `sqlfluff[rs]` extra, introduced in 4.0.0, enables a Rust-backed parser for significant performance improvements on large SQL files. However, due to the overhead of marshalling data between Python and Rust, it can be slightly slower than the pure Python parser for very small, simple SQL files.
Fix: For optimal performance, benchmark with and without `[rs]` for your typical workload. Most large projects will benefit from the Rust backend. If you experience unexpected slowdowns on small files, consider removing the `[rs]` extra or optimizing your linting strategy.
gotcha SQLFluff configuration is hierarchical, loading from default values, `.sqlfluff` files, `pyproject.toml`, environment variables, and CLI arguments, with later sources overriding earlier ones. Misunderstanding this precedence can lead to rules not being applied as expected or unexpected dialect choices.
Fix: Consult the official documentation on configuration precedence. Use `sqlfluff parse --verbose` or `sqlfluff lint --verbose` to see the active configuration being applied. Start with a single `.sqlfluff` file in your project root for clear, consistent configuration.

Install

pip install sqlfluff Standard Install
pip install sqlfluff[rs] With Rust-backed Parser (Recommended for Performance)

Imports

lint
```
from sqlfluff import lint
```
fix
```
from sqlfluff import fix
```
parse
```
from sqlfluff import parse
```

Quickstart

This quickstart demonstrates how to programmatically lint and fix a SQL string using SQLFluff's Python API. It initializes a SQL string with style violations and then applies `lint()` to identify issues and `fix()` to automatically correct them based on the 'ansi' dialect. You can specify a different dialect if needed.

from sqlfluff import lint, fix

sql_string = "SELECT a , b FROM my_table"

# Lint the SQL string
linter_results = lint(sql_string, dialect='ansi')
print("Linting Results:")
for result in linter_results:
    print(result.as_dict()) # or result.to_string()

# Fix the SQL string
fixed_sql = fix(sql_string, dialect='ansi')
print("\nFixed SQL:")
print(fixed_sql)

view raw JSON →