企业官网建设流程全解析

Beekeeper Studio SQL 查询格式化器：预设管理与配置完整指南

【免费下载链接】beekeeper-studioModern and easy to use SQL client for MySQL, Postgres, SQLite, SQL Server, and more. Linux, MacOS, and Windows.项目地址: https://gitcode.com/GitHub_Trending/be/beekeeper-studio

Beekeeper Studio 内置的 SQL 查询格式化器（SQL Query Formatter）将 sql-formatter 为核心，结合仓库源码，完整讲解格式化器的打开方式、内置预设、自定义配置、预设的增删改，以及如何通过右键菜单一键套用预设。

格式化器是什么

Beekeeper Studio 的 SQL 查询格式化器是一个可视化工具，它把 sql-formatter 库的所有格式化选项暴露到你的指尖，使你能：

• 从内置的 3 套预设中选择基准配置；
• 实时调整缩进、大小写、运算符换行等细节，并在右侧预览效果；
• 把满意的配置保存为命名预设，跨连接、跨标签页反复使用；
• 在编辑器右键菜单中一键应用任意已保存的预设。

从源码结构看，格式化器被设计为主应用中的一个独立模态窗口组件，由 TabQueryEditor.vue 中的handleFormatterPresetModal方法控制开关（this.$modal.show(this.superFormatterId)/this.$modal.hide(...)），核心 UI 组件则沉淀在 ui-kit 仓库的 Super Formatter 组件中，其完整组件文档见 apps/ui-kit/docs/super-formatter.md。

快速上手：如何打开格式化器

打开 SQL 查询格式化器有两种方式：

1. 右键菜单：在编辑器窗口内右键，选择Format Query → Custom…（打开格式化器并进入自定义配置界面）；
2. 工具栏按钮：点击编辑器工具栏中Save（保存）和Run（运行）按钮旁边的格式化按钮。

打开后，你可以从下拉菜单选择一个预设作为基准，调整各项配置，右侧预览区会实时显示格式化效果。

三个内置预设

格式化器开箱即用，内置 3 套预设（见迁移脚本 apps/studio/src/migration/20250831_populate_formatter_presets.js 中的种子数据）：

1. bk-default（默认）——Beekeeper Studio 的默认配置：2 空格缩进、使用空格、关键字/数据类型/函数名大小写均保持原样（preserve）、逻辑运算符换行前置、表达式宽度 50、查询之间空 1 行；
2. pgFormatter——模仿经典 pgFormatter 工具的风格：4 空格缩进、关键字转大写（upper）、数据类型转小写（lower）、函数名保持原样；
3. prettier-sql——仿照 Prettier 的 SQL 风格：2 空格缩进、关键字大写、数据类型小写、函数名保持原样、查询之间空 2 行。

这 3 个内置预设都在数据库中以systemDefault = 1标记，不可删除，但可以编辑。它们的精确配置值如下：

设置默认格式化预设

格式化器默认使用bk-default作为编辑器打开时的默认预设。你可以通过 Beekeeper Studio 的配置系统修改这一默认值，相关配置项位于[ui.queryEditor]段落：

[ui.queryEditor] defaultFormatter = bk-default

该配置在默认配置文件中真实存在：apps/studio/default.config.ini 中defaultFormatter = bk-default，并在类型声明 apps/studio/src/typings/bksConfig.d.ts 中定义为queryEditor.defaultFormatter: string。将值替换为任意已保存预设的名称（例如pgFormatter），即可让编辑器默认套用该预设。

从源码看，编辑器加载时通过getPresets读取该配置并选中对应预设：

// apps/studio/src/components/TabQueryEditor.vue getPresets(presetId) { this.$util.send('appdb/formatter/getAll') .then((presets) => { const presetToFind = typeof presetId === 'object' ? this.$bksConfig.ui.queryEditor.defaultFormatter : presetId const selectedFormatter = presets.find(p => Number(p.id) === Number(presetToFind)) if (selectedFormatter != null) { this.selectedFormatter = { id: selectedFormatter.id, ...selectedFormatter.config } } this.formatterPresets = presets }) // ... }

注意：presetToFind既可以是预设的数字 id，也可以直接是配置中写的预设名称（字符串），两种方式都兼容。

如何格式化查询

格式化一条查询的标准流程：

1. 打开 SQL 查询格式化器（右键菜单 → Format Query → Custom…，或点击工具栏按钮）；
2. 从下拉菜单选择一个预设作为基准；
3. 调整各项格式选项，并通过右侧实时预览确认效果；
4. 点击Apply（应用）。

