sqlclean 0.4.0

The fastest SQL linter.

50× faster than sqruff. Lint 10,000 SQL files in under a second. Benchmarks
Website · Get started · Docs · Benchmarks

Catch SQL mistakes, apply safe fixes, and format consistently. Add your own rules in Python. SQLClean parses and checks SQL in Rust, and runs your Python Rules on statements it has already parsed.

uv tool install sqlclean        # or: pip install sqlclean

sqlclean check reports an unused CTE, a case-sensitive email comparison that a team's custom Rule forbids, and a = NULL comparison that is never true. sqlclean fix applies the safe fix, removing the CTE, and formats the file. It leaves = NULL alone because rewriting it to IS NULL changes which rows match; sqlclean fix --unsafe-fixes applies that fix. The custom Rule only reports, so its finding stays.

Quick start

sqlclean check     # report findings in every .sql file under the directory
sqlclean fix       # apply safe fixes, then format
sqlclean format    # rewrite files in the canonical layout

Add a sqlclean.toml to choose a dialect, files or Rules. See the quickstart and configuration.

Speed

Linting the same 10,282 Snowflake SQL files on a Linux machine with 4 CPUs, each tool with its default rules and no cache:

The tools don't check the same things: almost every sqruff and SQLFluff finding comes from a layout rule, which SQLClean leaves to its formatter. See the benchmarks for coverage, the corpus, the method and how to run it yourself.

SQLClean in other configurations, on the same files:

Correct and safe

• Rules for SQL that runs but is wrong. Built-in Rules flag comparisons with NULL, NOT IN lists that contain NULL, ROW_NUMBER with no deterministic order and more. See Rules.
• Safe fixes by default. sqlclean fix applies safe fixes only. A fix that can change which rows match waits for --unsafe-fixes, and a fix that would break parsing is discarded. See sqlclean fix.
• An idempotent formatter. Every statement gets one canonical layout, and formatting a formatted file changes nothing. See formatting.

Custom Rules in Python

A custom Rule is a Python function over each statement, already parsed and located by the Rust engine. This one enforces a team convention, not a rule of SQL: the columns the team lists in EMAIL_COLUMNS are compared case-insensitively. An = or <> that reads one of them, bare or as LOWER(email), passes only when both sides are LOWER(...) or a lower-case string literal. It reads comparisons from the statement's syntax tree, so comments and string literals never match, and it only reports, because changing a comparison is the author's call.

# sql_rules/team.py
import polyglot_sql as ast  # pip install "sqlclean[ast]"

from sqlclean import Finding, RuleContext, Statement, rule

EMAIL_COLUMNS = {"email", "billing_email"}  # the columns this team treats as email addresses


def email_column(operand: ast.Expression) -> ast.Column | None:
    """The designated email column an operand reads, written bare or as LOWER(column)."""
    column = operand.this if isinstance(operand, ast.Lower) else operand
    is_email = isinstance(column, ast.Column) and column.name.lower() in EMAIL_COLUMNS
    return column if is_email else None


def lowered(operand: ast.Expression) -> bool:
    """Whether an operand is LOWER(...) or a string literal with no upper-case letters."""
    literal = isinstance(operand, ast.Literal) and operand.is_string
    return isinstance(operand, ast.Lower) or (literal and operand.name == operand.name.lower())


@rule(
    code="XSQLCLEANTEAM001",
    message="Email comparisons must be case-insensitive",
    remediation="Compare LOWER(email) with LOWER(...) instead.",
    enabled_by_default=True,
)
def case_insensitive_email(*, statement: Statement, ctx: RuleContext) -> list[Finding]:
    starts = {
        column.to_dict()["column"]["span"]["start"]
        for comparison in statement.polyglot_ast().find_all(ast.Eq, ast.Neq)
        for column in map(email_column, (comparison.this, comparison.expression))
        if column is not None and not all(map(lowered, (comparison.this, comparison.expression)))
    }
    return [
        ctx.finding(subject=statement, node=column)
        for column in statement.columns
        if column.start - statement.start in starts
    ]

Point [rules] custom = ["sql_rules"] in sqlclean.toml at it. The syntax tree needs the ast extra: pip install "sqlclean[ast]". See custom Rules, statement facts and testing custom Rules.

Integrations

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/sqlstack-io/sqlclean
    rev: v0.1.0
    hooks:
      - id: sqlclean-fix
      - id: sqlclean-format

Use sqlclean-check where a hook must not change files. In CI, sqlclean check exits non-zero on findings and writes SARIF with --output-format sarif for code-scanning annotations. See integrations. sqlclean skills installs a skill for AI coding agents; see sqlclean skills.

Docs

• Docs home
• Rule reference
• Configuration
• Embedding the Rust engine

Development

uv sync --all-groups   # builds the native executable into .venv
make check             # format, lint, type-check, fensu and clippy
make test              # Rust and Python tests

License

Apache License 2.0.