dbx/docs/content/docs/sql-formatter.cn.mdx

---
title: SQL 格式化
description: 使用数据库方言格式化所选 SQL 或整个编辑器，并管理当前版本的格式化选项和 JSON 配置。
---

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

你可以使用编辑器工具栏的 **格式化 SQL** 按钮，或使用[快捷键](/cn/docs/keyboard-shortcuts)中配置的格式化命令。

<Callout type="info">
  SQL 格式化只重排文本，不会执行 SQL。无法解析的语法会返回错误并保留原内容；单次格式化最多处理 `1,000,000` 个字符。
</Callout>

## 方言选择

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

| 连接类型 | 格式化方言 |
| --- | --- |
| MySQL | MySQL |
| PostgreSQL、openGauss、GaussDB、KingbaseES、Redshift 等兼容连接 | PostgreSQL |
| SQLite、Turso、rqlite、Cloudflare D1 | SQLite |
| SQL Server | Transact-SQL |
| Oracle、OceanBase Oracle 模式 | PL/SQL |
| ClickHouse | ClickHouse |
| 其他 SQL 数据库 | 通用 SQL；必要时再尝试 PostgreSQL 语法 |

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 格式化**。表单模式提供以下选项：

| 选项 | 可用值或作用 |
| --- | --- |
| 排版风格 | `dbx`（DBX 排版，默认）或 `classic`（sql-formatter 上游排版） |
| 关键字、数据类型、函数、标识符大小写 | `upper`、`lower`、`preserve` |
| 缩进样式 | `standard`、`tabularLeft`、`tabularRight` |
| 缩进字符 | 空格或 Tab |
| Tab 宽度 | `2` 或 `4` |
| 逻辑操作符换行 | `before`、`after`，或 `none` 保持在同一行 |
| FROM 子句排版 | `sameLine` 让首个表留在 `FROM` 行，`newLine` 让它换到下一行 |
| 表达式宽度 | `20`–`500` 的整数，例如 `76`；长字面量不会被截断 |
| 查询间空行 | `0`、`1` 或 `2` |
| 保留空行 | 保留语句之间的空行 |
| 紧凑操作符 | 减少操作符周围的空格 |
| 分号前换行 | 把语句结尾分号放到新行 |
| 参数类型 | 识别位置参数、编号参数、命名参数、引号参数或自定义正则参数 |

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

## 分别控制 SELECT、INSERT 和 UPDATE

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

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

| 模式 | 排版方式 |
| --- | --- |
| `singleLine` | 列表保持单行，允许超出目标宽度；行注释仍保留必要的换行 |
| `fit` | 放得下时单行，否则每项一行 |
| `vertical` | 每项一行 |
| `wrap` | 每行放入尽可能多的完整项，超过目标宽度时换行 |

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`；以下旧配置示例仍可导入，省略的新规则使用默认值：

```json
{
  "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 设置。完整设置迁移请参阅[配置云同步](/cn/docs/cloud-sync)。

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

## 参数识别

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

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

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

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

<Cards>
  <Card title="查询编辑器" href="/cn/docs/query-editor">
    了解格式化、压缩、执行范围和自动补全。
  </Card>
  <Card title="SQL 代码片段" href="/cn/docs/sql-snippets">
    使用可跳转占位符创建可复用 SQL 模板。
  </Card>
</Cards>