Configuration¶

Settings for SQL dialect, indentation, capitalization, and other linting and style options are configured in a .sqruff, .sqruff.ini, sqruff.toml, or pyproject.toml file. SQLFluff's .sqlfluff format is also supported.

Global configuration and precedence¶

Use ~/.sqruff to set defaults for all projects, including projects outside your home directory. On Windows, ~ refers to your user profile directory. You can also put configuration in a user application config directory:

On every platform, an existing ~/.config/sqruff directory takes precedence over the platform-specific application config directory, matching SQLFluff's discovery behavior. Put a supported configuration file inside that directory, for example ~/.config/sqruff/.sqruff.

Configuration is merged in the following order, with later settings overriding earlier values individually:

1. Built-in defaults.
2. The user application config directory.
3. The user's home directory.
4. Ancestor directories between home (or its common ancestor with the target) and the configuration target.
5. The working directory and directories down to the configuration target.
6. An explicit file passed with --config.
7. Command-line overrides such as --dialect.

For files, each file sets its own configuration target, including files opened in the language server. Running sqruff fix . at a monorepo root therefore uses each subproject's dialect and style settings. Parent settings are inherited; nearer configurations override individual values rather than replacing the whole configuration. This also works when running from a project subdirectory or editing files in multiple VS Code workspace folders.

For stdin, --stdin-filename sets the configuration target. Each directory is checked for .sqlfluff, .sqruff, .sqruff.ini, pyproject.toml, and sqruff.toml, in that order; later files override earlier files in the same directory. Relative paths in settings are resolved from the configuration file's directory.

Use --ignore-local-config to skip discovery of global and project config files. Combine it with --config to use only that file and built-in defaults:

sqruff lint --ignore-local-config --config /path/to/config.cfg query.sql

Configuration files beside the executable can be selected using --config.

The following example highlights a few configuration points: setting the dialect to sqlite, turning on all rules except AM01 and AM02, and configuring some indentation settings. For a comprehensive list of configuration options, see the default configuration file. You can also refer to the rules documentation for more information on configuring specific rules.

[sqruff]
dialect = sqlite
exclude_rules = AM01,AM02
rules = all
sql_file_exts = .sql,.sql.j2,.dml,.ddl,.pkb

[sqruff:indentation]
indent_unit = space
tab_space_size = 4
indented_joins = True

The same configuration can be written in TOML:

[tool.sqlfluff.core]
dialect = "sqlite"
exclude_rules = ["AM01", "AM02"]
rules = "all"
sql_file_exts = ".sql,.sql.j2,.dml,.ddl,.pkb"

[tool.sqlfluff.indentation]
indent_unit = "space"
tab_space_size = 4
indented_joins = true

See sample configurations for more examples.

The warnings setting makes selected violations visible without causing lint to fail. It accepts either rule codes or rule names, for example warnings = LT01,layout.end_of_file.

Parser resource limits¶

Untrusted SQL can exhaust parser resources with deeply nested or unusually large query structures. Keep max_parse_depth and max_parse_nodes enabled when linting SQL from untrusted sources. Their defaults are 255 and 100000, respectively, and they limit parser nesting and parse-tree size. Projects with legitimately complex queries can raise either limit; setting a limit to 0 disables it.

Jinja branch variants¶

With templater = jinja, sqruff renders up to five branches of a template by default. Lint findings from those branches are combined, and compatible fixes from multiple branches can be applied to the source file. If a branch cannot be parsed, its parse error does not invalidate a different branch that can be parsed.

Set render_variant_limit under [sqruff] to change the maximum number of renderings. A value of 1 checks only the first rendering; higher values can increase templating and linting time.

[sqruff]
templater = jinja
render_variant_limit = 5

Implicit indents¶

Set implicit_indents in the indentation section to allow to accept implicit indents, or to require to collapse them. When using require, the skip_implicit_indents_in option excludes specific element types from collapsing and defaults to case_expression.

Aligning after leading punctuation¶

The leading:align-following line-position modifier aligns the element after a leading comma or binary operator with the surrounding expressions. For example:

