SQL 格式化

DBX 会根据当前连接选择接近的 SQL 方言，并把格式化结果写回查询编辑器。选中一段 SQL 时只格式化选区；没有选区时格式化整个编辑器。

你可以使用编辑器工具栏的 格式化 SQL 按钮，或使用快捷键中配置的格式化命令。

方言选择

DBX 当前对以下方言使用专用格式化语法：

MongoDB 查询编辑器使用单独的 Mongo Shell 格式化器，不使用本页的 SQL 方言映射。

默认风格

默认的 dbx 排版采用 DBX 布局：显式 AS 别名对齐，FROM 与表名同行。短查询仍会保持紧凑，CREATE TABLE 定义按列对齐。classic 使用 sql-formatter 上游的排版。点击恢复默认值会回到当前默认风格。

classic 使用 sql-formatter 自身的排版，也是 v0.6.16 之前 DBX 的默认风格。如需精确还原此前输出，可把表达式宽度设为 50、FROM 子句布局设为换行；JSON 中对应为 "expressionWidth": 50、"fromClauseLayout": "newLine"，与 "layoutStyle": "classic" 并列。除 Oracle 外结果与 v0.6.15 一致：Oracle 的字节/多字节函数变体（SUBSTRB、INSTR2、LENGTHB 等同族函数）保留较新的修复，会被规范为函数形式。

未启用自定义规则时，切换排版风格不会顺带改写其它选项，两种表格式缩进（tabularLeft、tabularRight）都使用 sql-formatter 自身的排版。

配置格式化选项

前往 设置 → SQL 格式化。表单模式提供以下选项：

恢复默认值会恢复当前代码定义的默认格式化设置。设置窗口中的改动需要点击 应用 才会持久化。

分别控制 SELECT、INSERT 和 UPDATE

在原格式化面板中启用自定义规则，再分别调整三类列表。自定义规则默认关闭；开启后使用规则布局，可与关键字左对齐或右对齐组合。关闭开关会恢复原先选择的基础布局，包括 classic，并保留已填写的规则值。

四种列表模式适用于通用列表，也可由 SELECT 字段、INSERT 目标列与 VALUES 行、UPDATE SET 项分别覆盖：

DML 选择 inherit 时继承通用规则。通用规则也用于函数参数、IN、GROUP BY、ORDER BY 等列表，不拆分字符串中的逗号。嵌套列表或条件要求的换行优先于外层短语句合并。

其他细粒度选项：

• listItemAlignment 选择续行对齐首项（firstItem）或缩进一级（indent）。alignSelectAliases 和 alignUpdateAssignments 分别控制多行显式 AS 与 SET 等号对齐；无法安全对齐时保留正常排版。
• selectCommaPosition、insertCommaPosition、updateCommaPosition 分别选择前置、后置逗号，或以 inherit 使用全局 commaPosition。
• whereLogicalOperatorNewline、onLogicalOperatorNewline、expressionLogicalOperatorNewline 分别控制 WHERE、JOIN ON 和其他表达式的 AND/OR，接受 before、after、none 或 inherit。newlineBeforeJoinOn 控制 ON 前换行。BETWEEN 自身的 AND 不会被当作条件分隔符。
• collapseShortStatements 允许短语句合并为单行，但不能覆盖明确要求的换行。emptyLineMode 可移除代码空行（remove）、将连续空行合并为一行（single）、保留空行（preserve），或以 inherit 沿用原 preserveEmptyLines；字符串和注释内部空行不受影响。

自定义规则生效时，remove 和 single 也将生成的查询间空行分别限制为 0 和 1；关闭规则或降级到基础布局后恢复原先保存的查询间隔。

先在面板内输入 SQL、选择方言并观察即时预览，再应用设置。预览不会执行 SQL，也不会覆盖已打开的查询。用同一方言和设置在编辑器中格式化相同 SQL，结果与预览一致；选区外文本保持原样，可通过编辑器撤销恢复。

完整过程块等超出规则模型的输入仍使用已选择的基础布局，并提示本次未应用自定义规则。需要细调过程内的查询时，选中独立 SELECT、INSERT 或 UPDATE 再格式化。本功能不提供 PL/SQL 过程声明、:= 赋值对齐或任意大小写词典。

JSON 模式与导入导出

JSON 模式适合精确编辑、复制或迁移格式化器配置。配置文件包含 version、formatter 和 options；以下旧配置示例仍可导入，省略的新规则使用默认值：

{
  "version": 2,
  "formatter": "sql-formatter",
  "options": {
    "layoutStyle": "dbx",
    "keywordCase": "upper",
    "dataTypeCase": "preserve",
    "functionCase": "preserve",
    "identifierCase": "preserve",
    "indentStyle": "standard",
    "useTabs": false,
    "tabWidth": 2,
    "logicalOperatorNewline": "before",
    "commaPosition": "after",
    "fromClauseLayout": "sameLine",
    "expressionWidth": 120,
    "linesBetweenQueries": 1,
    "preserveEmptyLines": false,
    "denseOperators": false,
    "newlineBeforeSemicolon": false,
    "paramTypes": null
  }
}

JSON 编辑器会实时校验配置。以下情况会阻止应用或导入：

• JSON 语法错误；
• version 不是 1 或 2；
• formatter 不是 sql-formatter；
• options 中包含未知字段；
• 字段值不在当前代码允许的范围内。

点击 导出配置 会下载 dbx-sql-formatter.json。导入只替换 SQL 格式化选项，不会修改连接、编辑器快捷键或其他 DBX 设置。完整设置迁移请参阅配置云同步。

导出会保存全部自定义规则。当前版本可导入缺少新字段的 v1/v2 配置及旧应用设置备份；旧版程序可能拒绝含新字段的配置，跨版本迁移时请保留原文件。

参数识别

paramTypes 为 null 时使用格式化器默认识别规则。需要额外语法时，可以配置：

{
  "positional": true,
  "numbered": ["?", "$"],
  "named": [":", "@", "$"],
  "quoted": [":", "@", "$"],
  "custom": [
    { "regex": "@\\{[^}]+\\}" }
  ]
}

• numbered 只接受 ?、:、$；
• named 和 quoted 只接受 :、@、$；
• custom 中每项只能包含非空且合法的 regex。

DBX 始终额外识别 ${name} 和 #{name} 形式的变量，避免这类模板变量导致格式化解析失败。旧配置中的非空 params 字段不再用于文本替换，应改用 paramTypes。