SQLFluff 入门指南The SQL Linter for Humans——多方言 SQL 代码检查与自动格式化实战【免费下载链接】sqlfluffA modular SQL linter and auto-formatter with support for multiple dialects and templated code.项目地址: https://gitcode.com/GitHub_Trending/sq/sqlfluffSQLFluff 是一个可扩展、模块化的 SQL linter代码检查工具旨在帮助开发者写出规范的 SQL并在 SQL 进入数据库之前提前发现错误与坏味道。本文以官方文档 docs/source/index.rst 为骨架结合仓库内安装指南、CLI 源码与默认配置完整覆盖从安装、lint、fix 到自定义配置的实战路径并深入讲解其多方言解析与模板化代码支持的核心原理。读完本文你将能独立完成 SQLFluff 的安装部署、命令行使用、规则修复与团队级配置落地。SQLFluff 的口号是The SQL Linter for Humans——为人类打造的 SQL 检查器。它解决的问题非常现实当你切换不同的数据库方言、面对被 Jinja/dbt 模板化之后的不再是合法 SQL的文件时传统 lint 工具往往束手无策。SQLFluff 的设计目标正是与方言无关、可配置、能理解模板代码让代码检查前移到 CI/CD 流水线中而不是等到生产环境才暴露问题。一、SQLFluff 为什么值得用质量保证与模块化在 docs/source/why_sqlfluff.rst 中官方阐述了项目的两大立足点质量保证Quality Assurance。随着团队规模扩大、SQL 代码库日益庞大代码不仅需要正确更需要易读。保证可读性的最有效手段之一是强制一致的风格而执行这一工作的工具就是 linter。正如软件社区的 flake8、jslintSQLFluff 的目标是在 SQL 领域填补这一空白。模块化Modularity。SQL 本身并不擅长模块化实践中通常通过模板化来引入灵活性与可复用性常见方式有两种使用编程语言内置的格式化语法例如 Python 的 format 字符串SELECT {foo} FROM {tbl}.format(foobar, tblmytable) # 求值结果为SELECT bar FROM mytable使用专用模板库如 Jinja2支持更强大的表达式与宏dbt、Apache Airflow 等工具底层也往往内嵌了 Jinja2 类模板引擎。问题在于模板化之后SQL 文件里充满了占位符与模板指令文件本身不再是合法的 SQL普通 linter 无法解析。SQLFluff 同时支持上述两种模板化方式以及 dbt 项目从而让这些动态 SQL 文件也能在 CI/CD 阶段被检查而非等到生产环境那可能已经太晚。关于模板参数dummy parameters的关键实践针对模板代码SQLFluff 需要额外信息才能把模板解释为合法 SQL。做法是在配置文件中提供虚拟参数dummy parameters。代入模板后这些值应当能求值为合法 SQL以便 SQLFluff 检查风格、格式与正确性但不必与生产环境的真实值一致。官方明确建议使用尽可能简单、只要能让代码求值为合法 SQL 的虚拟值这样配置可以保持最精简。详细配置方法见 docs/source/configuration/templating/index.rst。二、版本演进1.0 到 4.0 的关键里程碑docs/source/index.rst 列出了几个 Notable releases重要版本理解它们有助于你判断升级路径版本线核心变化1.0.x首个**稳定stable**版本利用相对稳定的时间点发布无重大功能变更2.0.x规则rules全面重写、空白修复逻辑整合、新增sqlfluff format命令并移除对 dbt1.1以下版本的支持带来了规则编写与配置层面的破坏性变更3.0.xsqlfluff fix默认不再询问确认删除--force选项sqlfluff lint返回更丰富的信息但输出结构与此前版本不同4.0.x首个引入可选 Rust 例程的版本。安装sqlfluff[rs]将包含 Rust 实现的解析与词法例程更完整的发布记录见 docs/source/reference/releasenotes.rst。三、30 秒快速上手官方文档给出的快速起步只有三步安装、造一个测试文件、运行 lint。$ pip install sqlfluff $ echo SELECT a b FROM tbl; test.sql $ sqlfluff lint test.sql --dialect ansi [test.sql] FAIL L: 1 | P: 1 | LT01 | Expected only single space before SELECT keyword. | Found . [layout.spacing] L: 1 | P: 1 | LT02 | First line should not be indented. | [layout.indent] L: 1 | P: 1 | LT13 | Files must not begin with newlines or whitespace. | [layout.start_of_file] L: 1 | P: 11 | LT01 | Expected only single space before binary operator . | Found . [layout.spacing] L: 1 | P: 14 | LT01 | Expected only single space before naked identifier. | Found . [layout.spacing] L: 1 | P: 27 | LT01 | Unnecessary trailing whitespace at end of file. | [layout.spacing] L: 1 | P: 27 | LT12 | Files must end with a single trailing newline. | [layout.end_of_file] All Finished !仅凭这一条命令SQLFluff 就发现了 7 处问题多余空格、首行缩进、文件首尾空白等每一条都带有行号L、列号P、规则编号如 LT01/LT02与规则分类如layout.spacing。这也直观体现了检查结果足够人性化的设计理念。四、完整安装指南从 Python 到 Rust 扩展详细安装步骤见 docs/source/gettingstarted.rst。4.1 准备 Python 环境SQLFluff 需要 Python 与 pip。注意Python 2 支持已于 2020 年初移除请选择以 3 开头的版本。在 src/sqlfluff/init.py 中可以看到运行时强校验低于 Python 3.10 会直接抛出异常。$ python --version Python 3.13.1 $ pip --version pip 25.3 from ...4.2 安装 SQLFluff$ pip install sqlfluff如需可选的Rust 后端解析器与词法器安装rsextra$ pip install sqlfluff[rs]在受支持的 CPython 3.10 平台上这会安装预构建的 ABI3 wheel若当前平台/架构/Python 实现没有对应 wheelpip 会回退到从源码构建sqlfluffrs此时需要 Rust 工具链推荐通过 rustup 安装与可用的原生构建工具链。仓库中的 Rust 实现位于 sqlfluffrs/ 目录对应的 Python 绑定见 src/sqlfluff/core/parser/rust_parser.py。安装后验证版本$ sqlfluff version 4.3.0该命令的实现位于 src/sqlfluff/cli/commands.py-v时还会输出详细配置。五、核心实战lint 与 fix 的完整走查沿用 docs/source/gettingstarted.rst 的经典示例创建test.sqlSELECT ab AS foo, c AS bar from my_table执行 lint$ sqlfluff lint test.sql --dialect ansi [test.sql] FAIL L: 1 | P: 1 | LT09 | Select targets should be on a new line unless there is | only one select target. | [layout.select_targets] L: 1 | P: 1 | ST06 | Select wildcards then simple targets before calculations | and aggregates. [structure.column_order] L: 1 | P: 7 | LT02 | Expected line break and indent of 4 spaces before a. | [layout.indent] L: 1 | P: 9 | LT01 | Expected single whitespace between naked identifier and | binary operator . [layout.spacing] L: 1 | P: 10 | LT01 | Expected single whitespace between binary operator | and naked identifier. [layout.spacing] L: 1 | P: 11 | LT01 | Expected only single space before AS keyword. Found | . [layout.spacing] L: 2 | P: 1 | LT02 | Expected indent of 4 spaces. | [layout.indent] L: 2 | P: 9 | LT02 | Expected line break and no indent before from. | [layout.indent] L: 2 | P: 10 | CP01 | Keywords must be consistently upper case. | [capitalisation.keywords] All Finished !每个违规都包含L:行号、P:列号、规则 ID 与人类可读描述。例如L: 1 | P: 9的 LT01 告诉我们ab中两侧缺少空格。5.1 手工修复后复检修复两侧空格SELECT a b AS foo, c AS bar from my_table再次 lintLT01 相关报错消失剩余问题集中在缩进LT02、关键字大小写CP01、select 目标换行LT09与列排序ST06。5.2 使用 fix 自动修复并非所有规则都能自动修复但对于许多简单场景sqlfluff fix是一个很好的起点。先只修复指定的三条规则$ sqlfluff fix test.sql --rules LT02,LT12,CP01 --dialect ansi finding fixable violations [test.sql] FAIL L: 1 | P: 7 | LT02 | Expected line break and indent of 4 spaces before a. | [layout.indent] L: 2 | P: 1 | LT02 | Expected indent of 4 spaces. | [layout.indent] L: 2 | P: 9 | LT02 | Expected line break and no indent before FROM. | [layout.indent] L: 2 | P: 10 | CP01 | Keywords must be consistently upper case. | [capitalisation.keywords] [test.sql] FIXED 4 fixable linting violations found打开test.sql内容已经变化SELECT a b AS foo, c AS bar FROM my_table可以看到两个列被缩进以体现处于SELECT语句内部FROM关键字被大写以匹配其他关键字。若不指定--rules则会修复所有可修复的问题$ sqlfluff fix test.sql --dialect ansi finding fixable violations [test.sql] FAIL L: 1 | P: 1 | ST06 | Select wildcards then simple targets before calculations | and aggregates. [structure.column_order] L: 2 | P: 10 | LT01 | Expected only single space before AS keyword. Found | . [layout.spacing] [test.sql] FIXED 2 fixable linting violations found最终文件变为完全符合 SQLFluff 全部规则风格的 SQLSELECT c AS bar, a b AS foo FROM my_table六、自定义配置.sqlfluff文件实战默认风格未必符合你的团队约定。假设我们希望缩进改为 2 个空格、关键字全部小写可以在当前目录创建.sqlfluff配置文件[sqlfluff] dialect ansi [sqlfluff:indentation] tab_space_size 2 [sqlfluff:rules:capitalisation.keywords] capitalisation_policy lower然后重新执行修复$ sqlfluff fix test.sql --rules LT02,LT12,CP01,ST06,LT09,LT01文件被按新约定修复select c as bar, a b as foo from my_table配置采用分层覆盖机制只设置需要改动的项其余沿用默认值。完整配置项见 docs/source/configuration/default_configuration.rst各规则的专属配置见 docs/source/reference/rules.rst 中每条规则文档的 Configuration 小节。七、默认配置深度解读仓库内default_config.cfg关键参数配置文件的基础默认值定义在 src/sqlfluff/core/default_config.cfg理解这些默认值对排查问题很有帮助配置项默认值说明dialectNone目标方言可通过sqlfluff dialects查看全部支持的方言templaterjinja模板引擎可选raw、jinja、python、placeholderrulesall要检查的规则列表逗号分隔exclude_rulesNone要排除的规则列表max_line_length80与 dbt 风格指南保持一致设为零或负数可禁用检查tab_space_size4一个 Tab 折算的空格数indentation段indent_unitspace缩进单位space/tabmax_parse_depth600最大解析深度语法 括号嵌套防止深层嵌套 SQL 引发 DoSmax_parse_nodes100000最终解析树的最大节点数large_file_skip_byte_limit20000超大文件跳过检查的字节上限设为 0 禁用sql_file_exts.sql,.sql.j2,.dml,.ddl,.pkb参与 lint 的文件扩展名render_variant_limit5Jinja 模板最多渲染 5 个变体用于 lint 多个分支use_rust_parserauto是否使用 Rust 解析器auto表示可用时启用processes1lint 使用的 CPU 进程数ignore/warningsNone按类别忽略lexing/linting/parsing/templating或将违规降级为警告encodingautodetect文件编码fix_even_unparsableFalse是否允许对含解析错误的文件执行 fix官方不推荐开启可能损坏 SQL这些参数既支持全局配置文件也支持通过 CLI 的--config覆盖或环境变量注入详见 docs/source/configuration/setting_configuration.rst。八、多方言支持与模板支持全景8.1 方言支持从 README.md 可知SQLFluff 以 ANSI SQL 为基础方言并支持可能并非全部特性以下方言Athena、BigQuery、ClickHouse、Databricks扩展自 sparksql增加 Unity Catalog 语法、Db2、Doris、DuckDB、Exasol、FlinkSQL、Greenplum、Hive、Impala、MariaDB、Materialize、MySQL、Oracle、PostgreSQL、Redshift、Snowflake、SOQL、SparkSQL、SQLite、StarRocks、Teradata、T-SQL、Trino、Vertica。每个方言对应仓库 src/sqlfluff/dialects/ 下的dialect_name.py与配套关键字文件并通过继承与覆盖扩展基础方言。可用sqlfluff dialects命令实时查看当前安装支持的全部方言实现见 src/sqlfluff/cli/commands.py。8.2 模板支持SQLFluff 支持以下模板引擎Jinja即 Jinja2默认模板器SQL 占位符例如 SQLAlchemy 参数Python format 字符串dbt需要安装插件仓库内实现位于 plugins/sqlfluff-templater-dbt/。对应源码在 src/sqlfluff/core/templaters/ 目录各模板器的行为差异与参数配置详见 docs/source/configuration/templating/index.rst。九、架构视角Parser、Linter 与 Rules 三组件docs/source/why_sqlfluff.rst 的 Vision for SQLFluff 一节明确了项目的三个核心组件Parser解析器通用 SQL 解析器目标是能把不同方言书写的 SQL 统一为可比较的格式。官方坦言代码库中占比最大的是解析器因为开发 SQLFluff 时市场上缺少可用的空白感知whitespace-aware解析器。它位于 src/sqlfluff/core/parser/。Linter检查器将 SQL 与一组规则进行度量的机制并能修复发现的违规。核心实现在 src/sqlfluff/core/linter/。Rules规则集一组关于 SQL 结构组织的**有主见opinionated**的指南。项目承认许多组织已有强烈的既有约定因此规则必须足够灵活以支持用户自定义规则集。规则实现分布在 src/sqlfluff/rules/ 下的layout、capitalisation、structure、aliasing、references等子目录中。核心愿景是把 linter 做到极致。从 CLI 源码看lint、fix、parse、render、rules、dialects、version等命令全部在 src/sqlfluff/cli/commands.py 中实现同时 src/sqlfluff/init.py 还暴露了 Python APIlint、fix、parse、list_rules、list_dialects可编程调用示例见 examples/01_basic_api_usage.py。十、继续深入下一步可以探索什么入门之后官方文档 docs/source/gettingstarted.rst 建议从以下几点继续理解解析结果使用sqlfluff parse命令查看 SQLFluff 如何解释你的文件可用sqlfluff --help或sqlfluff parse --help查看帮助批量检查直接传目录而非单文件例如sqlfluff lint .检查当前目录所有 SQL 文件或sqlfluff lint path/to/my/sqlfiles规则总览完整的规则说明见 docs/source/reference/rules.rst可用sqlfluff rules查看当前生效规则团队落地准备在项目或团队内推广时阅读 docs/source/guides/setup/teamrollout.rst团队推广指南、docs/source/production/pre_commit.rstpre-commit 集成、docs/source/production/cli_use.rstCI 使用与 docs/source/production/diff_quality.rstdiff 质量门禁社区与案例想了解别人如何在实际项目中应用 SQLFluff可查阅 docs/source/inthewild.rst参与社区见 docs/source/jointhecommunity.rst。最后提醒SQLFluff 是一个相对年轻且持续活跃开发的项目使用中可能遇到 bug 或奇怪行为遇到问题时最有效的做法是向维护者提交 issue项目仓库位于GitHub_Trending/sq/sqlfluff可直接git clone后查看。总体而言从一条pip install命令到完整的团队级 SQL 风格治理SQLFluff 提供了从能用到好用的完整闭环值得每个重度使用 SQL 的团队纳入工具链。【免费下载链接】sqlfluffA modular SQL linter and auto-formatter with support for multiple dialects and templated code.项目地址: https://gitcode.com/GitHub_Trending/sq/sqlfluff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 SQLFluff 入门指南：The SQL Linter for Humans——多方言 SQL 代码检查与自动格式化实战
SQLFluff 入门指南The SQL Linter for Humans——多方言 SQL 代码检查与自动格式化实战【免费下载链接】sqlfluffA modular SQL linter and auto-formatter with support for multiple dialects and templated code.项目地址: https://gitcode.com/GitHub_Trending/sq/sqlfluffSQLFluff 是一个可扩展、模块化的 SQL linter代码检查工具旨在帮助开发者写出规范的 SQL并在 SQL 进入数据库之前提前发现错误与坏味道。本文以官方文档 docs/source/index.rst 为骨架结合仓库内安装指南、CLI 源码与默认配置完整覆盖从安装、lint、fix 到自定义配置的实战路径并深入讲解其多方言解析与模板化代码支持的核心原理。读完本文你将能独立完成 SQLFluff 的安装部署、命令行使用、规则修复与团队级配置落地。SQLFluff 的口号是The SQL Linter for Humans——为人类打造的 SQL 检查器。它解决的问题非常现实当你切换不同的数据库方言、面对被 Jinja/dbt 模板化之后的不再是合法 SQL的文件时传统 lint 工具往往束手无策。SQLFluff 的设计目标正是与方言无关、可配置、能理解模板代码让代码检查前移到 CI/CD 流水线中而不是等到生产环境才暴露问题。一、SQLFluff 为什么值得用质量保证与模块化在 docs/source/why_sqlfluff.rst 中官方阐述了项目的两大立足点质量保证Quality Assurance。随着团队规模扩大、SQL 代码库日益庞大代码不仅需要正确更需要易读。保证可读性的最有效手段之一是强制一致的风格而执行这一工作的工具就是 linter。正如软件社区的 flake8、jslintSQLFluff 的目标是在 SQL 领域填补这一空白。模块化Modularity。SQL 本身并不擅长模块化实践中通常通过模板化来引入灵活性与可复用性常见方式有两种使用编程语言内置的格式化语法例如 Python 的 format 字符串SELECT {foo} FROM {tbl}.format(foobar, tblmytable) # 求值结果为SELECT bar FROM mytable使用专用模板库如 Jinja2支持更强大的表达式与宏dbt、Apache Airflow 等工具底层也往往内嵌了 Jinja2 类模板引擎。问题在于模板化之后SQL 文件里充满了占位符与模板指令文件本身不再是合法的 SQL普通 linter 无法解析。SQLFluff 同时支持上述两种模板化方式以及 dbt 项目从而让这些动态 SQL 文件也能在 CI/CD 阶段被检查而非等到生产环境那可能已经太晚。关于模板参数dummy parameters的关键实践针对模板代码SQLFluff 需要额外信息才能把模板解释为合法 SQL。做法是在配置文件中提供虚拟参数dummy parameters。代入模板后这些值应当能求值为合法 SQL以便 SQLFluff 检查风格、格式与正确性但不必与生产环境的真实值一致。官方明确建议使用尽可能简单、只要能让代码求值为合法 SQL 的虚拟值这样配置可以保持最精简。详细配置方法见 docs/source/configuration/templating/index.rst。二、版本演进1.0 到 4.0 的关键里程碑docs/source/index.rst 列出了几个 Notable releases重要版本理解它们有助于你判断升级路径版本线核心变化1.0.x首个**稳定stable**版本利用相对稳定的时间点发布无重大功能变更2.0.x规则rules全面重写、空白修复逻辑整合、新增sqlfluff format命令并移除对 dbt1.1以下版本的支持带来了规则编写与配置层面的破坏性变更3.0.xsqlfluff fix默认不再询问确认删除--force选项sqlfluff lint返回更丰富的信息但输出结构与此前版本不同4.0.x首个引入可选 Rust 例程的版本。安装sqlfluff[rs]将包含 Rust 实现的解析与词法例程更完整的发布记录见 docs/source/reference/releasenotes.rst。三、30 秒快速上手官方文档给出的快速起步只有三步安装、造一个测试文件、运行 lint。$ pip install sqlfluff $ echo SELECT a b FROM tbl; test.sql $ sqlfluff lint test.sql --dialect ansi [test.sql] FAIL L: 1 | P: 1 | LT01 | Expected only single space before SELECT keyword. | Found . [layout.spacing] L: 1 | P: 1 | LT02 | First line should not be indented. | [layout.indent] L: 1 | P: 1 | LT13 | Files must not begin with newlines or whitespace. | [layout.start_of_file] L: 1 | P: 11 | LT01 | Expected only single space before binary operator . | Found . [layout.spacing] L: 1 | P: 14 | LT01 | Expected only single space before naked identifier. | Found . [layout.spacing] L: 1 | P: 27 | LT01 | Unnecessary trailing whitespace at end of file. | [layout.spacing] L: 1 | P: 27 | LT12 | Files must end with a single trailing newline. | [layout.end_of_file] All Finished !仅凭这一条命令SQLFluff 就发现了 7 处问题多余空格、首行缩进、文件首尾空白等每一条都带有行号L、列号P、规则编号如 LT01/LT02与规则分类如layout.spacing。这也直观体现了检查结果足够人性化的设计理念。四、完整安装指南从 Python 到 Rust 扩展详细安装步骤见 docs/source/gettingstarted.rst。4.1 准备 Python 环境SQLFluff 需要 Python 与 pip。注意Python 2 支持已于 2020 年初移除请选择以 3 开头的版本。在 src/sqlfluff/init.py 中可以看到运行时强校验低于 Python 3.10 会直接抛出异常。$ python --version Python 3.13.1 $ pip --version pip 25.3 from ...4.2 安装 SQLFluff$ pip install sqlfluff如需可选的Rust 后端解析器与词法器安装rsextra$ pip install sqlfluff[rs]在受支持的 CPython 3.10 平台上这会安装预构建的 ABI3 wheel若当前平台/架构/Python 实现没有对应 wheelpip 会回退到从源码构建sqlfluffrs此时需要 Rust 工具链推荐通过 rustup 安装与可用的原生构建工具链。仓库中的 Rust 实现位于 sqlfluffrs/ 目录对应的 Python 绑定见 src/sqlfluff/core/parser/rust_parser.py。安装后验证版本$ sqlfluff version 4.3.0该命令的实现位于 src/sqlfluff/cli/commands.py-v时还会输出详细配置。五、核心实战lint 与 fix 的完整走查沿用 docs/source/gettingstarted.rst 的经典示例创建test.sqlSELECT ab AS foo, c AS bar from my_table执行 lint$ sqlfluff lint test.sql --dialect ansi [test.sql] FAIL L: 1 | P: 1 | LT09 | Select targets should be on a new line unless there is | only one select target. | [layout.select_targets] L: 1 | P: 1 | ST06 | Select wildcards then simple targets before calculations | and aggregates. [structure.column_order] L: 1 | P: 7 | LT02 | Expected line break and indent of 4 spaces before a. | [layout.indent] L: 1 | P: 9 | LT01 | Expected single whitespace between naked identifier and | binary operator . [layout.spacing] L: 1 | P: 10 | LT01 | Expected single whitespace between binary operator | and naked identifier. [layout.spacing] L: 1 | P: 11 | LT01 | Expected only single space before AS keyword. Found | . [layout.spacing] L: 2 | P: 1 | LT02 | Expected indent of 4 spaces. | [layout.indent] L: 2 | P: 9 | LT02 | Expected line break and no indent before from. | [layout.indent] L: 2 | P: 10 | CP01 | Keywords must be consistently upper case. | [capitalisation.keywords] All Finished !每个违规都包含L:行号、P:列号、规则 ID 与人类可读描述。例如L: 1 | P: 9的 LT01 告诉我们ab中两侧缺少空格。5.1 手工修复后复检修复两侧空格SELECT a b AS foo, c AS bar from my_table再次 lintLT01 相关报错消失剩余问题集中在缩进LT02、关键字大小写CP01、select 目标换行LT09与列排序ST06。5.2 使用 fix 自动修复并非所有规则都能自动修复但对于许多简单场景sqlfluff fix是一个很好的起点。先只修复指定的三条规则$ sqlfluff fix test.sql --rules LT02,LT12,CP01 --dialect ansi finding fixable violations [test.sql] FAIL L: 1 | P: 7 | LT02 | Expected line break and indent of 4 spaces before a. | [layout.indent] L: 2 | P: 1 | LT02 | Expected indent of 4 spaces. | [layout.indent] L: 2 | P: 9 | LT02 | Expected line break and no indent before FROM. | [layout.indent] L: 2 | P: 10 | CP01 | Keywords must be consistently upper case. | [capitalisation.keywords] [test.sql] FIXED 4 fixable linting violations found打开test.sql内容已经变化SELECT a b AS foo, c AS bar FROM my_table可以看到两个列被缩进以体现处于SELECT语句内部FROM关键字被大写以匹配其他关键字。若不指定--rules则会修复所有可修复的问题$ sqlfluff fix test.sql --dialect ansi finding fixable violations [test.sql] FAIL L: 1 | P: 1 | ST06 | Select wildcards then simple targets before calculations | and aggregates. [structure.column_order] L: 2 | P: 10 | LT01 | Expected only single space before AS keyword. Found | . [layout.spacing] [test.sql] FIXED 2 fixable linting violations found最终文件变为完全符合 SQLFluff 全部规则风格的 SQLSELECT c AS bar, a b AS foo FROM my_table六、自定义配置.sqlfluff文件实战默认风格未必符合你的团队约定。假设我们希望缩进改为 2 个空格、关键字全部小写可以在当前目录创建.sqlfluff配置文件[sqlfluff] dialect ansi [sqlfluff:indentation] tab_space_size 2 [sqlfluff:rules:capitalisation.keywords] capitalisation_policy lower然后重新执行修复$ sqlfluff fix test.sql --rules LT02,LT12,CP01,ST06,LT09,LT01文件被按新约定修复select c as bar, a b as foo from my_table配置采用分层覆盖机制只设置需要改动的项其余沿用默认值。完整配置项见 docs/source/configuration/default_configuration.rst各规则的专属配置见 docs/source/reference/rules.rst 中每条规则文档的 Configuration 小节。七、默认配置深度解读仓库内default_config.cfg关键参数配置文件的基础默认值定义在 src/sqlfluff/core/default_config.cfg理解这些默认值对排查问题很有帮助配置项默认值说明dialectNone目标方言可通过sqlfluff dialects查看全部支持的方言templaterjinja模板引擎可选raw、jinja、python、placeholderrulesall要检查的规则列表逗号分隔exclude_rulesNone要排除的规则列表max_line_length80与 dbt 风格指南保持一致设为零或负数可禁用检查tab_space_size4一个 Tab 折算的空格数indentation段indent_unitspace缩进单位space/tabmax_parse_depth600最大解析深度语法 括号嵌套防止深层嵌套 SQL 引发 DoSmax_parse_nodes100000最终解析树的最大节点数large_file_skip_byte_limit20000超大文件跳过检查的字节上限设为 0 禁用sql_file_exts.sql,.sql.j2,.dml,.ddl,.pkb参与 lint 的文件扩展名render_variant_limit5Jinja 模板最多渲染 5 个变体用于 lint 多个分支use_rust_parserauto是否使用 Rust 解析器auto表示可用时启用processes1lint 使用的 CPU 进程数ignore/warningsNone按类别忽略lexing/linting/parsing/templating或将违规降级为警告encodingautodetect文件编码fix_even_unparsableFalse是否允许对含解析错误的文件执行 fix官方不推荐开启可能损坏 SQL这些参数既支持全局配置文件也支持通过 CLI 的--config覆盖或环境变量注入详见 docs/source/configuration/setting_configuration.rst。八、多方言支持与模板支持全景8.1 方言支持从 README.md 可知SQLFluff 以 ANSI SQL 为基础方言并支持可能并非全部特性以下方言Athena、BigQuery、ClickHouse、Databricks扩展自 sparksql增加 Unity Catalog 语法、Db2、Doris、DuckDB、Exasol、FlinkSQL、Greenplum、Hive、Impala、MariaDB、Materialize、MySQL、Oracle、PostgreSQL、Redshift、Snowflake、SOQL、SparkSQL、SQLite、StarRocks、Teradata、T-SQL、Trino、Vertica。每个方言对应仓库 src/sqlfluff/dialects/ 下的dialect_name.py与配套关键字文件并通过继承与覆盖扩展基础方言。可用sqlfluff dialects命令实时查看当前安装支持的全部方言实现见 src/sqlfluff/cli/commands.py。8.2 模板支持SQLFluff 支持以下模板引擎Jinja即 Jinja2默认模板器SQL 占位符例如 SQLAlchemy 参数Python format 字符串dbt需要安装插件仓库内实现位于 plugins/sqlfluff-templater-dbt/。对应源码在 src/sqlfluff/core/templaters/ 目录各模板器的行为差异与参数配置详见 docs/source/configuration/templating/index.rst。九、架构视角Parser、Linter 与 Rules 三组件docs/source/why_sqlfluff.rst 的 Vision for SQLFluff 一节明确了项目的三个核心组件Parser解析器通用 SQL 解析器目标是能把不同方言书写的 SQL 统一为可比较的格式。官方坦言代码库中占比最大的是解析器因为开发 SQLFluff 时市场上缺少可用的空白感知whitespace-aware解析器。它位于 src/sqlfluff/core/parser/。Linter检查器将 SQL 与一组规则进行度量的机制并能修复发现的违规。核心实现在 src/sqlfluff/core/linter/。Rules规则集一组关于 SQL 结构组织的**有主见opinionated**的指南。项目承认许多组织已有强烈的既有约定因此规则必须足够灵活以支持用户自定义规则集。规则实现分布在 src/sqlfluff/rules/ 下的layout、capitalisation、structure、aliasing、references等子目录中。核心愿景是把 linter 做到极致。从 CLI 源码看lint、fix、parse、render、rules、dialects、version等命令全部在 src/sqlfluff/cli/commands.py 中实现同时 src/sqlfluff/init.py 还暴露了 Python APIlint、fix、parse、list_rules、list_dialects可编程调用示例见 examples/01_basic_api_usage.py。十、继续深入下一步可以探索什么入门之后官方文档 docs/source/gettingstarted.rst 建议从以下几点继续理解解析结果使用sqlfluff parse命令查看 SQLFluff 如何解释你的文件可用sqlfluff --help或sqlfluff parse --help查看帮助批量检查直接传目录而非单文件例如sqlfluff lint .检查当前目录所有 SQL 文件或sqlfluff lint path/to/my/sqlfiles规则总览完整的规则说明见 docs/source/reference/rules.rst可用sqlfluff rules查看当前生效规则团队落地准备在项目或团队内推广时阅读 docs/source/guides/setup/teamrollout.rst团队推广指南、docs/source/production/pre_commit.rstpre-commit 集成、docs/source/production/cli_use.rstCI 使用与 docs/source/production/diff_quality.rstdiff 质量门禁社区与案例想了解别人如何在实际项目中应用 SQLFluff可查阅 docs/source/inthewild.rst参与社区见 docs/source/jointhecommunity.rst。最后提醒SQLFluff 是一个相对年轻且持续活跃开发的项目使用中可能遇到 bug 或奇怪行为遇到问题时最有效的做法是向维护者提交 issue项目仓库位于GitHub_Trending/sq/sqlfluff可直接git clone后查看。总体而言从一条pip install命令到完整的团队级 SQL 风格治理SQLFluff 提供了从能用到好用的完整闭环值得每个重度使用 SQL 的团队纳入工具链。【免费下载链接】sqlfluffA modular SQL linter and auto-formatter with support for multiple dialects and templated code.项目地址: https://gitcode.com/GitHub_Trending/sq/sqlfluff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考