DBFlux 使用指南

面向最终用户的实用入门：连接数据库、浏览 Schema、执行查询、处理结果、绘制图表，以及键盘操作模型。

DBFlux 以键盘操作为先。几乎所有操作都同时提供鼠标入口和键盘快捷键。本指南列出的是应用程序默认的键位；完整的活动键位映射可在 设置 → 键盘快捷键 中查看（只读查看器，参见设置概览）。

1. 首次启动与创建连接

启动时，DBFlux 会恢复上一次的会话（打开的标签页）。全新安装时没有可恢复的内容，因此焦点默认落在侧边栏。

打开连接管理器

打开连接管理器以创建或编辑连接：

在侧边栏按 c。
或使用命令面板（Ctrl+Shift+P，macOS 上为 Cmd+Shift+P）执行 打开连接管理器。

选择驱动

连接管理器会显示一个驱动选择器。可用驱动取决于二进制构建时启用的 feature；标准构建包含 SQLite、PostgreSQL、MySQL/MariaDB、MongoDB、Redis、DynamoDB、Microsoft SQL Server 以及基于 AWS 的集成。外部注册的 RPC 驱动在配置后也会出现在这里（参见 RPC services config）。

使用 / 筛选驱动列表，j/k（或方向键）移动，Enter 确认选择。

表单模式与直接填写 URI

每个驱动都有自己的连接表单。表单是动态的：只显示该驱动真正需要的字段。大多数关系型驱动支持两种填写连接信息的方式：

表单模式：逐项填写各个字段（主机、端口、数据库、用户等）。
直接填写 URI：只填一个连接字符串字段。

以文件为基础的驱动（如 SQLite）则使用文件路径表单。

访问标签页：直连、SSH、代理、托管

访问标签页决定 DBFlux 如何到达数据库：

直连 — 使用基础选项中的字段直接连接主机。直连模式仍支持按字段解析 AWS 云密钥管理、AWS 参数存储和认证会话字段等取值来源。
SSH — 通过 SSH 主机建立隧道后连接。SSH 隧道配置在设置 → SSH 隧道中集中管理，按连接选择。
代理 — 通过 SOCKS5 或 HTTP CONNECT 代理路由连接。对单个连接而言，代理与 SSH 互斥。
托管 — 由提供程序托管的访问方式（例如 aws-ssm，界面中显示为 SSM 端口转发），DBFlux 先通过外部提供程序开通访问，再建立连接。

连接时，DBFlux 会执行预连接流水线：认证与会话验证、解析动态值，然后打开托管 / 直连访问通道，接着连接驱动并获取初始 Schema。连接 Hook（如果已配置）在预连接、后连接、预断开和后断开阶段执行。Hook 的定义位置见设置概览。

2. 浏览 Schema

侧边栏有两个标签页：

连接 — Schema 树（数据库、Schema、表 / 集合、列、索引，以及在驱动支持时的例程文件夹）。
脚本 — 已保存的查询文件、脚本 Hook 和其他用户文件的文件与文件夹管理。

使用 q 或 e 在两个标签页之间切换。

浏览树

j/k（或 Down/Up）— 选择下一项 / 上一项。
h 折叠、l 展开当前节点。Space 展开 / 折叠。
g 选择第一项，Shift+g 选择最后一项；Home/End 作用相同。
Ctrl+d/Ctrl+u（或 PageDown/PageUp）— 向下 / 向上翻页。
/ 聚焦侧边栏搜索 / 筛选框。
Enter 打开选中项（例如打开表会打开一个数据网格）。
r 刷新 Schema；d 断开当前连接。
m 打开选中项的项目菜单。

延迟加载

Schema 采用延迟加载。连接时，DBFlux 仅获取名称等浅层元数据；展开节点时，再按需获取列、索引等详细元数据。这样可以在大型数据库中缩短初始连接时间。

例程 / 存储过程

对于声明支持例程的驱动（PostgreSQL 是第一个实现），Schema 树中包含一个例程文件夹，内有函数、存储过程、聚合函数和窗口函数。打开某个例程会打开一个只读代码文档，显示其定义。该文档不可编辑，但仍可选取并复制其中的文本；执行与变更控件会被隐藏。

3. 执行查询

使用 Ctrl+n（macOS 上为 Cmd+n）新建查询标签页，或使用 Ctrl+o 打开脚本文件。编辑器的查询语言（SQL、MongoDB 查询语法、Redis 命令等）由当前活动连接的驱动决定，该驱动同时决定语法高亮方式和占位提示文本。

执行

