1工具概述
SQLFluff 是什么？
SQLFluff 是一款开源的 SQL Linter 和 Formatter，类似于 Python 的 flake8 或 JavaScript 的 ESLint，但专门针对 SQL 语言。
核心能力：
• 语法检查（Lint）：检测 SQL 中的风格问题和潜在错误
• 自动格式化（Fix）：一键修复不符合规范的 SQL 代码
• 多方言支持：MySQL、PostgreSQL、Oracle、BigQuery、Snowflake 等 20+ 种方言
• 规则丰富：内置 60+ 条规则，覆盖缩进、命名、关键字大小写、JOIN 写法等
• CI/CD 友好：可直接集成到 GitHub Actions、GitLab CI 等流水线中
为什么需要 SQL Linter？
• 团队协作时 SQL 风格不统一，代码审查效率低
• 手动检查 SQL 规范耗时且容易遗漏
• 不规范的 SQL 可能隐藏性能问题（如 SELECT *、缺少 WHERE 条件）
• 新人入职缺乏统一的编码规范参考
GitHub Stars：7k+
开源协议：MIT
开发语言：Python
2安装与配置
安装方式：
1. pip 安装（推荐）
pip install sqlfluff
2. 指定方言插件安装
pip install sqlfluff-templater-dbt # 如需 dbt 支持
3. Docker 运行
docker run -it --rm -v $(pwd):/sql sqlfluff/sqlfluff:latest lint /sql
配置文件（.sqlfluff）：
项目根目录创建 .sqlfluff 文件，常用配置：
[sqlfluff]
dialect = mysql
templater = raw
max_line_length = 120
[sqlfluff:indentation]
indented_joins = true
indented_using_on = true
indent_unit = space
tab_space_size = 4
[sqlfluff:rules:capitalisation.keywords]
capitalisation_policy = upper
[sqlfluff:rules:capitalisation.identifiers]
capitalisation_policy = lower
[sqlfluff:rules:capitalisation.functions]
extended_capitalisation_policy = upper
配置优先级：
命令行参数 > 项目 .sqlfluff > 用户目录 ~/.sqlfluff > 默认配置
常用方言设置：
• MySQL：dialect = mysql
• PostgreSQL：dialect = postgres
• Oracle：dialect = oracle
• BigQuery：dialect = bigquery
3基本用法
三个核心命令：
1. sqlfluff lint — 检查 SQL 问题
sqlfluff lint query.sql
sqlfluff lint src/sql/ --dialect mysql
输出示例：
== [query.sql] FAIL
L: 1 | P: 1 | LT01 | Expected only single space before 'SELECT'.
L: 3 | P: 10 | CP01 | Keywords must be upper case.
L: 5 | P: 1 | LT02 | Expected indent of 4 spaces.
2. sqlfluff fix — 自动修复问题
sqlfluff fix query.sql
sqlfluff fix src/sql/ --dialect mysql --force
• --force 跳过确认直接修复
• 部分规则无法自动修复，需手动处理
3. sqlfluff parse — 解析 SQL 语法树
sqlfluff parse query.sql
• 调试复杂 SQL 解析问题时有用
• 输出 SQL 的抽象语法树（AST）
常用参数：
• --dialect：指定 SQL 方言
• --exclude-rules：排除特定规则
• --rules：只检查特定规则
• --ignore：忽略指定模式的文件
• -f human / json / github-annotation：输出格式
行内忽略注释：
SELECT * -- noqa: AM04
FROM users;
• -- noqa 忽略当前行所有规则
• -- noqa: AM04 忽略指定规则
• -- noqa: disable=AM04 忽略该行之后的指定规则
4核心规则详解
SQLFluff 规则按类别分组，以下是最重要的规则：
1. 布局规则（LT）
• LT01：多余的空格
• LT02：缩进不正确
• LT04：逗号位置（行首 vs 行尾）
• LT09：SELECT 目标一行一个
• LT12：文件末尾换行
2. 大小写规则（CP）
• CP01：关键字大小写不一致
• CP02：标识符大小写不一致
• CP03：函数名大小写不一致
3. 别名规则（AL）
• AL01：表别名不使用 AS 关键字
• AL02：列别名不使用 AS 关键字
• AL05：未使用的表别名
4. 结构规则（ST）
• ST06：SELECT 通配符（SELECT *）
• ST07：USING 替代 ON（适用时）
• ST08：DISTINCT 用法
5. 反模式规则（AM）
• AM04：查询中使用 COUNT 而非 EXISTS
• AM05：JOIN 条件放在 ON 中而非 WHERE
6. 引用规则（RF）
• RF01：FROM 子句中未引用的列
• RF03：单表查询使用了限定名
自定义规则配置示例：
[sqlfluff:rules:layout.long_lines]
max_line_length = 120
[sqlfluff:rules:aliasing.table]
aliasing = explicit
[sqlfluff:rules:structure.subquery]
forbid_subquery_in = both
5CI/CD 集成
GitHub Actions 集成：
创建 .github/workflows/sql-lint.yml：
name: SQL Lint
on:
pull_request:
paths: ['**/*.sql']
jobs:
sqlfluff:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.11'
- run: pip install sqlfluff
- run: sqlfluff lint sql/ --dialect mysql -f github-annotation
关键点：
• 只在 SQL 文件变更时触发（paths 过滤）
• 使用 github-annotation 格式，直接在 PR 中显示问题位置
• 可配合 reviewdog 实现增量检查（只检查变更的文件）
Pre-commit Hook 集成：
在 .pre-commit-config.yaml 中添加：
repos:
- repo: https://github.com/sqlfluff/sqlfluff
rev: 3.0.0
hooks:
- id: sqlfluff-lint
args: [--dialect, mysql]
- id: sqlfluff-fix
args: [--dialect, mysql, --force]
GitLab CI 集成：
sql-lint:
image: sqlfluff/sqlfluff:latest
script:
- sqlfluff lint sql/ --dialect mysql
only:
changes:
- '**/*.sql'
VS Code 插件：
安装 sqlfluff 扩展，实时显示 lint 问题，保存时自动修复。
6团队规范落地
第一步：建立基线
新项目：
1. 选择适合团队的规则集（建议从默认规则开始，逐步收紧）
2. 创建 .sqlfluff 配置文件并提交到仓库
3. 配置 CI 检查
存量项目：
1. 先运行 sqlfluff lint 统计现有问题数量
2. 使用 --exclude-rules 暂时排除问题最多的规则
3. 运行 sqlfluff fix 批量修复可自动修复的问题
4. 每个迭代逐步启用更多规则
第二步：规范文档
建议在项目 Wiki 或 README 中说明：
• 使用的方言和版本
• 自定义的规则及原因
• 如何本地运行检查
• 如何处理误报（noqa 注释的使用规范）
第三步：渐进式推广
• 第一阶段：只警告不阻断（CI 标记失败但不阻止合并）
• 第二阶段：新文件必须通过检查
• 第三阶段：所有文件必须通过检查
与 Archery 配合：
• Archery 负责 SQL 审核流程管控（谁提交、谁审批）
• SQLFluff 负责 SQL 代码质量检查（风格、规范）
• 两者互补：SQLFluff 在开发阶段把关 → Archery 在上线阶段把关
推荐配置模板：
• 保守模式：只启用大小写和缩进规则，适合初期推广
• 标准模式：启用所有默认规则
• 严格模式：启用所有规则 + 自定义反模式检查，适合成熟团队