注意：点击 Apply 只会把当前配置应用到编辑器中的 SQL，并不会把修改写回所选预设。

应用操作在源码中的对应实现是applyPreset：它先关闭格式化器模态窗口，再把当前配置设为编辑器生效的 formatter 配置：

// apps/studio/src/components/TabQueryEditor.vue applyPreset(presetConfig) { this.handleFormatterPresetModal({ showFormatter: false }) this.selectedFormatter = { ...presetConfig } }

如何保存一个预设（覆盖更新）

如果你想更新某个已有预设的配置：

1. 按格式化查询的步骤 1～3 操作（打开格式化器、选择预设、调整选项）；
2. 不要点击Apply，而是点击Save Preset（保存预设）。

注意：保存操作不会自动把新配置应用到当前查询；如需应用，仍需点击 Apply。

保存（更新）流程在源码中走savePreset方法，当存在id时调用appdb/formatter/updatePreset端点：

// apps/studio/src/components/TabQueryEditor.vue savePreset({ id, config, name }) { // id == null → appdb/formatter/newPreset（新建） // id != null → appdb/formatter/updatePreset（更新） this.$util.send(endpoint, inputData) .then((presetValues) => { this.$noty.success(`${notyMessage} complete`) this.selectedFormatter = { id: presetValues.id, ...presetValues.config } }) // ... }

底层数据操作由 apps/studio/src/handlers/formatterPresetHandlers.ts 中的appdb/formatter/updatePreset处理器完成，最终落到 FormatterPreset.updatePreset：按id查找记录、更新config（JSON 字符串化后存储）并保存。

如何创建新预设

1. 打开 SQL 查询格式化器；
2. 从下拉菜单选择一个预设作为基准；
3. 点击预设下拉菜单旁的+按钮；
4. 输入格式名称（名称必须唯一）；
5. 调整各项选项，并通过右侧预览确认效果；
6. 点击Save Preset保存。

提示：新预设保存后不会自动应用到当前 SQL；如需应用，请点击 Apply。

新预设的持久化链路与更新一致：savePreset在id为null时调用appdb/formatter/newPreset端点，处理器转交 FormatterPreset.addPreset：将配置JSON.stringify后连同名称写入数据库，systemDefault标记为0（即用户自定义预设）。

名称唯一性保证

迁移脚本 apps/studio/src/migration/20251013_unique_name_formatter_presets.js 在formatter_presets表上创建了唯一索引：

CREATE UNIQUE INDEX idx_formatter_presets_name on formatter_presets(name);

这意味着在数据库中层面就强制了“名称唯一”规则，重复名称的新建会直接失败。预设本身存储在应用的 SQLite 数据库的formatter_presets表中（建表脚本见 apps/studio/src/migration/20250831_create_formatter_presets.js）：

CREATE TABLE IF NOT EXISTS formatter_presets ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, config TEXT NOT NULL, -- JSON 序列化的格式化配置 systemDefault INTEGER NOT NULL DEFAULT 0, createdAt DATETIME NOT NULL DEFAULT (datetime('now')), updatedAt DATETIME NOT NULL DEFAULT (datetime('now')), version INTEGER NOT NULL DEFAULT 0 )

如何删除一个预设

1. 打开 SQL 查询格式化器；
2. 从下拉菜单选择要删除的预设；
3. 点击旁边的Delete Config（删除配置）按钮。

注意：3 个内置预设（bk-default、pgFormatter、prettier-sql）不可删除，但可以被编辑。

删除在 UI 层先弹出确认框，随后调用appdb/formatter/deletePreset端点（apps/studio/src/handlers/formatterPresetHandlers.ts），最终由 FormatterPreset.deletePreset 按id执行删除，删除成功后会通过 noty 通知提示Formatter Configuration successfully deleted。

使用预设格式化查询（右键菜单快捷方式）

除了打开格式化器界面，编辑器还提供了更快捷的方式直接套用预设：

1. 在编辑器窗口内右键；
2. 将鼠标悬停在Format Query菜单项上；
3. 在弹出的子菜单中选择一个已保存的预设。

此时不会打开格式化器，而是直接把该预设的配置应用到当前查询。从源码看，右键菜单的Format Query会直接列出已保存的预设（包含内置与自定义），同时提供Custom…入口跳转到完整的自定义界面。

底层原理：配置如何被真正应用到 SQL

格式化器界面中的每一项配置最终都会映射为 sql-formatter 库的格式化选项。应用核心格式化逻辑位于 apps/studio/src/lib/db/sql_tools.ts：

