1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
.. _ruleconfig:
Rule Configuration
------------------
Rules can be configured with the :code:`.sqlfluff` config files.
Common rule configurations can be set in the :code:`[sqlfluff:rules]` section.
For example:
.. code-block:: cfg
[sqlfluff:rules]
allow_scalar = True
single_table_references = consistent
unquoted_identifiers_policy = all
Rule specific configurations are set in rule specific subsections.
For example, enforce that keywords are upper case by configuring the rule
:sqlfluff:ref:`CP01`:
.. code-block:: cfg
[sqlfluff:rules:capitalisation.keywords]
# Keywords
capitalisation_policy = upper
All possible options for rule sections are documented in :ref:`ruleref`.
For an overview of the most common rule configurations that you may want to
tweak, see :ref:`defaultconfig` (and use :ref:`ruleref` to find the
available alternatives).
.. _ruleselection:
Enabling and Disabling Rules
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The decision as to which rules are applied to a given file is applied on a file
by file basis, by the effective configuration for that file. There are two
configuration values which you can use to set this:
* :code:`rules`, which explicitly *enables* the specified rules. If this
parameter is unset or empty for a file, this implies "no selection" and
so "all rules" is taken to be the meaning.
* :code:`exclude_rules`, which explicitly *disables* the specified rules.
This parameter is applied *after* the :code:`rules` parameter so can be
used to *subtract* from the otherwise enabled set.
Each of these two configuration values accept a comma separated list of
*references*. Each of those references can be:
* a rule *code* e.g. :code:`LN01`
* a rule *name* e.g. :code:`layout.indent`
* a rule *alias*, which is often a deprecated *code* e.g. :code:`L003`
* a rule *group* e.g. :code:`layout` or :code:`capitalisation`
These different references can be mixed within a given expression, which
results in a very powerful syntax for selecting exactly which rules are
active for a given file.
.. note::
It's worth mentioning here that the application of :code:`rules` and
:code:`exclude_rules`, with *groups*, *aliases* and *names*, in projects
with potentially multiple nested configuration files defining different
rules for different areas of a project can get very confusing very fast.
While this flexibility is intended for users to take advantage of, we do
have some recommendations about how to do this is a way that remains
manageable.
When considering configuration inheritance, each of :code:`rules` and
:code:`exclude_rules` will totally overwrite any values in parent config
files if they are set in a child file. While the subtraction operation
between both of them is calculated *"per file"*, there is no combination
operation between two definitions of :code:`rules` (just one overwrites
the other).
The effect of this is that we recommend one of two approaches:
#. Simply only use :code:`rules`. This has the upshot of each area of
your project being very explicit in which rules are enabled. When
that changes for part of your project you just reset the whole list
of applicable rules for that part of the project.
#. Set a single :code:`rules` value in your master project config file
and then only use :code:`exclude_rules` in sub-configuration files
to *turn off* specific rules for parts of the project where those
rules are inappropriate. This keeps the simplicity of only having
one value which is inherited, but allows slightly easier and simpler
rollout of new rules because we manage by exception.
For example, to disable the rules :sqlfluff:ref:`LT08`
and :sqlfluff:ref:`RF02`:
.. code-block:: cfg
[sqlfluff]
exclude_rules = LT08, RF02
To enable individual rules, configure :code:`rules`, respectively.
For example, to enable :sqlfluff:ref:`RF02`:
.. code-block:: cfg
[sqlfluff]
rules = RF02
Rules can also be enabled/disabled by their grouping. Right now, the only
rule grouping is :code:`core`. This will enable (or disable) a select group
of rules that have been deemed 'core rules'.
.. code-block:: cfg
[sqlfluff]
rules = core
More information about 'core rules' can be found in the :ref:`ruleref`.
Additionally, some rules have a special :code:`force_enable` configuration
option, which allows to enable the given rule even for dialects where it is
disabled by default. The rules that support this can be found in the
:ref:`ruleref`.
The default values can be seen in :ref:`defaultconfig`.
See :ref:`ignoreconfig` for more information on how to turn ignore particular
rules for specific lines, sections or files.
Downgrading rules to warnings
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To keep displaying violations for specific rules, but not have those
issues lead to a failed run, rules can be downgraded to *warnings*.
Rules set as *warnings* won't cause a file to fail, but will still
be shown in the CLI to warn users of their presence.
The configuration of this behaves very like :code:`exclude_rules`
above:
.. code-block:: cfg
[sqlfluff]
warnings = LT01, LT04
With this configuration, files with no other issues (other than
those set to warn) will pass. If there are still other issues, then
the file will still fail, but will show both warnings and failures.
.. code-block::
== [test.sql] PASS
L: 2 | P: 9 | LT01 | WARNING: Missing whitespace before +
== [test2.sql] FAIL
L: 2 | P: 8 | CP02 | Unquoted identifiers must be consistently upper case.
L: 2 | P: 11 | LT01 | WARNING: Missing whitespace before +
This is particularly useful as a transitional tool when considering
the introduction on new rules on a project where you might want to
make users aware of issues without blocking their workflow (yet).
You can use either rule code or rule name for this setting.
Layout & Spacing Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The :code:`[sqlfluff:layout]` section of the config controls the
treatment of spacing and line breaks across all rules. To understand
more about this section, see the section of the docs dedicated to
layout: :ref:`layoutconfig`.
|
