SQL 格式化工具 — MySQL、PostgreSQL、BigQuery 在线

阿里巴巴 MaxCompute（原 ODPS）是国内数据仓库的事实标准，数万名数据工程师每天在 DataWorks 上提交 SQL 模型。代码评审时，一位工程师将 200 行 CTE 手动格式化，另一位将其压缩为单行后合并，diff 就会爆炸成噪音，真正的逻辑变更被淹没。京东 PrestoDB 集群、字节跳动内部 ClickHouse 以及蚂蚁 OceanBase 团队均已将 SQL 格式化纳入 pre-commit 钩子，提交前统一对齐关键字大小写和缩进，使 Code Review 聚焦于谓词逻辑而非空白字符之争。本工具在浏览器本地运行 sql-formatter，查询文本不离开页面，符合数据安全管理办法对敏感字段的保护要求。

SQL 格式化的工作原理

SQL 格式化是一种词法驱动的重写过程，它遍历查询中的每个词元，并根据所选方言的规则在其周围重新输出空白字符。查询语义不会改变，只有布局会变。

选择方言. MySQL 反引号、PostgreSQL :: 类型转换、BigQuery 点分表路径和 T-SQL 方括号标识符各自需要能识别它们的词法分析器。方言选择器决定应用哪种语法。
词法分析输入. 格式化工具将查询拆分为词元流：关键字（SELECT、JOIN）、标识符、字面量、运算符、括号和注释。字符串字面量和带引号的标识符原样传递，方言特定语法得以保留。
应用布局规则. 顶层子句（SELECT、FROM、WHERE、GROUP BY、ORDER BY）各自另起一行。选择列表和列列表中以逗号分隔的表达式各占一行，并按所选缩进单位缩进。
应用关键字大小写. 关键字大小写切换将识别到的 SQL 关键字重写为大写、小写或保留输入的原始大小写。标识符不会被改动——列名和表名始终按原样输出。
输出格式化字符串. 词元流重新连接为单个字符串，使用缩进字符（2 个空格、4 个空格或制表符）和配置的换行规则。实时模式在您输入时以 200 毫秒防抖重新运行整个流水线。

为何要美化打印 SQL

提升 Pull Request 差异可读性. 将 200 行 CTE 重写为一行会让代码审查变成猜谜游戏。一致的格式化将差异范围限定在实际修改上——新增列、额外的 JOIN、不同的 WHERE 谓词——审查者无需解开空白字符即可看到变更。
更易调试. 当查询返回错误的行数时，首先要逐行阅读它。格式化后的 SQL 将每个 JOIN 放在独立行上，对齐 WHERE 谓词，缺少的 AND 或多余的 OR 一眼就能发现。
统一团队风格. 大多数团队采用 SQL 风格指南（dbt Labs、GitLab、Mode Analytics 均有发布），并希望每条提交的查询都遵循它。提交前运行格式化工具，将风格争议从审查中移除，只剩逻辑供讨论。
在文档中分享 SQL. 运维手册、故障复盘和 Notion 文档均受益于自上而下可读的 SQL。格式化后的 SQL 可以干净地粘贴到围栏代码块中，在 PDF 导出中可预期地打印，关键字中间不会出现尴尬的换行。

常见应用场景

SQL 格式化广泛出现在数据分析工程、后端开发和运维工作中，凡是查询需要被未编写者阅读的场合均适用。

数据分析工程：在 dbt 项目中设置 pre-commit 钩子，重新格式化每个模型文件，使 PR 差异聚焦于逻辑变更而非空白字符扰动。
数据库管理：粘贴慢查询日志中的单行条目，格式化后逐步分析连接顺序，同时撰写故障复盘报告。
文档编写：从 Looker Explore 或 Tableau 工作簿中取出查询，为运维手册格式化，嵌入为值班人员可直接复制粘贴的示例。

实际示例

将 SELECT u.id,u.email,COUNT(o.id) FROM users u LEFT JOIN orders o ON o.user_id=u.id WHERE u.created_at > '2024-01-01' GROUP BY u.id,u.email ORDER BY u.id; 粘贴到输入框，方言选择 PostgreSQL，缩进 2 个空格，关键字大小写选 UPPER。输出将 SELECT、FROM、LEFT JOIN、WHERE、GROUP BY 和 ORDER BY 各自放在独立行上；选择列表和 GROUP BY 列表中的每列各占一行缩进显示；ON 谓词比其所属的 JOIN 关键字多缩进一级。同一查询通过 BigQuery 方言产生相同输出，但若存在反引号标识符则会原样保留。

FAQ

支持哪些 SQL 方言？

方言下拉列表涵盖标准 SQL、MySQL、PostgreSQL、SQLite、MariaDB、Transact-SQL（SQL Server / Azure SQL）、BigQuery、Snowflake 和 Redshift。底层 sql-formatter 库还支持 DuckDB、Spark SQL、Hive、Trino、Db2、N1QL、PL/SQL、ClickHouse、TiDB 和 SingleStoreDB——选择最接近的方言，即使目标不在列表中也能产生合理输出。标识符、字符串字面量和方言特定运算符（PostgreSQL @>、BigQuery SAFE. 前缀）均原样保留。

这个工具会验证我的 SQL 吗？

不会。格式化工具是词法重写器，而非解析器。它对输入进行词法分析，应用布局规则并输出结果；它不检查查询是否语义有效、引用的表是否存在，或语法在所选方言中是否合法。请将格式化后的输出通过实际数据库（或 SQLFluff 等 SQL 检查工具）进行真正的正确性检查。

为什么我的关键字被转换为大写？

关键字大小写下拉列表默认为大写，这是大多数已发布 SQL 风格指南（dbt Labs、Mode、GitLab）的惯例。若您的团队使用小写 select / from，请切换为小写；若希望输出保留您输入的大小写，请选择保留原样。标识符不受影响——只有识别到的关键字集合会被重写。

我的查询会被上传吗？

不会。vendored sql-formatter 库在您的浏览器中运行，格式化在您的本地计算机上完成，查询文本不会经过网络传输。此页面发出的唯一出站请求，与 tools.ultim8soft.com 上每个页面相同的共享分析和广告请求；SQL 文本本身不是其中任何一个的组成部分。

美化打印的 SQL 一旦交由格式化工具处理，就不再是风格争议。本工具完全在浏览器中运行，查询永远不会离开页面，驱动重写的词法分析器与 sql-formatter npm 包所用的相同。

格式化 SQL 查询 _

// 相关工具