import { format, ParamItems } from 'sql-formatter' export function deparameterizeQuery(queryText, dialect, params, paramTypes) { if (dialect === 'redis') { // 格式化会破坏 Redis 多行命令执行，直接返回原文 return queryText } const result = format(queryText, { language: FormatterDialect(dialect), paramTypes, params }) return result }

值得注意的细节：

• 方言映射：Beekeeper 的 Dialect 名称与 sql-formatter 的 language 名称并不一一对应，apps/studio/src/shared/lib/dialects/models.ts 中的FormatterDialect函数负责转换，例如sqlserver → tsql、oracle → plsql、greengage → postgresql、cassandra/duckdb/surrealdb → sql，默认回退为mysql；
• 自定义方言：对于 sql-formatter 未内置的方言（如 DynamoDB 的 PartiQL），formatOptionsFor返回自定义的dialect配置而非language，使用formatDialect分发处理；
• 特殊例外：Redis 方言会跳过格式化，以保护多行命令的执行语义；
• 参数还原：convertParamsForReplacement会把占位符值转换为 sql-formatter 可识别的参数格式，从而在格式化时保持?/:name等参数占位符完整。

在编辑器中，格式化后的 SQL 通过deparameterizeQuery生成后回填到编辑器（见 TabQueryEditor.vue 中对safelyIdentify、convertParamsForReplacement、deparameterizeQuery的调用链）。

可配置选项速查表

Super Formatter 组件（UI 层）支持的全部格式化选项如下，完整 API 文档见 apps/ui-kit/docs/super-formatter.md：

缩进

• tabWidth：每级缩进的空格数（1～20）；
• useTabs：是否用制表符替代空格（true/false）。

大小写

• keywordCase：SQL 关键字大小写转换（preserve / upper / lower）；
• dataTypeCase：数据类型名大小写转换（preserve / upper / lower）；
• functionCase：函数名大小写转换（preserve / upper / lower）。

排版

• logicalOperatorNewline：逻辑运算符（AND/OR）的换行位置（before / after）；
• expressionWidth：表达式最大宽度，超出后换行（1～100，默认 50）；
• linesBetweenQueries：多条查询之间的空行数（1～20）；
• denseOperators：是否压缩运算符两侧空格（如a=b而非a = b）；
• newlineBeforeSemicolon：分号是否单独换行放置。

一个完整的预设配置对象示例：

{ "tabWidth": 2, "useTabs": false, "keywordCase": "upper", "dataTypeCase": "upper", "functionCase": "upper", "logicalOperatorNewline": "before", "expressionWidth": 50, "linesBetweenQueries": 1, "denseOperators": false, "newlineBeforeSemicolon": false }

常见问题

问：Apply 和 Save Preset 有什么区别？Apply 只把当前配置应用到编辑器中的 SQL，不写回预设；Save Preset 把配置写入所选预设（或新建预设），但不会自动应用到当前 SQL。两者是独立的操作，想既保存又应用需要分别执行。

问：内置预设能删除吗？不能。3 个内置预设（bk-default、pgFormatter、prettier-sql）以systemDefault = 1标记，禁止删除；但它们可以被编辑覆盖。

问：预设名称能重复吗？不能。数据库层面的唯一索引idx_formatter_presets_name强制预设名称唯一。

问：怎么让新打开的表/编辑器默认使用我的预设？在配置文件（如default.config.ini或用户配置文件）的[ui.queryEditor]段落设置defaultFormatter = 你的预设名称。

参考资源

• 官方用户指南：docs/user_guide/sql-query-formatter.md（英文原版）、docs/user_guide/sql-query-formatter.es.md（西班牙语版）
• 配置系统说明：docs/user_guide/configuration.md
• UI 组件 API 文档：apps/ui-kit/docs/super-formatter.md
• 预设数据模型：apps/studio/src/common/appdb/models/FormatterPreset.ts
• 预设持久化处理器：apps/studio/src/handlers/formatterPresetHandlers.ts
• 格式化核心逻辑：apps/studio/src/lib/db/sql_tools.ts
• 方言到 formatter 语言映射：apps/studio/src/shared/lib/dialects/models.ts
• 数据库迁移：20250831_create_formatter_presets.js、20250831_populate_formatter_presets.js、20251013_unique_name_formatter_presets.js
• 默认配置：apps/studio/default.config.ini

【免费下载链接】beekeeper-studioModern and easy to use SQL client for MySQL, Postgres, SQLite, SQL Server, and more. Linux, MacOS, and Windows.项目地址: https://gitcode.com/GitHub_Trending/be/beekeeper-studio