Ctrl+Enter（Cmd+Enter）— 执行查询。
Ctrl+Shift+Enter（Cmd+Shift+Enter）— 在新标签页中执行查询。

如果存在非空文本选区，则只执行选中的文本；如果未选中文本，则执行整个编辑器中的内容。

多语句脚本

当未选中文本且编辑器内容包含多个以 ; 分隔的语句时，如果当前活动驱动声明支持批量执行，DBFlux 会在执行前显示确认对话框（执行整个脚本，询问是否按顺序执行全部 N 条语句）。确认后，每个语句的结果集会渲染在各自的结果标签页中。

语句分割对 SQL 系列语言是可感知语言的：字符串、标识符、单行 / 块注释以及 PostgreSQL 美元引用代码块中的分隔符不会被视为语句边界。非 SQL 语言仍按单语句处理。批量执行支持按驱动而定 — 内置 SQL 驱动中，PostgreSQL、MySQL/MariaDB、SQLite 和 Microsoft SQL Server 支持该能力。选中的文本始终按原样执行，不会触发脚本确认。

危险查询确认

DBFlux 会跨语言检测危险操作 — SQL 的 DELETE/DROP/TRUNCATE 以及不带 WHERE 的 DELETE/UPDATE、MongoDB 的 deleteMany/drop、Redis 的 FLUSHALL/FLUSHDB/KEYS — 并在执行前提示确认。该行为由设置控制：可以关闭 确认危险查询、可以要求 DELETE/UPDATE 必须带 WHERE 子句（DELETE / UPDATE 需要 WHERE），也可以完全禁用 Redis 的 FLUSHALL/FLUSHDB（此时这些命令会被直接阻止，而不是弹出确认）。

脚本（Lua / Python / Bash）

Lua、Python 和 Bash 文档作为脚本执行，而不是数据库查询。执行过程中，它们的输出会实时流入文档的输出区域，最终输出则保留为文本结果。内嵌 Lua 运行时参见 Lua scripting。

可视化查询构建器

对于 SQL 连接，无需编写 SQL 也能组合查询。在表的数据网格工具栏中点击 构建器，即可打开右侧栏面板。构建器仅在 SQL 驱动上可用；非 SQL 连接不会显示该入口。

面板顶部有一个模式选择器 — SELECT、UPDATE、DELETE — 以及一个实时 SQL 预览，每次更改都会重新生成。预览始终可见。点击执行执行查询，或（在 SELECT 模式下）点击 在编辑器中打开 把生成的 SQL 放入普通查询编辑器。标题栏中有保存和重置。

按键	操作
`Cmd+Enter` / `Ctrl+Enter`	执行
`Cmd+E` / `Ctrl+E`	在编辑器中打开（仅 SELECT 模式）
`Cmd+S` / `Ctrl+S`	保存
`Cmd+Shift+S` / `Ctrl+Shift+S`	文件另存为
`Cmd+Backspace` / `Ctrl+Backspace`	重置

构建 SELECT

SELECT 主体按从上到下的顺序分为以下几个部分：

列 — 投影，即要选取哪些列。
筛选 — 一个 WHERE 谓词树。谓词可以嵌套成 AND/OR 分组，因此可以可视化地组合复杂条件。
连接 — 附加的表，需要指定别名和 ON 条件。
按列分组 / 聚合项 — 见下文。
排序 — ORDER BY 条目。
Limit & Offset — 分页边界。

SQL 预览是参数化的：字面值会按当前活动方言（SQLite、PostgreSQL、MySQL/MariaDB 或 SQL Server）输出为占位符。

GROUP BY 与聚合

在 按列分组 / 聚合项 部分添加分组列和聚合。支持的聚合函数为 COUNT、COUNT(*)、COUNT(DISTINCT)、SUM、AVG、MIN 和 MAX。每个聚合都有一个可编辑的别名，由函数和列名自动生成。

一旦查询进入分组状态：

列部分会替换为有效 SELECT 的只读预览（分组列在前，聚合别名在后）。
出现 Having 部分，使用与筛选相同的谓词编辑器，但作用于 HAVING。
排序条目被限制为分组列和聚合别名；无效条目会被拒绝并给出可见的错误提示。

分组结果在数据网格中的行为，参见聚合结果。

Schema 感知自动补全

构建器的单行输入框（筛选、排序、投影列、连接目标表，以及连接 ON 的两侧）提供内联建议，建议来源于实时 Schema 和构建器自身的 spec：源表列、已声明的连接别名，以及被连接表的列（在后台延迟加载）。输入 <alias>. 会把建议范围限定为该别名下的列。匹配仅按前缀进行。

