DBX

查询编辑器

查询编辑器是 DBX 的 SQL 工作区。它把方言感知的高亮与补全、语义诊断、参数输入、执行进度、多结果、执行计划、查询历史、SQL 库和 AI 助手放在同一个标签页中。

全局文件搜索预览

桌面版的全局文件内容搜索会在结果列表下方预览当前选中的文件。使用上下方向键或鼠标悬停切换结果,预览会显示文件路径、行号并定位和高亮匹配内容。可直接在预览中拖选文本,按 Mod+C 复制;按 Mod+A 选择全文,或使用 Shift+方向键扩展选区。单击结果或按回车打开文件。在只读预览区域内按上下键仍可切换结果,回车打开当前结果,Esc 关闭搜索窗口。仅文件名匹配时从文件开头预览。空文件和读取失败会显示相应提示。

点击预览工具栏的编辑按钮,可直接修改文件,包括空文件。编辑时,回车和方向键用于文本编辑,支持撤销与重做;点击保存或按 Mod+S 写入文件,点击取消放弃本次修改。保存或取消前,当前预览文件保持固定,搜索、打开其他结果和关闭搜索窗口暂不可用。保存保留检测到的编码和换行格式;如果文件已被其他程序修改、删除或保存失败,DBX 会保留编辑内容并显示错误,不会自动覆盖外部修改。

Vim 配置

在桌面版的编辑器设置中启用 Vim 模式后,DBX 会读取 ~/.dbx/vimrc。如文件不存在,请先创建;修改后重启 DBX 才会生效。空行及以 " 开头的注释行会被忽略。CodeMirror Vim 支持的命令会应用到每个 SQL 编辑器标签页,例如:

" DBX Vim 映射
imap jj <Esc>
nmap Y y$
set clipboard=unnamedplus

配置 set clipboard=unnamedplus 后,Vim 的复制和删除会写入系统剪贴板,普通模式下的 p 和 P 会从系统剪贴板读取。不支持的命令不会阻止编辑器启动。

在 Vim 中执行 DBX 操作

在 Vim 命令行中输入 :dbx <action> 即可执行 DBX 操作。操作名与快捷键的 action ID 一致,且不区分大小写,例如 :dbx formatsql 同样有效。输入未知的操作名时只会显示提示,不会执行任何操作。

范围操作
编辑器executeSql、executeSqlInNewResultTab、explainSql、formatSql、saveSql、expandSelectStar、toggleLineComment、toggleBlockComment、selectCurrentStatement、previousStatement、nextStatement、statementStart、uppercaseSelection、lowercaseSelection、sendSelectionToAi、sqlIntentionActions
应用newQuery、closeTab、closeOtherTabs、closeAllTabs、reopenClosedTab、openSettings

编辑器操作的行为与对应的快捷键相同。例如 executeSql 有选区时执行选中内容,否则执行当前语句。在可视模式下执行(命令行会变成 :'<,'>dbx executeSql)时,会先恢复可视选区,只使用选中的 SQL;行可视和块可视选区会扩展为整行。

撤销、缩进、删除行、合并行等 Vim 本身已提供的编辑操作不会通过 :dbx 提供,请直接使用 Vim 原生命令。

每个操作还有一个不含空格的命令::Dbx 加上首字母大写的操作名,例如 :DbxExecuteSql、:DbxFormatSql。在 vimrc 的映射中请使用这些命令,因为 CodeMirror Vim 的映射遇到第一个空格就会截断,无法直接映射 :dbx executeSql:

nnoremap Qr :DbxExecuteSql<CR>
vnoremap Qr :DbxExecuteSql<CR>
nnoremap Qf :DbxFormatSql<CR>
nnoremap Qj :DbxNextStatement<CR>
nnoremap Qk :DbxPreviousStatement<CR>

CodeMirror Vim 在已输入的按键完整匹配某个内置命令时会立即执行,不会像 Vim 那样按 timeoutlen 等待后续按键。因此映射前缀请选择本身不是单键命令的键,例如 Q。常用的 leader 键 <Space>(光标右移)和 ,(反向重复上一次 f/t 查找)会被内置命令直接吃掉,<Space>r、,x 这类映射不会被触发。如果想用它们作为前缀,请先取消其内置命令(该键原本的功能也会随之失效):

unmap <Space>
nnoremap <Space>r :DbxExecuteSql<CR>
vnoremap <Space>r :DbxExecuteSql<CR>

基本工作流

选择连接上下文

新建查询时选择连接、数据库和 Schema。也可以从对象树、快速打开、SQL 库或 SQL 文件创建带上下文的查询标签。

编写并检查 SQL

使用补全、悬停信息、语义诊断、格式化和代码折叠理解 SQL。Ctrl/Cmd+Click 可以按设置跳转到表数据或对象位置。

