技能介绍

要解决的问题

在 dbt 项目里，SQL 文件的格式一致性往往是靠约定而不是靠工具保证的。同一份 stg_orders.sql 可能同时被 dbt 编译、Jinja 渲染和 sqlfluff 校验，人写的 SQL、agent 生成的 SQL、模板拼接产物混在一起后，缩进、引号风格、逗号位置的细微差异会让 code review 里充斥着大量无意义的 diff 行。更现实的问题是：谁来决定 {{ ref('x') }} 前后要不要换行？Jinja 控制块该竖排还是横排？靠人盯 PR 不仅慢，而且标准会漂移。

技能如何工作

这个技能的核心是把 sqlfmt 作为可编程的格式化边界接入工作流，而不是写一套自定义规则：

解析即重排：sqlfmt 直接读取 .sql / .sql.jinja 文件，识别 dbt 宏、Jinja 控制结构和 SQL 关键字，按其内置风格重新排版，输出可直接提交的成品文件。
面向审查场景：默认目标是产出风格稳定的文件，使 review diff 只反映逻辑改动，而非空白字符变化。
增量处理：只对上次运行后变更过的文件重新格式化，适合放进 pre-commit 或 CI 流水线，不必每次全量跑。
生态兼容：与 dbt、pre-commit、SQLFluff、VSCode、GitHub Actions 均可协同工作，Python 编写的 CLI 在 macOS、Linux、Windows 上行为一致。

关键步骤通常是：在提交前或 CI 阶段对目标 SQL 文件执行格式化，随后由 reviewer 在 PR 中只关注语义改动。

适用边界与注意点

风格即 opinionated：sqlfmt 输出的是它自己认定的"标准"，不是 SQL 风格指南的通用实现。如果你所在团队已有明确的 SQLFluff 规则集，两者需要先对齐，否则可能出现格式化结果与 lint 规则互相打架的情况。
不重写逻辑：sqlfmt 是 formatter 不是 linter，它不会检测 SQL 语义错误、不会重写查询计划，也不会保证 Jinja 渲染结果正确——渲染验证仍要交给 dbt compile/build 或单元测试。
需自行安装依赖：使用前必须在执行环境中预先准备 sqlfmt CLI（含 Jinja 支持）。
Jinja 密集文件优先：对纯 SQL、不含 Jinja 的文件，其价值会下降；它真正的用武之地是模板逻辑与 SQL 混写、且需要机器可读 diff 的 dbt 项目。