按键	操作
`Up` / `Down`	在建议项之间移动
`Tab` / `Enter`	采用高亮的建议项
`Esc`（或失去焦点）	关闭建议

数据网格的 WHERE 筛选输入框也提供同样的自动补全（参见筛选结果）。

已保存的查询

构建器可以按连接配置保存，之后重新打开。已保存的查询归属于该连接配置，名称唯一。已保存的查询也可以导入到另一个连接上；导入时，DBFlux 会先验证被引用的表在目标连接上存在，再加载。

可视化 UPDATE 与 DELETE

把模式选择器切换到 UPDATE 或 DELETE 即可构建变更语句。两种模式都复用同一个筛选编辑器来构造 WHERE 子句；UPDATE 额外提供一个赋值部分，用于 SET 列（包括原生 SQL 表达式赋值）。SQL 预览全程保持可见。

变更受一项策略约束，该策略综合了连接的只读状态与执行者上下文：

策略	效果
允许	可以执行该变更。
只读	不允许执行变更（例如只读连接配置）。
需要审批	该变更必须先获得审批才能执行。

执行模式。 执行部分提供三种模式，默认值根据行数估计、驱动的事务支持能力和主键可用性自动建议。覆盖该建议时会弹出一个权衡说明模态框。

模式	行为
单事务	整个变更使用一个事务。
分块事务	基于表的主键以 keyset 方式分页，把变更拆分成多个分块（分块大小限制在 `[1000, 10000]`，默认 5000）。每个分块各自是一个事务，会在任务面板中显示条目，支持在分块之间取消，失败时回滚。
直接	不使用事务包装（自动提交）。在驱动不支持事务时使用。

危险查询闸门。 不带 WHERE 的 UPDATE 或 DELETE 在执行前会受到危险查询确认的拦截（参见危险查询确认）。

4. 处理结果

结果渲染在文档内的结果标签页中。视图模式根据数据库类别自动选择：

关系型数据库使用表格视图。
文档数据库（例如 MongoDB、DynamoDB）使用文档树视图。
Redis 使用键值视图。

当驱动声明了事件流呈现方式时，事件流类型的容器会作为事件流打开。

浏览数据网格

当结果面板获得焦点时：

j/k（或 Down/Up）— 选择下一项 / 上一项。
h/l（或 Left/Right）— 左移 / 右移一列。
g/Shift+g（或 Home/End）— 选择第一项 / 最后一项。
Ctrl+d/Ctrl+u（或 PageDown/PageUp）— 向下 / 向上翻页。
[ / ] — 结果上一页 / 下一页。
f 聚焦工具栏；/ 聚焦搜索 / 筛选框。
z 切换面板。
m（或 Shift+F10）打开行 / 单元格上下文菜单。

筛选结果

数据网格工具栏有一个 WHERE 筛选输入框，会带上你输入的条件重新执行查询。对于 SQL 连接，它支持两种写法：

原生 WHERE — 输入一个普通条件（例如 status = 'active'）。这是默认行为。
关系型（ORM 风格）路径 — 输入一个沿外键前进的点分路径，例如 created_by.email LIKE '%@acme.com' 或 created_by.organization.name = 'Acme'。DBFlux 会依据表的外键元数据解析该路径，并自动连接到被引用的表，无需手工编写 JOIN。

当关系型筛选解析成功时，会显示一个标签，说明它添加了多少个连接。如果某一段存在歧义或无法解析，会出现内联错误，并附一个 在构建器中打开 链接，用于打开可视化查询构建器，并预填已解析出的连接。不含点号的输入始终保持原生 WHERE 行为。

筛选输入框同样提供 Schema 感知自动补全（导航方式与构建器相同，参见Schema 感知自动补全）。

编辑与增删改查

在数据网格中：

o — 添加行。
x — 删除选中的行。
r — 重命名 / 编辑（随上下文而定）。
y — 复制选中的行。
Ctrl+c（Cmd+c）— 把选中的单元格复制到剪贴板。

结果何时可编辑

普通的表浏览在表有主键时可编辑。由构建器（SELECT 模式）产生的结果同样可编辑，但前提是该结果可证明绑定到单一表：结果与唯一的底层表 1:1 映射，且该表的每个主键列都以原始名称被投影出来。此后，编辑和删除会依据投影出的主键值构造 WHERE。

允许 JOIN：来自源表的列可编辑，被连接的列则为只读。

构建器结果在以下任一情况成立时会回退为只读，并在工具栏给出原因提示：

查询使用了聚合，或使用了 GROUP BY / HAVING。
投影是跨 JOIN 的通配符。
某个主键列缺失，或以别名形式被投影。
表的键尚未从 Schema 缓存加载完成（键加载完成后，网格会自动升级为可编辑）。