明确执行范围

选中要执行的 SQL,或使用当前语句/全部内容。多语句时可以通过执行目标选择器确认范围。

查看结果或执行计划

结果区支持多个运行记录、横向标签或列表视图。需要分析性能时,使用执行计划入口读取树、摘要和标准表格。

保存和复用

把稳定查询保存到 SQL 库或外部 .sql 文件,并通过历史记录、快速打开或文件夹再次使用。

双击选中字符串内容或单词

默认情况下,在 SQL 字符串内双击会选中整段内容。例如,双击 '2013-12-20 09:30:26.603' 中的年份,会选中整个时间字符串,而不包含两侧引号。

如果只想选中双击处的单词或数字片段:

  1. 打开 设置 → 编辑器。
  2. 将 双击字符串时选中 改为 只选中单词。
  3. 点击 应用 或 应用并关闭。

该模式使用编辑器的默认单词边界。例如:

字符串内容双击位置选中内容
2013-12-20 09:30:26.603年份2013
2013-12-20 09:30:26.603毫秒603
123-456后半段数字456
123.456后半段数字456
abc123数字部分abc123

这不是“只选数字”模式:相邻字母和数字仍属于同一个单词。切回 选中整段内容 可恢复默认行为。此选项控制 SQL 编辑器中的字符串双击行为,不控制结果表格中的文本选择。

执行 SQL

操作macOSWindows / Linux
执行当前范围Cmd+EnterCtrl+Enter
在新结果中执行Cmd+\Ctrl+\
停止执行点击执行按钮变成的停止按钮点击执行按钮变成的停止按钮

有选中文本时,DBX 优先执行选中内容;没有选中时,根据当前语句和执行目标设置决定范围。快捷键可以在 快捷键 中修改。

普通执行会更新当前激活结果。在新结果中执行适合保留旧结果进行对比。结果可以平铺为横向标签,也可以切换为列表;多次执行还会保留运行记录,并可以固定重要结果。

多语句执行时,结果区显示当前语句、总语句数、完成状态和错误。驱动支持时,可以取消当前查询或后续语句。

查询取消取决于驱动和数据库能力。点击停止后,服务端可能仍需要时间中断正在执行的语句。

执行前预览变更

对 UPDATE / INSERT / DELETE 语句,编辑区工具栏会出现**「预览变更」**按钮(右键菜单里也可用)。DBX 会把该语句改写成一条等价的只读 SELECT,在新结果标签中展示影响到的数据。预览会重新求值被写入的表达式,带副作用的表达式(推进序列、volatile 函数)在预览中同样生效,非确定性函数(uuid()、rand()、now())显示的值可能与实际执行不同:

  • UPDATE:网格展示受影响行 + 每个被赋值列一列 列名 (new)(表达式按行内旧值求值,SET a = a + 1 也能算出真实新值);
  • INSERT:网格展示即将插入的行(列名来自目标列,VALUES 展开);
  • DELETE:网格展示将被删除的行。

无法安全改写的语句会提示 Preview is not supported,但仍可正常执行原语句。

执行范围与目标选择器

范围如何确定适合场景
选中 SQL执行前高亮文本多语句草稿中最明确、安全
当前语句光标位于语句内快速执行脚本中的一条语句
全部内容没有选择且按设置执行整个编辑器单用途短脚本

执行目标选择器会在需要时标出可执行语句并展示预览。可以在设置中启用或关闭,但生产和复杂脚本建议保留。

大型 .sql 文件、需要逐语句进度或文件级统计的任务,应使用 SQL 文件执行。

自动补全与语义诊断

补全会结合当前数据库方言和元数据提供:

  • SQL 关键字、函数、类型和数据库专属语法
  • 数据库、Schema、表、视图、字段和字段注释
  • 表别名、CTE、子查询作用域和可见字段
  • 基于外键或关系元数据的 JOIN 条件
  • MySQL、PostgreSQL、SQL Server、ClickHouse 等方言的函数和语法建议
  • 用户配置的 SQL 代码片段

语义诊断会标出部分无法解析的表、字段、别名和 SQL 结构。它用于提前发现问题,不代表数据库一定会拒绝或接受语句;厂商扩展语法仍以服务端结果为准。

刚创建或修改对象后,先刷新连接元数据。DBX 会缓存并按需加载表结构,以减少大型 Schema 的重复请求。

表和对象导航

  • Ctrl/Cmd+Click 表名可以按设置打开表数据或定位对象
  • 从光标位置可以在侧边栏定位当前引用的表
  • 快速打开支持搜索连接、数据库、表、SQL 文件和 SQL 库
  • 对象源码视图支持搜索,并可以把 SQL 打开到编辑器继续修改

导航依赖 SQL 解析和当前元数据。动态 SQL、同名对象或缺少 Schema 的引用可能需要手动确认目标。

