SQLFluff — Modular SQL Linter and Auto-Formatter

Introduction

SQLFluff is an open-source SQL linter that brings the same code-quality discipline to SQL that ESLint brings to JavaScript. It parses, analyzes, and auto-fixes SQL files across many dialects, helping data teams enforce consistent formatting in version-controlled analytics repos.

What SQLFluff Does

• Lints SQL files against configurable rules for style and correctness
• Auto-fixes violations with a single command
• Supports 20+ dialects including PostgreSQL, BigQuery, Snowflake, Redshift, and SparkSQL
• Integrates with CI pipelines, pre-commit hooks, and dbt projects
• Provides a templating layer to handle Jinja and dbt macros

Architecture Overview

SQLFluff parses SQL into an abstract syntax tree using dialect-specific grammars. Each rule inspects tree nodes and emits lint violations with optional fix patches. The fix engine applies non-conflicting patches in a single pass; conflicting fixes require multiple passes. A plugin system allows third-party rules.

Self-Hosting & Configuration

• Install via pip: pip install sqlfluff
• Configure with .sqlfluff file in your project root
• Set dialect: [sqlfluff] dialect = bigquery
• Exclude rules: [sqlfluff:rules] exclude_rules = L011,L031
• Integrate with pre-commit by adding the sqlfluff hook entry

Key Features

• Over 60 built-in lint rules covering indentation, aliasing, joins, and naming
• Dialect-aware parsing handles syntax differences correctly
• Jinja and dbt templating support for analytics SQL
• Configurable via TOML or INI-style config files
• Plugin architecture for custom rules

Comparison with Similar Tools

• sqlfmt — opinionated formatter with fewer configuration options
• pg_format — PostgreSQL-only, no lint rules
• sql-formatter — JavaScript library focused on pretty-printing, no linting
• dbt SQLFluff plugin — extends SQLFluff with dbt-aware templating
• SonarQube SQL — enterprise tool with broader scope but commercial licensing

FAQ

Q: Does SQLFluff work with dbt projects? A: Yes. It has built-in dbt templating support and can parse Jinja macros before linting.

Q: Can I use SQLFluff in CI? A: Yes. Run sqlfluff lint --format github-annotation for inline PR comments in GitHub Actions.

Q: How do I ignore a specific violation? A: Add -- noqa: L042 as an inline comment on the offending line.

Q: Does it support BigQuery and Snowflake? A: Yes, both are first-class supported dialects with dedicated grammar files.

Sources

• https://github.com/sqlfluff/sqlfluff
• https://docs.sqlfluff.com/