在编辑器中手写的自由 SQL 始终保持只读；内联编辑只适用于普通表浏览和构建器生成的 SELECT。

聚合结果

当结果来自分组（GROUP BY）查询时，各行显示聚合后的输出，编辑功能被禁用 — 添加行、删除行、编辑单元格和检查行都不可用，并给出解释性提示。分页按分组后的行数计算（而不是底层行数），因此总页数是准确的。聚合列保持正确的列类型，因此仍能正常绘制图表。

复制为查询

结果上下文菜单中包含 复制为查询，它使用驱动自身的查询生成器，根据选中的行生成驱动专属的变更语句（对于非 SQL 驱动则是信封）。

导出

在结果面板中按 Ctrl+e（Cmd+e），或从命令面板执行 导出结果。可用格式取决于结果形态，包括：

CSV
JSON（美化） 与 JSON（紧凑）
文本
二进制（用于二进制形态的结果）

5. 绘制结果图表

任何产生表格化结果的查询都可以绘制成图表。在查询编辑器工具栏中点击图表按钮（提示文本为“在图表文档中打开当前查询”），即可在图表文档中打开当前查询。

图表使用驱动提供的列类型元数据来自动检测轴（时间列、数字列等）。支持的图表类型包括：

Line — 折线图
Bar — 柱状图
Scatter — 散点图
Area — 面积图
Stacked Bar — 堆叠图
Pie — 饼图

图表可以按连接配置保存。要重新打开已保存的图表，请从命令面板执行 打开图表…（OpenSavedChart），它会以支持模糊搜索的浮层列出当前连接配置下已保存的图表。

6. 已保存的查询与历史记录

DBFlux 会保留已完成查询的历史记录，并允许你保存命名查询。

Alt+h（在编辑器中）切换历史下拉菜单。
Ctrl+s（Cmd+s）— 保存查询。
Ctrl+Shift+s（Cmd+Shift+s）— 文件另存为。
Ctrl+p（Cmd+p，在编辑器中）— 打开已保存查询。

在历史模态框中，可以使用 Ctrl+j/Ctrl+k（或方向键）导航，Enter 打开条目，并使用该模态框内的局部快捷键 Ctrl+f（切换收藏）、Ctrl+r（重命名）和 Ctrl+d（删除）。/ 聚焦模态框搜索框。

7. 键盘快捷键

DBFlux 使用分层、随上下文变化的键位映射。当前生效的层取决于哪个面板拥有焦点。以 primary 修饰键书写的绑定，在 macOS 上使用 Cmd，在其他平台上使用 Ctrl；以字面 Ctrl 书写的绑定则在所有平台上都保持 Ctrl（以避免与 macOS 系统快捷键冲突）。

全局（无论焦点在哪都可用）

按键	操作
`Ctrl+Shift+P` / `Cmd+Shift+P`	切换命令面板
`Ctrl+n` / `Cmd+n`	新建查询标签页
`Ctrl+w` / `Cmd+w`	关闭当前标签页
`Ctrl+Tab` / `Ctrl+Shift+Tab`	下一个 / 上一个标签页
`Ctrl+1` .. `Ctrl+9` / `Cmd+1` .. `Cmd+9`	切换到标签页 N
`Ctrl+o` / `Cmd+o`	打开脚本文件
`Ctrl+Enter` / `Cmd+Enter`	执行查询
`Ctrl+Shift+Enter` / `Cmd+Shift+Enter`	在新标签页中执行查询
`Escape`	取消 / 关闭模态框
`Tab` / `Shift+Tab`	向前 / 向后循环聚焦
`Ctrl+Shift+1`	聚焦侧边栏
`Ctrl+Shift+2`	聚焦编辑器
`Ctrl+Shift+3`	聚焦结果
`Ctrl+Shift+4`	聚焦后台任务
`Ctrl+Shift+A` / `Cmd+Shift+A`	打开审计查看器
`Ctrl+b` / `Cmd+b`	切换侧边栏
`Ctrl+m`	打开标签页菜单

侧边栏

