122 lines
4.6 KiB
Plaintext
122 lines
4.6 KiB
Plaintext
---
|
||
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 |
|
||
| ClickHouse | ClickHouse |
|
||
| 其他 SQL 数据库 | 通用 SQL；必要时再尝试 PostgreSQL 语法 |
|
||
|
||
MongoDB 查询编辑器使用单独的 Mongo Shell 格式化器，不使用本页的 SQL 方言映射。
|
||
|
||
## 默认风格
|
||
|
||
默认排版规则：能放下的语句保持一行，放不下的按子句逐行展开，子句的后续元素与第一个元素对齐；条件的逻辑操作符放在续行行首；`CREATE TABLE` 的列定义按列对齐。下面的设置用于调整这些规则，**恢复默认值**会回到该风格。
|
||
|
||
## 配置格式化选项
|
||
|
||
前往 **设置 → SQL 格式化**。表单模式提供以下选项：
|
||
|
||
| 选项 | 可用值或作用 |
|
||
| --- | --- |
|
||
| 关键字、数据类型、函数、标识符大小写 | `upper`、`lower`、`preserve` |
|
||
| 缩进样式 | `standard`、`tabularLeft`、`tabularRight` |
|
||
| 缩进字符 | 空格或 Tab |
|
||
| Tab 宽度 | `2` 或 `4` |
|
||
| 逻辑操作符换行 | `before`、`after`，或 `none` 保持在同一行 |
|
||
| FROM 子句排版 | `sameLine` 让首个表留在 `FROM` 行，`newLine` 让它换到下一行 |
|
||
| 表达式宽度 | `50`、`80` 或 `120` |
|
||
| 查询间空行 | `0`、`1` 或 `2` |
|
||
| 保留空行 | 保留语句之间的空行 |
|
||
| 紧凑操作符 | 减少操作符周围的空格 |
|
||
| 分号前换行 | 把语句结尾分号放到新行 |
|
||
| 参数类型 | 识别位置参数、编号参数、命名参数、引号参数或自定义正则参数 |
|
||
|
||
**恢复默认值**会恢复当前代码定义的默认格式化设置。设置窗口中的改动需要点击 **应用** 才会持久化。
|
||
|
||
## JSON 模式与导入导出
|
||
|
||
JSON 模式适合精确编辑、复制或迁移格式化器配置。当前配置文件只包含 `version`、`formatter` 和 `options`：
|
||
|
||
```json
|
||
{
|
||
"version": 1,
|
||
"formatter": "sql-formatter",
|
||
"options": {
|
||
"keywordCase": "upper",
|
||
"dataTypeCase": "preserve",
|
||
"functionCase": "preserve",
|
||
"identifierCase": "preserve",
|
||
"indentStyle": "standard",
|
||
"useTabs": false,
|
||
"tabWidth": 2,
|
||
"logicalOperatorNewline": "before",
|
||
"fromClauseLayout": "sameLine",
|
||
"expressionWidth": 120,
|
||
"linesBetweenQueries": 1,
|
||
"preserveEmptyLines": false,
|
||
"denseOperators": false,
|
||
"newlineBeforeSemicolon": false,
|
||
"paramTypes": null
|
||
}
|
||
}
|
||
```
|
||
|
||
JSON 编辑器会实时校验配置。以下情况会阻止应用或导入：
|
||
|
||
- JSON 语法错误；
|
||
- `version` 不是 `1`；
|
||
- `formatter` 不是 `sql-formatter`；
|
||
- `options` 中包含未知字段；
|
||
- 字段值不在当前代码允许的范围内。
|
||
|
||
点击 **导出配置** 会下载 `dbx-sql-formatter.json`。导入只替换 SQL 格式化选项，不会修改连接、编辑器快捷键或其他 DBX 设置。完整设置迁移请参阅[配置云同步](/cn/docs/cloud-sync)。
|
||
|
||
## 参数识别
|
||
|
||
`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>
|