SQL 参数与变量

执行前,DBX 可以识别常见占位符并打开参数输入对话框:

语法示例
位置参数?
命名参数:user_id
Shell 风格${user_id}
MyBatis 风格#{user_id}
SQL Server 风格@user_id
脚本变量@set user_id = 42;

参数可以按字符串、数字、布尔、NULL 或原始 SQL 值输入。每种数据库可以在设置中关闭会与原生语法冲突的占位符形式。

“原始 SQL”参数不会自动加引号。只应填入经过审查的 SQL 片段,不要直接拼接不可信输入。

格式化、压缩与折叠

  • 格式化 SQL统一缩进、换行和关键字风格
  • 压缩 SQL移除不必要的空白,适合复制或排查生成 SQL
  • 代码折叠收起长查询、子查询或过程块;折叠快捷键可以配置
  • 格式化选项和变量语法见 SQL 格式化

格式化和压缩只修改编辑器文本,不会执行 SQL。

PL/SQL 调试

Oracle 与 OceanBase Oracle 模式的过程、函数、包成员和匿名块可从调试入口执行逐步检查。启动、显式调试编译、会话恢复及事务边界见 PL/SQL 调试。

执行计划

执行计划入口只接受可安全分析的查询类 SQL,例如 SELECT、WITH、TABLE 或 VALUES。支持的数据库会返回:

  • 标准结果表格
  • 可展开的计划树
  • 节点、成本、预估行数、表和索引摘要
  • 数据库返回的原始详情

不同数据库的 EXPLAIN 语义不同,部分引擎只提供表格或文本结果。执行计划反映优化器估算,不等于真实生产性能;需要结合数据量、统计信息、索引和实际耗时判断。

查看会话已有的诊断证据

Oracle 和 OceanBase Oracle 连接可从连接右键菜单打开进程列表,点击会话行的诊断,查看 SQL、已有计划、统计与等待、长操作。此入口只读取数据库已经保留的证据,不执行目标 SQL,也不生成新的执行计划。

诊断会固定打开时的会话与 SQL 身份;刷新继续读取同一目标。会话切换 SQL 后,页面会标明目标已变化,不会把新 SQL 的数据接到原结果。多个审计请求或缓存计划需要手动选择。SQL 文本会标明完整性;缓存计划中的行数是估算值,Oracle 游标累计统计、OB 请求统计和缓存累计统计分别标明口径。

停止读取结束本地等待,并尝试取消诊断查询,不会终止目标会话。权限不足、视图不可用、缓存淘汰或数据未采集会分别显示;刷新失败时保留此前读到的数据及其采样时间。长操作没有记录不代表 SQL 已完成;OB 长操作只显示已有时间信息,不推算工作量百分比。

查询历史

在 设置 → 数据 → 查询历史保留条数 中,可选择 200、1000(默认)、5000、10000 或 不限。上限由所有连接及执行来源(包括 MCP)共用。调小后,下次记录历史时才会删除超出上限的旧记录;提高上限不会恢复已删除的记录。历史分页大小保持不变。

查询历史按连接保存已执行 SQL,并记录时间和相关上下文。可以:

  • 按日期范围过滤
  • 搜索并重新填入编辑器
  • 区分普通执行和 AI 辅助来源
  • 从历史 SQL 恢复或对比之前的排查过程
  • 在字段血缘中把历史 SQL 作为可能引用关系
查询历史可能包含业务字段、表名、筛选条件或数据字面量。共享日志、截图或配置备份前先检查敏感信息。

SQL 库与 SQL 文件

方式适合场景平台边界
SQL 库在 DBX 中按文件夹保存和搜索常用查询桌面版支持完整本地 SQL 库管理;同步范围见云同步设置
外部 SQL 文件与项目仓库、脚本目录或编辑器共享 .sql 文件本地文件打开、保存和文件树属于桌面端能力
查询标签临时分析和未完成草稿可按设置恢复全部、仅固定标签或不恢复

保存 SQL 时可以搜索或创建文件夹。快速打开会同时索引 SQL 库和 SQL 文件。

桌面端 SQL 文件面板顶部的“定位当前文件”按钮会展开父目录、选中当前打开的文件并滚动到其位置。如果所在目录尚未打开,会先将其加入文件树;未保存的查询无法定位。文件筛选仍然生效,被隐藏或已不存在的文件会显示提示。

安全与边界

  • 只读连接会在核心执行路径拒绝可识别写入
  • 生产环境保护会对写入逐次显示明确确认
  • 危险 SQL 确认和 Redis 命令安全是额外保护层
  • USE 或数据库切换会更新查询上下文,但仍应检查当前连接和目标数据库
  • 自动补全、语义诊断和执行计划都依赖当前驱动与元数据能力

完整规则见 生产环境与写入安全。