[sqruff:layout:type:comma]
line_position = leading:align-following

With that configuration, this indentation is valid:

SELECT
   col_a AS a
 , col_b AS b
FROM foo;

The same modifier can be configured for binary_operator.

Finding segment types for layout configuration¶

A [sqruff:layout:type:<type>] section applies layout settings to segments in the parsed SQL tree. A segment can represent a whole clause, an expression, or a single token. For example, a FROM clause has type from_clause, while its FROM token has type keyword.

To browse the available names, open the dialect reference, find your dialect, and expand its Segment types list. Each list is generated from that dialect's reachable grammar and lexer, including inherited grammar, using its default configuration. The names are sorted and deduplicated; the list also includes internal and meta segments that may appear in a CST.

To find the types used by your SQL, inspect its concrete syntax tree (CST) with the same dialect you use for linting and fixing:

sqruff parse query.sql --dialect ansi

You can also read SQL from stdin:

echo 'SELECT a, b FROM example' | sqruff parse --dialect ansi -

The default output shows node labels and raw token text. For example, the tree for this query includes the following labels:

...
select_clause:
...
    comma: ','
...
from_clause:

Copy the label for the construct you want to configure into the section heading. For example, this puts commas at the beginning of a line when the surrounding SQL spans multiple lines:

[sqruff:layout:type:comma]
line_position = leading

Use --format json or --format yaml for structured CST output. Add --include-meta to include meta segments and source positions in those formats:

sqruff parse query.sql --dialect ansi --format json --include-meta

In the playground, select the Cst tool to inspect the same tree interactively.

Attaching operators to adjacent lines¶

The leading:attached and trailing:attached modifiers allow an operator in the middle of a line, but do not allow it on a line by itself. With trailing:attached, an operator before a line break stays with the preceding token; with leading:attached, it stays with the following token. For example:

[sqruff:layout:type:assignment_operator]
line_position = trailing:attached

For my_var := some_value, this permits either a single line or my_var := followed by some_value on the next line, but not a standalone :=, nor one at the start of the next line. Use leading:attached to require the opposite side of a line break instead.

Segment and keyword line positions¶

The line_position setting applies to a configured segment type as a whole, such as where a where_clause should break relative to the surrounding SQL. The keyword_line_position setting applies to the clause's leading keyword tokens, such as WHERE or ORDER BY, inside that segment.

For clause-like types, the settings are often used together. For example:

[sqruff:layout:type:where_clause]
line_position = alone
keyword_line_position = leading

This treats the WHERE clause as its own line-oriented block and requires the WHERE keyword to start a line. In the following SQL, line_position controls where the whole clause sits relative to FROM, while keyword_line_position controls where WHERE sits relative to its expression:

SELECT
    a
FROM t
WHERE b = 1
    AND c = 2

Setting keyword_line_position = alone instead puts the expression on the following line:

SELECT
    a
FROM t
WHERE
    b = 1
    AND c = 2

Keyword positioning also supports trailing placement. For example:

[sqruff:layout:type:join_on_condition]
keyword_line_position = trailing

This places the ON keyword at the end of the line, with the condition expression on the following line.

Keyword line position exclusions¶

LT14 supports keyword_line_position_exclusions, a comma-separated list of ancestor segment types whose keywords should be left in place. For example, keep ORDER BY inline inside window specifications and aggregate functions while requiring an outer ORDER BY to start a line:

[sqruff:layout:type:orderby_clause]
keyword_line_position = leading
keyword_line_position_exclusions = window_specification, aggregate_order_by

With this configuration, the following passes LT14:

SELECT
    ROW_NUMBER() OVER (PARTITION BY c ORDER BY d) AS e,
    STRING_AGG(a ORDER BY b, c)
FROM f
ORDER BY e

Writing FROM f ORDER BY e instead would fail LT14, which moves the outer ORDER BY onto a new line. The exclusions apply only inside the specified ancestor segments. Use keyword_line_position_exclusions = None to clear inherited exclusions and apply keyword positioning inside those segments too.