SQL 格式化工具

功能的

在不改变查询含义的前提下把它整理干净。格式化工具特意做得非常小心。

格式化器可以配置,但它刻意保持谨慎。SQLly 会重新做词法分析,并逐个 token 比较其输出 与输入进行比对;任何不匹配都不会改动你的 SQL。它可以重新缩进、调整关键字大小写并对齐子句,而不会拿注释或字面值冒险。

格式化 SQL

按 ⌥⇧F (Alt+Shift+F 在 Windows 和 Linux 上),选择 编辑 › 格式化文档,或右键 › 格式化文档 格式化整个查询,无论选中什么。要仅格式化所选内容,按 ⌘K ⌘F (Ctrl+K Ctrl+F)用于 格式化所选内容。这两个快捷键都可以在 设置 › 工作区 › 键盘快捷键。你也可以选择 查询 › 格式化 SQL,用于

-- before
select o.OrderId, c.Name, sum(l.Qty * l.Price) as total from dbo.Orders o join dbo.Customers c on c.Id = o.CustomerId left join dbo.OrderLines l on l.OrderId = o.OrderId where o.Status = 'open' and o.Total > 100 group by o.OrderId, c.Name order by total desc

-- after
SELECT
    o.OrderId,
    c.Name,
    SUM(l.Qty * l.Price) AS total
FROM
    dbo.Orders o
    JOIN dbo.Customers c ON c.Id = o.CustomerId
    LEFT JOIN dbo.OrderLines l ON l.OrderId = o.OrderId
WHERE
    o.Status = 'open'
    AND o.Total > 100
GROUP BY
    o.OrderId,
    c.Name
ORDER BY
    total DESC

关键字和函数大写,每个主要子句另起一行,选择列表每列堆叠一行,而 FROM 的表(及其 JOIN)和紧随其后的条件 WHERE 和 HAVING 各自单独成行并缩进,并且 AND/OR 都写在各自所在行的开头。能放进 80 个字符的单条语句会保持在一行: SELECT id, name FROM dbo.Users WHERE id = 1。缩进会跟随你编辑器的制表符设置,除非你另行选择。

SQLly
格式化 SQL 后的编辑器,显示一个多连接的 Orders 查询,关键字大写,各子句分行格式化 SQL 后的编辑器,显示一个多连接的 Orders 查询,关键字大写,各子句分行
格式化 SQL 后的一行多连接查询:关键字大写,每列单独一行,子句对齐。

边写边格式化

这 边写边格式化 切换在顶部 设置 › 编辑器 › 格式化 在你输入时进行格式化。开启后,按下 输入 会重新格式化你正在输入的语句,而光标仍停在此前跟随的那个字符之后,所以你可以原地继续输入。默认关闭;关闭时,可通过“格式化文档”按需格式化(⌥⇧F 在 macOS 上, Alt+Shift+F 在 Windows 和 Linux 上,可在以下位置重新绑定: 设置 › 工作区 › 键盘快捷键).

按下回车时,如果满足以下条件,文本保持不变:

  • 文本被选中,或者你正在使用多个光标编辑;
  • 标签页位于 Redis 连接上,其编辑器保存的是命令而非 SQL;
  • 语句未以语句关键字开头: SELECT, INSERT, UPDATE, DELETE, WITH, CREATE, ALTER, DROP, MERGE, TRUNCATE, GRANT, REVOKE, BEGIN, DECLARE,或 EXEC.

脚本和 GO 批处理

包含多条语句的脚本会一次格式化一条语句,每条语句都从新的一行开始,单行快捷方式只在整段文本是单条语句时适用。语句结束于 ; 结束,对于 SQL Server,则以 GO 批分隔符。 GO 总是独占一行,大小写随你的其他关键字,并带上重复次数(GO 5)或与它同行的注释:

-- before
select 1
go
select name from dbo.Users
go

-- after
SELECT
    1
GO
SELECT
    name
FROM dbo.Users
GO

GO 只有当它起始的行除了可选的数量或注释外别无其他内容、并且位于语句之间时,才算作分隔符,例如 sqlcmd 和 SSMS 的预期。一个名为 go 在选择列表中间, [go],以及 go 在字符串或注释内出现时,会作为普通 SQL 原样保留。方言设为自动检测时,一个 GO 行会把脚本标记为 SQL Server。方言设为其他引擎时, GO 不是分隔符。

设置

一切都存放在 设置 › 编辑器 › 格式化,它带实时预览:粘贴你自己的 SQL,边调整设置边看效果。最快的上手方式是 预设:

预设风格
默认如上所示的布局。
紧凑简短的子句和选择列表保持在同一行,并且 AND/OR 跟在各自所在行的后面。
已展开前置逗号、主要子句前空行, ON 独立占一行,并对齐运算符、数据类型和别名。
关键字大写 / 关键字小写关键字和函数采用该大小写的默认布局。
保留现有保留你的大小写、逗号和子句位置,其余的帮你收拾整齐。

