SQLFluff 是什么
SQLFluff 是可配置的 SQL 检查与格式化工具：把 SQL 解析成语法树后按规则检查风格与结构，支持自动修复。必须指定方言（--dialect，如 postgres、mysql、bigquery），因为不同方言的关键字与语法差异很大。规则以字母数字编号，布局类规则前缀为 LT。它解决的是格式与结构一致性问题，不能替代逻辑评审。
基本信息
| 方言 | --dialect 必须指定（postgres / mysql / bigquery 等） |
|---|---|
| 规则 | 编号规则，布局类前缀 LT（如 LT01 空白、LT02 缩进） |
| 修复 | sqlfluff fix 自动处理部分问题 |
| 模板 | 默认 jinja 模板器；dbt 项目可切 dbt 模板器 |
| 配置 | .sqlfluff 文件声明方言、规则与排除路径 |
典型使用场景
- 迁移脚本与建表语句入库前统一格式，评审只看逻辑不争格式
- CI 中检查新增 SQL 文件，命中即失败
- dbt 或自研数仓项目：用 dbt 模板器先渲染再检查
- 把方言相关的写法问题提前暴露，减少上生产才发现的语法差异
- 用 fix 批量规整历史 SQL，再人工复核 diff
- 多套方言并存时按目录分别配置：同一个仓库里 Postgres 与 MySQL 脚本各用一份配置
用法
用法
sqlfluff lint migrations/ --dialect postgres
sqlfluff fix migrations/ --dialect postgres
sqlfluff lint --dialect mysql --format json reports/ # 结构化输出
sqlfluff parse query.sql --dialect postgres # 排查模板渲染问题
# .sqlfluff 片段
# [sqlfluff]
# dialect = postgres
# templater = jinja常用命令
| 命令 | 作用 | 使用建议 |
|---|---|---|
| lint | 检查规则违规 | CI 门禁用，可输出 JSON |
| fix | 自动修复可修项 | 修复后人工看一遍 diff |
| parse | 打印语法树 | 模板渲染出错时用它定位 |
| --dialect | 指定 SQL 方言 | 必填，写进配置文件更省事 |
| --exclude-rules | 排除指定规则 | 对生成 SQL 目录单独配置 |
方言明确后误报率会明显下降：把方言猜错（例如把 BigQuery 的写法按 Postgres 检查）会产生大量看似莫名其妙的告警，团队很快就对结果失去信任。把它当成格式一致性工具，不要指望它替代逻辑评审。
对生成的 SQL 目录直接 lint 会得到一堆无法修复的告警：先把生成物排除，或为这些目录使用独立配置，避免真实问题被淹没。