SQLFluff 配置完全指南配置文件、嵌套层级与文件内配置指令【免费下载链接】sqlfluffA modular SQL linter and auto-formatter with support for multiple dialects and templated code.项目地址: https://gitcode.com/GitHub_Trending/sq/sqlfluffSQLFluff 是一个模块化的 SQL 检查器linter与自动格式化工具支持多种方言与模板化代码。配置是使用 SQLFluff 的核心环节——无论是选择方言、指定模板引擎还是控制具体规则的启停与参数都通过一套统一的配置体系完成。读完本文你将掌握 SQLFluff 的两种配置途径命令行与配置文件、五种配置文件格式及其优先级、嵌套配置的分层覆盖规则以及仅在单个文件内生效的注释式配置指令能够独立搭建一套贴合团队规范的 SQL 配置体系。配置的两种途径命令行与配置文件SQLFluff 的配置既可以来自命令行参数也可以来自配置文件两者之间存在大致对等的关系。唯一的例外是模板templating配置——模板相关的配置只能通过配置文件完成因为模板配置涉及上下文context、宏macros等复杂结构不适合放在命令行中表达。命令行的可用选项参见仓库中的 CLI 文档 docs/source/production/cli_use.rst 与命令实现 src/sqlfluff/cli/commands.py。在源码中命令行选项通过--config、--dialect、--templater、--rules、--exclude-rules等参数传入最终以overrides的形式注入配置对象FluffConfig的overrides参数会覆盖所有来自文件的值参见 src/sqlfluff/core/config/fluffconfig.py 中_configs nested_combine(defaults, configs, overrides)的合并顺序。配置文件格式与加载顺序对于基于文件的配置SQLFluff 会按以下顺序查找下列文件后找到的文件会覆盖先找到文件中的同名值setup.cfgtox.inipep8.ini.sqlfluffpyproject.toml这一顺序在源码中有直接体现src/sqlfluff/core/config/loader.py 中的filename_options列表正是按此优先级排列注释明确写着later in this list overwrites earlier并且在遍历时把前一步加载的configs传入下一步进行合并# The potential filenames we would look for at this path. # NB: later in this list overwrites earlier filename_options [ setup.cfg, tox.ini, pep8.ini, .sqlfluff, pyproject.toml, ]因此如果同一目录下同时存在.sqlfluff和pyproject.toml后者的值会胜出。需要说明的是这些文件都不是必须存在的——没有任何配置文件SQLFluff 也能以默认配置工作。cfg 风格文件.sqlfluff / setup.cfg / tox.ini / pep8.ini前四种文件按 Pythoncfg格式INI 风格解析。SQLFluff 只关心以sqlfluff开头的 section子 section 用冒号分隔。例如jinjacontextsection 写作[sqlfluff:jinjacontext]。以下是.sqlfluff或任意受支持的 cfg 风格文件的示例片段[sqlfluff] templater jinja sql_file_exts .sql,.sql.j2,.dml,.ddl,.pkb [sqlfluff:indentation] indented_joins False indented_using_on True template_blocks_indent False [sqlfluff:templater] unwrap_wrapped_queries True [sqlfluff:templater:jinja] apply_dbt_builtins True # Custom Jinja delimiters (optional, defaults shown) # variable_start_string {{ # variable_end_string }} # block_start_string {% # block_end_string %} # comment_start_string {# # comment_end_string #}从 src/sqlfluff/core/config/ini.py 的实现可以看到几个关键细节根 section[sqlfluff]会被内部重命名为core与其它配置文件保持一致大小写敏感与大多数 cfg 读取器不同SQLFluff 读取配置时保持大小写敏感通过覆写optionxform实现这是为了兼容 Jinja 本身的大小写敏感性值类型自动转换coerce_value会把true/false转为布尔值、把数字字符串转为int/float、把none转为None其余保持字符串见 ini.py配置项名中的点号会被拆分为嵌套结构例如[sqlfluff:templater:jinja:context]下的namespace.projectname test会生成{namespace: {projectname: test}}的嵌套字典这正是 Jinja 上下文中传入命名空间变量的方式。pyproject.toml 文件对于pyproject.toml所有有效 section 都以tool.sqlfluff开头子 section 用点号分隔。例如jinjacontextsection 写作[tool.sqlfluff.jinjacontext]。[tool.sqlfluff.core] templater jinja sql_file_exts .sql,.sql.j2,.dml,.ddl,.pkb [tool.sqlfluff.indentation] indented_joins false indented_using_on true template_blocks_indent false [tool.sqlfluff.templater] unwrap_wrapped_queries true [tool.sqlfluff.templater.jinja] apply_dbt_builtins true # Custom Jinja delimiters (optional, defaults shown) # variable_start_string {{ # variable_end_string }} # block_start_string {% # block_end_string %} # comment_start_string {# # comment_end_string #} # For rule specific configuration, use dots between the names exactly # as you would in .sqlfluff. In the background, SQLFluff will unpack the # configuration paths accordingly. [tool.sqlfluff.rules.capitalisation.keywords] capitalisation_policy upperTOML 解析实现在 src/sqlfluff/core/config/toml.py。值得注意的一个特例是rulessection规则名本身常含点号如capitalisation.keywordsTOML 会把点号解释为嵌套 section因此load_toml_file_config会专门对rules部分做一次压缩处理_condense_rule_record把{rules: {capitalisation: {keywords: {...}}}}重新合并为{rules: {capitalisation.keywords: {...}}}从而与.sqlfluff中点号分隔的规则路径保持一致。新项目推荐的最小化配置搭建新项目时官方建议配置文件尽量精简。配置文件应作为团队的一种文档——记录你关于 SQL 格式化所作出的决策。只定义与默认值不同的配置项能更清晰地让团队了解你做出的取舍。不过默认配置有一部分是为存量项目设计的而非全新项目。因此新项目有机会采用比现有代码库更严格的配置。仓库提供了一份适合新项目的 starter 配置docs/source/_partials/starter_config.cfg完整内容如下[sqlfluff] # Supported dialects https://docs.sqlfluff.com/en/stable/perma/dialects.html # Or run sqlfluff dialects dialect snowflake # One of [raw|jinja|python|placeholder] templater jinja # Comma separated list of rules to exclude, or None # See https://docs.sqlfluff.com/en/stable/perma/rule_disabling.html # AM04 (ambiguous.column_count) and ST06 (structure.column_order) are # two of the more controversial rules included to illustrate usage. exclude_rules ambiguous.column_count, structure.column_order # The standard max_line_length is 80 in line with the convention of # other tools and several style guides. Many projects however prefer # something a little longer. # Set to zero or negative to disable checks. max_line_length 120 # CPU processes to use while linting. # The default is single threaded to allow easy debugging, but this # is often undesirable at scale. # If positive, just implies number of processes. # If negative or zero, implies number_of_cpus - specified_number. # e.g. -1 means use all processors but one. 0 means all cpus. processes -1 # If using the dbt templater, we recommend setting the project dir. [sqlfluff:templater:dbt] project_dir ./ [sqlfluff:indentation] # While implicit indents are not enabled by default. Many of the # SQLFluff maintainers do use them in their projects. implicit_indents allow [sqlfluff:rules:aliasing.length] min_alias_length 3 # The default configuration for capitalisation rules is consistent # which will auto-detect the setting from the rest of the file. This # is less desirable in a new project and you may find this (slightly # more strict) setting more useful. # Typically we find users rely on syntax highlighting rather than # capitalisation to distinguish between keywords and identifiers. # Clearly, if your organisation has already settled on uppercase # formatting for any of these syntax elements then set them to upper. [sqlfluff:rules:capitalisation.keywords] capitalisation_policy lower [sqlfluff:rules:capitalisation.identifiers] extended_capitalisation_policy lower [sqlfluff:rules:capitalisation.functions] extended_capitalisation_policy lower [sqlfluff:rules:capitalisation.literals] capitalisation_policy lower [sqlfluff:rules:capitalisation.types] extended_capitalisation_policy lower # The default configuration for the not equal convention rule is consistent # which will auto-detect the setting from the rest of the file. This # is less desirable in a new project and you may find this (slightly # more strict) setting more useful. [sqlfluff:rules:convention.not_equal] # Default to preferring the c_style (i.e. !) preferred_not_equal_style c_style这份配置的要点dialect snowflakestarter 以 Snowflake 为例实际应按项目使用的数据库修改。可用sqlfluff dialects命令查看全部受支持的方言列表。templater jinja模板引擎可选值为raw | jinja | python | placeholder。raw不处理模板jinja渲染 Jinja 模板python运行 Python 模板代码placeholder仅替换占位符。exclude_rules以逗号分隔需要排除的规则可写规则码如AM04或规则名如ambiguous.column_count。这里示范排除了两个较有争议的规则ambiguous.column_countAM04与structure.column_orderST06。max_line_length 120默认 80 是沿袭其它工具与多种风格指南的惯例但很多项目偏好更长设为 0 或负数可禁用长度检查。processes -1并行 lint 进程数。默认为单线程便于调试大规模场景通常不够用。正数表示进程数负数或 0 表示CPU 数 - 指定值例如-1表示使用全部 CPU 减一0表示使用全部 CPU。注意默认配置见下文中该值实际为1。[sqlfluff:templater:dbt]的 project_dir若使用 dbt 模板器建议显式设置 dbt 项目目录dbt 模板器以独立包sqlfluff-templater-dbt分发。implicit_indents allow隐式缩进默认不启用但很多 SQLFluff 维护者在自己的项目中会开启。aliasing.length / min_alias_length 3强制表别名至少 3 个字符。大小写规则从 consistent 收紧为 lower默认的consistent策略会从文件其余部分自动检测大小写风格对新项目而言不够严格若团队已统一为大写可改为upper。上述各项参数的默认值都可以在打包的默认配置 src/sqlfluff/core/default_config.cfg 中核对例如max_line_length 80、processes 1、templater jinja、implicit_indents forbid、capitalisation_policy consistent、preferred_not_equal_style consistent等。嵌套配置Nesting配置的分层覆盖SQLFluff 在配置文件上使用嵌套机制距离更近的配置文件会覆盖或者说修补其它文件中的值。最终生效的配置是所有从当前路径向上逐级加载的配置文件值的拼接结果。这个设计让配置管理非常高效尤其适合大量使用复杂模板的项目——例如可以在项目根目录统一设置模板配置再在某个子目录中针对特定场景覆盖个别参数。你不需要任何配置文件也能让 SQLFluff 正常工作。但如果想覆盖某些值SQLFluff 会按以下位置依次查找后面步骤的值覆盖前面步骤其实不算数的一步SQLFluff 包内自带的默认配置。可以在 src/sqlfluff/core/default_config.cfg 中查看覆盖了核心参数、缩进、布局、模板器与全部规则的默认值。用户操作系统特定的应用配置目录。macOS 与 Unix 下为~/.config/sqlfluffWindows 下为home\AppData\Local\sqlfluff\sqlfluff查找上文列出的各种文件名如果存在多个文件按前述顺序互相覆盖。用户主目录~下的同名配置文件。仅当当前工作目录是用户主目录的子目录时查找用户主目录~到当前工作目录之间所有中间目录中的同名配置文件。当前工作目录下的同名配置文件。仅当被解析的文件位于当前工作目录的子目录中时查找当前工作目录到文件所在目录之间每个子目录中的同名配置文件。被 lint 文件所在目录下的同名配置文件。这一分层逻辑在 src/sqlfluff/core/config/loader.py 的load_config_up_to_path中实现它依次加载 appdir 配置、用户主目录配置、主目录到目标路径之间的父目录配置、工作目录到目标路径之间的配置以及可选的额外配置路径extra_config_path最后通过nested_combine按后加载者优先逐层合并return nested_combine( user_appdir_config, user_config, *parent_config_stack, *config_stack, extra_config, )每次通过load_config_at_path加载时都会在单个路径内按pyproject.toml.sqlfluffpep8.initox.inisetup.cfg的优先级解析且结果带缓存cache让同一路径的配置在多个文件之间复用避免重复读盘。嵌套配置的例外templater嵌套机制有一个例外templater的值不能在当前工作目录子目录的配置文件中设置。也就是说模板引擎的选择只能在更上游的位置如用户配置、主目录、当前工作目录本身确定子目录的配置文件无法改变它。这是为了保证整个 lint 过程中模板渲染行为的一致性。文件内配置指令In-File Configuration Directives除了上述配置文件SQLFluff 还支持基于注释的配置切换让某个 SQL 文件在自身内部修改默认配置以满足其特定需求。这类指令作用于整个文件并且会在文件其余部分正式解析之前的初始步骤中被提取出来。这意味着它们既可以用于规则配置也可以用于解析parsing配置——例如在文件内修改方言。使用语法要求以内联 SQL 注释开头注释内容以sqlfluff起始即-- sqlfluff随后用冒号分隔的地址指明要设置的配置项路径。常见示例-- Set Indented Joins -- sqlfluff:indentation:indented_joins:True -- Set a smaller indent for this file -- sqlfluff:indentation:tab_space_size:2 -- Set keywords to be capitalised -- sqlfluff:rules:capitalisation.keywords:capitalisation_policy:upper SELECT * FROM a JOIN b USING(c)官方建议只对单独一个文件适用的配置使用这种注释方式涉及项目某个区域或整个项目的配置变更应使用前文介绍的配置文件嵌套机制。该指令的底层实现在 src/sqlfluff/core/config/fluffconfig.py 中核心是process_inline_config与process_raw_file_for_config两个方法process_raw_file_for_config逐行扫描原始 SQL 文本识别以-- sqlfluff或--sqlfluff带或不带空格均可开头的行process_inline_config剥离--与sqlfluff:前缀用split_colon_separated_string将剩余部分拆成配置路径与值两部分单段路径如dialect会被自动放入coresection即根[sqlfluff]section与普通配置文件的行为一致值同样经过coerce_value做类型转换True/2等会被转为布尔/整数如果设置的是dialect还会即时重新初始化方言对象处理完所有指令后会重新校验rules/exclude_rules等逗号分隔值并复查 Rust 解析器相关配置的一致性。这种冒号语法与文件中忽略错误的注释语法-- noqa非常相似关于忽略错误的配置可参考 docs/source/configuration/ignoring_configuration.rst。从源码看配置的读取与校验链路综合以上内容一条配置从磁盘到生效的完整链路如下文件发现load_config_at_pathloader.py按优先级列表发现并加载目录内的配置文件load_config_up_to_path负责跨目录逐层收集。格式解析.sqlfluff等 INI 风格文件走 src/sqlfluff/core/config/ini.py大小写敏感 值类型强转 点号嵌套pyproject.toml走 src/sqlfluff/core/config/toml.py含rules点号压缩与 TOML 语法错误的友好提示。合并与校验FluffConfig.__init__fluffconfig.py将插件提供的默认配置、文件配置、CLI overrides 三者按优先级合并调用validate_config_dict校验未知配置项并完成方言对象与模板器对象的实例化。按文件生效lint 每个文件时通过make_child_from_path生成子配置配合文件内配置指令process_raw_file_for_config最终确定该文件的实际配置。如果对配置中具体规则参数的默认值与取值范围感兴趣可以在 src/sqlfluff/core/default_config.cfg 中逐一查询CLI 与各规则、模板器的具体行为分别参见 docs/source/reference/cli.rst、docs/source/configuration/rule_configuration.rst 与 docs/source/configuration/templating/index.rst。【免费下载链接】sqlfluffA modular SQL linter and auto-formatter with support for multiple dialects and templated code.项目地址: https://gitcode.com/GitHub_Trending/sq/sqlfluff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考