Introduction & Vision
Relevant source files
The following files were used as context for generating this wiki page:
SQLFluff is a dialect-flexible and highly configurable SQL linter and auto-fixer. It supports over 25 SQL dialects and integrates with modern data workflows, including Jinja templating and dbt. The project aims to improve SQL code quality by automating style enforcement, allowing developers to focus on logic rather than formatting.
The core vision focuses on providing a robust mechanism for measuring written SQL against a set of rules and fixing violations. While the project contains a comprehensive whitespace-aware parser, its primary purpose is to serve as a reliable linter that accommodates the diverse conventions of different organizations.
Sources: README.md:20-25, docsv/guide/vision.md:3-12, AGENTS.md:3-7
Core Architectural Components
SQLFluff operates through three primary functional layers: the parser, the linter, and the rules.
- The Parser: A generic, whitespace-aware component that unifies SQL from different dialects into a comparable format. It creates a segment-based Abstract Syntax Tree (AST) where every node is a
BaseSegment. - The Linter: The central engine that measures parsed SQL against defined rules. It identifies violations and can optionally apply
LintFixobjects to auto-correct code. - The Rules: An opinionated but flexible set of guidelines. Rules are implemented as Python classes that subclass
BaseRule.
System Architecture Flow
The following diagram illustrates the high-level data flow from raw SQL to linted and fixed output.
The diagram shows the sequential process of lexing, parsing into a segment tree, and the subsequent linting/fixing phase.
Sources: docsv/guide/vision.md:3-12, AGENTS.md:8-14
Vision and Success Criteria
The vision for SQLFluff is to become the industry-standard linter for SQL, particularly in ELT (Extract-Load-Transform) applications. Success is defined by improving team efficiency and code maintainability.
| Success Criterion | Description |
|---|---|
| Faster Collaboration | Shared codebases become easier to read, review, and build upon. |
| Easier Onboarding | Consistent styles across organizations reduce the learning curve for new members. |
| Shared SQL Adoption | Familiar formatting makes it easier to adopt and reuse open-source SQL. |
| Productive Discussions | Style guides are defined in code, enabling version-controlled style debates. |
Sources: docsv/usage/team-rollout.md:12-32, README.md:20-23
Project Principles
SQLFluff follows specific architectural and development principles to maintain its dialect flexibility and reliability.
Parser Design
The parser is designed to be permissive rather than a strict validator. It allows SQL that a database engine might reject, as its goal is to provide a "loose, allowable grammar" for linting purposes. Tightening grammar to reject invalid SQL is discouraged unless it prevents a valid construct from parsing correctly.
Sources: AGENTS.md:104-118
Layer Separation
The codebase enforces strict boundaries between layers. The core layer is isolated and cannot import from higher-level layers like api, cli, dialects, or rules. This ensures the infrastructure remains modular and maintainable.
Sources: AGENTS.md:86-91
Immuntability
Segments within the AST are immutable. Developers must never modify a segment instance directly; instead, they must use .copy() or the LintFix mechanism to propose changes to the tree.
Sources: AGENTS.md:93-96
Community and Development
SQLFluff is maintained by a community of volunteers. Major features are organized into "Major Releases" via GitHub issues, while small bug fixes are handled more flexibly. The project values documentation as a critical component, requiring all public functions to have type annotations and Google-style docstrings.
The sequence diagram outlines the standard contribution and review process enforced by the project.
Sources: CONTRIBUTING.md:46-60, docsv/development/documentation.md:27-32, AGENTS.md:133-138
Summary
The Introduction & Vision of SQLFluff centers on providing a dialect-agnostic toolset for SQL quality. By separating the technical challenges of parsing from the organizational challenges of style enforcement, SQLFluff enables teams to maintain high-quality data pipelines. The project's commitment to permissiveness in parsing and strictness in architectural layers ensures it remains adaptable to the evolving landscape of SQL dialects.
Sources: docsv/guide/vision.md:14-25, AGENTS.md:3-14