Configuration System
Relevant source files
The following files were used as context for generating this wiki page:
The Configuration System manages settings for the SQLFluff linter, including dialects, templating, and rule enforcement. It merges discovered configuration files, command-line arguments, and in-file directives into a unified internal representation used throughout the linting pipeline.
The system relies on the FluffConfig object, which threads through the core logic to provide consistent settings for lexing, parsing, and rule evaluation. Settings are organized in a nested dictionary structure where keys often reflect the hierarchy found in configuration files like .sqlfluff or pyproject.toml.
Sources: docsv/configuration/index.md, docsv/scripts/generate-internals-docs.py:34-45, src/sqlfluff/AGENTS.md:144-150
Configuration Hierarchy and Loading
SQLFluff utilizes a multi-layered nesting strategy to resolve configuration. Files closer to the target SQL file override values from parent directories. The system searches for specific filenames in a defined order and patches the configuration object at each step.
File Loading Priority
SQLFluff looks for the following files in order of increasing priority:
setup.cfgtox.inipep8.ini.sqlfluffpyproject.toml
Sources: docsv/configuration/index.md:9-15
Nested Resolution Flow
The system resolves settings by traversing the directory structure from the system level down to the individual file level.
The diagram shows the priority of configuration sources, where each step overrides or patches the previous values. Sources: docsv/configuration/index.md:104-124
Core Loading Functions
The sqlfluff.core.config.loader module provides functions for building the configuration dictionary.
| Function | Description |
|---|---|
load_config_string | Builds a config dict from a raw string. |
load_config_file | Loads a config dict from a specific file path. |
load_config_resource | Loads built-in configuration resources. |
load_config_up_to_path | Recursively loads configs from a path up to the root. |
Sources: docsv/scripts/generate-internals-docs.py:186-191
Configuration Formats
SQLFluff supports INI-style and TOML-style configurations. Internally, these formats are converted into a nested dictionary where subsections are delimited by specific characters.
INI and CFG Format
In .sqlfluff, setup.cfg, and tox.ini, sections start with sqlfluff and use colons for nesting.
[sqlfluff:rules:capitalisation.keywords]
capitalisation_policy = lower
This converts to {"rules": {"capitalisation.keywords": {"capitalisation_policy": "lower"}}}.
Sources: docsv/configuration/index.md:17-43, docsv/scripts/generate-internals-docs.py:46-55
TOML Format
In pyproject.toml, sections start with tool.sqlfluff and use dots for nesting.
[tool.sqlfluff.rules.capitalisation.keywords]
capitalisation_policy = "upper"
Sources: docsv/configuration/index.md:45-72
Rule Configuration and Selection
The configuration system determines which rules are active for a specific file through explicit inclusion, exclusion, and group selection.
Selection Parameters
rules: Explicitly enables specific rules or groups. If empty, all rules are enabled.exclude_rules: Explicitly disables specific rules, subtracted from the enabled set.warnings: Downgrades specific rules to warnings, allowing the linter to pass even if violations occur.
Sources: docsv/configuration/rules.md:21-36, docsv/configuration/rules.md:88-95
Rule References
Selection lists accept various reference types:
- Code: Unique ID like
LT01. - Name: Full name like
layout.indent. - Alias: Deprecated codes like
L003. - Group: Category identifiers like
layoutorcapitalisation.
Sources: docsv/configuration/rules.md:38-43
In-File Configuration Directives
SQLFluff supports comment-based directives within SQL files to modify settings locally. These directives are parsed in an initial step before full parsing and apply to the entire file.
-- sqlfluff:indentation:indented_joins:True
-- sqlfluff:rules:capitalisation.keywords:capitalisation_policy:upper
Sources: docsv/configuration/index.md:128-149
The FluffConfig Object
The FluffConfig class is the primary data structure for configuration. It is immutable by design and should be copied using .from_root() or .copy() when modifications are required.
from sqlfluff.core import FluffConfig
# Loading config from the project root
config = FluffConfig.from_root(overrides={"dialect": "snowflake"})
Sources: src/sqlfluff/AGENTS.md:144-150, docsv/scripts/generate-internals-docs.py:34-40
Implementation Summary
The configuration system ensures that project-wide standards are maintained while allowing for granular overrides at the directory or file level.
| Component | Responsibility |
|---|---|
loader.py | Handles the physical reading and parsing of file formats into dicts. |
FluffConfig | Merges dicts and provides a queryable interface for other modules. |
ini.py | Logic for parsing .sqlfluff and other INI-style files. |
defaults.md | Documents the baseline settings applied before any user overrides. |
Sources: docsv/scripts/generate-internals-docs.py:183-195, docsv/configuration/defaults.md:1-25