SQLFluff 2.0: Reorganisation of Linting Rules

Until now, SQLFluff’s rules have been added fairly organically, as members of the community implemented the checks they needed. Each new rule received the next available Lxxx code. That meant the rules were effectively in chronological order: the number reflected when a rule was added, rather than what it checked.

That was a reasonable way to start, but it became less useful as the project grew. Related rules could be quite far apart in the list, and understanding a configuration file often meant looking up several codes before you could work out what it was doing. It also differed from the named rules and categories used by other linting tools.

By 2.0, the set of rules had stabilised enough for us to identify useful groupings. We’ve reorganised them around those groups and given each rule a name. This changes how rules are referenced in configuration, which is the main reason for making it a major release.

Rule names and grouped codes

The old L010 becomes CP01, named capitalisation.keywords. The code is still short enough for terminal output or a review comment, while the prefix identifies the group. The name describes what the rule checks.

Related checks sit together: CP02 is capitalisation.identifiers and CP03 is capitalisation.functions. The same approach applies to aliasing (AL), layout (LT), references (RF) and the other rule families.

The intention is to make it easier to refer to a rule without needing to remember its number. It also gives us a more consistent way to organise the configuration for related checks.

Changes to configuration

Rule-specific configuration sections now use the rule’s name, rather than its old code. For example, this 1.x configuration:

[sqlfluff:rules:L010]
capitalisation_policy = upper

becomes:

[sqlfluff:rules:capitalisation.keywords]
capitalisation_policy = upper

The setting itself hasn’t changed in this example; only the section heading has. In 2.0, unrecognised rule configuration sections raise warnings and their settings are ignored. This means you need to use the full rule name here, rather than simply replacing L010 with CP01 in the heading.

Rule selection is more flexible. In rules and exclude_rules, you can use names, grouped codes or group names. For example, to select the capitalisation checks, replace:

[sqlfluff]
rules = L010, L014, L030, L040, L063

with:

[sqlfluff]
rules = capitalisation

In 2.0 that group selects CP01 through CP05. A group expresses an ongoing policy, so future rules added to it may also be selected when you upgrade. Use individual names or codes when you want an explicit list.

Legacy codes remain supported as aliases for selecting rules, so these references don’t all need to change immediately. However, some old rules have been combined, so an alias may now select a broader set of checks. It’s worth reviewing those references as part of the upgrade.

Rule code migration table

The table maps legacy codes to the grouped codes introduced in 2.0. It is organised by the new rule families so related changes are easy to find. For rule names, options and behaviour in the version you’re using, consult the current rules reference. Run sqlfluff rules to inspect the rules available in your installed version.

Why the layout mappings aren’t all one-to-one

The layout work also consolidated checks that had grown separately around different pieces of SQL. Nine spacing rules now map to LT01, while three indentation rules map to LT02. This lets one consistent layout configuration describe how SQL should look, instead of scattering related settings across several checks.

For example, L005 checked for spaces before commas, L008 checked for a single space after them, and L006 checked spacing around operators. These are now all handled by LT01 (layout.spacing). The associated configuration is organised by the type of SQL element: [sqlfluff:layout:type:comma] can specify spacing_before = touch, meaning no space before a comma, while the same layout configuration system describes spacing around operators and other elements. This separates the choice of which checks to run from the description of the layout they should enforce, rather than requiring a separate rule and set of options for each spacing convention.

For example, selecting the legacy L005 now selects LT01, which checks much more than spacing around commas. Review the resulting scope instead of treating every alias as an exact replacement. The layout configuration guide explains the available controls and their current behaviour.

Updating an existing project

Start with your configuration file and remove settings that merely repeat the defaults. Then update rule selections in rules or exclude_rules, and rename rule-specific sections to use full names. Check in-file configuration directives for old references too.

Pay particular attention to layout settings and the many-to-one mappings above. Lint a representative set of files, read any configuration warnings, and review the changes before applying fixes across the project. Where several settings express the same intention, consider whether a group or a shared layout setting would make that easier to maintain.

See the 2.0 migration guide and rule configuration documentation for the detailed upgrade steps. For everything else included in the release, including contributor credits, see the 2.0.0 changelog.