SQLFluff: a dialect-aware SQL linter and formatter for templated code

The problem SQLFluff solves: SQL that is not plain SQL

Most SQL linters treat a file as text. That works until the file contains Jinja braces, dbt ref() calls, or a dialect-specific function that a generic parser rejects. SQLFluff's premise, stated in its README, is that it is dialect-flexible and built with ELT applications in mind, and that it works with Jinja templating and dbt. The README also lists the dialects it supports, from ANSI SQL through BigQuery, ClickHouse, Databricks, DuckDB, Snowflake, SparkSQL, T-SQL, Trino and Vertica, with the caveat that support may not be complete in every dialect.

The audience is data and analytics engineers who keep SQL in version control. If your queries are generated by dbt, or assembled from Jinja macros, or written against a warehouse that extends standard SQL, a text-matching linter will produce findings you cannot act on. SQLFluff's answer is to render the template first and parse the result, which is why the dialect and templater settings are the two things you configure before anything else.

How the parse, lint and fix pipeline actually works

The mechanism is a pipeline rather than a set of regular expressions. SQLFluff renders templated code into concrete SQL, lexes and parses that SQL against the dialect you selected, builds a syntax tree, and then runs rules over the tree. The README describes the project as a modular SQL linter that will auto-fix most linting errors, and the term modular is literal: rules are grouped into families, and the lint output in the README labels each finding with both a rule code and a family name, for example LT01 with layout.spacing and LT02 with layout.indent.

That structure explains the fix behaviour. A rule that knows a token is a binary operator, rather than a run of characters, can rewrite the spacing around it without touching string literals that happen to contain the same characters. The README's own example shows seven findings on a one-line query, covering spacing, indentation, start-of-file whitespace, trailing whitespace and the missing final newline. Those are all layout rules, which is why they are the ones most commonly auto-fixed.

The templating layer is where most adoption friction lives. SQLFluff supports Jinja, SQL placeholders, Python format strings, and dbt through a plugin. Rendering is a prerequisite for parsing, so any template the configured templater cannot resolve becomes a parse error rather than a lint finding. The repository also ships a Rust-backed parser and lexer as an optional extra, installed with the rs extra, which the README presents as an option rather than the default.

Installing SQLFluff and running a first lint

The README's getting-started section is four commands. Install the package, write a deliberately messy query to a file, and lint it against a named dialect. The dialect flag is required in this example and there is no default dialect implied by the snippet.

$ pip install sqlfluff
$ echo "  SELECT a  +  b FROM tbl;  " > test.sql
$ sqlfluff lint test.sql --dialect ansi

The output is a list of findings with line and position, a rule code, a message and a family tag. Expect the seven entries quoted in the README for this exact input, starting with LT01 for the double space before SELECT and ending with LT12 for the missing trailing newline, followed by the completion line.

If you want the optional Rust-backed parser and lexer, the README gives the extra form:

$ pip install sqlfluff[rs]

For a containerised run, the Dockerfile sets the image entrypoint to sqlfluff and the working directory to /sql, and its own comment gives the invocation pattern with a bind mount:

docker run --rm -it -v $PWD:/sql sqlfluff/sqlfluff:latest lint test.sql

Once lint output looks sane on a real file, the README points to sqlfluff fix as the second command in the workflow. Run it on a branch you can discard, because it rewrites files in place.

Where SQLFluff gets in the way

The templater is the sharp edge. Because SQLFluff renders before it parses, a macro it cannot resolve produces a parse error, and parse errors are not the same class of problem as a spacing complaint. If your dbt project depends on the dbt templater plugin, you are running dbt's rendering path inside your linter, which means the lint step inherits dbt's environment requirements: a profile, a target, and whatever credentials that target needs. The repository's docker-compose.yml reflects this, mounting test/fixtures/dbt/profiles_yml into /root/.dbt and passing POSTGRES_HOST and a Postgres service on port 5432 for development work. A lint job that needs a database connection to check whitespace is a real cost.