按键	操作
`q` / `e`	侧边栏下一个标签页（连接 / 脚本）
`/`	聚焦搜索
`j` / `k`（或 `Down` / `Up`）	选择下一项 / 上一项
`h` / `l`	折叠 / 展开节点
`Space`	展开 / 折叠
`g` / `Shift+g`（或 `Home` / `End`）	选择第一项 / 最后一项
`Ctrl+d` / `Ctrl+u`（或 `PageDown` / `PageUp`）	向下 / 向上翻页
`Enter`	打开 / 执行项
`r`	刷新 Schema
`c`	打开连接管理器
`d`	断开连接
`m`	打开项目菜单
`Shift+j` / `Shift+k`	向下 / 向上扩展选择
`Space`（配合 Shift）	切换选择
`Ctrl+j` / `Ctrl+k`	下移 / 上移所选项
`Shift+r`	重命名
`x`	删除
`Shift+n`	新建文件夹
`Ctrl+l`	聚焦右侧

编辑器

按键	操作
`Ctrl+h` / `Ctrl+j` / `Ctrl+k`	聚焦左侧 / 下方 / 上方
`Alt+h`	切换历史下拉菜单
`Ctrl+p` / `Cmd+p`	打开已保存查询
`Ctrl+s` / `Cmd+s`	保存查询
`Ctrl+Shift+s` / `Cmd+Shift+s`	文件另存为
`Enter`	聚焦 / 执行

（未加修饰的字母键有意留给文本输入，以保证正常录入。）

结果

按键	操作
`Ctrl+h` / `Ctrl+k` / `Ctrl+l`	聚焦左侧 / 上方 / 右侧
`Ctrl+j`	聚焦工具栏
`j` / `k`（或 `Down` / `Up`）	选择下一项 / 上一项
`h` / `l`（或 `Left` / `Right`）	左移 / 右移一列
`g` / `Shift+g`（或 `Home` / `End`）	选择第一项 / 最后一项
`Ctrl+d` / `Ctrl+u`（或 `PageDown` / `PageUp`）	向下 / 向上翻页
`]` / `[`	结果下一页 / 上一页
`Ctrl+e` / `Cmd+e`	导出结果
`f`	聚焦工具栏
`/`	聚焦搜索 / 筛选
`x`	删除行
`r`	重命名 / 编辑
`o`	添加行
`y`	复制行
`Ctrl+c` / `Cmd+c`	复制单元格
`z`	切换面板
`m`（或 `Shift+F10`）	打开上下文菜单

后台任务

按键	操作
`Ctrl+h` / `Ctrl+j` / `Ctrl+k`	聚焦左侧 / 下方 / 上方
`j` / `k`（或 `Down` / `Up`）	选择下一项 / 上一项
`g` / `Shift+g`（或 `Home` / `End`）	选择第一项 / 最后一项
`Ctrl+d` / `Ctrl+u`（或 `PageDown` / `PageUp`）	向下 / 向上翻页
`z`	切换面板

命令面板

按键	操作
`j` / `k`（或 `Down` / `Up`）	选择下一项 / 上一项
`Enter`	执行
`Escape`	取消

上下文菜单

按键	操作
`j` / `k`（或 `Down` / `Up`）	菜单下移 / 上移
`Enter` / `l`（或 `Right`）	菜单选择 / 进入子菜单
`Escape` / `h`（或 `Left`）	菜单返回 / 关闭

历史

按键	操作
`Ctrl+j` / `Ctrl+k`（或 `Down` / `Up`）	选择下一项 / 上一项
`Enter`	打开条目
`Ctrl+f`	切换收藏
`Ctrl+r`	重命名
`Ctrl+d`	删除
`/`	聚焦搜索
`Ctrl+s` / `Cmd+s`	保存查询

8. 设置概览

设置包含以下部分（MCP 相关部分只在带有 AI/MCP 支持的构建中出现，默认为带）：

常规 — 应用级偏好：主题、启动 / 会话、刷新默认值，以及危险查询确认行为。
审计 — 审计日志捕获的内容（日志捕获最低级别）与保留策略。
MCP 客户端 / 角色 / 策略 — AI 客户端治理（受信客户端、角色、策略）。参见 AI + MCP。
键盘快捷键 — 活动键位映射的只读查看器，提供文本筛选和冲突警告。不支持在 UI 中重新绑定。
代理 — SOCKS5 / HTTP CONNECT 代理配置。
SSH 隧道 — 可按连接选择的 SSH 隧道配置。
访问提供程序 — 由提供程序驱动的认证配置文件（AWS SSO / 共享凭据）。
RPC 服务 — 外部注册的 RPC 服务（驱动与认证提供程序）。参见 RPC services config。
Hooks — 全局连接 Hook 定义（命令、脚本和 Lua 模式）。按连接配置的阶段绑定位于连接管理器的 Hooks 标签页中。
驱动 — 各驱动的覆盖项和设置。
关于 — 版本与构建信息。

完整的逐项设置参考以及连接 Hook 指南，参见 Settings & hooks。