选择预设会重写所有布局设置,但会保留你的格式触发器(边写边格式化, 保存时格式化,以及 粘贴时格式化),所以换用其他预设也不会再把它们关掉。之后再改任何一项设置,都会把它切换为 自定义。各个部分涵盖关键字大小写(整体或按组,如数据类型或 JOINs)、标识符大小写和引号、子句布局、选择列表、逗号样式、布尔条件, CASE、运算符、JOIN、函数、子查询和 CTE、DML、DDL、注释、缩进、行长(默认 120)以及语句。 SQL 方言 设置默认为“自动检测”,它会根据 SQL 本身判断方言。

保存时格式化 和 粘贴时格式化 位于 格式化触发时机。两者默认都是关闭的。

FROM 和 WHERE 的位置

有两个设置位于 子句布局 可以选择子句主体是从关键字所在行开始,还是在下方单独缩进一行开始:

选项作用
FROM 之后的表换行并缩进 (默认)会把第一张表单独放到一行,位于 FROM,并让它的 JOIN与它对齐;而 ON 独占一行时再缩进一级。 与关键词在同一行 会让表保持在 FROM 行,带有 JOIN则遵循 JOIN 布局 设置。
WHERE / HAVING 后的第一个条件换行并缩进 (默认)将第一个条件放在它自己的行上,位于 WHERE 或者 HAVING,与 AND/OR 随后的行。 与关键词在同一行 会把它留在关键字所在的那一行。

这 紧凑 和 保留现有 预设将两者都保留在关键字所在的行上。紧跟 FROM 或者 WHERE 仍会留在那一行。

CTE、DML 和索引列

这些选项控制常见语句结构的布局方式:

选项作用
CTE 风格堆叠 (默认)将每个 CTE 的主体放在它自己的行上。 内联 将每个 CTE 的 name AS ( … ) 放在一行上。包含 -- 注释,或会超出最大行长度的行,保持堆叠。
DML 风格标准版 (默认)是常用的布局。 紧凑 放置一个 INSERT, UPDATE, DELETE,或 MERGE 的语句只要放得进最大行宽,就会保持在一行。 已展开 放置每个 INSERT 列,每个 VALUES 项,每一个 UPDATE SET 赋值会单独占一行,而且哪怕开着 让短查询保持在一行.
多行索引列当索引包含多个列时,每个键列和每个 INCLUDE 一列 CREATE INDEX 要单独占一行。同样适用于 PRIMARY KEY, UNIQUE, INDEX,以及 KEY 列列表内部 CREATE TABLE. FOREIGN KEY 列列表保持原样。
将尾随注释与表达式一起移动可与 让行内注释保持在行内。两者都启用时,行尾的 -- comment 在格式化器重新折行后,仍留在其代码行的末尾。

这 紧凑 和 已展开 预设会启用该组中的匹配选项。在 CREATE INDEX … ON table (…),表名保留原有大小写;不再像关键字那样被转成大写。

补全遵循你的设置

当你接受 IntelliSense 建议时,SQLly 会将其插入并按照 Format SQL 的布局方式排列该语句:关键字和函数的大小写、标识符的大小写及引用方式、 JOIN 和 ON 位置,以及其他所有格式化设置。例如,使用 ON 子句位置 设置为 在新行上、 JOIN 建议 把它的 ON 单独占一行。一条短到足以 让短查询保持在一行 保持在同一行上,就像用格式化 SQL 处理时一样。如果格式化器的结果与你输入的内容对不齐,建议就会按原样插入。

不改动 SQL

想让格式化器别碰某段代码时,就把这个区域标记为原样保留:

-- formatter:off
SELECT weird , hand_aligned
       , columns   -- left exactly as typed
FROM t;
-- formatter:on

该开关按语句逐条生效。凡是在 -- formatter:off 会原样保留,它之后的每条语句也是,直到遇到 -- formatter:on。放在语句中间的标记保护不到语句的一部分,因此语句应以 ; 或一个 GO 行。你可以用 遵守控制注释 在“注释”部分。

绝不会弄坏你的 SQL。 这项词法检查会把格式化缺陷变成空操作,而不会产出损坏的 SQL。无法顺利词法分析的 SQL——比如未闭合的字符串或注释——会原样返回,不会被重新排版。注释绝不会被丢弃。

格式化 SQL 在 Redis 连接上不起作用,因为其编辑器里是命令而不是 SQL。

压缩 SQL

反过来说,对于日志、JSON 载荷或命令行,就用紧凑的单行形式, 压缩 SQL 去除普通注释并将所有空白字符压缩为单个空格,同时保留字符串字面值、带引号的标识符和美元符号引用的主体不变,因此压缩后的 SQL 仍然与原始 SQL 完全一样执行。 -- sqlly 指令注释和 /*+ hint */ 优化器提示,SQL Server 的 GO 分隔符单独占一行,这是服务器的要求;无法顺利解析的 SQL 会原样保留,而不会被弄乱。

选中要压缩的 SQL,或将光标放在某条语句中,也可以什么都不选来压缩整个查询,然后按 ⌘⌥⇧F (Ctrl+Alt+Shift+F 在 Windows 和 Linux 上),选择 查询 › 压缩 SQL,或者从命令面板运行。结果会作为一次可撤销的编辑落下,撤销一次即可还原。