The second constraint is dialect coverage. The README is explicit that the listed dialects may not be supported in full, and it asks users to raise issues for missing syntax. Unsupported syntax shows up as a parse failure, not as a skipped rule, so a warehouse-specific construct can block linting on an otherwise clean file. The project's own guidance for adding dialect support is that pull requests from people who know the missing syntax are the best route, and that large feature changes should start with an issue.

Third, SQLFluff is a Python package with a parse step. That is a different performance profile from a text linter, and the README makes no throughput claims, so treat speed as something to measure on your own repository rather than assume.

SQLFluff compared with SQLFMT in dbt projects

The most common comparison in dbt shops is SQLFluff against sqlfmt, and the difference is architectural. sqlfmt is a formatter: it rewrites layout and stops there, and it does not need to parse your SQL against a warehouse dialect to do it. SQLFluff parses against a dialect and then applies rules, of which formatting is one family among several. That is why SQLFluff can report LT01 through LT12 on a single line while a formatter would simply rewrite the line.

The practical consequence is configuration surface. A formatter has few decisions to make. SQLFluff asks you to choose a dialect, choose a templater, and decide which rules are enabled, and each of those choices can be wrong in a way that produces noise. The upside is that a rule flagged as layout.spacing is a statement about a token in a syntax tree, which is why the same rule can be auto-fixed with reasonable confidence.

If your team only wants consistent whitespace and cannot spare a parse step in CI, a pure formatter is the smaller tool. If you want findings that distinguish a real syntax problem from a style problem, and you work in a templated codebase, the parse is the feature you are paying for.

Maintenance, licence and the cost of upgrading

The repository is not archived and the last push was on 2026-09-21. Releases are frequent and versioned: 4.3.0 on 2026-08-07, 4.2.2 on 2026-06-04, and 4.2.1 on 2026-05-14. The pyproject.toml declares version 4.3.0, requires Python 3.10 or newer, and classifies the project as Production/Stable with an MIT licence.

Two upgrade costs are visible in the repository files. First, Python version floor: requires-python is >=3.10, so an environment pinned below that cannot install current releases. Second, the Rust extra is optional and separately installed, which means an environment using sqlfluff[rs] has a second dependency to track alongside the Python package. The Dockerfile builds from python:3.14-slim-trixie and compiles requirements out of pyproject.toml with pip-compile, so the container path and the pip path can drift if you pin them differently.

The MIT licence permits commercial use and redistribution, and the repository ships LICENSE.md at the top level. That is a statement about the licence text, not legal advice; if you vendor SQLFluff into a product, read LICENSE.md and your own obligations rather than relying on the classifier in pyproject.toml.

Editors, CI and the pieces around the core tool

SQLFluff is not only a CLI. The repository contains an examples/ directory with six scripts, including 01_basic_api_usage.py, 03_getting_rules_and_dialects.py, 04_config_overrides.py and 06_full_parse_api.py. Those names describe the Python surface: you can list rules and dialects programmatically, override configuration in code, and reach the full parse tree. If you are building a custom check or wiring SQLFluff into a service, that is the entry point rather than shelling out to the binary.

For editors, the README points to a VS Code extension with its own repository and marketplace listing, maintained separately from the core project. For pre-commit users, the repository ships .pre-commit-hooks.yaml at the top level, which is what a pre-commit configuration would reference.

SQLFluff also appears in a broader ecosystem: the pyproject keywords list dbt and sqlmesh alongside the dialect names, and the README documents a Slack channel, a Twitter account, and a Gurubase assistant. None of those change the tool's behaviour, but they are where the project says to ask questions.

Editorial conclusion

Adopt SQLFluff if your SQL lives in dbt, Jinja or a warehouse dialect that plain text linters misread, and if you can afford a parse step in CI. Skip it if you only need keyword casing and whitespace on static ANSI files, where a regex-based tool is cheaper to run and configure. Before rolling it out, verify two things on your own repository: that the dialect you pass to --dialect is the one your warehouse actually accepts, and that the templater setting matches how your files are rendered. Run sqlfluff lint on a representative model with the templater you intend to use and read the parse errors before you enable sqlfluff fix in a pipeline.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. sqlfluff/sqlfluff on GitHub