# 通过 1Panel 部署 DBX > 使用 1Panel 应用商店安装、访问和更新 DBX Web 版。 Source: https://dbxio.com/cn/docs/1panel Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/1panel. 1Panel 应用商店提供了 DBX 官方 Docker 镜像，可以直接在服务器上完成安装和更新，不需要手动编写 Docker 命令。 1Panel 安装的是 DBX Web 版。数据库查询、对象浏览、数据编辑、导入导出、AI 和驱动管理等核心能力在服务器端运行；本机文件选择、Deep Link、本机 CLI Agent 和桌面版定时数据库备份不属于 Web 运行方式。 ## 可选的服务器方案 如果你还没有用于部署 DBX 的服务器，可以了解[雨云](https://www.rainyun.com/MTE5Mjc4Ng==_)。雨云是面向开发者和站长的云服务提供商，提供云服务器、物理服务器、游戏云和配套基础设施服务。当然，任何满足 Docker 和 1Panel 运行要求的服务器都可以部署 DBX。 ## 安装 DBX 1. 登录 1Panel，打开 **应用商店**。 2. 搜索 `DBX`，选择 DBX 官方应用。 3. 选择要安装的版本，点击 **安装**。 4. 在安装表单中确认以下配置： | 配置项 | 默认值 | 说明 | | ---- | ------ | ---------------------------------------------------------------- | | 端口 | `4224` | 服务器对外提供 DBX Web 访问的端口。若该端口已被占用，请改为其他未使用端口。 | | 访问密码 | 自动生成 | 打开 DBX Web 版时使用的登录密码。1Panel 会按 `random: true` 规则生成默认值，也可以在安装时修改。 | 5. 点击 **确定**，等待 1Panel 拉取镜像并启动容器。 访问密码不是数据库密码，而是 DBX Web 版的登录密码。请保存安装时设置或生成的密码。 ## 访问 DBX 安装完成后，在浏览器中打开： ```text http://服务器 IP:端口 ``` 例如端口保持默认值时： ```text http://192.168.1.100:4224 ``` 在登录页面输入安装时设置的 **访问密码**。如果无法访问，请依次检查： * 1Panel 中 DBX 应用是否显示为运行中； * 浏览器地址中的端口是否与安装表单中的端口一致； * 云服务器安全组和系统防火墙是否允许该端口； * 端口是否被其他服务占用。 ## 持久化与更新 DBX 的应用数据保存在 1Panel 应用目录的 `data` 目录，并挂载到容器内的 `/app/data`。这里包含 DBX 自身的存储数据库、已保存连接、插件、驱动和其他持久化状态。重启容器或更新 DBX 时，只要挂载目录未被删除，这些数据就会继续保留。 更新时，在 1Panel 的 **已安装** 应用中打开 DBX，选择可用的新版本并执行更新。更新前建议先确认数据目录已经纳入服务器备份。 不要直接删除 DBX 的应用数据目录，否则会同时删除已保存的连接配置和其他本地数据。卸载应用前请先完成备份。 备份 `/app/data` 只保护 DBX 的应用配置和运行数据，不会备份 MySQL、PostgreSQL 等目标数据库中的业务数据。Web 版不提供桌面版的定时数据库备份任务；业务数据库仍应使用数据库原生备份、云服务快照或独立备份系统。 DuckDB 不嵌入 `dbx-web` 镜像。首次启动后如需使用 DuckDB，请在[驱动管理器](/cn/docs/driver-management)中单独安装；驱动保存在 `/app/data/agents`，因此也依赖同一个持久化目录。 ## Web 版路径与文件 在 1Panel 部署中，DBX 后端读取的是服务器或容器文件系统： * SSH 私钥路径必须是容器可读取的路径，不是浏览器电脑上的路径； * JDBC JAR、插件、Agent 和下载的驱动保存在服务器端数据目录； * 浏览器上传的导入文件会先进入服务器端受控目录，再由任务读取； * 数据库文件连接和服务器端路径都必须从容器视角判断可访问性。 不要因为浏览器运行在个人电脑上，就把本机绝对路径填写到 Web 版配置中。桌面版与 Web 版的完整边界见[什么是 DBX](/cn/docs/what-is-dbx)。 ## 连接数据库 登录 DBX 后，点击 **新建连接**，填写目标数据库的类型、地址、端口、用户名和数据库密码。运行在 1Panel 服务器上的 DBX 容器必须能够访问目标数据库： * 如果数据库也运行在同一台服务器上，使用服务器可访问的地址和端口； * 如果数据库运行在同一个 Docker 网络中，使用数据库容器名和容器端口； * 如果数据库位于内网，确保 1Panel 服务器已经接入对应网络，或按需配置 [SSH 隧道](/cn/docs/ssh-tunnel)。 `4224` 是 DBX Web 服务端口，不是目标数据库端口。连接数据库时仍需填写 MySQL、PostgreSQL、Redis 等目标数据库自身的端口。 ## 生产部署建议 * 使用足够长且唯一的访问密码，不要保留示例值； * 通过 1Panel 反向代理配置 HTTPS，并限制安全组和主机防火墙暴露范围； * 需要受控升级时固定版本，更新前备份 `/app/data` 并阅读[更新日志](/cn/changelog)； * 为 DBX 使用独立、最小权限的数据库账号，生产连接优先启用只读保护； * 定期检查驱动和插件来源，不要把不受信任的 JAR 或可执行文件放入数据目录。 更多连接、写入、AI 和 API 边界见[生产安全](/cn/docs/production-safety)。 ### [驱动管理](/cn/docs/driver-management) 安装 Web 版需要的 DuckDB、JDBC 和 Agent 驱动，并查看运行状态。 ### [数据库备份](/cn/docs/database-backup) 了解桌面版定时备份的支持范围，以及 Web 部署为什么需要外部备份方案。 --- # AI 助手 > 配置云端、兼容 API 或本地 CLI 模型，在 Schema 上下文中生成 SQL、分析数据并执行受控 Agent 工作流。 Source: https://dbxio.com/cn/docs/ai-assistant Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/ai-assistant. AI 助手把当前会话绑定的连接、数据库和 Schema，与编辑器 SQL、错误、结果预览和用户点名的对象组合成上下文，用于生成 SQL、解释查询、优化语句、修复错误和分析数据。每个会话各自持有绑定，使用不同连接的会话互不串用目标。 Ask 模式只生成建议；Agent 模式在用户明确要求真实数据时可以调用查询工具。任何模型输出都可能错误。执行 SQL 前仍应检查目标连接、字段、过滤条件、参数和影响范围。 ## 支持的模型接入方式 ### API 供应商 DBX 内置以下配置预设： * Claude * OpenAI * Gemini * DeepSeek * Qwen * MiniMax * Ollama * OpenAI Compatible * Anthropic Compatible * Custom 兼容或自定义配置可以设置端点、模型、API 风格、认证方式、代理、上下文窗口和额外 HTTP 请求头。API 风格包括 OpenAI 风格 completions、Responses API 和 Anthropic Messages。供应商支持时，DBX 会读取模型列表并过滤掉不适合对话/Agent 的模型。 ### 本地 CLI Agent Desktop 还可以直接调用已安装并登录的： * Claude Code CLI * Codex CLI * Pi Coding Agent 可以配置可执行文件路径和额外环境变量。CLI Agent 运行在 Desktop 所在电脑，并通过 DBX 提供的受限 MCP 工具访问当前数据库。Docker/Web 不会显示这些本机 CLI 供应商，因为服务器不能假设浏览器电脑上安装了对应命令。 ## 添加配置 ### 打开 AI 设置 在编辑器设置中进入 AI，添加一个命名配置。可以为同一供应商保存多套端点或凭据。 ### 选择供应商和模型 使用预设、兼容 API、自定义端点或本地 CLI。模型列表可发现时从供应商或本地 CLI 读取，也可以手动填写。手动填写的模型会保存到当前配置；当兼容供应商未提供模型发现接口或发现失败时，已保存的模型仍可选择。 ### 配置认证和推理参数 API 模式填写 API Key、认证方式、端点、代理和自定义 HTTP 请求头。请求头可用于网关认证或租户路由，例如 `X-GoModel-User-Path: /dbx-assistant`；模型发现、连接测试、对话和 Agent 请求都会携带它们。支持的模型可以选择 effort、reasoning 或 thinking；具体选项来自供应商能力，而不是对所有模型统一显示。 ### 测试并保存 测试会报告成功、延迟、实际模型和认证、限流、超时、模型不存在等错误类别。 API Key、自定义请求头的值、CLI 环境变量和自定义端点可能具有敏感性。不要把设置截图、导出的配置或调试日志发送到不可信位置。 ## Ask 和 Agent | 模式 | 适合任务 | 工具和执行行为 | | ----- | ---------------------------------- | ----------------------------- | | Ask | 生成、解释、优化、修复、转换 SQL，或基于已有上下文给建议 | 不主动执行数据库查询；最终答案应明确区分建议和已验证结果 | | Agent | “查出结果”“对比真实数据”“先看表结构再回答”等需要迭代取证的任务 | 可以列表、读字段、取样和执行只读查询；写入必须经过精确确认 | Agent 只有在原始请求明确要求真实数据/结果时才应执行查询。仅要求“写一条 SQL”时，即使处于 Agent 模式，也应返回 SQL 而不是自动运行。 ## Agent 轮次和重试 * **最大 Agent 轮次**：默认 30，可配置 5–500。它限制模型、工具调用和修复循环的总轮数，防止复杂任务无限运行 * **最大 API 重试次数**：默认 2，可配置 0–10。只用于限流、超时和临时网络错误；Claude Code、Codex 和 Pi CLI 不使用这个 API 重试设置 * 达到轮次上限、用户取消、连接失败或工具策略拒绝时，Agent 会停止并保留已有步骤和错误 提高轮次上限会增加时间、数据库读取次数和模型成本。应先通过明确提示、表提及和缩小任务范围减少无效探索。 ## Schema、表和 SQL 文件上下文 AI 上下文可以包含： * 数据库类型、连接名称、数据库和 Schema * 当前编辑器 SQL、最近错误（编辑器与会话绑定在同一连接和数据库上时才纳入），以及显式发送过来的编辑器选区 * 表、字段、索引、外键和少量样例数据 * 连接笔记文件中的表和字段笔记（优先于数据库注释） * 当前结果集的有限预览 * 用户选择的提示模板 * 被提及的保存 SQL 文件内容 在输入框键入 `@` 可以搜索表和保存的 SQL 文件： * `@users`：优先加入 `users` 的元数据 * `@public.orders`：指定 Schema 中的表 * 同时选择多张表或 SQL 文件：把相关上下文一起交给模型 ### 从编辑器发送选区到 AI 在 SQL 编辑器中选中文本后，右键选择 **发送到 AI**（或使用对应快捷键），选区会以可移除的芯片出现在 AI 输入框上方，输入框保持为空并聚焦，由你输入真正的问题。选区按**数据**处理而不是指令：SQL 注释里写的“忽略以上指令”不会被当作命令执行。 会话目标取自选区所在的编辑器标签页： * 与当前会话绑定共用同一个连接、数据库（和 Schema）时，复用当前会话 * 不同时新建一个会话并绑定到该标签页，已有会话的绑定不会被改写 * 该标签页的连接已被删除时会话保持未绑定并给出提示，需要你手动选择连接 单个选区上限 12 000 字符，超出会截断并在芯片上标明“已截断”。查询结果报错处的 **用 AI 修复** 使用同一套规则。 完整 Schema 过大时会截断。表提及比让模型在所有对象中猜测更可靠，也能减少 token 和元数据请求。 ## 全局指令和提示模板 设置中可以维护： * **全局指令**：每次 AI 请求都注入，例如命名规范、时区、软删除字段和生产约束 * **提示模板**：按场景保存可复用规则，例如“只生成 PostgreSQL 兼容 SQL”或“分析必须包含索引建议” 助手中可以同时选择多个模板。DBX 在发送时冻结当前全局指令和模板快照，因此请求开始后修改设置不会改变已经运行的任务。 模板会进入模型上下文，应避免放入密码、令牌或不必要的业务数据。规则冲突时，模型未必能按预期选择优先级，应保持全局指令和模板简短、明确且互不矛盾。 ## Skills（SKILL.md） Desktop 可以把只读的 [`SKILL.md`](https://developers.openai.com/codex/skills) 规则文件作为补充性指令使用。技能始终从 `~/.agents/skills` 发现；设置 → AI 中还可以额外启用一个自定义目录。两个目录独立校验，同名技能并列保留并标注来源（`默认目录` / `自定义目录`），自定义目录的技能排在前面。 进入模型上下文的只有每个技能的**名称与描述**（listing）；技能正文改为**按需加载**——模型判断需要时调用 `use_skill` 工具，DBX 才从磁盘读取正文并返回；技能附带的文件（参考文档、脚本、模板）再由模型逐个用 `read_skill_file` 读取。DBX 绝不写入技能文件，读到文件内容也不等于获得执行许可。 在输入区的 `Skills` 入口（或输入 `/skill`）选择技能，选中项以芯片形式显示在输入框上方，可随时移除。**勾选不排他**：选中项在 listing 中标记为用户指定、优先级更高，但模型同样可以从同一份 listing 里加载未勾选的技能。开启**设置 → AI → 允许 AI 自动使用 Skills**（默认关闭）后，即使未勾选任何技能，每次请求也会附带 listing，由模型自行挑选。 芯片有两态：默认态与**本会话中已加载**。模型调用过 `use_skill`，或你点击芯片手动加载过，该芯片就会标记为「已加载」。**点击芯片会立即加载该技能**：DBX 当场读取正文并放进本次对话，下一轮起模型就能看到它。「已加载」按会话记录，关闭后重新打开 AI 面板仍然保留，新建会话则重置。重启 DBX 后 DBX 记住的是「这个技能加载过」这一事实本身：下一次请求需要它时会重新从磁盘读取正文，因此期间被删除、或超过大小限制的技能会退回未加载状态并说明原因。若已勾选的技能在本次对话中始终没有被加载，输入框上方会出现**一次性**提示，点击即可立即加载（每个会话只提示一次）。 Skill 仅对 DBX 内置 AI 可用。CLI 供应商（Claude Code / Codex / Cursor / OpenCode / Grok / Qoder / CodeBuddy / Pi）拿不到 listing、正文与 skill 工具；其选择器会被禁用并说明原因，已勾选的芯片仍然可见、可移除。 因为按需加载，发送时不再读取正文：正文文件被删除、frontmatter 无效、不是 UTF-8 等失败会在**加载时**暴露，而不是阻断发送。唯一的例外是已勾选的技能已不在目录中——此时仍会阻断发送，并在输入框上方显示横幅标明失败的技能，提供重试、刷新、移除或打开设置等恢复操作。超过 1 MiB 的文件、二进制文件、以及离开技能目录的路径一律拒绝。未勾选任何技能且开关关闭时，提示词与既有行为逐字节一致。Web 端不提供该功能。 ## 插件工具 使用 API 供应商的 Agent 模式下，助手还可以调用已安装插件提供的工具——例如通过 SSH 执行命令、读取容器日志、查看 Kafka 消费延迟——并与数据库工具结合起来回答同一个问题。 1. 插件工具按插件显式开启：打开「插件中心 → 已安装」选中插件，开启 **内置 AI 工具** 开关后助手才能调用其工具；点击 **查看工具** 可以看到助手能用哪些工具、以及哪些需要确认；关闭开关即可排除某插件（选择会持久保留）。 2. 打开助手要使用的插件连接（例如那台 SSH 服务器）。工具只会作用于已打开的连接。 3. 在 Agent 模式下提问。插件声明为只读的工具会直接执行；其他调用会暂停运行，并展示完整参数，由你选择 **允许本次** 或 **拒绝**。五分钟未响应视为拒绝，点击停止会取消等待中的请求。 绑定插件连接时，输入框显示插件图标，并隐藏数据库和 Schema 选择器。AI 不再加载数据库表结构，Agent 模式仅保留时间工具与已启用的插件工具。关闭插件的内置 AI 工具开关，也会阻止正在进行的会话继续调用该插件。 工具输出会像查询结果一样发送给你配置的 AI 模型；不希望数据发给模型的插件，请关闭其 **内置 AI 工具** 开关。CLI Agent 供应商不会获得插件工具。 ## 写入和生产安全 AI Agent 的执行边界是后端强制的，不只是提示词： 1. 只读工具可以按任务调用 2. 非只读 SQL 必须先作为明确的 SQL 提案展示 3. 用户确认后，授权只绑定到同一连接、同一数据库和完全相同的 SQL 文本 4. 授权只对下一次运行有效，不会变成永久写入权限 5. 生产数据库上的写入和 DDL 不会授权给 AI Agent；模型只能返回 SQL 供用户在 DBX 中人工审阅执行 连接只读保护、生产保护和数据库账号权限仍是上限。即使用户确认，目标变化、SQL 变化、空确认或后端风险分类不通过都会使授权失效。 Redis 连接改用只读命令工具，而不是 SQL。助手可以执行 DBX 判定为只读的命令（`SCAN`、`GET`、`TYPE`、`TTL`、`HGET` 等）并基于结果回答。写命令或被拦截的命令（`SET`、`DEL`、`EXPIRE`、`EVAL`、`KEYS`、`CONFIG` 等）AI Agent 永不执行：它会把命令作为代码块返回，由你在 Redis 控制台中执行，控制台会先要求确认。`SELECT` 同样不可用，逻辑数据库通过工具的 `db` 参数选择。 AI Agent 不会获得“以后都可以写”的授权，也不会绕过 MCP 策略、连接只读保护或数据库权限。更多边界见 [生产环境安全](/cn/docs/production-safety) 。 ## SQL 代码块操作 回复里的每个 SQL 代码块都提供 **临时运行**、**立即执行** 和 **应用到编辑器**。三者都作用于该对话**自己绑定**的连接、数据库和 Schema 对应的查询页签，而不是当前恰好在前台的那个编辑器。 该页签不存在时会在后台创建，动作本身也**不会移动你的工作区**：AI 动作不会自行切换、选中或打开任何页签。 正因为结果不总落在你眼前，代码块会自己报告结果： * 块内显示 **执行中…**，结束后显示返回或影响的行数，失败则显示数据库返回的错误文本。 * 目标页签不在屏幕上时，提示会写明是哪个页签并提供 **查看**；只有点击 **查看** 才会切过去。 * 根本没跑起来的情况（没有可用连接、页签仍在处理上一个请求、没有可执行的 SQL）也会在块内说明原因。 危险 SQL、生产库、参数和只读解锁仍然使用各自的确认对话框，代码块和提示不会重复一遍。 ## 推理强度和 Thinking 不同供应商使用不同机制：枚举 effort、reasoning level、布尔 thinking、整数预算或自定义文本。DBX 按当前模型能力展示可用选项，并记住每个配置/模型的选择。 * 简单生成或解释可使用供应商默认或较低强度 * 多表推理、复杂优化和错误诊断可提高强度 * 更高强度通常增加延迟和费用，但不保证答案正确 不要把 UI 中的统一标签理解为所有供应商拥有相同推理语义。 ## 对话、历史和导出 * 输入框支持使用 ↑ / ↓ 浏览当前提示历史 * 每个会话按自身的连接、数据库和 Schema 绑定保存，重新打开时恢复该绑定 * 每条最终 AI 分析可以导出为 Markdown，文件包含连接名、时间和最终回答 * Markdown 导出只包含最终分析内容，不会把内部 reasoning 或 Agent 步骤附加到文件中 导出内容仍可能包含表名、SQL、结果片段和业务数据，分享前请审阅和脱敏。 ## 常见任务 ### 生成 SQL > 根据 `@orders` 和 `@customers` 生成最近 30 天客户销售额 Top 10 查询，只返回 SQL，不执行。 明确写出“不执行”可以让意图更清晰。检查时间函数、Schema 限定、JOIN 键、空值和返回行数。 ### 分析真实数据 > 查询 `@orders` 最近 7 天每天的订单数，执行只读查询并解释异常峰值。 这类请求适合 Agent 模式，因为它明确要求真实结果。 ### 修复错误 把失败 SQL、数据库错误和涉及的表一起提供。AI 可以读取字段和方言信息，但版本特有行为、权限、锁和运行计划仍需人工验证。 ## 隐私和故障排查 * 云端供应商会收到发送给模型的提示、Schema 摘要、SQL 和有限结果上下文；以供应商隐私条款为准 * Ollama 和本地 CLI 可以在本机运行，但模型进程和 CLI 插件仍可能有自己的联网或日志行为 * 代理、兼容端点和自定义网关可能记录请求内容 * 测试失败时先检查端点、认证方式、模型名、代理和模型是否支持当前 API 风格 * Agent 反复失败时减少上下文、点名目标表、降低任务范围，并查看具体工具错误，而不是只提高轮次上限 ## 相关功能 ### [生产环境安全](/cn/docs/production-safety) 查看 AI、MCP、只读连接和生产保护的统一边界。 ### [MCP 集成](/cn/docs/mcp) 让外部 AI 编程助手通过 DBX 访问数据库。 ### [SQL 编辑器](/cn/docs/query-editor) 了解 AI 所使用的当前 SQL、结果和元数据上下文。 --- # 更新日志 > 按版本查看 DBX 的新增功能、体验改进和问题修复，内容同步自 GitHub Releases。 Source: https://dbxio.com/cn/docs/changelog Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/changelog. 更新日志会直接读取 R2 上的最新 Release 数据，因此发布后无需重新构建文档站也能刷新。 [打开实时更新日志](/cn/changelog) --- # DBX CLI > 使用原生 DBX CLI 在终端、脚本、CI 和 Codex 中读取连接、Schema、查询结果和 AI 上下文。 Source: https://dbxio.com/cn/docs/cli Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/cli. DBX CLI 是独立命令行包，适合终端、脚本和 AI 编程助手工作流。它与 MCP Server 共享 DBX 连接存储和 SQL 安全规则。 ## 安装 ### npm ```bash npm install -g @dbx-app/cli ``` ### Homebrew ```bash brew tap t8y2/tap brew install dbx-cli ``` 通过 npm 安装时需要 Node.js 18.18.0 或更高版本。CLI 本身不依赖 `better-sqlite3`，也不受 Node.js native module ABI 影响。Homebrew 用户不需要单独管理 Node.js。 ### 独立原生版本 `packages-v*` GitHub Release 会提供适用于 macOS、Linux 和 Windows 的 CLI 原生压缩包。下载对应平台的压缩包后，使用 `CLI-SHA256SUMS` 校验，解压即可直接运行 `dbx`，不需要 Node.js。 ```bash tar -xzf dbx-cli-linux-x64-gnu.tar.gz chmod +x dbx ./dbx --version ``` 如果使用自定义或便携版 DBX 数据目录，可以设置 `DBX_DATA_DIR`。 查看版本： ```bash dbx --version ``` ## 官方 Agent Skill CLI 二进制内置了供 Codex、Claude Code 等可执行 Shell 的 AI Agent 使用的官方 DBX Skill。安装或升级 CLI 后启用一次： ```bash dbx agent setup dbx agent status ``` 默认安装到 `~/.agents/skills/dbx`。`setup` 全程离线运行，可重复执行并升级到 CLI 内置的新版本；如果目标位置存在非 DBX 管理或经过本地修改的 Skill，则不会覆盖，除非显式使用 `--force`。Agent 使用其它 Skill 根目录时可传入 `--skills-dir <路径>`。 Skill 负责告诉 AI 何时以及如何安全调用 CLI，并不会绕过 CLI、连接或数据库本身的权限限制。普通用户仍然可以直接运行所有 `dbx` 命令。 ## 常用命令 ```bash dbx doctor dbx capabilities dbx agent setup dbx agent status --json dbx connections list --json dbx connections list --format csv dbx schema list local --json dbx schema describe local users --json dbx query local "select count(*) as total from users" --json dbx query local "select id, name from users" --format csv dbx query local "select * from users" --limit 50 --timeout 10s --json dbx query local --file ./query.sql --json dbx context local --tables users,orders dbx open local users ``` ## 诊断 使用 `dbx doctor` 查看本地 DBX 路径、连接存储健康状态，以及桌面端 bridge 是否可用： ```bash dbx doctor dbx doctor --json ``` 如果 npm 没有安装当前平台包，请不要使用 `--no-optional`，重新安装： ```bash npm uninstall -g @dbx-app/cli npm install -g @dbx-app/cli ``` 使用 `dbx capabilities` 查看哪些数据库类型可以直接查询，哪些当前需要 DBX 桌面端： ```bash dbx capabilities dbx capabilities --json ``` 当前原生直连清单由 CLI 二进制维护，包括 PostgreSQL、Redshift、MySQL、Doris、StarRocks、Manticore Search、SQLite、rqlite、KWDB 和 QuestDB。`dbx capabilities` 是当前版本的权威输出；其他类型需要运行中的 DBX Desktop bridge 或对应 Agent/外部驱动基础设施。 ## 执行模式 ### 本地存储 默认情况下 CLI 读取与 Desktop/MCP 相同的 `dbx.db` 连接存储。设置 `DBX_DATA_DIR` 时应指向包含 `dbx.db` 的目录。 * 原生直连类型可以在 Desktop 关闭时查询 * bridge 类型需要 Desktop 正在运行，并能从数据目录中的 bridge 端口文件发现本地服务 * Agent/JDBC、DuckDB 和其它外部驱动路径仍需要在 DBX 中安装匹配组件 * `dbx open` 始终是 Desktop UI 操作，Desktop 未运行时返回 `DBX_NOT_RUNNING` ### DBX Web / Docker 设置 `DBX_WEB_URL` 后，CLI 改为使用部署的 DBX Web 后端，而不是读取本机连接存储： ```bash DBX_WEB_URL=https://dbx.example.com \ DBX_WEB_PASSWORD='your-login-password' \ dbx connections list --json ``` `DBX_WEB_PASSWORD` 是 Web 登录密码。Web 模式中的连接、权限、驱动和文件路径都属于服务器环境；`dbx open` 仍需要本机 Desktop bridge，不应作为远程 Web 自动化入口。 ## 默认连接 设置 `DBX_CONNECTION` 后，`query` 和 `context` 命令可以省略连接名： ```bash DBX_CONNECTION=local dbx query "select 1" --json DBX_CONNECTION=local dbx context --tables users,orders ``` ## 输出格式 使用 `--json` 或 `--format json` 可以获得稳定的机器可读输出。`--format csv` 适合把查询、连接、Schema 数据传给其它命令行工具。 ```bash dbx query local "select id, name from users" --format csv ``` 错误会写入 stderr，并返回非零退出码。 ## 查询控制 `dbx query` 对 SQL 连接执行一条 SQL，对 MongoDB 连接接受受支持的 Mongo shell 命令。Redis 不通过这个命令执行，需使用 MCP Redis 工具或 DBX 专用工作区。默认只读。 ```bash dbx query local "select * from users" --limit 50 --timeout 10s --json ``` 时间支持 `ms`、`s`、`m`，例如 `500ms`、`10s`、`1m`。 非危险写操作需要显式使用 `--allow-writes`： ```bash dbx query local "update users set name = 'Ada' where id = 1" --allow-writes ``` `DROP`、`TRUNCATE`、`ALTER` 等危险 SQL 需要同时显式使用 `--allow-writes` 和 `--allow-dangerous-sql`。显式事务语句仍会被 CLI 阻止；需要多步固定 Session 时使用 [MCP 有状态会话](/cn/docs/mcp#有状态查询会话) 或 DBX 编辑器。 生产数据库上的写入和 DDL 即使传入两个允许参数也会被阻止。CLI 使用连接/数据库生产识别、SQL 风险分类、连接只读保护和数据库权限形成多层边界；允许参数不是绕过生产保护的开关。 ## 以短横线开头的 SQL 如果 SQL 以短横线开头，在 SQL 前加 `--`： ```bash dbx query local --json -- "-- comment select 1" ``` ## 错误码 CLI JSON 错误使用稳定错误码： | 错误码 | 含义 | | ------------------------ | -------------------- | | `UNKNOWN_OPTION` | 使用了不支持的参数 | | `INVALID_OPTION` | 参数缺少值或值不合法 | | `INVALID_ARGUMENT` | 位置参数缺失或冲突 | | `CONNECTION_STORE_ERROR` | DBX 连接存储存在，但无法读取 | | `CONNECTION_NOT_FOUND` | 找不到指定的 DBX 连接 | | `SQL_BLOCKED` | SQL 被安全规则拦截 | | `DBX_NOT_RUNNING` | DBX 桌面端 bridge 不可用 | | `HOME_NOT_FOUND` | 无法确定默认用户 Skill 目录 | | `SKILL_MODIFIED` | Skill 未被 DBX 管理或已被修改 | | `SKILL_PATH_UNSAFE` | 受管理的 Skill 路径是符号链接 | | `SKILL_READ_FAILED` | 无法读取已安装的 Skill 文件 | | `SKILL_WRITE_FAILED` | 无法安装 CLI 内置的 Skill | | `ERROR` | 未预期的运行时错误 | ## 桌面端 Deep Link DBX 桌面端支持通过 Deep Link 从浏览器、堡垒机或脚本唤起客户端。 仅启动或聚焦 DBX，不打开其他窗口： ```bash open 'dbx://open' ``` 网页按钮可以直接使用： ```html 使用 DBX 打开 ``` 使用不带 `id` 的 `dbx://connection/new` 可以打开新建连接窗口并预填连接信息。 DSN 模式： ```bash open 'dbx://connection/new?url=postgres%3A%2F%2Fapp%3Asecret%40db.internal%3A5432%2Forders' ``` 字段模式： ```bash open 'dbx://connection/new?type=mysql&host=127.0.0.1&port=3306&user=root&password=secret&database=test' ``` 支持的字段： | 字段 | 含义 | | ------------ | ------------------------------------------------------------- | | `type` | 数据库类型；服务类连接包括 `etcd`、`consul`、`nacos-v2`、`nacos-v3`、`r-nacos` | | `url` | 数据库 DSN，建议 URL encode | | `name` | DBX 中显示的连接名；未传时优先使用 `database`，其次使用 `host` | | `host` | 主机地址 | | `port` | 端口 | | `user` | 用户名 | | `password` | 密码 | | `database` | 数据库名；Redis 可传 DB index，例如 `0` | | `url_params` | 额外连接参数，例如 `sslmode=require` | | `ssl` | 是否启用 SSL，`true` 表示启用 | | `one_time` | `true` 时自动连接，断开后自动删除连接信息 | 一次性连接示例： ```bash open 'dbx://connection/new?type=redis&host=127.0.0.1&port=6379&user=default&password=secret&database=0&one_time=true' ``` Nacos 与服务注册中心示例： ```bash open 'dbx://connection/new?type=consul&host=127.0.0.1&port=8500&password=acl-token' open 'dbx://connection/new?type=nacos-v3&host=127.0.0.1&port=8848&user=nacos&password=secret' open 'dbx://connection/new?type=r-nacos&url=http%3A%2F%2F127.0.0.1%3A8848%2Fnacos&user=admin&password=secret' ``` `nacos` 是 `nacos-v2` 的别名，`rnacos` 是 `r-nacos` 的别名。URL 模式会保留服务端点路径，顶层 `host`、`port`、`user`、`password`、`ssl` 会覆盖 `url` 中的对应值。Consul 的 `password` 表示 ACL token；Nacos 传入 `password` 时必须同时传入 `user`。省略 `v` 或使用 `v=1` 表示当前深链协议，其他版本会被拒绝。 ### 按 ID 更新已保存连接 在同一个 `dbx://connection/new` 路由上增加 `id`，即可打开指定的已保存连接进行编辑。例如，堡垒机可以为已有连接传入新的登录凭据： ```bash open 'dbx://connection/new?id=saved-connection-id&user=fresh-sso-token&password=fresh-sso-token' ``` 将 `saved-connection-id` 替换为 MCP 工具 `dbx_list_connections` 返回的连接 ID。更新按 ID 精确匹配，不按显示名称查找。CLI 命令 `dbx connections list --json` 目前只列出名称和端点等信息，不返回连接 ID。 收到更新链接后，DBX 只打开预填好的编辑窗口。检查修改内容并点击**保存**后，才会以原连接 ID 和原侧栏分组持久化修改。链接不会自动保存、测试或连接数据库；取消编辑不会修改已保存配置。ID 为空或不存在、目标是一次性连接、已有其他连接窗口打开时，更新会被拒绝，不会退回新建连接。 更新支持使用内置 MySQL、PostgreSQL、SQL Server 配置的已保存字段式连接；存在非空 `connection_string` 的连接不支持此更新流程。只有链接中明确提供的字段才会修改： | 参数 | 更新行为 | | ----------------------- | --------------------------------- | | `name`、`host` | 替换当前值，不接受空值 | | `port` | 替换为 1 到 65535 之间的整数端口 | | `user`、`password` | 预填凭据并保留首尾空白字符；传空值表示清空 | | `database`、`url_params` | 替换当前值；传空值表示清空 | | `ssl` | 更新 SSL 开关；最终 TLS 行为遵循驱动和 URL 参数规则 | 省略的字段保留原值，包括端口和 SSL 设置。需要清空字段时，保留参数名并传空值，例如 `database=&url_params=`。参数值应进行 URL 编码，例如密码中的字面量 `+` 应编码为 `%2B`。 保存时仍遵循现有的凭据清理规则和该连接的“保存密码”设置。 除 `id` 和上述字段外，只接受可选的协议版本 `v=1`。更新链接不接受 `type`、`url`、`one_time`（包括 `one_time=false`）、未知参数或重复参数名，也不能更改驱动配置或要求自动操作。 保存新的 SSO 凭据不会延长其有效期。MCP 可以读取保存后的连接配置，但仍会独立建立数据库会话，需要凭据仍然有效；更新不会把桌面端正在使用的会话转交给 MCP。 测试系统级 `dbx://` 唤起前，请先安装并启动一次 DBX 桌面端，让系统注册 URL 协议。macOS 可使用 `open 'dbx://open'` 或 `open 'dbx://connection/new?...'` 测试。 深链可能在浏览器或终端历史中暴露数据库密码或 Consul ACL token。不要将携带凭据的链接写入共享日志、Shell 历史、工单或聊天消息。 ## Codex Codex 可以直接通过 shell 调用 CLI： ```bash dbx schema describe local users --json dbx context local --tables users,orders | codex exec "Write a retention query" ``` --- # DBX 配置云同步 > 使用 WebDAV、GitHub Gist、Gitee 或 GitLab Snippets 同步 DBX 连接、设置和保存的 SQL。 Source: https://dbxio.com/cn/docs/cloud-sync Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/cloud-sync. DBX 可以把连接配置、界面设置和保存的 SQL 组成一个快照。桌面端可通过 WebDAV 或私有代码片段同步，Web/Docker 可通过 WebDAV 同步，并在另一个 DBX 实例恢复。 云同步备份的是 DBX 配置，不会读取或备份连接中的业务数据库。表结构和数据请使用 [数据库导出](/cn/docs/database-export) ；Desktop 定时 MySQL/PostgreSQL 备份请使用 [数据库备份](/cn/docs/database-backup) 。 在 **设置 → 同步** 中选择同步方式： * **WebDAV**：适合已有 NAS、Nextcloud、坚果云或其他 WebDAV 服务的用户，支持定时自动上传。 * **GitHub / Gitee / GitLab 代码片段**：通过私有代码片段保存快照，GitLab 支持企业自托管实例。目前仅桌面端显示，且需要手动上传和下载，不自动合并。 ## 同步哪些内容 | 项目 | 默认行为 | | ---------------------------------------------- | --------------- | | 数据库连接及普通连接参数 | 同步 | | 侧边栏布局、固定节点 | 同步 | | 保存的 SQL 库 | 同步 | | 桌面和编辑器设置 | 同步 | | 数据库密码、SSH 密码、代理密码、HTTP 隧道 Token、连接串、AI API Key | 默认不同步；可以选择加密后同步 | | JDBC 驱动、插件和本地文件 | 不同步 | 下载会用远端快照替换本地连接元信息和保存的 SQL。恢复前请确认代码片段 ID 或 WebDAV 路径正确。 ## GitHub Gist ### 创建访问令牌 推荐使用 GitHub **Fine-grained personal access token**： [打开 GitHub Fine-grained token 创建页面](https://github.com/settings/personal-access-tokens/new) ### 打开令牌设置 登录 GitHub，进入 **Settings → Developer settings → Personal access tokens → Fine-grained tokens**。 ### 创建令牌 点击 **Generate new token**，设置名称和有效期。 ### 设置权限 在 **Account permissions** 中找到 **Gists**，选择 **Read and write**。不需要授予仓库权限。 ### 保存令牌 创建后立即复制令牌。GitHub 只会完整显示一次。 也可以使用 Classic token，但只应勾选 `gist` scope，不要授予无关权限。 ### 首次上传 ### 选择平台 打开 **设置 → 同步 → 代码片段**，平台选择 **GitHub Gist**。 ### 填写令牌 将访问令牌粘贴到 **访问令牌**。建议勾选 **加密保存在本机**。 ### 创建 Gist 将 **代码片段 ID** 留空，点击 **上传**。DBX 会创建私有 Gist，并自动保存返回的 ID。 DBX 会在 Gist 中保存一个经过**代码片段加密密码**加密的 `dbx-sync.json` 文件。该密码保护完整快照，片段链接本身不会暴露连接信息、SQL 或设置；历史明文片段仍可下载一次以便迁移。 旧版本创建的明文片段不能安全地原地迁移：更新同一个 Gist 不会删除历史修订。请使用 **迁移旧版代码片段** 操作。DBX 会先将已有的远端快照加密写入新片段并保存新 ID，然后重新读取旧片段后才删除它；如果另一台设备已更新旧内容，则停止自动删除并提示手动清理。若旧快照包含已加密的敏感信息，请输入其原敏感信息同步密码以完成删除前验证。请轮换旧片段中可能已经暴露的凭据。 ### 在另一台设备恢复 1. 打开该私有 Gist，从地址栏复制 ID。地址通常类似 `https://gist.github.com/<实际用户名>/`，最后一段就是 ID。也可以直接访问 `https://gist.github.com/`，GitHub 会跳转到包含实际用户名的地址。 2. 在新设备填写相同的 GitHub 令牌和 Gist ID。 3. 点击 **测试**，确认令牌和 ID 可访问。 4. 点击 **下载** 并确认恢复。 ## Gitee 代码片段 ### 创建私人令牌 [打开 Gitee 私人令牌页面](https://gitee.com/profile/personal_access_tokens) ### 打开私人令牌页面 登录 Gitee，进入 **设置 → 私人令牌**。 ### 生成新令牌 点击 **生成新令牌**，填写描述。 ### 设置权限 只勾选代码片段（`gists`）相关权限。如果界面只提供合并权限，选择能够读写代码片段的最小权限。 ### 保存令牌 生成后立即复制令牌，并存放在密码管理器中。 ### 上传与恢复 1. 在 **设置 → 同步 → 代码片段** 中选择 **Gitee 代码片段**。 2. 输入私人令牌。首次上传时将代码片段 ID 留空，DBX 会创建私有代码片段并保存 ID。 3. 在其他设备恢复时，填写同一个代码片段 ID，然后点击 **下载**。 Gitee 代码片段中同样使用 `dbx-sync.json` 文件。 ## GitLab Snippets（包括私有化实例） 1. 在 GitLab **User Settings → Access Tokens** 创建个人访问令牌，授予 `api` 权限；不要把令牌放在实例地址里。 2. 在桌面端 **设置 → 同步 → 代码片段** 选择 **GitLab Snippets**，输入公司的 GitLab 根地址（例如 `https://gitlab.example.com` 或内网 `http://gitlab.internal`，默认 `https://gitlab.com`）。不接受含账号密码、查询参数或片段的地址。修改地址后，失焦或按 Enter 才会切换实例。 3. 输入令牌和代码片段加密密码；首次上传时留空 ID，DBX 创建仅自己可见的个人 Snippet。后续上传更新同一 ID 对应的 `dbx-sync.json`；在另一台设备输入相同实例、令牌、ID 和加密密码后手动下载。 GitLab Snippets 不是 GitLab 仓库文件同步。不同实例的本地令牌、ID 和迁移待清理记录互相隔离；上传和下载不会自动合并。旧明文 DBX 快照须使用 **迁移旧版代码片段**，DBX 先创建加密的新 Snippet，再核对并删除旧 Snippet。如果发现旧内容已变化或清理失败，旧 Snippet 仍须手动处理。 HTTP 会明文传输 GitLab 访问令牌，即使快照内容已加密。只在可信内网使用 HTTP，优先为私有化 GitLab 配置 HTTPS。 ## 同步密码与敏感信息 GitHub Gist、Gitee 和 GitLab 代码片段始终使用**代码片段加密密码**加密整个快照。该密码不会上传或保存，也无法找回；它与可选敏感信息的同步密码相互独立。 默认快照不会包含数据库密码等密钥。如果需要在新设备直接恢复密码： 1. 开启 **上传时包含加密敏感信息**。 2. 输入单独的 **敏感信息同步密码**。 3. 上传快照。 4. 在另一台设备开启 **下载时恢复加密敏感信息** 并输入同一密码；保持关闭即可保留本地密码。 同步密码使用 **Argon2id** 派生密钥，并使用 **AES-256-GCM** 加密。访问令牌只会使用设备密钥加密保存在本机，永远不会写入 `dbx-sync.json`。 两种密码都无法找回。加密代码片段没有代码片段加密密码就无法恢复；WebDAV 中不含加密敏感信息的快照仍可不使用同步密码恢复。 ## WebDAV 填写 WebDAV 服务地址、用户名、应用密码和远端快照路径。默认路径为 `DBX/sync/snapshot.json`。 将远端快照路径改为 `DBX/sync/snapshot.zip` 可启用 ZIP 快照：DBX 会将同一份 JSON 快照压缩为仅包含 `snapshot.json` 的 ZIP 文件，并以 `application/zip` 上传。其他路径仍上传 JSON。下载按文件内容识别 JSON 或 ZIP，因此也能读取旧版本写入 `.zip` 路径的 JSON 快照。ZIP 文件及解压后的 JSON 均不得超过 100 MiB，且不会解压到本地文件系统。压缩不等于加密，敏感信息仍遵循原有同步加密设置。 部分 WebDAV 服务（如中国科技云数据胶囊）会同时限制客户端应用和上传文件类型。遇到客户端限制时，在 User-Agent 输入框填写服务允许的客户端标识（例如 `Zotero/10.0.0`）；默认留空，表示不发送 User-Agent。Zotero 专用接口还可能仅允许 `.zip` / `.prop` 上传，仅修改 User-Agent 无法让 JSON 上传通过，此时可尝试 ZIP 快照。上传返回 403、405 或 415 时，也应核对账号写权限和服务端策略；ZIP 格式不会绕过权限检查。 切换格式会使用新的远端路径，不会删除原 JSON 快照。所有同步设备需配置同一路径；启用 ZIP 前请先升级所有设备到支持 ZIP 快照的 DBX 版本，旧版本仍需使用 JSON 路径。请使用 DBX 独立目录，不要与 Zotero 自身的同步目录混用。 Web/Docker 模式下，WebDAV 请求由 DBX 服务端发起，因此不受浏览器 CORS 限制；WebDAV 应用密码会加密保存在当前 DBX 实例中，不会写入同步快照。 WebDAV 支持定时自动上传。自动上传只在对应 DBX 客户端保持打开时执行；Web/Docker 使用时需保持至少一个 DBX 页面打开。下载始终需要手动确认，避免远端快照意外覆盖当前实例的数据。 ## 常见问题 ### HTTP 401 或 403 令牌无效、已过期，或没有代码片段读写权限。重新创建最小权限令牌后再测试。 ### HTTP 404 代码片段 ID 不正确，或者当前令牌无权访问该私有代码片段。 ### 首次上传后在哪里找 ID DBX 会自动保存 ID。也可以在 GitHub Gist 或 Gitee 代码片段页面的地址栏中查看。 ### 多台设备可以同时自动同步吗 代码片段同步目前只支持手动上传和下载，不会自动合并两台设备上的修改。上传前建议先下载最新快照，避免覆盖另一台设备刚上传的版本。 --- # 配置导出/导入 > 导出数据库连接配置（AES-256-GCM 加密），安全地在不同电脑之间迁移。 Source: https://dbxio.com/cn/docs/config-export Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/config-export. 导出你的数据库连接配置（含加密密码），用 AES-256-GCM 加密保护，安全地在不同电脑之间迁移。默认使用加密导出。 这里导出的是 DBX 连接配置，不包含业务数据库的表结构或数据，也不是数据库备份。数据库内容请使用 [数据库导出](/cn/docs/database-export) 或 [数据库备份](/cn/docs/database-backup) 。 ## 导出 ### 发起导出 点击侧边栏顶部的 **导出** 按钮。 ### 选择连接 勾选一个或多个连接。默认全选。最终只会导出已选连接、相关的侧边栏分组和排序，以及引用的隧道配置（Tunnel Profile）。 ### 选择导出保护 输入密码短语来加密连接密码。仅在可信环境下临时迁移时，也可以选择**不加密导出**并确认风险。明文文件可能包含数据库密码、SSH Tunnel 凭据和其他敏感信息。 ### 保存文件 选择保存位置。导出文件只包含已选连接、相关布局和引用的 Tunnel Profile。推荐使用加密导出。 ## 导入 ### 发起导入 点击侧边栏顶部的 **导入** 按钮。 ### 选择文件并解密 选择导出的文件。DBX 会自动识别加密和明文配置文件；加密文件会先要求输入密码短语，DBX 会先解密并预览，此时不会写入本地连接。 ### 选择连接 勾选文件中要导入的连接。默认全选。 ### 完成 只有已选连接会被导入，密码自动恢复。按 名称 + 主机 + 端口 自动去重。已选连接的侧边栏分组和排序仍可在导入后选择应用。 ## 安全性 * 密码使用 **AES-256-GCM** 加密，密钥通过 **PBKDF2** 派生 * 加密文件没有密码短语无法解密 * 明文导出未加密，可能暴露数据库密码、SSH Tunnel 凭据和其他敏感信息；仅建议在可信环境下用于临时迁移 * 导出文件是标准 JSON 格式，可以通过 U 盘、网盘等方式传输 * DBX 会把普通连接字段与数据库密码、SSH 密码、SSH 密钥密码、完整连接字符串等密钥信息分开存储。加密导出会保护组合后的数据；明文导出会把这些敏感信息写成可直接读取的 JSON。 * 请把导出口令当作密钥管理。任何人同时拿到导出文件和口令，都可以恢复其中的连接。 ## 向后兼容 导入会自动识别加密或明文配置文件，也支持旧版本导出的明文 JSON 文件（不含密码）和原始的连接配置数组。 ## 包含哪些内容 | 项目 | 是否包含 | | --------------------------- | -------------------------------------- | | 连接名称、类型、主机、端口、数据库、颜色 | 包含 | | URL 参数、SSL、SSH、代理、可见数据库设置 | 包含 | | 数据库密码、SSH 密码、SSH 密钥密码、连接字符串 | 包含；加密导出中加密，明文导出中可直接读取 | | 厂商 JDBC 驱动 JAR 文件 | 不包含；目标机器需要重新安装或导入 | | 已选连接的侧边栏分组和排序 | 包含；导入连接后可选择是否应用 | | 已保存 SQL 和界面/编辑器设置 | 不包含；需要迁移时使用 [云同步](/cn/docs/cloud-sync) | 如果要迁移 JDBC 连接，先在这里导出连接配置，再在目标机器通过 [JDBC 插件](/cn/docs/plugins) 安装插件并导入驱动 JAR。 --- # 连接导入 > 从 Navicat、DBeaver 和 DataGrip 导入连接、分组和可识别的数据库类型。 Source: https://dbxio.com/cn/docs/connection-import Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/connection-import. DBX 可以从其他数据库工具导入连接，在切换工具时无需手动重新创建大量连接。 ## 支持的格式 | 来源 | 格式 | 导入内容 | | -------- | -------------------------- | ------------------------- | | Navicat | `.ncx` 导出文件 | 主机、端口、用户名、数据库类型、连接名称 | | DBeaver | 连接配置文件 | 主机、端口、用户名、数据库类型、连接名称 | | DataGrip | `dataSources.xml` 等项目/全局配置 | JDBC URL、驱动、连接名称、分组和可读取凭据 | 导入的连接保留原始连接名称和类型。其他工具以加密格式存储的密码无法解密——导入后需要重新输入密码。 ## 导入 Navicat 连接 ### 从 Navicat 导出 在 Navicat 中，选择要迁移的连接。使用**文件 → 导出连接**并保存 `.ncx` 文件。 ### 打开导入对话框 在 DBX 中，前往**设置 → 导入连接**，或右键点击侧边栏分组标题选择**导入连接**。 ### 选择 NCX 文件 选择从 Navicat 导出的 `.ncx` 文件。 ### 检查并完成 DBX 解析文件并列出所有找到的连接。检查列表，在需要处重新输入密码并保存。 ## 导入 DBeaver 连接 ### 找到 DBeaver 配置 DBeaver 将连接存储在其工作区目录中。具体路径取决于操作系统和 DBeaver 版本。常见位置包括 `~/.local/share/DBeaverData/workspace6/General/.dbeaver/`。 ### 打开导入对话框 在 DBX 中，前往**设置 → 导入连接**。 ### 选择 DBeaver 文件 选择 DBeaver 连接配置文件（`.dbeaver-data-sources.xml` 或类似文件）。 ### 检查并完成 DBX 从配置中提取连接信息。重新输入无法解密的密码。 ## 导入 DataGrip 连接 ### 选择配置 在 DBX 中选择**导入 DataGrip**，再选择 DataGrip 项目或全局配置中的 `dataSources.xml`；同目录的 local 配置会用于补充字段。 ### 检查类型识别 DBX 会结合 driver reference、数据库产品名、JDBC subprotocol 和驱动类识别数据库。KingbaseES 等数据库会映射到对应 DBX profile，未知驱动保留为通用 JDBC。 ### 检查分组 DataGrip 的分组路径会导入为 DBX 连接分组，方便保留项目组织方式。 ### 补充凭据 macOS 上 DBX 会在允许时读取 DataGrip 钥匙串密码；其它加密或不可访问的凭据仍需手动填写。 ## 导入后 导入的连接与手动创建的连接一同出现在侧边栏中。你应该： * **测试每个连接**以验证导入的设置是否正常工作 * **设置密码**，用于原始密码无法导入的连接 * **分配连接颜色**以区分生产、测试和开发环境 * **配置 SSH 隧道**，用于需要隧道访问的连接 * **设置可见数据库过滤**，如果服务器包含大量数据库 ## 无法导入的内容 | 设置 | 原因 | | -------- | ------------------------ | | 加密密码 | 每个工具使用各自的加密方式，密码需要重新输入 | | SSH 隧道密钥 | 密钥文件路径可能因机器而异，需要重新选择密钥文件 | | 自定义驱动配置 | 驱动路径和版本是工具特定的 | | 代理设置 | 在连接的代理标签页中重新配置 | 导入只创建连接草稿，不证明连接一定可用。保存前检查数据库 profile、JDBC URL、SSL、SSH、代理和数据库名，保存后逐个执行连接测试。 --- # 从源码编译与参与贡献 > 从零搭建 DBX 开发环境，运行桌面版，完成第一次修改、测试并提交 Pull Request。 Source: https://dbxio.com/cn/docs/contributing Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/contributing. 这是一份面向第一次参与 DBX 开发者的完整教程。跟着本页操作，你将完成： 1. 准备 Node.js、pnpm、Rust 和系统编译依赖 2. Fork、克隆并运行 DBX 桌面版 3. 找到要修改的代码并完成一次小改动 4. 运行与改动范围匹配的检查和测试 5. 推送分支并提交 Pull Request 第一次贡献推荐从文档、翻译、小型 UI 问题或你熟悉的数据库问题开始。一个 PR 只解决一个明确问题，会更容易验证和合并。 本页的 PR 目标仓库是 `t8y2/dbx`，适用于 DBX 主应用、插件框架、SDK、CLI、文档和 Agent。普通插件源码保留在插件自己的仓库；插件上架 PR 应提交到 `t8y2/dbx-store`。完整流程见[开发和提交 DBX 插件](/cn/docs/plugin-development)。 ## 1. 选择并认领任务 打开 [DBX Issues](https://github.com/t8y2/dbx/issues)，选择一个尚未分配、评论中也没有人正在处理的 Issue。第一次贡献优先考虑： * 复现步骤和预期行为已经写清楚的问题 * 改动范围较小的文档、翻译或 UI 问题 * 你正在使用并且可以连接真实环境验证的数据库问题 不要只根据标签判断是否适合处理；先阅读完整正文、评论、截图和已有讨论，确认需求仍然有效并且没有重复实现。 确认 Issue 没有人处理后，在评论中单独发送： ```text /claim ``` 认领成功后，机器人会把 Issue 分配给你。如果你准备采用的方案可能影响现有行为，先在 Issue 中简要说明思路，等维护者确认后再开始大规模修改。 如果后续不准备继续或暂时无法完成，可以单独评论 `/unclaim`，也兼容 `/unclaimed`。工作流只会移除你自己的 assignee，之后其他贡献者可以重新认领。 ## 2. 安装开发环境 DBX 桌面版基于 Tauri、Vue 和 Rust。仓库当前要求： | 工具 | 版本 | | ------- | --------------------------- | | Node.js | 22.13.0 或更高版本 | | pnpm | 10.34.7 | | Rust | 1.88 或更高版本 | | Git | 当前稳定版本 | | Make | macOS 和 Linux 需要；Windows 可选 | ### 安装 Node.js 和 pnpm 先从 [Node.js 官网](https://nodejs.org/)安装 Node.js 22 或更新的 LTS 版本，然后启用仓库指定的 pnpm： ```bash corepack enable corepack prepare pnpm@10.34.7 --activate node --version pnpm --version ``` 如果你的 Node.js 安装不包含 Corepack，也可以执行： ```bash npm install --global pnpm@10.34.7 ``` ### 安装 Rust 按照 [Rust 官方安装说明](https://www.rust-lang.org/tools/install)安装 `rustup`。安装后重新打开终端并检查： ```bash rustc --version cargo --version ``` ### 安装系统依赖 Tauri 的完整系统要求可以参考 [Tauri 官方前置依赖文档](https://v2.tauri.app/start/prerequisites/)。DBX 还需要 ODBC 开发库。 ### macOS 安装 Xcode Command Line Tools 和 unixODBC： ```bash xcode-select --install brew install unixodbc ``` 如果尚未安装 Homebrew，请先按照 [Homebrew 官网](https://brew.sh/)完成安装。 ### Ubuntu / Debian 安装编译工具、Tauri WebKit/GTK 依赖和 unixODBC： ```bash sudo apt update sudo apt install -y \ build-essential curl wget file pkg-config \ libwebkit2gtk-4.1-dev libgtk-3-dev libxdo-dev \ libayatana-appindicator3-dev librsvg2-dev patchelf \ libssl-dev unixodbc-dev ``` ### Windows 1. 安装 [Microsoft C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)。 2. 在安装器中选择 **Desktop development with C++**。 3. 确认已安装 Windows 10/11 SDK 和 WebView2。Windows 11 通常已自带 WebView2。 4. 安装 [Strawberry Perl](https://github.com/StrawberryPerl/Perl-Dist-Strawberry/releases)（编译内置 OpenSSL 所需）： ```powershell winget install StrawberryPerl.StrawberryPerl ``` DBX 默认启用 `sqlite-sqlcipher` 特性，需要从源码编译 SQLCipher 和 OpenSSL，而 Windows 上编译 OpenSSL 必须使用 Perl 执行 `Configure` 脚本。安装后请重新打开终端，使 `perl` 进入 `PATH`。 5. 使用 PowerShell 执行本页的 Windows 命令。 Windows 不必安装 Make，本页会同时给出对应的 pnpm 命令。 ## 3. Fork 和克隆仓库 先在 GitHub 打开 [t8y2/dbx](https://github.com/t8y2/dbx)，点击右上角 **Fork** 创建自己的仓库副本。 将下面的 `<你的 GitHub 用户名>` 替换为你的账号： ```bash git clone https://github.com/<你的 GitHub 用户名>/dbx.git cd dbx git remote add upstream https://github.com/t8y2/dbx.git git remote -v ``` 推荐每个 Issue 使用一个独立分支： ```bash git switch -c fix/issue-1234-short-description ``` 开始新任务前，先同步主仓库： ```bash git switch main git fetch upstream git rebase upstream/main git push origin main ``` ## 4. 第一次运行 DBX ### macOS 和 Linux 在仓库根目录执行： ```bash make ``` `make` 会使用锁文件安装依赖，然后启动 Tauri 桌面开发环境。第一次编译 Rust 依赖需要较长时间，后续启动会明显更快。 如需轻量桌面开发构建，可以关闭默认 Rust feature，仅启用 DuckDB sidecar、DynamoDB 和 bundled SQLite： ```bash make dev-fast ``` 开发版可以与已安装的 DBX 同时运行。两者使用同一份本地 DBX 数据，因此连接和历史记录会同时可用；请避免在两个窗口中同时修改同一个连接、收藏 SQL 或全局设置。 测试 MCP bridge 时，后启动的实例会写入共享的 `mcp-bridge-port` 发现文件并接收 MCP 请求。Redis PubSub 优先使用端口 `4224`（设置 `DBX_PORT` 时优先使用该端口）；端口被占用时会自动回退到可用的本地端口，前端会使用实际监听端口。 ### Windows 在 PowerShell 中执行： ```powershell pnpm install --frozen-lockfile pnpm dev:tauri ``` 使用相同的轻量构建： ```powershell pnpm tauri dev -- --no-default-features --features duckdb-sidecar,dynamodb,sqlite-bundled ``` ### 判断是否启动成功 成功时会出现 DBX 桌面窗口，并且终端中没有编译错误。建议完成三个快速检查： 1. 打开设置页面 2. 创建或打开一个本地测试连接 3. 关闭窗口后再次启动，确认开发环境可重复运行 如果端口 `1420` 已被占用，先关闭旧的 DBX/Vite 开发进程再重新启动。 ## 本地数据库测试环境 涉及数据库驱动、连接流程、元数据查询或数据库专用 UI 的改动，应尽可能通过真实实例验证。仓库为此提供了固定版本的本地 Docker Compose 配方： ```bash make db-list make db DB=mysql@8.4 make db-verify DB=mysql@8.4 make db-down DB=mysql@8.4 ``` 服务端口默认监听 `127.0.0.1`；在共享网络中暴露主机前，请设置 `DB_BIND_ADDRESS=0.0.0.0`、使用强 `DB_PASSWORD` 并配置防火墙。所有支持的配方、覆盖变量和重置安全要求请参阅[数据库测试实验室](/cn/docs/database-lab)。 ## 5. 认识项目结构 | 路径 | 适合修改的内容 | | ---------------------- | ------------------------ | | `apps/desktop/src/` | Vue 页面、组件、状态管理、交互和多语言文本 | | `src-tauri/` | Tauri 桌面命令、系统集成和应用打包 | | `crates/dbx-core/` | 数据库连接、查询、元数据和共享 Rust 逻辑 | | `crates/dbx-web/` | Docker/Web 后端 | | `packages/app-tests/` | 前端共享逻辑测试 | | `packages/cli/` | DBX CLI | | `packages/mcp-server/` | MCP Server | | `docs/content/docs/` | 官网中英文文档 | | `agents/drivers/` | Java/JDBC 和部分原生数据库 Agent | 不确定代码位置时，可以先用功能名称、界面文字或错误信息搜索： ```bash rg "要查找的文字" apps/desktop/src crates src-tauri packages ``` ## 6. 完成第一次修改 ### 路线 A：修改官网文档 文档是最容易完成的第一次贡献。英文和中文页面使用相同文件名： ```text docs/content/docs/example.mdx docs/content/docs/example.cn.mdx ``` 当前文档站语言以 `docs/lib/i18n.ts`、`docs/scripts/languages.mjs` 为准（现为 `en` / `cn`）。 启动文档站： ```bash make docs ``` Windows 使用： ```powershell cd docs pnpm install --frozen-lockfile --ignore-workspace pnpm dev ``` 浏览器打开终端显示的本地地址。新增页面时，还要同时更新： ```text docs/content/docs/meta.json docs/content/docs/meta.cn.json ``` 提交前先运行快速内容检查，再执行完整文档构建： ```bash pnpm --dir docs content:check make docs-build ``` `content:check` 会检查中英文页面配对、导航覆盖与顺序、frontmatter、重复标题和站内链接。`make docs-build` 会再次运行该检查并验证 Next.js 生产构建。 ### 路线 B：修改桌面前端 前端代码位于 `apps/desktop/src/`。开发时可以运行完整桌面版，也可以只运行 Web 前端： ```bash make dev-web ``` 完成修改后至少运行： ```bash pnpm typecheck pnpm lint pnpm test ``` 涉及 UI 时，请同时检查亮色/暗色主题、窄窗口、空数据、加载中和失败状态，并在 PR 中附截图或录屏。 ### 路线 C：修改 Rust 后端 Rust 共享逻辑主要位于 `crates/dbx-core/`，桌面命令位于 `src-tauri/`。不涉及 DuckDB 时先运行快速检查： ```bash make cargo-check-fast make cargo-test-fast ``` 数据库相关修改应使用真实数据库实例验证，不要只依赖 mock。PR 中写清数据库类型、版本、复现 SQL、修改前行为和修改后行为。 ### 路线 D：修改 Agent 驱动 Agent 是独立进程，通过 stdin/stdout JSON-RPC 与 DBX 通信。Java/JDBC Agent 通常使用 JDK 21；原生 Agent 使用 Go 或 Rust。开始前先阅读： * [`agents/README.zh-CN.md`](https://github.com/t8y2/dbx/blob/main/agents/README.zh-CN.md) * [`agents/docs/agent-authoring.zh-CN.md`](https://github.com/t8y2/dbx/blob/main/agents/docs/agent-authoring.zh-CN.md) #### 修改现有 Java/JDBC Agent 从仓库根目录进入 `agents/`，只构建和测试目标模块： ```bash cd agents java --version ./gradlew :<驱动模块名>:test :<驱动模块名>:shadowJar ``` Shadow JAR 输出在： ```text agents/drivers/<驱动模块名>/build/libs/ ``` 仅仅构建成功还不代表本地 DBX 使用了新代码。DBX 运行时读取用户目录下 `.dbx/agents/drivers//agent.jar`，因此必须备份并替换运行时 JAR： ### macOS / Linux ```bash cp ~/.dbx/agents/drivers//agent.jar \ ~/.dbx/agents/drivers//agent.jar.bak cp drivers/<驱动模块名>/build/libs/*-all.jar \ ~/.dbx/agents/drivers//agent.jar ``` ### Windows PowerShell ```powershell Copy-Item "$HOME\.dbx\agents\drivers\\agent.jar" ` "$HOME\.dbx\agents\drivers\\agent.jar.bak" $jar = Get-ChildItem "drivers\<驱动模块名>\build\libs\*-all.jar" | Select-Object -First 1 Copy-Item $jar.FullName "$HOME\.dbx\agents\drivers\\agent.jar" -Force ``` 替换后重启 DBX，或者断开并重新连接数据库，确保旧 Agent 进程退出并加载新 JAR。然后使用 Issue 对应的真实数据库版本重新执行复现步骤。 #### `agents/versions.json` 什么时候修改 修改已有驱动时，不要手动修改 `agents/versions.json`。Agent 发布工作流会以上一个 `agents-v*` 标签对比运行时代码，并使用该版本发布后的版本同步提交作为有效版本基线，自动为发生变化的模块增加 patch 版本；未变化模块会复用上一不可变 Release 中经过校验的产物。 * 修改 `agents/drivers//`：发布时自动 bump 该模块版本 * 修改 `agents/common/src/main/` 或 `agents/common/build.gradle`：发布时自动 bump 所有打包了 shared common runtime 的模块 * 新增驱动模块：必须在 `agents/versions.json` 增加初始版本，例如 `"rabbitmq": "0.1.0"` * 新增 Java/JDBC 驱动时还必须同步 `agents/settings.gradle`、Agent README 支持列表、构建配置和测试 * 新增原生驱动时按照 Agent authoring/release checklist 登记对应构建和发布产物，不要假设 Gradle 会处理原生模块 * `versions.json` 中的键必须与实际发布模块一致；`common` 和 `test-support` 是基础设施模块，不登记版本 普通修复 PR 不需要为了“让更新生效”手动 bump 版本。版本 bump 和发布产物由 Agent release workflow 统一处理。 #### 原生 Agent `oracle`、`kingbase`、`xugu` 等原生 Agent 使用 `agent` 可执行文件，而不是 `agent.jar`。在对应模块目录运行 Go 测试和构建，并按模块 README 替换本地运行时可执行文件： ```bash cd agents/drivers/<原生模块> go test ./... go build -o agent . ``` 新增数据库 Agent 时，如果存在成熟且许可证兼容的 Go/Rust 驱动，优先使用原生 Agent；只有缺少可靠原生驱动时再使用 Java/JDBC。 #### Agent 提交前完整验证 在 `agents/` 目录执行： ```bash python3 -m unittest discover -s scripts -p '*_test.py' python3 scripts/validate_agents.py ./gradlew test shadowJar --continue python3 scripts/validate_agent_jars.py ``` `validate_agents.py` 会检查模块声明、`versions.json`、Gradle 配置、Main-Class、运行时分类和禁止残留文件；`validate_agent_jars.py` 会检查构建出的 JAR 是否包含正确入口类。 ## 7. 提交前检查 先查看实际改动，确认没有提交构建产物、数据库文件、密钥或无关格式化： ```bash git status git diff ``` 按修改范围执行检查： | 修改范围 | 最低检查 | | ----------------- | ----------------------------------------------- | | 官网文档 | `make docs-build` | | 前端/UI | `pnpm typecheck && pnpm lint && pnpm test` | | Rust | `make cargo-check-fast && make cargo-test-fast` | | CLI/MCP/Node Core | `pnpm test:packages` | | Agent | Agent 脚本校验、对应 Gradle/Go 测试、构建产物校验和本地运行时真实验证 | 如果修改跨越多个区域，需要合并执行对应检查。修复 Bug 时，还应再次执行原始复现步骤，证明问题已消失，并检查相邻正常场景没有回归。 ## 8. 提交并推送 提交信息使用简短的 conventional commit 格式： ```bash git add <本次修改的文件> git commit -m "fix(scope): describe the change" git push -u origin HEAD ``` 常用前缀： * `fix(scope):` 修复问题 * `feat(scope):` 增加功能 * `docs:` 修改文档 * `test(scope):` 补充测试 不要把多个无关问题放在同一个提交或 PR 中。 ## 9. 创建 Pull Request 在 GitHub 打开你的 Fork，点击 **Compare & pull request**，目标仓库选择 `t8y2/dbx`，目标分支选择 `main`。 PR 描述至少写清： 1. 关联的 Issue，例如 `Fixes #1234` 2. 修改了什么 3. 为什么这样修改 4. 运行了哪些测试 5. UI 改动的截图或录屏 6. 数据库改动的数据库名称、版本和验证步骤 提交 PR 后，如果 CI 失败，点击失败任务查看日志，在原分支继续提交修复即可，不需要重新创建 PR。 关联 PR 合并到默认分支后，如果 Issue 仍然处于打开状态，可以在 Issue 下单独评论 `/close`。工作流只会在评论者是当前 assignee，并且是已合并关联 PR 的作者时关闭 Issue。 ## 10. 根据 Review 更新代码 维护者提出修改意见后，在同一分支继续修改、提交并推送： ```bash git add <修改的文件> git commit -m "fix(scope): address review feedback" git push ``` 如果主分支在 Review 期间有较多变化，可以同步后重新推送： ```bash git fetch upstream git rebase upstream/main git push --force-with-lease ``` 使用 `--force-with-lease`，不要使用裸 `--force`。它会在远程分支出现你未拉取的新提交时拒绝覆盖。 ## 常见问题 ### 第一次 Rust 编译很慢 这是正常现象。轻量桌面开发可以使用 `make dev-fast`，它关闭默认 Rust feature，仅启用 DuckDB sidecar 和 DynamoDB。`make cargo-check-fast` 和 `make cargo-test-fast` 会跳过全部可选默认 feature，因此不会验证 DuckDB 专用路径。 ### pnpm 提示版本不正确 重新启用仓库指定版本： ```bash corepack prepare pnpm@10.34.7 --activate ``` ### 改了代码但界面没有变化 确认修改的是 `apps/desktop/src/`，终端中的 Vite/Tauri 进程仍在运行，并检查浏览器控制台或终端是否有编译错误。Rust 命令改动通常会触发重新编译。 ### 不知道需要跑哪些测试 先运行与改动目录对应的最低检查，再针对 Issue 的复现路径做真实验证。仍不确定时，在 PR 中列出已完成的验证和未覆盖风险，维护者会补充建议。 ## 获取帮助 * 在原 Issue 中描述卡点，并附完整错误信息和操作系统版本 * 加入 [Discord](https://discord.gg/W7NyVDRt6a) * 查看仓库根目录的 [CONTRIBUTING.zh-CN.md](https://github.com/t8y2/dbx/blob/main/CONTRIBUTING.zh-CN.md) 请不要只发送“编译失败”。至少附上执行的命令、错误日志中最早出现的错误、操作系统、Node.js、pnpm 和 Rust 版本。 --- # 数据表格 > 在 DBX 中浏览、筛选、编辑、校验、复制和导出查询结果或表数据。 Source: https://dbxio.com/cn/docs/data-grid Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/data-grid. 数据表格用于显示查询结果和表数据。它同时覆盖只读分析和小范围数据修改：浏览大结果集、筛选排序、检查复杂值、批量复制，以及在 DBX 能可靠识别目标行时生成并预览 `INSERT`、`UPDATE` 或 `DELETE`。 Redis、MongoDB、向量数据库、HBase 等系统使用各自的专项数据界面。这里主要说明关系型和兼容 SQL 数据源的结果表格。 ## 浏览与布局 视图选项提供独立的“隐藏 NULL 列”和“隐藏 NULL / 空字符串列”开关。后者隐藏当前已加载数据中全部为 `NULL` 或 `""` 的列，也支持两者混合；不会将 `0`、`false`、空格视为空值，也不会根据空结果隐藏列。两个开关默认关闭，关闭自动隐藏时仍保留手动隐藏的列。 DBX 使用虚拟滚动，只渲染当前可视区域。常用浏览操作包括： * 拖拽列边缘调整宽度，或双击按内容自适应 * 拖拽列头重排顺序，并按表或查询保存布局 * 冻结左侧或右侧列，横向滚动时保留关键字段 * 显示、隐藏和搜索列；搜索可以同时匹配列名和字段注释 * 调整表格字体、字号、行高和列宽密度 * 在标准视图与转置视图之间切换 * 查看连接名、结果来源、字段类型和字段注释 列宽、列顺序、冻结状态和多个显示选项可以跨会话保留。需要恢复时，在视图选项中重置当前表格布局。 ## 过滤、搜索与排序 | 方式 | 执行位置 | 适合场景 | | ---------- | ------- | -------------------- | | 表格搜索 | 当前已加载结果 | 快速定位文本、字段值或字段注释 | | 本地值过滤 | 当前已加载结果 | 临时勾选值、列表或范围，不重新查询数据库 | | `WHERE` | 数据库 | 大表、精确条件、可使用索引的筛选 | | `ORDER BY` | 数据库 | 跨页稳定排序和可复现结果 | | 当前页排序 | 客户端当前页 | 临时比较已加载数据，不改变数据库查询 | `WHERE` 和 `ORDER BY` 输入支持较长表达式、折叠/展开和基于字段元数据的条件补全。可以在设置中配置打开表时的默认排序。 面对大表时，优先使用数据库侧 `WHERE` 和 `ORDER BY` 。客户端搜索、值过滤和当前页排序不会减少数据库实际返回的数据量。 ## 什么时候可以编辑 只有当 DBX 能识别目标表，并有足够的主键或行标识生成可审查 SQL 时，结果才可编辑。 | 结果类型 | 通常行为 | | --------------- | ------------------- | | 从对象树直接打开的表数据 | 数据库和表支持时可编辑 | | 简单 `SELECT` | 能解析单一目标表且有可靠行标识时可编辑 | | Join、聚合、表达式、计算列 | 通常只读 | | 没有主键或可靠唯一标识 | 通常只读，避免生成不安全条件 | | 连接被标记为只读 | 所有可识别修改都被拒绝 | 只读单元格仍可以打开详情、复制和导出。需要了解无法编辑的原因时，查看数据表头和单元格详情中的只读说明。 ## 编辑、新增与删除 * **修改单元格**：双击进入编辑，或在详情面板中处理长文本 * **新增行**：创建一行或多行待插入记录 * **批量粘贴**：把制表符分隔的数据直接粘贴到新增行区域 * **克隆行**：复制选中记录作为新行，并按需要排除主键 * **删除行**：把选中记录标记为待删除 * **设置 NULL**：明确写入数据库 `NULL`，与空字符串区分 * **使用默认值**：让新增字段使用数据库默认值（数据库和字段支持时） * **生成值**：为选中单元格使用内置数据生成器填充测试值 * **按 `WHERE` 更新**：在 MySQL 表数据页中，将单个可写字段更新到所输入条件匹配的全部行，包括尚未加载的分页数据 日期时间、枚举、JSON 和其他类型会在可识别时使用专用编辑控件。批量编辑前应确认所选区域和目标字段类型一致。 ## 键盘操作 * **下键到末尾再加一行**：光标停在当前显示的最后一行时，再按一次 `↓` 会新增一行并进入首列编辑；新行**固定追加到结果末尾**（与工具栏「新增行」按钮不同——按钮跟随「插入位置」设置） * **`Esc` 取消新增行**：在从未填写过的新增行上按 `Esc`，该行会被撤掉（`Ctrl+Z` 可恢复）；填写过再清空的行会保留 * **`Esc` 回退单元格**：编辑器打开时 `Esc` 只取消本次输入；焦点回到表格后再按 `Esc`，当前单元格的待保存改动回退成原值（对齐 DBeaver 的 Reset cell changes）。多格选区不适用 ## SQL 预览与保存 行级关系型数据修改先保存在本地待提交状态。点击保存时，DBX 会展示生成的 `INSERT`、`UPDATE` 和 `DELETE` SQL。 MySQL 按条件批量更新有所不同，因为条件匹配的数据可能并未全部加载到表格中。在批量修改对话框中，可直接使用当前表格筛选，或通过选择字段、运算符和值来设置匹配条件，并用 `AND` 或 `OR` 组合多条规则；自定义 `WHERE` 表达式保留为高级选项。继续前可预览预计影响行数，但它只是执行前快照，实际更新时可能因并发数据变化而不同。DBX 会在危险确认框中展示完整的 `UPDATE ... WHERE ...`，确认后立即执行。数据库按执行时的数据计算匹配范围，DBX 无法为未加载行生成可靠的回滚 SQL。 保存前重点检查： * `UPDATE` 和 `DELETE` 的主键或条件是否只命中目标行 * 新增行是否遗漏必填字段 * `NULL`、空字符串、默认值和自动生成值是否符合预期 * 批量操作是否包含了未注意到的行 * 当前连接和数据库是否正确 生产环境保护启用后，保存仍会进入统一的生产写入确认。完整规则见 [生产环境与写入安全](/cn/docs/production-safety)。 SQL 预览是最后检查点，不是事务审批系统。重要生产变更仍应使用最小权限账号、备份和团队变更流程。 ## 单元格详情与复杂值预览 单元格详情用于表格内不适合直接显示或编辑的值： * 长文本、多行文本、SQL 和带语法高亮的 JSON * JSON 格式化、压缩和路径查看 * 二进制值的十六进制与 ASCII 查看 * 图片 URL、图片二进制或可识别图像数据预览 * 日期、时间和带时区值的专用编辑与格式化 * 几何/空间数据的文本、坐标和地图预览，包括可识别的 SRID * 被截断值、只读值和字段元数据说明 详情面板中的格式化和预览通常只影响显示；真正修改值时，仍会进入待保存状态并生成 SQL。 ## 转置视图 转置视图交换行列，适合： * 单行但字段很多的记录 * 并排查看字段类型、注释、默认值和可空状态 * 对比少量记录的大字段 转置视图支持选择、复制、详情、编辑和导航。排序与数据库侧过滤仍以原始结果方向为准。 ## 列格式化器 列格式化器只改变显示，不修改底层数据。常见选项包括： * 全局或列级日期/时间格式 * JSON 路径提取 * 值掩码 * 自定义显示模板 * 数字、布尔值和数据库类型对应的显示方式 如果需要恢复原始值，清除当前列格式化器即可。 ## 选择、复制与导航 表格支持单元格、矩形区域、整行和多行选择。选择后可以： * 查看数量、求和等选择摘要（适用于可计算值） * 复制为 TSV、CSV、JSON、Markdown、SQL `INSERT` 或 `UPDATE` * 复制单元格、选中区域、整行或带表头结果 * 选择列名引用方式，包括数据库标识符引号 * 使用字段注释作为复制列名（适合面向业务的表格） * 为多行生成单条批量 `INSERT`，或逐行 `INSERT` * 排除主键后复制为新记录模板 * 复制为 SQL DML（`INSERT` / `UPDATE`）时默认包含数据库限定名（版本迁移会为此前手动关闭该选项的用户重新开启为默认值，可在数据提取器设置中按需调整） 当字段存在可识别外键关系时，可以从单元格跳转到被引用记录。这个入口依赖元数据和目标连接权限。 ## 导出 | 格式 | 适合场景 | | --------- | ---------------------------- | | CSV / TSV | 电子表格、脚本和文本交换 | | JSON | API 调试和程序处理 | | Markdown | Issue、PR、文档和聊天 | | XLSX | Excel 交付；超出单工作表上限时会拆分工作表 | | SQL | 复用选中数据生成 `INSERT` 或 `UPDATE` | 导出查询结果时，DBX 会按当前结果和选择范围处理。导出前确认当前页面、筛选、排序和选择区域，避免把“当前可见数据”误认为完整表。 ## 自动刷新、分页与大结果集 * 打开表时的分页大小可以配置并持久化 * 自动刷新适合监控变化较快的小结果集 * 查询执行结果可以保留多个运行记录或固定需要对比的结果 * 大结果集只在可视区域渲染，但数据库查询和传输成本仍取决于实际返回行数 * 排序、过滤或自动刷新会重新获取数据，未保存编辑可能阻止或影响刷新 自动刷新不适合正在编辑的数据，也不能替代监控系统。大表请先缩小查询范围，再提高刷新频率。 ## 常见问题 | 现象 | 检查项 | | ----------- | --------------------------------- | | 结果只能查看不能编辑 | 是否为 Join/聚合；是否有主键；连接是否只读；驱动是否支持编辑 | | 过滤后行数没有减少 | 使用的是客户端搜索/过滤，而不是数据库侧 `WHERE` | | 排序只影响当前页 | 当前使用了本地排序；需要跨页稳定排序时改用 `ORDER BY` | | 粘贴后列错位 | 剪贴板列数、当前选中起始列、隐藏列和字段顺序 | | 图片或空间数据没有预览 | 值格式、MIME/二进制类型、几何编码或 SRID 无法识别 | | 导出数量和预期不同 | 当前页、选择区域、客户端过滤和数据库查询范围 | ### [编写查询](/cn/docs/query-editor) 使用补全、执行目标、多结果和查询历史生成数据表格。 ### [批量导入](/cn/docs/table-import) 从 CSV、TSV、JSON 或 Excel 导入大量数据。 ### [跨库传输](/cn/docs/data-transfer) 在不同连接或数据库引擎之间复制表数据。 ### [保护生产写入](/cn/docs/production-safety) 配置只读连接、生产确认和 MCP 权限。 --- # 数据安全升级与迁移 > 将已有 DBX 数据升级到加密 Secret Store 的完整指南。 Source: https://dbxio.com/cn/docs/data-security-migration Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/data-security-migration. 如果当前安装已经保存连接、密码、插件凭据、AI 提供商密钥、Tunnel 凭据或同步凭据，请先完成数据安全升级再使用 DBX。升级前请备份完整数据目录，并保留原有加密密钥。 本版本会把历史明文字段和 JSON 配置中的敏感值迁移到 DBX 加密 Secret Store。每个数据目录只需执行一次。向导会展示迁移范围，创建可回滚备份，执行迁移和验证，并在你明确删除前保留备份。 ## 本次升级会改变什么 迁移覆盖以下敏感数据： * 数据库连接密码、SSH 凭据、私钥口令和 HTTP Tunnel 密钥； * 标记为 secret 的插件连接字段； * AI 提供商凭据； * SSH 和其他 Tunnel 配置； * WebDAV 及其他同步凭据； * 历史 `connections.json`、`secrets.json` 和相关 JSON 文件。 连接和提供商的公开配置仍保留在普通配置中。敏感值改为加密字段，只能通过本机 Secret Store 解密。原始值不会上传、写入日志或出现在迁移诊断中。 迁移使用固定 ID `secret-store-v1`，并记录以下状态： | 状态 | 含义 | 处理方式 | | -------------- | ------------ | ------------------ | | `pending` | 需要迁移，或环境仍需修复 | 查看向导并处理密钥或文件问题 | | `running` | 正在备份或迁移 | 等待完成，不要替换数据目录 | | `failed` | 检查、写入或验证失败 | 查看脱敏错误，修复后点击“重试迁移” | | `succeeded` | 迁移和验证完成 | 测试 DBX，之后可选择删除迁移备份 | | `not_required` | 没有需要转换的历史数据 | 直接进入 DBX | ## 升级前准备 1. 退出 DBX，复制完整数据目录，包括 `dbx.db`、WAL 文件、JSON 配置文件和 `.dbx` 目录。 2. 确认当前部署使用的密钥来源。已有密文时绝对不要轮换、删除或替换密钥。 3. 确认运行 DBX 的账户可以读写数据目录，并能访问系统凭据库或外部密钥。 4. 如果数据目录位于挂载卷，升级前先确保该卷会持久化。 5. 不要只复制 `dbx.db` 到另一种操作系统。跨设备请使用 DBX 加密导出/导入。 迁移备份是额外的回滚副本，不能替代正常备份策略。 ## 按部署方式升级 ### 桌面端应用 桌面版使用操作系统凭据库： | 平台 | 密钥来源 | | ------- | ------------------------------ | | macOS | Keychain，以及构建版本支持的平台兼容密钥 | | Windows | Credential Manager | | Linux | Secret Service；没有可用提供者时配置持久化密钥 | 升级步骤： 1. 安装新版本，不要删除已有配置目录。 2. 启动 DBX，并在提示时允许访问 Keychain、Credential Manager 或 Secret Service。 3. 在“数据安全升级”向导中查看统计和历史文件列表。 4. 点击“开始迁移”，等待备份、迁移和验证完成。 5. 完成页出现后，打开代表性的连接，并验证插件、AI 提供商、Tunnel 和同步功能。 6. 验证通过前保留备份；确认不再需要回滚后再点击“删除迁移备份”。 迁移期间主界面和普通业务命令会保持阻塞。状态、开始、重试、诊断和备份清理请求仍可用，向导才能恢复未完成的升级。 ### Docker 和 `dbx-web` 数据库、历史文件和托管密钥必须使用同一个持久化数据卷。默认托管密钥位置是： ```text ${DBX_DATA_DIR}/.dbx/secret.key ``` Docker 升级步骤： 1. 停止旧容器，备份命名卷或绑定的 `DBX_DATA_DIR`。 2. 新容器继续把同一个卷挂载到同一个路径。 3. 如果使用生产环境密钥，在启动新镜像前挂载密钥并设置 `DBX_SECRET_KEY_FILE`： ```yaml services: dbx: image: t8y2/dbx:latest environment: DBX_DATA_DIR: /app/data DBX_SECRET_KEY_FILE: /run/secrets/dbx_secret_key secrets: - dbx_secret_key volumes: - dbx-data:/app/data secrets: dbx_secret_key: file: ./dbx_secret_key ``` 4. 启动新容器并打开 Web UI。业务 API 开放前会先显示迁移向导。 5. 执行迁移，等待成功页出现，并通过 Web UI 验证代表性连接。 6. 始终把数据卷和密钥一起保留；验证通过后再删除迁移备份。 也可以由密钥管理系统提供 `DBX_SECRET_KEY`，不使用 `DBX_SECRET_KEY_FILE`。显式配置优先于数据目录托管密钥；如果显式密钥不可读或格式错误，DBX 不会静默回退到其他密钥。 迁移未完成时，Web API 只允许迁移状态、开始、重试、ping、认证和备份清理。其他 API、MCP 路由和业务操作会返回 `423 DATA_MIGRATION_REQUIRED`。 ### 直接运行二进制或 systemd 服务 1. 停止服务，备份 `DBX_DATA_DIR` 指向的目录。 2. 确认服务账户能保留 `${DBX_DATA_DIR}/.dbx/secret.key`，或配置稳定的 `DBX_SECRET_KEY_FILE`/`DBX_SECRET_KEY`。 3. 替换二进制并重启服务。 4. 打开 `dbx-web` 提供的 Web UI，完成迁移向导。 5. 使用 systemd 时，把密钥环境放在受保护的环境文件或凭据机制中，不要把生产密钥放在所有用户可读的 unit 文件里。 6. 删除迁移备份前，先验证连接和相关集成。 ### CLI 和 MCP CLI 与独立 MCP 只检查迁移状态和已有密钥，不会创建密钥，也不会执行历史数据迁移。将 `DBX_DATA_DIR` 指向原数据目录，先通过桌面端或 `dbx-web` 完成迁移；在此之前，依赖业务数据的命令会返回 `DATA_MIGRATION_REQUIRED`。 ## 密钥管理规则 DBX 有两条相互独立的密钥边界： | 密钥 | 用途 | 存放位置 | 是否通过同步复制 | | ------------------ | -------------------- | --------------------- | ---------------- | | 本地 Secret Store 密钥 | 加密本机 `dbx.db` 中的敏感值 | 系统凭据库、数据目录托管密钥或环境变量密钥 | 否 | | 同步口令 | 加密导出/导入包中的敏感 payload | 用户为该同步包输入的口令 | 只作为同步包保护，不作为本地密钥 | 数据目录托管密钥只有在迁移或首次写入敏感值时才会创建。它必须与 `dbx.db` 一起备份。密钥和数据库在同一卷中，只能保护静态数据内容，不能防止整个数据卷被复制后泄露。 已有密文时使用新密钥会导致数据无法解密。正确做法是恢复原密钥，不要生成替代密钥。 ## 迁移内部流程 存储层把迁移分成三个阶段： ```text open_unmigrated() -> 打开 SQLite 并初始化必要 schema，不修改历史数据 inspect_data_migration() -> 只读扫描数据库行、JSON 文件和密钥可用性 start_data_migration()/retry_data_migration() -> 创建备份、迁移、验证并记录最终状态 ``` 写入数据前，DBX 会创建权限受限的 `dbx-secret-migration-/` 目录，存放一致性 SQLite 备份和存在的历史 JSON 文件。SQLite 使用备份 API 以保留 WAL 状态；备份失败时不会开始迁移。 迁移把敏感字段写入本地 Secret Store，公开 JSON 只保留非敏感配置，并验证旧明文列为空且所有密文都能解密。历史 JSON 遵循“导入、验证、最后改名”顺序；只有成功后才改成 `.bak`。解析或验证失败时原文件仍保留，方便修复和重试。后续步骤失败时会先恢复 SQLite 备份，再记录 `failed`。 预检查只返回数量、状态、非敏感提供商名称和文件名，不返回密码、Token、私钥、密钥内容或密钥路径。扫描统计带有源数据指纹，避免旧缓存让成功迁移再次显示为未完成。 ## 迁移成功后 1. 测试你使用的每种数据库至少一个连接。 2. 测试插件连接、AI 提供商、SSH/Tunnel 配置和包含凭据的同步操作。 3. 重启 DBX 或容器，确认下一次启动直接进入主界面。 4. 这些检查通过前保留迁移备份。 5. 确认不再需要回滚后，点击“删除迁移备份”。启动门禁允许发送清理请求，但存储层仍会强制要求记录状态为 `succeeded`。 保留备份不会阻塞后续启动。删除备份不可逆；如果仍需要恢复迁移前状态，请保留普通数据备份。 ## 失败处理 ### 向导显示迁移失败 原始数据和迁移备份会保留。阅读向导错误，修复环境后点击“重试迁移”。常见原因包括： * 没有允许访问 Keychain、Credential Manager 或 Secret Service； * `.dbx/secret.key` 缺失或不可读； * `DBX_SECRET_KEY_FILE` 或 `DBX_SECRET_KEY` 已更换； * 历史 JSON 格式错误； * 没有足够权限或磁盘空间创建备份； * 历史值无法通过验证。 排查期间不要删除 `dbx.db`、WAL、历史 JSON 或迁移目录。 ### 重启后向导再次出现 导出脱敏诊断，检查 `state`、`needsMigration`、`errorCode`、`backupPath` 和统计字段。成功迁移应为 `succeeded` 或 `not_required`。如果启动之间更换了密钥或数据目录，先恢复原来的配对关系再重试。 ### 密钥不可用 桌面端请允许 DBX 访问系统凭据库。Web、Docker 或二进制服务请确认数据目录挂载正确，且显式密钥配置可读。已有加密配置不能通过创建新密钥解决。 ### 连接密码消失 确认应用使用的是升级前相同的数据目录和密钥。如果连接设置为 `save_password=false`，迁移会按设计不恢复主密码。确认配置目录和密钥正确后，再通过连接编辑器重新输入密码。 ### 删除备份失败 保留备份并重试，同时检查迁移状态是否为 `succeeded`、数据目录是否可写，以及备份文件是否被手动修改。清理过程会在删除前校验清单路径和文件摘要。 ## 跨设备迁移不是本次升级 不要通过复制 `dbx.db` 在不同操作系统之间搬迁配置。本地密钥属于源设备，请使用加密配置导出/导入： 1. 分离导出公开配置和敏感值。 2. 使用用户提供的同步口令保护敏感 payload。 3. 在目标设备导入。 4. 使用目标设备自己的本地 Secret Store 密钥重新加密。 同步口令错误、ID 冲突或任一字段失败时，不会提交半成品导入结果。 ## 验证清单 * [ ] 已创建完整的升级前数据目录备份。 * [ ] 原有本地密钥或外部托管密钥仍然保留。 * [ ] 向导以 `succeeded` 完成，或状态为 `not_required`。 * [ ] 代表性连接和相关集成均可用。 * [ ] 重启后不再阻塞在迁移向导。 * [ ] 已保留迁移备份，或在验证后明确删除。 * [ ] 跨设备迁移使用加密导出/导入，没有直接复制数据库。 状态机、存储实现和开发者测试矩阵请参阅 [DBX 数据安全升级与迁移参考](https://github.com/t8y2/dbx/blob/main/docs/data-security-migration.zh-CN.md)。 --- # 数据传输 > 在不同连接、数据库、Schema 或数据库引擎之间批量复制表数据，并跟踪每张表的结果。 Source: https://dbxio.com/cn/docs/data-transfer Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/data-transfer. 数据传输把一个数据源中的表或集合复制到另一个连接、数据库或 Schema。它适合环境迁移、测试数据准备和一次性数据整合，不是持续复制、CDC 或双向同步方案。 跨引擎传输会经过 DBX 的字段和类型转换层。目标数据库的权限、约束、触发器、默认值和类型语义仍会影响结果。重要迁移应先在测试环境演练并做行数与关键字段校验。 ## 入口 ### 数据传输向导 向导适合一次传输多张表。你可以分别选择源和目标连接、Catalog、数据库和 Schema，再配置建表、写入模式、目标表名大小写和批大小。 ### 侧边栏复制与粘贴 在对象树中复制一张或多张表后，可以粘贴到目标位置： * 同一上下文中可选择“结构和数据”“仅结构”或“仅数据”，并逐表修改目标名称 * 粘贴到另一个连接、数据库或 Schema 时，DBX 会自动打开数据传输向导并带入源表和目标位置 * 表数据复制会跳过生成列或计算列，并对 PostgreSQL identity、SQL Server identity 等路径应用相应写入处理 ### 查询结果导出到数据库 在查询结果网格的“导出”菜单或右键菜单中选择“导出到数据库”，填写目标连接、数据库、Schema（如适用）和表名。 填写目标后，可点击“执行预览”查看数据来源、目标位置、当前已加载行列数、源字段和预计操作。预览不会写入数据库；显示的行数是当前已加载行数，执行时仍会读取完整可导出结果并检查限制。点击“开始传输”后必须再次点击“确认传输”；覆盖已有表时会明确提示删除目标表全部原有数据。返回修改会保留当前填写内容。 * **创建目标表**：同引擎的单表 `SELECT * FROM 表` 会读取源表 DDL，保留字段类型、长度、精度、默认值、注释、主键、索引及表选项，再替换目标表名。Schema 内必须唯一的索引或约束名会调整，避免与源对象冲突。无法安全复制结构时会停止，不会自动降级为全部文本字段。 * 投影、关联、表达式查询和跨引擎查询使用结果字段生成新表；这些结果没有唯一对应的整表 DDL。元数据不足或目标时间精度不足时使用可保留值的文本类型，不推断原表约束。写入已有表时，无法保留的时间精度会在写入前报错。 * 创建表时目标名称必须尚不存在。写入已有表请取消勾选“创建目标表”；追加保留原数据，覆盖以事务执行 `DELETE + INSERT`，保留目标结构、外键和触发器。MySQL 已有表需要 InnoDB。 * 导出读取完整查询结果，并检查导出行数限制、分页完整性和大字段预览。存储过程或会修改数据的语句不会为了传输而再次执行；只有已完整加载的结果可直接使用。 * 使用活动游标或手动事务的结果需要先在网格中加载全部行。普通分页在源查询会话中读取，保留会话设置，避免从其他连接读到不同数据。 * 手动事务中暂不支持复制源表结构；提交或回滚后重新查询，再选择“创建目标表”。MySQL、H2 临时表也会停止结构复制，避免生成生命周期不同的目标表。 * 准备阶段可以取消；开始写入后等待事务结束。对于会隐式提交建表的驱动，写入失败后会尝试删除本次成功创建的表，清理失败会显示表名。 此入口只列出已实现事务写入的目标驱动。它不迁移独立触发器、权限或跨表依赖；复杂 DDL、目标不兼容的类型和不支持的标识列处理会明确失败。需要整库或多对象迁移时使用数据传输向导。 ## 向导流程 ### 选择源位置 选择源连接、Catalog（如适用）、数据库和 Schema。DBX 只列出可传输的基础表；MongoDB 路径列出集合。 ### 选择目标位置 选择另一个连接、数据库或 Schema。源和目标不能是完全相同的位置。 ### 选择表 可以全选、搜索或只选择部分表。一次请求中的表必须来自同一个源位置。 ### 配置传输选项 确认是否创建目标表、写入模式、目标表名大小写和批大小。 ### 后台执行并检查结果 对话框关闭后任务继续运行。进度中心显示当前表、表序号、行数、耗时、失败表和取消状态。 ## 传输选项 | 选项 | 说明 | | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 创建目标表 | 目标表不存在时，根据源元数据和目标数据库能力生成表结构 | | 重建结构和数据 | 将现有目标表重命名为备份表（`__dbx_bak_` 前缀），从源结构重建，插入数据后删除备份。任一步骤失败则保留备份表以供手工恢复。生产数据库需二次确认。支持 MySQL、PostgreSQL、SQL Server、KingBase、GaussDB、OpenGauss、KWDB、GoldenDB、SQLite、DuckDB 和 Cloudflare D1。 | | 追加 | 保留目标表已有数据并插入源数据 | | 覆盖 | 在传输该表前清空目标表，再写入源数据 | | Upsert | 目标路径支持且能确定键时，按键更新或插入 | | 表名大小写 | 保持原样、转小写或转大写；转换后的目标名必须互不冲突 | | 批大小 | 控制分页读取和分批写入，默认 1000，可在界面中调整 | | 操作超时 | 默认分别继承源连接和目标连接的查询超时；也可为当前传输设置 `0`–`3600` 秒，`0` 表示不限制 | 如果关闭“创建目标表”，目标表必须已经存在且字段可兼容。即使开启建表，跨引擎 DDL 也可能因目标数据库不支持某些类型、默认值、约束或对象而需要人工调整。 操作超时不限制整个传输任务的总时长。支持增量结果流的驱动会把它作为“无进展等待时间”，每次收到数据都会重新计时；只能一次性返回结果的驱动则按单次数据库操作的总耗时计算。自定义值只作用于当前传输及其保存任务，不会修改连接或查询编辑器的超时设置。 **重建结构和数据** 会替换现有目标表及其索引、触发器、约束、注释和对象权限为源结构。原表会先被重命名为备份表，传输成功后删除。任一步骤失败则保留备份表，可手工恢复。 ## 结构 SQL 预览 “仅结构”传输不会静默修改目标库：DBX 会先生成即将执行的结构语句，在只读确认对话框中展示（语法高亮、可复制、可换行），此时取消则不会执行任何语句。 SQL Preview 上方会显示 **结构传输计划**，包含操作计数和对象级列表，例如计划创建的表、明确跳过的已有目标、重建，以及结构化元数据支持的索引、外键、序列或注释。操作来自与 SQL 相同的规划决策；DBX 不会解析 SQL 来猜测操作。 该摘要描述的是传输计划，不是完整的源/目标 Schema Diff。它不会比较列类型、默认值或可空性，不会检测仅目标端对象，也不表示已有目标与源结构完全相同。例如，`SKIP table users — target already exists` 表示该表不会规划结构 DDL，并不代表源表与目标表一致。 预览覆盖传输即将执行的表级结构操作： * `CREATE TABLE`（必要时还包括需要内联创建的 PostgreSQL 兼容 schema） * `COMMENT` 注释语句 * MySQL 系列延后执行的 `ALTER TABLE ... ADD CONSTRAINT ... FOREIGN KEY` * PostgreSQL 兼容的索引与外键 * 源结构对应的 PostgreSQL 序列语句 * 启用重建时，还包括改名为备份表与最终清理备份的语句 这是预览，不是冻结脚本。开始执行时 DBX 会重新读取源/目标元数据并重新执行现有安全检查，因此期间目标结构发生变化时，实际执行可能与预览不同——DBX 是重新校验，而不是照搬预览的语句。 所选的非表对象（视图、例程、触发器、独立序列等）仍会在执行阶段传输，但其生成的 DDL 不会在预览中展开，对话框中会明确说明这一点。 本阶段“结构和数据”模式的确认流程保持不变。 ## PostgreSQL 结构和所有者 PostgreSQL 到 PostgreSQL 且启用创建表时，DBX 会在能力允许时处理序列、索引、外键以及部分 Schema 级对象和依赖。若源对象所有者在目标实例中不存在，开始前会提示选择： * 跳过相关所有者信息 * 把缺失所有者重新分配为目标当前用户 * 取消并先在目标实例创建所需角色 这不等价于完整的 `pg_dump` / `pg_restore`。扩展、权限、策略、触发器或依赖复杂时，仍应使用 PostgreSQL 原生迁移工具验证。 ## 失败处理 多表任务不会因为第一张表失败就立即丢弃整个队列。DBX 会记录该表的错误并继续尝试后续表，最后以成功或带失败的终态结束。 * 进度中保存每张失败表及错误摘要 * 失败数量较多时，界面只展示有限条目并报告被省略的数量 * 同一目标表已有传输任务运行时，新任务会被阻止，避免并发覆盖 * 取消会停止后续读取和写入，但已提交的数据不会自动撤销 因此“任务完成”不代表所有表都成功；应检查最终状态、失败列表、目标行数和关键字段。 ## 数据库覆盖范围 DBX 按驱动能力清单过滤源和目标连接。当前实现同时包含 SQL 到 SQL、MongoDB 到 MongoDB，以及部分 MongoDB 与 SQL 之间的转换路径；并非所有已支持连接都提供数据传输。 不同组合的能力也不完全相同，例如： * 某些引擎只能传输表数据，不能复用源 DDL * Upsert 依赖目标数据库和可识别的键 * Catalog、Schema、identity、数组、JSON 和二进制值的处理因引擎而异 * 专用搜索、向量、消息队列和配置中心连接不使用此通用表传输入口 如果连接未出现在下拉列表中，表示当前驱动没有声明数据传输能力，而不是仅仅缺少 UI 入口。 ## 传输前检查 * 目标连接是否开启只读保护；只读目标会被直接阻止 * 源和目标账号是否分别具有读取、建表和写入权限 * 目标表名大小写转换后是否冲突 * 主键、唯一约束、外键、触发器和非空字段是否会拒绝数据 * 从生产环境复制到低环境前是否需要脱敏 * 大表是否更适合数据库原生导出、导入或在线迁移工具 ## 相关功能 ### [表数据导入](/cn/docs/table-import) 从文件导入现有表，或按文件批量创建新表。 ### [数据库导出](/cn/docs/database-export) 生成可审阅和离线传递的 SQL 文件。 ### [生产环境安全](/cn/docs/production-safety) 了解只读保护、生产保护和权限边界。 --- # 定时数据库备份 > 在 DBX 桌面端为 MySQL 和 PostgreSQL 创建可手动运行或按小时、每天、每周执行的 SQL 备份计划。 Source: https://dbxio.com/cn/docs/database-backup Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/database-backup. 定时数据库备份使用 DBX 的数据库导出引擎，为 MySQL 和 PostgreSQL 连接生成 SQL 文件。它适合开发、测试和中小型数据库的周期性逻辑备份，并提供表范围、保留数量、运行历史和手动执行。 如果只需要立即备份一次，可以在设置中使用**立即备份**，不必创建计划。配置连接、目录、数据库、表范围和备份内容后点击**开始备份**。一次性备份不会创建或修改计划，不会计算下次执行时间，并会出现在统一的备份历史中。 定时备份当前仅支持 DBX 桌面端，并要求应用保持运行。它不是数据库服务器上的独立调度器，也不能替代物理备份、Point-in-Time Recovery、WAL/binlog 归档或云厂商备份服务。 ## 支持范围 | 项目 | 当前行为 | | --- | ------------------------------------------------------------- | | 数据库 | MySQL、PostgreSQL | | 平台 | DBX 桌面端 | | 输出 | 默认模板为每次计划运行创建独立目录；目录内按数据库/Schema 生成 `.sql` 文件，且可通过模板自定义目录与文件名 | | 频率 | 每隔若干小时、每天指定时间、每周指定星期和时间 | | 内容 | 表结构、表数据、数据库对象、可选 `DROP TABLE IF EXISTS` | | 表范围 | 全部、按模式包含、按模式排除 | | 保留 | 按计划保留最近若干次成功备份文件 | ## 立即执行一次备份 ### 打开一次性备份表单 在设置中进入数据库备份页面，点击**立即备份**。 ### 配置备份范围 选择 MySQL 或 PostgreSQL 连接、备份目录、数据库范围、表范围和备份内容。一次性备份不包含计划名称、执行频率、执行时间、保留数量或启用状态。 连接列表支持多选，可一次勾选多个连接统一备份；每个连接会在**备份历史**中生成独立的备份记录，并依次执行。选择多个连接时，每个连接都备份其全部数据库，不支持精确选择表，且文件名模板必须包含 `{runId}`，避免不同连接的备份文件重名。 ### 开始并确认结果 点击**开始备份**。任务会使用与定时备份相同的导出引擎、进度、取消和错误处理，并在**备份历史**中显示。 ## 创建计划 ### 打开备份设置 在设置中进入数据库备份页面，创建新的备份计划。 ### 选择连接和数据库 选择 MySQL 或 PostgreSQL 连接。可以备份所有非系统数据库，也可以选择指定数据库。 ### 配置表范围 选择全部表、只包含匹配模式的表，或排除匹配模式的表。模式支持 `*` 和 `?`，并可以匹配 `schema.table` 或 `database.schema.table`。 ### 设置目录与频率 选择本机目标目录，设置由运行目录模板和文件名模板组成的输出路径模板，并配置每小时、每天或每周计划。目录模板支持 `{schedule}`、`{date}`、`{timestamp}` 和 `{runId}`；文件名模板还支持 `{database}`。DBX 会预览完整输出路径，并自动补齐文件名中缺失的数据库目标。运行 ID 只有在模板中显式填写 `{runId}` 时才会拼接；如果模板解析出的路径已被其他运行使用，DBX 会拒绝本次运行，避免覆盖已有备份。 ### 选择内容和保留数量 选择结构、数据、对象和 `DROP TABLE IF EXISTS`，然后设置要保留的历史备份数量。 ### 保存并验证 保存后先点击**立即运行**，确认连接权限、表范围、目标目录和生成文件都符合预期，再启用计划。 ## 表匹配模式 表模式可以使用逗号、分号或换行分隔。例如： ```text public.* audit_* orders_202? ``` * **包含**只导出匹配表 * **排除**导出其他表并跳过匹配表 * PostgreSQL 名称按大小写区分 * MySQL 会结合 `lower_case_table_names` 判断匹配是否区分大小写 如果没有任何表匹配包含规则，运行会失败，不会生成空的成功备份。 ## 一致性与执行方式 每次备份会在数据库会话中建立一致性快照，再按数据库/Schema 运行导出。完成后回滚只读快照事务，不提交业务修改。 备份任务会显示在统一导出任务区，并提供： * 当前数据库和对象 * 成功、失败或取消状态 * 手动或计划触发来源 * 生成文件列表 * 错误信息和运行时间 取消只会停止后续导出。失败或取消时，DBX 会尽量删除本次已经生成的部分文件，避免把不完整结果误当成成功备份。 ## 保留与历史 每个计划可以设置保留数量。超过数量的旧运行会从历史中清理，并删除相应文件。默认运行目录会使用唯一运行 ID；也可按实际需要自定义目录模板。也可以手动删除某次备份记录和文件。 目标目录仍应纳入操作系统、NAS 或对象存储的独立备份。单机同盘保存无法防止磁盘损坏、勒索软件或整机丢失。 ## 恢复演练 MySQL 兼容连接支持从单个 `.sql` 或 `.sql.gz` 备份中恢复指定表。在备份历史中展开文件列表并点击**恢复**，将**恢复范围**切换为**指定表**。扫描完成后，可以搜索并勾选表，再执行恢复。列表来自完整备份文件，因此目标数据库尚不存在的表也能选择；跨数据库同名表会分别显示。 指定表模式仅恢复所选表的结构、索引和数据，不恢复视图、存储过程、函数、触发器或事件。文件中的数据库上下文仍然生效，未显式指定数据库的表使用弹窗所选的目标数据库。现有外键或触发器可能影响恢复；需要完整恢复所有对象时选择**全部内容**。遇到无法确定作用范围的语句时，DBX 会在执行前拒绝选择性恢复。 生成的 `.sql` 文件可以通过 [SQL 文件执行](/cn/docs/sql-file) 导入。建议定期在隔离环境验证： * 文件可以完整读取和执行 * 表结构、索引、对象和数据量符合预期 * 字符集、时区、序列/自增值和权限需要的额外步骤 * 应用可以连接恢复后的数据库 备份成功只代表文件生成完成，不代表已经验证可恢复。 ## 选择定时备份还是数据库导出 | 功能 | 适合场景 | | --------------------------------- | --------------------------- | | [数据库导出](/cn/docs/database-export) | 一次性迁移、变更前备份、手动选择当前范围 | | 定时数据库备份 | 固定连接和范围的周期性逻辑备份 | | 数据库原生备份 | 大型生产库、PITR、增量/物理备份、高可用与合规要求 | ## 安全建议 * 使用只具备备份所需读取权限的数据库账号 * 目标目录按敏感数据级别控制权限和加密 * 不要把包含业务数据的 SQL 文件提交到公开仓库 * 计划中数据库或表改名后，重新检查范围 * DBX 桌面端未运行、电脑休眠或目标目录不可用时，计划不会像服务器调度器一样可靠执行 ### [一次性数据库导出](/cn/docs/database-export) 手动选择结构、数据、对象和数据库范围。 ### [恢复 SQL 文件](/cn/docs/sql-file) 执行备份文件并查看语句级进度与错误。 ### [生产安全](/cn/docs/production-safety) 使用只读账号、生产保护和最小权限策略。 --- # 数据库文档 > 以文档方式浏览 Schema，为表和字段编写笔记并按颜色分组，导出 DBML 用于 dbdiagram.io 或 CI 中的结构漂移检查。 Source: https://dbxio.com/cn/docs/database-docs Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/database-docs. 数据库文档把线上 Schema 变成可读的资料。DBX 会把表、字段、索引和关系收集成一份快照，与你自己编写的笔记合并后渲染成可浏览的参考文档。同一份快照还能序列化为 DBML，因此图形工具和 CI 检查读到的内容与查看器中显示的完全一致。 笔记保存在一个普通的 JSON 文件中，你可以把它和 migration 放在一起提交，让 Schema 文档能够在 Pull Request 中被评审。 ## 打开方式 在[对象浏览器](/cn/docs/object-browser)中右键点击一张表，选择 **Documentation**。查看器会基于当前连接、数据库和 Schema 打开。 侧边栏可在 **Schemas** 和 **Table Groups** 之间切换。搜索会同时覆盖表、字段和分组。每个表页面列出字段、索引、**References** 与 **Referenced by**，因此关系可以双向查看。 ## 笔记与分组 | 可标注的内容 | 位置 | | ------- | --------- | | 项目笔记 | 文档首页 | | 表笔记 | 表页面标题处 | | 字段笔记 | 表格中的字段行 | | 表分组及其颜色 | 表页面的分组选择器 | 笔记支持 Markdown，并在索引中内联渲染。每次编辑都会自动保存，标题栏会依次显示 **Saving…** 和 **Saved**。写入失败会被明确提示而不是被吞掉，你的文字会保留下来，下一次编辑时重试。 分组保存的是**色相（hue）**，而不是固定颜色。明度和彩度由当前主题决定，因此同一个分组在浅色和深色模式下都保持清晰可读；导出 DBML 时，这个色相会转换成 `[color: #rrggbb]`。 ## 本地笔记与数据库注释 如果某个字段既有数据库的 `COMMENT ON`，又有你在 DBX 中写的笔记，页面会显示你的笔记并标记 **LOCAL**，同时在下方保留原有的数据库注释。数据库中的内容不会被覆盖——DBX 从不为文档执行 DDL，原始注释始终可以找回。 ## 笔记的存储位置 默认情况下，每个连接在 DBX 数据目录中拥有各自的笔记文件，因此该功能开箱即用。 你也可以在连接的**高级**设置中填写 **Notes file**（对应配置项 `docs_notes_path`），把它指向仓库中的文件。笔记文件的结构如下： ```json { "formatVersion": 1, "project": { "name": "Billing", "note": "# Billing\n\n每个租户一个 schema。" }, "groups": [{ "id": "core", "name": "Core", "hue": 210 }], "tables": { "public.orders": { "group": "core", "note": "每次结算对应一行。", "columns": { "status": { "note": "生命周期状态。" } } } } } ``` 键名为 `schema.table` 和 `schema.table.column`，并按各数据库对标识符大小写的处理方式折叠。写入是原子的——先写入同目录下的临时文件再重命名——因此保存被中断也不会在原有文字的位置留下半个文件。 AI 助手在构建 Schema 上下文时也会读取同一份笔记文件：表/字段笔记会作为对应对象的描述，优先级高于数据库注释。这样无需执行 `COMMENT ON`，写在这里的业务含义就能被模型看到。 笔记文件不存在是正常情况，会以空笔记开始；但文件格式损坏在文档查看器中会直接报错，这是有意为之：继续执行会渲染出看似完整的文档，同时悄悄丢弃已写好的内容。AI 助手则保持可用：回退到数据库注释，并明确告知模型本地笔记不可用。 ## 警告提示 文档只会显式降级，不会静默降级。出现以下情况时，查看器会显示提示条： | 情况 | 含义 | | ------------ | ----------------------------- | | 某张表无法生成文档 | 单张表的元数据读取失败，Schema 的其余部分仍然可用。 | | 没有可用的关系 | 该数据库不提供外键元数据，因此无法推导关系连线。 | | 无法获取数据库注释 | 该数据库不支持注释，所有描述都来自你自己的笔记。 | | 部分笔记不再匹配任何对象 | 笔记指向的表或字段已不存在。内容不会被删除。 | | 无法在 DBML 中表示 | 某个结构在 DBX 中有文档，但无法写入导出的 DBML。 | ## DBML 导出 ```bash dbx dbml [--out path] [--notes path] [--schema name] [--database name] [--tables a,b] ``` 不指定 `--out` 时，DBML 会输出到 stdout，便于管道处理。只有在 `--notes` 明确指定文件时才会合并笔记和分组；该参数是显式的，因此路径写错会直接失败，而不是悄悄生成一份没有笔记的结果。 输出包含 `Table`、带推导基数的 `Ref`、`Enum` 和 `TableGroup` 块，可直接粘贴到 [dbdiagram.io](https://dbdiagram.io)。 把结果提交到仓库，就能让 CI 在未经评审的结构漂移时失败： ```yaml - run: dbx dbml prod --notes docs/dbx-docs.json --out docs/schema.dbml - run: git diff --exit-code docs/schema.dbml ``` ## 支持范围与边界 * 仅支持关系型数据库。文档型数据库和键值存储没有对应的 DBML 表达方式，不在支持范围内。 * 覆盖表、字段、索引、关系和枚举；不包含触发器、存储过程、函数、序列和权限。 * DBML 导出是单向的。`.dbml` 文件只是输出，不会作为数据来源——DBX 不会导入它。 * 缺少外键元数据的数据库会生成没有关系连线的文档，并以警告说明，而不是给出一个空白页面。 * 不记录 Schema 历史，也没有按表的“最近更新”。快照带有版本标记，方便后续增量添加该能力。 ### [对象浏览器](/cn/docs/object-browser) 文档的入口，也是查看对象源码的地方。 ### [Schema 浏览器](/cn/docs/schema-browser) 直接查看字段、外键和注释。 ### [字段血缘](/cn/docs/field-lineage) 追踪字段的来源以及修改会影响到什么。 ### [命令行](/cn/docs/cli) 完整的命令参考，包括无界面的文档导出。 --- # 数据库导出 > 将一个或多个数据库的结构、数据和可读取对象流式导出为 SQL 文件。 Source: https://dbxio.com/cn/docs/database-export Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/database-export. 数据库导出会生成可审阅的 SQL 脚本，用于小型备份、迁移、测试数据准备或高风险操作前留档。它可以导出单个数据库/Schema，也可以按连接批量导出多个数据库。 SQL 导出是逻辑导出，不等同于数据库原生物理备份。大型生产库、时间点恢复、增量备份或严格一致性要求，应优先使用数据库官方备份工具；MySQL 和 PostgreSQL 的定时一致性备份可参阅 [数据库备份](/cn/docs/database-backup) 。 ## 可以导出的内容 | 内容 | 说明 | | ------ | ------------------------------------------------------- | | 表结构 | `CREATE TABLE`、字段、主键、索引、约束以及驱动可读取的 DDL | | 表数据 | 按批读取并生成 `INSERT` 语句，不需要先把整表加载到内存 | | 数据库对象 | 视图、序列、扩展、存储过程、函数、触发器、事件等；具体范围取决于数据库和源码可见性 | | 创建数据库 | MySQL 可选生成 `CREATE DATABASE IF NOT EXISTS` 和 `USE` 前导脚本 | | 导入辅助语句 | 根据引擎生成外键检查、identity 写入、例程分隔符等必要的 setup/收尾语句 | 启用“仅选中表”时，表结构和数据只处理所选表。例程等 Schema 级对象不会因为选择少量表而被一并带出；对象导出始终受当前数据库能力限制。 ## 单库导出 ### 选择连接和数据库 选择数据库以及 Schema（如适用），再勾选需要导出的表。 ### 配置内容和 DDL 选项 选择结构、数据、对象、删除已存在表、MySQL 创建数据库和自增起始值处理。 ### 选择输出位置 Desktop 选择本地 `.sql` 路径；Docker/Web 在服务器临时目录生成文件，完成后由浏览器下载。 ### 后台生成并检查结果 进度显示准备阶段、当前对象、对象序号、导出行数、错误和取消状态。任务可以保留在进度中心继续观察。 Desktop 导出成功后可以从任务结果直接在文件管理器中打开输出文件所在目录。Web 下载完成后，服务器临时文件会被清理。 ## 导出所有数据库 启用“导出所有数据库”后，可以搜索并选择当前连接中的多个数据库： * 非 Schema 型数据库通常每个数据库生成一个 `.sql` 文件 * PostgreSQL 等 Schema 感知数据库会为选中数据库下的每个 Schema 建立导出计划；一个数据库包含多个 Schema 时，文件名包含数据库和 Schema * Desktop 选择输出目录，文件按计划逐个写入 * Docker/Web 在服务器逐个生成文件并触发浏览器下载 * 任一计划项失败或被取消时，后续计划停止；已完成的文件不会自动删除 “所有数据库”是多个逻辑导出的串行编排，不是单个跨库事务，也不提供整个实例的一致时间点快照。 ## 结构选项 ### 删除已存在表 启用后，会在对应 `CREATE TABLE` 前写入数据库适配的 `DROP TABLE IF EXISTS`。执行导出文件时，这会删除目标表及其数据，应谨慎使用。 ### MySQL 创建数据库 MySQL 可以在文件开头加入 `CREATE DATABASE IF NOT EXISTS` 和 `USE`。导入账号需要相应权限；默认关闭，避免脚本意外创建或切换数据库。 ### MySQL 自增起始值 默认保留表级 `AUTO_INCREMENT=N`。启用“省略自增值”后，DBX 只移除表选项中的起始值，不会移除字段本身的 `AUTO_INCREMENT` 属性，适合在新环境中重新初始化序列位置。 ## 数据写入和一致性 DBX 使用分页或流式读取，把数据分批写入输出文件。交互式导出的批大小当前固定为 1000 行；实际 `INSERT` 形态会根据数据库能力选择多行或单行语句。 导出实现会尽量： * 对 MySQL 临时关闭并在末尾恢复外键检查 * 对需要的 identity 列生成允许显式写入的包裹语句 * 正确处理字符串、日期、JSON、数组、二进制和 `NULL` 等字面量 * 对存储过程和函数生成数据库需要的分隔符或批次边界 * 在支持的连接上使用稳定会话读取，减少同一表批次间的漂移 交互式 SQL 导出仍不能保证所有数据库、所有对象都位于同一个全局快照。需要一致性备份时使用 [数据库备份](/cn/docs/database-backup) 或数据库原生工具。 ## 错误和取消 * 普通导出在某个表或对象无法读取时，会在允许的路径中把错误写成 SQL 注释并继续；严重的元数据、连接或文件错误会终止任务 * 取消会在对象边界或数据批次之间生效 * Desktop 已写入的部分文件可能保留，需要在复用前检查完整性 * Web 失败或取消时会清理服务器临时文件，不触发成功下载 * 导出成功只表示文件生成完成，不代表它已在目标数据库成功恢复 ## 恢复和验证 可以使用 [SQL 文件执行](/cn/docs/sql-file) 预览并运行导出的脚本。恢复前应检查： * 目标数据库类型和版本是否兼容 * 文件是否包含 `DROP TABLE`、`CREATE DATABASE` 或大批量 `INSERT` * 账号是否有建表、对象创建和数据写入权限 * 导入后表数、行数、索引、约束、序列和关键对象是否符合预期 导出文件可能包含密码哈希、令牌、个人信息和业务敏感数据。不要把未脱敏文件提交到公开仓库或发送到不可信环境。 ## 相关功能 ### [数据库备份](/cn/docs/database-backup) 在 Desktop 中为 MySQL 和 PostgreSQL 配置定时一致性 SQL 备份。 ### [SQL 文件执行](/cn/docs/sql-file) 预览、批量执行并检查 SQL 文件结果。 ### [数据传输](/cn/docs/data-transfer) 不落地 SQL 文件，直接在连接之间复制表数据。 --- # 数据库测试实验室 > 为 DBX 开发与验证启动可重复创建的本地数据库实例。 Source: https://dbxio.com/cn/docs/database-lab Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/database-lab. 数据库测试实验室提供轻量、固定版本的 Docker Compose 环境，方便使用真实数据库版本验证 DBX。每个配方都使用命名数据卷、健康检查、初始化数据或验证阶段创建的冒烟数据，并且默认监听 `127.0.0.1`。 默认密码为 `123456` ，但端口默认只能从本机访问。如需远程访问，请显式设置 `DB_BIND_ADDRESS=0.0.0.0` 、修改 `DB_PASSWORD` ，并配置常规防火墙规则。这些环境用于开发，不是生产部署模板。 ## 可用配方 | 数据库 | 版本目录 | 官方上游镜像 | Compose 使用的 CNB 镜像 | 默认宿主端口 | 容器名 | | ------------- | ------------------- | --------------------------------------------------- | --------------------------------------------------------- | ------: | ----------------------- | | ClickHouse | `clickhouse/24.8` | `clickhouse/clickhouse-server:24.8.14.39` | `docker.cnb.cool/znb/images/clickhouse-server:24.8.14.39` | `10600` | `dbx-clickhouse-24.8` | | Consul | `consul/2.0.2` | `hashicorp/consul:2.0.2` | `docker.cnb.cool/znb/images/consul:2.0.2` | `10900` | `dbx-consul-2.0.2` | | Elasticsearch | `elasticsearch/6.8` | `docker.elastic.co/elasticsearch/elasticsearch:6.8` | `docker.cnb.cool/znb/images/elasticsearch:6.8` | `11500` | `dbx-elasticsearch-6.8` | | etcd | `etcd/3.5` | `quay.io/coreos/etcd:v3.5.21` | `quay.io/coreos/etcd:v3.5.21` | `10710` | `dbx-etcd-3.5` | | etcd | `etcd/3.7` | `gcr.io/etcd-development/etcd:v3.7.0` | `docker.cnb.cool/znb/images/etcd:v3.7.0` | `10700` | `dbx-etcd-3.7` | | Kafka | `kafka/4.3` | `apache/kafka:4.3.1` | `docker.cnb.cool/znb/images/kafka:4.3.1` | `11300` | `dbx-kafka-4.3` | | MariaDB | `mariadb/10.11` | `mariadb:10.11.11` | `docker.cnb.cool/znb/images/mariadb:10.11.11` | `10200` | `dbx-mariadb-10.11` | | MongoDB | `mongodb/5.0` | `mongo:5.0.5` | `docker.cnb.cool/znb/images/mongo:5.0.5` | `10400` | `dbx-mongodb-5.0` | | MongoDB | `mongodb/8.2` | `mongo:8.2.3-noble` | `docker.cnb.cool/znb/images/mongo:8.2.3-noble` | `10401` | `dbx-mongodb-8.2` | | MySQL | `mysql/5.7` | `mysql:5.7.44` | `docker.cnb.cool/znb/images/mysql:5.7.44` | `10100` | `dbx-mysql-5.7` | | MySQL | `mysql/8.4` | `mysql:8.4.6` | `docker.cnb.cool/znb/images/mysql:8.4.6` | `10101` | `dbx-mysql-8.4` | | Nacos | `nacos/2.5` | `nacos/nacos-server:v2.5.2` | `docker.cnb.cool/znb/images/nacos-server:v2.5.2` | `11000` | `dbx-nacos-2.5` | | Nacos | `nacos/3.2` | `nacos/nacos-server:v3.2.3` | `docker.cnb.cool/znb/images/nacos-server:v3.2.3` | `11003` | `dbx-nacos-3.2` | | PostgreSQL | `postgresql/14.23` | `postgres:14.23` | `docker.cnb.cool/znb/images/postgres:14.23` | `10300` | `dbx-postgresql-14.23` | | PostgreSQL | `postgresql/17.4` | `postgres:17.4` | `docker.cnb.cool/znb/images/postgres:17.4` | `10301` | `dbx-postgresql-17.4` | | Pulsar | `pulsar/4.2` | `apachepulsar/pulsar:4.2.3` | `docker.cnb.cool/znb/images/pulsar:4.2.3` | `11400` | `dbx-pulsar-4.2` | | Qdrant | `qdrant/1.8` | `qdrant/qdrant:v1.8.3` | `docker.cnb.cool/znb/images/qdrant:v1.8.3` | `11200` | `dbx-qdrant-1.8` | | Redis | `redis/3.0.7` | `redis:3.0.7-alpine` | `docker.cnb.cool/znb/images/redis:3.0.7-alpine` | `10500` | `dbx-redis-3.0.7` | | Redis | `redis/7.4` | `redis:7.4.9-alpine` | `docker.cnb.cool/znb/images/redis:7.4.9-alpine` | `10501` | `dbx-redis-7.4` | | r-nacos | `rnacos/0.8` | `qingpan/rnacos:v0.8.5` | `docker.cnb.cool/znb/images/rnacos:v0.8.5` | `11100` | `dbx-rnacos-0.8` | | ZooKeeper | `zookeeper/3.9` | `zookeeper:3.9.5` | `docker.cnb.cool/znb/images/zookeeper:3.9.5` | `10800` | `dbx-zookeeper-3.9` | 每个产品使用专属的 `101xx` 至 `115xx` 宿主端口段，校验器会验证全部声明的默认映射位于正确范围且全局唯一。默认密码统一为 `123456`，默认数据库名为 `dbx`。Redis 不支持命名数据库，因此使用 DB 0，并以 `dbx:` 作为冒烟键前缀。Compose 默认使用 CNB 镜像列；官方上游镜像列保留原始镜像地址，便于核对来源或直接拉取。Redis 3.0.7 仅支持 amd64；在 arm64 主机上启动时会单独提醒，Docker 将使用模拟运行。其余配方均支持 amd64 和 arm64。 Nacos 使用管理员用户名 `nacos`、密码 `123456` 和默认 `public` 命名空间。V2 的 HTTP、gRPC 和 Raft 宿主端口为 `11000`、`11001`、`11002`；V3 的 HTTP、Web 控制台、gRPC 和 Raft 宿主端口为 `11003`、`11004`、`11005`、`11006`。两个版本默认即可并行运行。 ```bash DB_PORT=11030 NACOS_CONSOLE_PORT=11031 NACOS_GRPC_PORT=11032 NACOS_RAFT_PORT=11033 make db DB=nacos@3.2 ``` r-nacos 使用管理员账号 `admin` 和密码 `123456`。DBX 配方的 HTTP、gRPC 和 Web 控制台宿主端口默认分别为 `11100`、`11101`、`11102`；上游单机 Compose 使用 `8848:8848`、`9848:9848`、`10848:10848`。 ```bash DB_PORT=11130 RNACOS_GRPC_PORT=11131 RNACOS_CONSOLE_PORT=11132 make db DB=rnacos@0.8 ``` etcd 会创建密码为 `123456` 的 `root` 用户、授予 root 角色并开启认证。默认客户端和 peer 主机端口为 `10700`、`10701`。如需使用上游 Docker 命令中的端口，可执行： ```bash DB_PORT=2379 ETCD_PEER_PORT=2380 make db DB=etcd@3.7 ``` Qdrant 将 `123456` 作为管理员 API Key。在 DBX 中请将用户名留空，并把 API Key 填入密码字段，驱动会通过 HTTP 请求头 `api-key` 发送。HTTP 和 gRPC 默认主机端口分别为 `11200`、`11201`。如需使用上游 Docker 命令中的端口，可执行： ```bash DB_PORT=6333 QDRANT_GRPC_PORT=6334 make db DB=qdrant@1.8 ``` ZooKeeper 使用 Digest 凭据 `root` / `123456` 保护 `/dbx` 节点。默认主机端口为 `10800`；设置 `DB_PORT=2181` 即可匹配上游 Docker 命令。ZooKeeper 的 Digest ACL 模型保护单个节点，并不提供全局登录开关。 Kafka 和 Pulsar 均为刻意保持未认证的单节点开发配方：Kafka 使用 PLAINTEXT，Pulsar 使用 standalone，因此不要将它们暴露到远程网络。Kafka 如需使用常用端口，可执行 `DB_PORT=9092 make db DB=kafka@4.3`；Pulsar 使用常用端口可执行 `DB_PORT=6650 PULSAR_WEB_PORT=8080 make db DB=pulsar@4.2`。 Redis 3.0.7 和 Redis 7.4.9 用于覆盖兼容性的两个端点。Redis 3 早于 ACL、RESP3、Streams 及许多现代命令，Redis 7 则覆盖当前协议与命令集。对这个实验室而言，同时保留 6.2 和 7.4 所提供的兼容性覆盖更小。 Consul 为单节点开发模式，使用 `agent -dev -client=0.0.0.0 -ui` 启动，不启用 ACL。HTTP API 与 UI、gRPC 和 DNS 的默认宿主端口分别为 `10900`、`10901` 和 `10902`；DNS 同时开放 TCP 和 UDP。以下命令可使用本地常用端口 `8500`、`8502` 和 `8600`： ```bash DB_PORT=8500 CONSUL_GRPC_PORT=8502 CONSUL_DNS_PORT=8600 make db DB=consul@2.0.2 ``` Elasticsearch 6.8 以未认证的单节点开发集群运行，并禁用机器学习功能。HTTP API 和 transport 默认宿主端口为 `11500`、`11501`；以下命令可使用上游端口 `9200`、`9300`： ```bash DB_PORT=9200 ELASTICSEARCH_TRANSPORT_PORT=9300 make db DB=elasticsearch@6.8 ``` 所有已提交配方都有唯一的默认宿主端口分配，因此版本和产品可默认并行运行。仅在本地规范需要不同端口时使用 `DB_PORT`： ```bash DB_PORT=10150 make db DB=mysql@5.7 make db DB=mysql@8.4 ``` ## 启动并验证环境 在仓库根目录执行。先列出可用配方，再选择数据库和版本： ```bash make db make db-list make db DB=postgresql@17.4 make db-verify DB=postgresql@17.4 make db DB=rnacos@0.8 make db DB=consul@2.0.2 make db DB=elasticsearch@6.8 ``` 不带参数执行 `make db` 会输出当前全部支持的、可直接复制启动的命令，以及可选参数。传入 `DB=product@version` 后，`db` 会等待 Compose 健康检查通过并输出 DBX 连接字段；对于 DBX 已支持的连接类型，还会输出预填完成的 `dbx://connection/new` 深链。etcd、Consul、Nacos 2、Nacos 3 和 r-nacos 均已支持，其中 Nacos 配方会自动选择正确分流，Nacos 3 使用 API 端口而非独立控制台端口。复制该链接到浏览器或终端执行 `open '<链接>'`，即可打开桌面端的新建连接窗口。使用前请先安装并启动一次 DBX 桌面端以注册 `dbx://` 协议。深链可能包含数据库密码或 Consul ACL token，因此不要将其写入共享终端历史、日志或工单。Kafka、Pulsar 等尚未具备 DBX 连接类型的配方会明确显示深链不可用。`db-verify` 还会在数据库容器中执行配方中的冒烟命令，并校验预期输出；提交数据库相关修复前推荐执行此命令。 ## 命令和变量 | Make 目标 | 用途 | | -------------------------------------------- | --------------------------- | | `make db-list` | 列出数据库版本、容器到宿主机端口映射、镜像和支持的平台 | | `make db DB=product@version` | 创建、等待环境就绪并输出连接字段 | | `make db-verify DB=product@version` | 启动并运行冒烟检查 | | `make db-down DB=product@version` | 停止环境但保留数据卷 | | `make db-reset DB=product@version CONFIRM=1` | 删除环境及数据卷 | | `make db-check` | 校验全部配方和 Compose 文件 | `DB_BIND_ADDRESS` 修改主机侧绑定地址，`DB_PORT` 修改主机侧端口，`DB_PASSWORD` 修改默认密码。例如： ```bash DB_PORT=13306 DB_PASSWORD=local-secret make db-verify DB=mysql@8.4 ``` 远程访问必须显式启用： ```bash DB_BIND_ADDRESS=0.0.0.0 DB_PASSWORD=local-secret make db DB=mysql@8.4 ``` `db-reset` 受安全保护：只有设置 `CONFIRM=1` 才会删除命名卷。Redis 不支持镜像初始化目录约定；其 `init/README.md` 说明了 `verify` 会创建并读取的冒烟键。需要诊断时，可直接运行 `pnpm db:env -- info|status|logs|shell `。 ## Tab 补全 仓库提供 Make 目标和 `DB=product@version` 值的动态补全。它会读取当前配方目录，因此新增版本后无需修改补全脚本。 ```bash # Bash source deploy/database/completion/dbx-make.bash # Zsh autoload -Uz compinit && compinit source deploy/database/completion/_dbx-make.zsh # PowerShell . .\deploy\database\completion\Dbx.Make.ps1 ``` 运行 `make db-completion` 可打印上述命令。加载对应脚本后，在 `make db DB=` 后按 Tab 即可选择配方。Make 目标本身已避免依赖 POSIX Shell 条件语法，因此在 PowerShell、Git Bash 或 WSL 中使用 GNU Make 均可运行；仍需安装 Docker Desktop 和 Node.js/pnpm。 ## 添加配方 在 `deploy/database///` 下添加目录，并提供： ```text recipe.json compose.yaml init/ ``` `recipe.json` 提供 DBX 连接字段和冒烟命令数组。不要使用 shell 字符串，命令必须作为参数数组执行。Compose 文件必须固定镜像版本、使用命名卷和健康检查、将端口默认绑定至 `${DB_BIND_ADDRESS:-127.0.0.1}`，并把 `container_name` 设置为 `dbx--`。 完成后运行： ```bash pnpm test:db-env make db-check ``` --- # 数据库支持 > 了解 DBX 的连接 profile、驱动运行时、专用工作区和按能力启用的高级功能。 Source: https://dbxio.com/cn/docs/databases Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/databases. DBX 的新建连接窗口提供 100+ 数据库和服务 profile。Profile 决定默认端口、表单字段、图标和驱动入口，但“能建立连接”不等于“支持所有高级功能”。 当前版本的连接选择器和 `crates/dbx-core/assets/database-drivers.manifest.json` 是数据库类型与能力的权威来源。文档不维护容易过期的全量静态矩阵。 ## 连接类型 ### SQL 和兼容协议 * MySQL、PostgreSQL、SQLite、SQL Server、ClickHouse、Oracle、Redshift 等核心 SQL 数据库 * MariaDB、TiDB、OceanBase、Doris、SelectDB、StarRocks、Manticore Search、GoldenDB、Dolt 等 MySQL 协议或语法兼容 profile * openGauss、GaussDB、KingbaseES、HighGo、Vastbase、CockroachDB 等 PostgreSQL 兼容 profile * DM、KWDB、YashanDB、GBase、Teradata、Vertica、Exasol、Firebird、SAP HANA 等厂商数据库 * Snowflake、Trino、PrestoSQL、Hive、Spark、DB2、Informix、Databricks、BigQuery 等 Agent/JDBC 分析数据库 * Google Cloud Spanner 等云托管关系型服务（Agent/JDBC，支持 GoogleSQL 与 PostgreSQL 两种方言） 兼容协议只说明连接和部分方言可以复用。数据库版本、系统表、DDL、权限和管理接口不同，DBX 会用独立 profile 或能力覆盖避免错误地启用功能。 ### 文件、边缘和托管数据库 * SQLite、DuckDB、Microsoft Access * Cloudflare D1、Turso、RQLite * H2 和通过 JDBC URL 访问的本地数据库 Desktop 的文件路径属于本机。Docker/Web 的文件路径属于服务器容器或宿主机挂载目录；浏览器电脑上的路径不会自动映射到服务器。 ### 专用数据模型和服务 * Redis、MongoDB、Apache CouchDB * Elasticsearch、Easysearch、Meilisearch、Manticore Search * Qdrant、Milvus、Weaviate、ChromaDB * HBase * Pulsar、Kafka、RocketMQ、RabbitMQ * etcd、ZooKeeper、Nacos、Consul KV * InfluxDB、IoTDB、TDengine 和其它时序/IoT profile 这些连接使用键值、文档、搜索、向量、消息或配置中心工作区，不应套用关系型表格和 SQL 的全部概念。入口详见 [专用工作区](/cn/docs/specialized-workspaces)。 ## 驱动运行时 | 运行方式 | 说明 | 典型边界 | | ------------------ | ---------------------- | -------------------------------------------------------------- | | 内置原生 | Rust 驱动编译进 DBX | 安装后可直接使用 | | 原生 Agent / sidecar | DBX 管理独立 Go/Rust/外部进程 | 需要匹配平台文件；DuckDB、Oracle、KingbaseES、XuguDB、RabbitMQ 等路径可能使用独立运行时 | | JDBC Agent | Java Agent 加厂商 JDBC 驱动 | 需要 JRE、Agent 和可合法获取的厂商 JAR | | JDBC 插件 | 可选通用 JDBC 扩展 | 未识别数据库按通用 JDBC 能力运行 | 驱动的安装、更新、离线包和运行时监控见 [驱动管理](/cn/docs/driver-management)；自定义 JDBC 见 [JDBC 插件](/cn/docs/plugins)。 ### Oracle OCI（thick 驱动） Oracle 连接默认走 thin 驱动；连接对话框的驱动模式里还可以选 **OCI**，它由独立的 `oracle-oci` Agent（基于 Oracle 调用接口构建的 Go agent）承担，连接由 Oracle 客户端库建立。OCI 驱动目前只提供 Windows x64 版本。 * **Instant Client 目录是全局设置**：填写包含 `oci.dll` 的目录，所有 OCI 连接共用；该目录会被加到 Agent 进程的动态库搜索路径最前面。 * **NLS\_LANG 在 Oracle Client 里是进程级的**，所以分两层配置：一个全局默认值，加上可选的连接级覆盖。一旦某个连接覆盖了 NLS\_LANG，它就会独占一个 Agent 进程，字符集不会在连接之间串。 * **TNS 别名与钱包 / sqlnet.ora**：`TNS_ADMIN` 支持全局默认与连接级覆盖（OCI 模式的连接表单里填写目录，留空跟随全局），任何 OCI 连接都能使用 tnsnames.ora 别名、ADB 钱包与 sqlnet.ora 网络选项（压缩、加密），不必切换到 TNS 连接方式；TNS 连接方式下目录也会随连接串传给 Agent 进程。 * OCI 只改变客户端库的加载方式；网格编辑、DDL、传输等功能与 thin 驱动一致。 ## 能力等级 DBX 驱动清单使用从连接到操作的能力等级，并允许按数据库覆盖单项能力： | 能力层 | 含义 | | ---------- | ------------------------ | | Connect | 建立连接并执行该 profile 支持的基础查询 | | Browse | 浏览数据库、Schema、表或专用对象 | | Understand | 增加对象源码、搜索、关系理解等只读能力 | | Operate | 增加表数据编辑等受控写入能力 | 具体功能还由独立 capability 控制，例如： * Schema 搜索和 ER 图 * 表数据编辑和表结构编辑 * 表导入和数据传输 * SQL 文件执行 * 字段血缘和执行计划 * 创建数据库、用户管理和驱动管理 因此菜单是否出现比“数据库名称是否在支持列表中”更能反映当前路径。缺少入口时，应检查 DBX 版本、数据库 profile、驱动模式和已安装组件。 ## 功能边界 ### SQL 文件和关系型工具 Redis、MongoDB、搜索、向量、HBase、配置中心和消息队列工作区不会使用关系型 SQL 文件执行。部分 SQL 数据库只支持查询和浏览，不支持结构编辑、表导入或数据传输。 ### 导入和传输 [表数据导入](/cn/docs/table-import) 与 [数据传输](/cn/docs/data-transfer) 都按 capability 过滤连接。跨引擎路径还受类型映射、键、identity、Schema 和目标 DDL 能力限制。 ### 备份和导出 * [数据库导出](/cn/docs/database-export) 是能力驱动的逻辑 SQL 导出 * [数据库备份](/cn/docs/database-backup) 当前只在 Desktop 为 MySQL 和 PostgreSQL 提供定时一致性备份 * 云同步和配置导出只迁移 DBX 配置，不会备份业务数据库 ### Desktop 和 Docker/Web 两种运行方式共享大部分 Rust 核心查询、元数据和安全策略，但并非功能完全相同。Desktop 才有本地 SQL 文件目录、系统文件选择、Deep Link、本机 CLI Agent 和定时数据库备份；Web 文件、驱动和 Agent 都位于服务器数据目录。 ## 默认端口和连接 URL 连接 profile 会填入常见默认端口，例如 MySQL `3306`、PostgreSQL `5432`、Redis `6379`、MongoDB `27017`、SQL Server `1433`、Oracle `1521`、Elasticsearch `9200`、CouchDB `5984`、Meilisearch `7700`、RabbitMQ AMQP `5672`。这些只是默认值，可以按部署修改。 RabbitMQ 等服务可能同时有业务端口和管理 API 端口；自定义 AMQP 端口不能用于推断 Management API 端口。SSH 隧道、HTTP 代理、TLS SNI 和实际拨号目标也应分别确认。 DBX 可以解析许多常见 DSN/URL，但不同数据库版本和云厂商参数差异很大。连接测试成功后仍应检查实际数据库、Schema、SSL 和权限范围。 ## 本地测试环境 仓库提供 ClickHouse、MariaDB、MongoDB、MySQL、PostgreSQL 和 Redis 的固定 Docker Compose 测试环境，适合验证连接、驱动行为和回归。详见 [数据库测试实验室](/cn/docs/database-lab)。 ## 相关页面 ### [专用工作区](/cn/docs/specialized-workspaces) 查看非关系型、搜索、向量、消息和配置中心界面。 ### [驱动管理](/cn/docs/driver-management) 安装和诊断原生 Agent、sidecar、JDBC Agent 和 JRE。 ### [生产环境安全](/cn/docs/production-safety) 了解数据库权限、只读保护、生产保护和自动化边界。 --- # 驱动管理 > 管理内置驱动、原生 Agent 和 JDBC Agent，配置 JRE 版本并处理驱动更新。 Source: https://dbxio.com/cn/docs/driver-management Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/driver-management. DBX 使用混合驱动架构：内置 Rust 驱动、独立原生 Agent，以及 Java/JDBC Agent。 ## 驱动架构 | 驱动类型 | 工作方式 | 适用场景 | | --------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | 原生（内置） | Rust 驱动编译进 DBX | MySQL、PostgreSQL、SQLite、SQL Server、Redis、MongoDB、ClickHouse 等 | | 原生 Agent / 外部驱动 | DBX 管理的 Go/Rust 独立进程或 sidecar | Oracle、KingbaseES、虚谷 XuguDB、DuckDB，以及 RabbitMQ 等需要独立运行时的连接 | | JDBC Agent | DBX 管理的 Java 子进程 | 需要 JDBC 的数据库：GaussDB、openGauss、DM、HighGo、Vastbase、UXDB、Trino、Hive、DB2、Informix、Neo4j、TDengine、YashanDB、GoldenDB、Kylin、SunDB 等 | 内置驱动可直接使用；原生 Agent/sidecar 需要对应平台文件，JDBC Agent 还需要 JRE。连接对话框会提示缺少的组件，但安装是否自动完成取决于网络、平台、驱动许可和当前设置。 ## 内置驱动 驱动管理的**内置驱动**标签页列出所有可用的 Agent 驱动及其状态： * **已安装驱动**：版本号、大小和更新可用性 * **可用驱动**：可一键安装的驱动 * **更新角标**：注册中心有新版本时显示 从顶部工具栏打开**驱动管理**（可在 设置 → 工具栏 中控制该按钮显隐），或点击创建需要 Agent 驱动的连接时出现的驱动提示。 ## 安装驱动 ### 打开驱动管理 从顶部工具栏打开**驱动管理**，或点击连接对话框中的驱动安装提示。 ### 选择驱动 找到所需的数据库驱动。每个条目显示支持的数据库和驱动版本。 ### 点击安装 DBX 会下载原生 Agent 可执行文件或 JDBC Agent JAR，以及所需运行时。下载过程中显示进度。 ### 创建连接 返回连接对话框。驱动此时即可使用。 ## JRE 管理 JDBC Agent 驱动需要 Java 运行环境。DBX 内置 JRE 管理： * **系统 JRE**：DBX 可使用系统上已有的 Java 安装 * **托管 JRE**：DBX 可下载并管理自己的 JRE，与系统 Java 隔离 * **多 JRE 支持**：不同驱动可按需使用不同 JRE 版本 * **重新安装**：如托管 JRE 损坏，可在**内置驱动**标签页顶部的 Java 运行时区域重新安装 ## 驱动更新 DBX 会定期检查驱动更新： * 有新版本时，**内置驱动**标签页中会显示更新角标 * 点击**升级全部驱动**一次性更新所有已安装的驱动 * 单个驱动可从商店中对应条目升级 ## 运行时监控 驱动管理会汇总正在运行的外部驱动和 Agent，包括协议模式、活动 Session、PID、内存、CPU、运行时长和最后错误。支持控制的运行时可以在这里停止或重启；共享运行时可能服务多个连接，操作前应检查活动 Session。 RabbitMQ 等消息队列 Agent 还可能同时使用业务协议和管理 API。自定义 AMQP/管理端口、SSH 隧道和 TLS 目标必须分别配置，不能从一个端口推断另一个端口。 ## 离线驱动导入 对于无法访问互联网的环境，DBX 支持离线驱动安装： 1. 从另一台机器下载与目标操作系统和 CPU 架构匹配的 DBX 离线驱动 ZIP 包 2. 将其传输到离线机器 3. 在驱动管理中使用**导入离线包**安装驱动包 这适用于气隙网络、严格防火墙环境或企业中预先批准的驱动版本。 所有 Agent 都提供单驱动 ZIP，可直接使用**导入离线包**安装。Java Agent 的单驱动包跨平台，但不重复携带 JRE；KingbaseES、Oracle、Xugu 等原生 Agent 的单驱动包按操作系统和 CPU 架构区分。 如果目标机器尚未安装 Java Agent 所需的托管 JRE，可在**导入离线包**中选择对应平台的 `dbx-jre--.tar.zst`（例如 `dbx-jre-21-macos-aarch64.tar.zst`），或者直接使用包含全部驱动和 JRE 的完整离线 ZIP 包。独立 JRE 包仅包含 Java 运行时，不包含数据库驱动，也不需要 `agent-registry.json`。DBX 会验证 Java 的操作系统和 CPU 架构后安装到托管 JRE 目录。 ### Windows 导入 KingbaseES Windows x64 下载 `dbx-agent-kingbase--windows-x64.zip`，Windows ARM64 下载 `dbx-agent-kingbase--windows-aarch64.zip`，然后在驱动管理中选择**导入离线包**。请勿导入 Linux 或 macOS 包。 ZIP 内包含版本信息和对应平台的原生 Agent。DBX 会将其安装为 `%USERPROFILE%\.dbx\agents\drivers\kingbase\agent.exe`，不需要手动解除浏览器下载文件的阻止状态或复制文件。 ### 离线导入 JDBC 插件 通用 JDBC 连接（自定义 JDBC URL + 导入的驱动 JAR）通过独立的 **DBX JDBC 插件** 运行，发布为单独的 `dbx-jdbc-plugin-*.zip` 资源，**不会**打进各数据库的 Agent ZIP。请在 **JDBC 驱动** 页签使用 **本地安装** 安装它（不要用内置驱动里的**导入离线包**，那是给 Agent ZIP 用的）。 导入真正的驱动 JAR（例如 Oracle 的 `ojdbc*.jar`）始终是本地操作，不需要这个插件包，也不需要网络——在同一页签使用 **导入 JAR**，无论 JDBC 插件本身是否已安装。 ## 插件更新 对于由 [JDBC 插件](/cn/docs/plugins)支持的数据库，当有新插件版本可用时，DBX 会显示更新通知。插件更新遵循与内置 Agent 驱动相同的安装流程。 ## 故障排除 | 问题 | 解决方案 | | ----------- | ------------------------------------- | | 驱动下载失败 | 检查网络连接和防火墙规则。尝试离线导入方法。 | | Agent 无法启动 | 在驱动管理中验证 JRE 安装。如需要，重新安装托管 JRE。 | | 驱动安装后连接测试失败 | 确认 JDBC URL 格式与驱动的预期格式匹配。检查 SSH/代理设置。 | | 驱动版本错误 | 卸载当前驱动并从商店安装正确版本。 | --- # 常见问题 > DBX 常见问题：连接数据保存在哪里、如何备份、如何让数据与程序同目录或自定义数据目录。 Source: https://dbxio.com/cn/docs/faq Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/faq. DBX 桌面端的常见问题。本页从数据存储与数据目录开始，后续会持续补充新条目。 ## 数据与备份 ### 连接配置保存在哪里？ DBX 桌面端把连接、已保存的凭据、SSH 隧道配置、查询历史和应用设置保存在数据目录下的单个 SQLite 数据库文件 `dbx.db` 中： * **Windows（安装版）：** `C:\Users\<用户名>\AppData\Roaming\com.dbx.app\dbx.db` * **Windows（便携版压缩包）：** `\data\dbx.db` * **macOS：** `~/Library/Application Support/com.dbx.app/dbx.db` * **Linux：** `~/.local/share/com.dbx.app/dbx.db` SSH 主机指纹保存在同目录的 `known_hosts` 中，DBX 不会读写 `~/.ssh`。数据目录下还可能出现 `dbx.db-wal`、`dbx.db-shm` 检查点文件。 旧版本 DBX 曾使用 `connections.json` 和 `secrets.json` 保存连接，现在启动时会自动迁移进 `dbx.db`，原文件改名为 `*.bak` 保留。 跨设备迁移推荐使用加密的[配置导出/导入](/cn/docs/config-export)，而不是直接拷贝文件。手动备份时请先退出 DBX，再复制整个数据目录，或至少复制 `dbx.db` 并连同 `-wal`、`-shm` 文件。 ### 能把数据放在程序同目录，或自定义数据目录吗？ 可以，有两种官方支持的方式： * **Windows 便携版：** Release 页面的 `DBX_<版本>_<架构>-portable.zip` 自带 `portable.dbx` 标记文件。解压到任意目录运行，所有数据自动保存在 `DBX.exe` 旁边的 `data` 目录。首次启动时，如果便携目录还没有数据、而 AppData 中存在旧数据，会自动导入一次。 * **`DBX_DATA_DIR` 环境变量：** 所有平台、安装版和便携版均可用，优先级最高，可指向任意目录。新目录首次启动是空库，请用配置导出/导入迁移，或在 DBX 退出后拷贝 `dbx.db`。 `portable.dbx` 标记仅对 Windows 生效，且当 exe 旁存在 `uninstall.exe`（安装版）时会被忽略；解压版目录中手动创建该标记同样可以启用便携模式。应用内没有切换数据目录的设置项。

升级已有安装前，请先阅读 [数据安全升级与迁移说明](/cn/docs/data-security-migration) 。

## Linux 窗口闪烁或内容消失 在 GNOME 且系统已开启窗口合成时，Linux 主窗口会绘制带圆角、阴影的浮动边框；在其他桌面（KDE、XFCE、Cinnamon 等）默认使用不透明背景，避免部分显卡驱动与 WebKitGTK 的透明窗口合成兼容问题。两种模式都不会关闭 GPU 加速或改变 Wayland/X11 后端。 可以通过环境变量覆盖默认行为。在其他桌面强制启用浮动边框： ```bash DBX_LINUX_FLOATING_FRAME=1 dbx ``` 若在 GNOME 上出现闪烁、内容消失或必须缩放窗口才能重绘，请完全退出 DBX（包括托盘），并使用 `DBX_LINUX_FLOATING_FRAME=0 dbx` 重新启动以强制使用不透明窗口。没有窗口合成时始终不启用浮动边框。AppImage 用户请将 `dbx` 替换为实际的 AppImage 文件路径。 如果默认的不透明窗口仍有问题，请在反馈中提供 DBX 版本、安装方式、KDE/Plasma 版本、Wayland/X11 会话类型、显卡及驱动信息，以及系统 WebKitGTK 版本。 ## PostgreSQL / openGauss 中文乱码 如果数据库声明为 `LATIN1`，但历史文本实际保存的是 GB18030 字节，可以在 **编辑连接 → 连接 → URL 参数** 中填写： ```text clientEncoding=GB18030&serverEncoding=ISO-8859-1 ``` 保存后重新连接。DBX 原生驱动使用这组参数转换查询结果、中文 SQL 和绑定参数；支持表格读取与编辑、文本数组、JSON、元数据和按行导出。不会修改数据库编码或已有数据。`clientEncoding` 也支持 `GBK` 和 `UTF-8`，`serverEncoding` 可写为 `LATIN1`；两个参数必须同时提供。 这组参数只适用于数据库声明编码与实际文本字节不一致的连接。服务端必须报告 `server_encoding=LATIN1`，且 `standard_conforming_strings=on`。读取遇到无法转换的值时保留原文，并在查询消息中提示；其他完整的文本仍正常解码。按字节截断的脱敏值（例如半个汉字后接星号）不会再导致整条查询失败，也不会被替换字符或 NULL 覆盖。写入时不能用指定编码表示的内容仍明确报错。未填写参数的连接使用正常的 PostgreSQL 编码转换。 COPY 文本导入支持 DBX 的默认文本格式；跨连接数据传输会使用按行 INSERT 路径。原始 COPY 输出和其他 COPY 格式请使用按行导入/导出。 --- # 字段血缘 > 从外键、视图定义、查询历史和同名字段中分析字段的上游、下游与潜在影响范围。 Source: https://dbxio.com/cn/docs/field-lineage Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/field-lineage. 字段血缘用于回答“这个字段从哪里来、被谁使用、修改后可能影响什么”。DBX 会组合数据库元数据和本地查询历史，并按证据强度标记关系，而不是把所有同名字段都当成确定依赖。 ## 打开方式 从字段节点、表结构或相关上下文菜单打开字段血缘。当前字段会作为中心目标，结果列表展示相关表、字段、视图或历史 SQL。 ## 关系来源与可信度 | 来源 | 默认可信度 | 说明 | | ---- | ------ | -------------------- | | 外键 | 确定 | 数据库声明了当前字段与目标字段的约束关系 | | 视图定义 | 高置信或可能 | 视图源码同时引用目标表和字段时置信度更高 | | 查询历史 | 高置信或可能 | 历史 SQL 同时命中表和字段时更可信 | | 同名字段 | 可能 | 仅根据字段名相同推断，需要业务确认 | 界面会区分**确定**、**高置信**和**可能相关**。筛选低置信结果可以先聚焦外键和明确源码引用。 ## 搜索与筛选 * 搜索表、字段、视图或 SQL 片段 * 按置信度过滤 * 查看当前显示数量和总关系数 * 复制表名或字段名 * 打开目标表数据或结构 * 从结果回到对应对象树位置 血缘读取会按数据库能力加载外键、视图源码和相关元数据。大型 Schema 首次分析可能需要时间。 ## 查询历史的作用 DBX 会把已执行查询作为辅助证据，例如： * `JOIN` 中同时出现两个字段 * `WHERE`、`SELECT` 或表达式中引用目标字段 * 历史修复 SQL 或报表 SQL 使用同名字段 查询历史只代表曾经在 DBX 中执行或保存过的 SQL，不代表应用代码、ETL、BI 或其他客户端的完整使用情况。 查询历史可能包含敏感表名、条件和字面量。演示血缘结果、导出日志或共享截图前先检查隐私信息。 ## 视图与源码分析 视图来源通过数据库返回的定义进行文本和结构分析。以下情况可能降低置信度： * 动态 SQL 或存储过程拼接 * 同名表/字段但没有明确 Schema * `SELECT *`、复杂子查询或厂商扩展语法 * 数据库没有返回完整视图源码 点击视图结果后，可以结合 [对象浏览器](/cn/docs/object-browser) 中的源码进行人工确认。 ## 使用方式 ### 修改字段前 1. 先看确定的外键关系 2. 检查高置信视图和历史 SQL 3. 对可能相关的同名字段进行业务确认 4. 在代码仓库、ETL 和 BI 中继续搜索 5. 使用 [Schema 对比](/cn/docs/schema-diff) 审查目标环境变化 ### 接手陌生数据库 从核心主键、业务编号、用户 ID 或时间字段开始，逐步打开关联表和视图。字段注释和对象源码通常比单纯同名推断更可靠。 ## 支持与边界 * 血缘需要外键、视图源码或可解析查询历史；功能范围因数据库而异 * 数据库没有声明外键时，DBX 只能提供视图、历史 SQL 和同名字段线索 * 结果不是强一致数据治理图，不包含所有应用代码、消息流、ETL 和外部 BI * 删除历史记录或清理本地数据会减少查询历史来源 * 当前支持范围以 [数据库支持](/cn/docs/databases) 的功能矩阵为准 关键结构变更仍应结合数据库约束、对象源码、应用代码搜索和实际业务负责人确认。字段血缘用于缩小调查范围，不替代变更影响分析。 ### [结构浏览](/cn/docs/schema-browser) 查看字段、外键、注释和对象层级。 ### [对象源码](/cn/docs/object-browser) 查看视图、过程、函数和触发器定义。 ### [Schema 对比](/cn/docs/schema-diff) 检查不同环境之间的结构差异和部署脚本。 --- # 快速开始 > 安装 DBX、创建第一个连接，并了解桌面版、Docker 版和源码运行方式。 Source: https://dbxio.com/cn/docs/getting-started Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/getting-started. 本页帮助你完成三件事： 1. 安装 DBX 或启动 Docker 版本 2. 创建并测试第一个数据库连接 3. 在需要参与开发或本地调试时从源码运行 DBX ## 选择安装方式 ### macOS 使用 Homebrew 安装： ```bash brew install --cask dbx ``` 之后可用以下命令更新： ```bash brew upgrade --cask dbx ``` 也可以从 [GitHub Releases](https://github.com/t8y2/dbx/releases) 下载 `.dmg` 安装包。 ### Windows 使用 Scoop 安装： ```bash scoop bucket add dbx https://github.com/t8y2/scoop-bucket scoop install dbx ``` 之后可用以下命令更新： ```bash scoop update dbx ``` 也可以从 [GitHub Releases](https://github.com/t8y2/dbx/releases) 下载 `.msi` 安装包。 ### Linux 使用 Flatpak 从 [FlatPark](https://flatpark.org/apps/com.dbxio.dbx/) 安装（适用于任意发行版）： ```bash flatpak remote-add --if-not-exists flatpark https://dl.flatpark.org/flatpark.flatpakrepo flatpak install flatpark com.dbxio.dbx ``` 之后可用以下命令更新： ```bash flatpak update com.dbxio.dbx ``` 银河麒麟 V10、统信 UOS 等系统推荐通过[星火应用商店](https://spk-resolv.spark-app.store/?spk=spk://store/development/dbx)安装，并选择 **APM 版本**。AmberPM 提供兼容运行环境，可减少发行版依赖差异导致的安装或启动问题，后续也可直接在星火应用商店客户端中获取更新。 APM 版本在兼容环境中运行 DBX。如果为 Agent/JDBC 驱动选择宿主机 Java，需要在路径前添加 `/host`，例如将 `/usr/bin/java` 填写为 `/host/usr/bin/java`。 也可以从 [GitHub Releases](https://github.com/t8y2/dbx/releases) 下载对应安装包： | 格式 | 适用场景 | | ----------- | --------------------------- | | `.deb` | Debian、Ubuntu 及兼容发行版 | | `.rpm` | Fedora、 CentOS、 SUSE 及兼容发行版 | | `.AppImage` | 通用 Linux 桌面环境 | 如果使用 `.AppImage`，首次运行前可能需要添加执行权限： ```bash chmod +x DBX*.AppImage ``` ### Docker Docker 版本适合部署在服务器上，并通过浏览器访问： ```bash docker run -d \ --pull=always \ --name dbx \ -p 4224:4224 \ -v dbx-data:/app/data \ t8y2/dbx:latest ``` `latest` 标签会拉取当前发布版本。这里使用跨平台的 `dbx-data` 命名卷；中国大陆用户可改用 `docker.cnb.cool/dbxio.com/dbx:latest`，以获得更快的拉取速度。 ### 环境变量 Docker 镜像支持以下启动参数。使用 `-e 变量名=值` 指定，例如生产环境可添加 `-e DBX_PASSWORD=your-password`： | 参数 | 默认值 | 用途 | | ----------------------------- | ----------- | ---------------------------------------------------- | | `DBX_PASSWORD` | 未设置 | Web 登录密码，生产环境建议设置 | | `DBX_DISABLE_PASSWORD` | `false` | 设为 `true` 或 `1` 可关闭登录保护 | | `DBX_DISABLE_PASSWORD_VIEWER` | `false` | 设为 `true` 或 `1` 后，已保存连接凭据不返回浏览器，关闭密码查看、含密码复制及含凭据同步导出 | | `DBX_DATA_DIR` | `/app/data` | 持久化数据目录 | | `DBX_PORT` | `4224` | 容器内监听端口 | | `DBX_PUBLIC_BASE_PATH` | `/` | 子路径部署，例如 `/dbx` | 关闭密码查看后，已配置连接仍使用服务端保存的凭据。密码框显示固定占位符；不修改时保留原值，输入新值可替换原值。修改连接目标时不能复用隐藏的旧凭据，需要输入替换凭据。修改环境变量后请重启服务端并刷新浏览器。 启动后访问 `http://localhost:4224`。 `deploy/docker-compose.yml` 用于构建当前源码。若要部署已发布镜像，请使用 `deploy/docker-compose.release.yml`： ```bash docker compose -f deploy/docker-compose.release.yml up -d ``` ```yaml services: dbx: image: t8y2/dbx:latest # 中国大陆用户可改用 CNB 镜像，以加快拉取速度： # image: docker.cnb.cool/dbxio.com/dbx:latest pull_policy: always ports: - "4224:4224" volumes: - dbx-data:/app/data restart: unless-stopped volumes: dbx-data: ``` ## 桌面版还是 Docker | 模式 | 适合场景 | 存储位置 | 需要注意 | | ------------ | -------------------- | ---------------- | ----------------------------------------- | | 桌面版 | 本机日常工作、本地数据库文件、完整工作台 | 本机应用数据目录 | 支持本地 SQL 文件树/SQL 库、桌面 Deep Link 和操作系统文件集成 | | Docker / Web | 服务器自托管、远程浏览器访问 | Docker 卷或服务器数据目录 | 文件路径属于服务器；部分本地文件和桌面集成功能不可用 | 桌面版和 Web 版共享大部分数据库工作流和 Rust 核心能力，但并非所有本地集成完全一致。需要 SQLite、DuckDB、Access、外部 SQL 文件或本机目录时，先确认文件实际位于哪台机器；Docker 中通常还需要把目录挂载进容器。 通过 MCP 打开表或展示查询结果等桌面 UI 工具，需要 DBX 桌面版正在运行。只使用查询类 MCP 工具时，可以直接读取本机 DBX 数据目录，或连接 DBX Web/Docker 后端。 ## 创建第一个连接 ### 打开新建连接 在侧边栏或工具栏中点击 **新建连接**。 ### 选择数据库类型 选择 MySQL、PostgreSQL、SQLite、Redis、MongoDB、DuckDB、ClickHouse、SQL Server、Oracle，或 [数据库支持](/cn/docs/databases) 中列出的兼容类型、Agent/JDBC 类型。 ### 填写连接信息 网络数据库需要填写主机、端口、用户名、密码和必要的默认数据库。SQLite、DuckDB、Access 这类文件型数据库需要选择本地数据库文件，不填写主机和端口。 ### 有 URL 时直接粘贴 DBX 可以解析常见连接 URL，例如 MySQL、PostgreSQL、Redis、MongoDB、ClickHouse、SQL Server、Oracle、Elasticsearch、Easysearch、Meilisearch、CouchDB、DM、GaussDB、openGauss、TDengine 和 Access。保存前请检查解析出的字段。 ### 配置网络选项 如果数据库在内网、跳板机后面、只能通过 Web 网关访问，或网络要求 SOCKS5/HTTP 代理，可以配置 [隧道/代理](/cn/docs/ssh-tunnel)。 ### 测试并保存 点击 **测试** 验证账号、网络和权限。测试通过后保存连接，并从侧边栏打开。 连接密码、SSH 密码、SSH 密钥密码和连接字符串会与普通连接 JSON 分开存储在 DBX 本地数据中。需要迁移加密连接配置时，使用 [配置导出/导入](/cn/docs/config-export) 。 ## 降低生产误操作 * 给生产连接起明确名称，例如 `prod-orders`，并使用颜色、分组和备注说明用途。 * 查询专用连接同时启用数据库只读账号和 DBX **只读连接**。 * 启用**生产环境保护**，按连接或指定数据库标记生产范围；写入时 DBX 会逐次要求明确确认。 * 一个服务器上数据库或 Schema 很多时，只显示当前需要的对象，减少误选目标。 * 对编辑、导入、传输、SQL 文件执行或 Schema 同步生成的 SQL，先审查再执行。 * 提供给 MCP 的连接使用 allowlist，并优先选择“只读”或“数据读写”，不要默认开放“完全访问”。 完整行为和推荐配置见 [生产环境与写入安全](/cn/docs/production-safety)。 ## 下一步可以做什么 ### [写 SQL](/cn/docs/query-editor) 使用补全、格式化、选中执行、取消执行和查询历史。 ### [看数据](/cn/docs/data-grid) 查看结果、在安全时编辑行、预览 SQL 并导出数据。 ### [看结构](/cn/docs/schema-browser) 浏览数据库、Schema、表、字段、Redis 键和 MongoDB 集合。 ## 常见连接问题 | 现象 | 检查项 | | --------- | ------------------------------------ | | 连接超时 | 主机、端口、防火墙、安全组、VPN、Docker 主机网络或内网访问权限 | | 认证失败 | 用户名、密码、认证方式、SSL 要求、账号是否允许远程登录 | | 能连接但看不到表 | 默认数据库、Schema、权限、元数据读取权限、可见数据库过滤 | | 文件数据库打不开 | 文件路径、文件权限、Docker volume 挂载、文件扩展名是否支持 | | 内网数据库无法访问 | 配置隧道/代理、VPN，或让 Docker 部署机器能访问目标数据库 | ## 从源码运行 当你想参与开发或本地调试 DBX 时，可以从源码运行。 第一次参与开发请阅读[从源码编译与参与贡献](/cn/docs/contributing)。教程包含各系统环境安装、Fork、Issue 认领、测试和提交 PR 的完整步骤。 ### 环境要求 * [Node.js](https://nodejs.org/) >= 22.13.0 * [pnpm](https://pnpm.io/) 10.34.7 * Make（macOS 和 Linux 需要；Windows 可选） * [Rust](https://www.rust-lang.org/tools/install) >= 1.88 ### 系统依赖 ### macOS `bash brew install unixodbc ` ### Linux `bash sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev libappindicator3-dev librsvg2-dev patchelf libssl-dev unixodbc-dev ` ### Windows 安装 [Strawberry Perl](https://github.com/StrawberryPerl/Perl-Dist-Strawberry/releases)（编译内置 OpenSSL 所需）： ```powershell winget install StrawberryPerl.StrawberryPerl ``` DBX 默认启用 `sqlite-sqlcipher` 特性，需要从源码编译 SQLCipher 和 OpenSSL，而 Windows 上编译 OpenSSL 必须使用 Perl 执行 `Configure` 脚本。安装后请重新打开终端，使 `perl` 进入 `PATH`。 ### 启动开发环境 ```bash git clone https://github.com/t8y2/dbx.git cd dbx make ``` `make` 会在需要时安装根目录依赖，并启动本地 Tauri 桌面端开发环境。 Web 版本： ```bash make dev-web make dev-backend ``` ### 构建桌面安装包 ```bash make package ``` 桌面安装包会输出到 `target/release/bundle/`。 --- # 快捷键 > 查看当前默认按键，并在设置中为编辑器、表格、侧边栏和全局操作自定义快捷键。 Source: https://dbxio.com/cn/docs/keyboard-shortcuts Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/keyboard-shortcuts. DBX 的快捷键来自同一份可配置 action registry。**设置 → 快捷键**显示当前版本和当前平台的实际绑定，是默认键变化或用户自定义后的权威来源。 `Mod` 表示 macOS 的 `Cmd`，Windows/Linux 的 `Ctrl`。 ## 常用默认快捷键 ### SQL 编辑器 | 默认键 | 操作 | | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | `Mod+Enter` | 执行当前语句或选中 SQL | | `Mod+\` | 在新的结果标签页执行 | | `Shift+Mod+F` | 格式化 SQL | | `Mod+/` | 切换行注释 | | `Mod+S` | 保存 SQL | | `Tab` | 接受补全 | | `Shift+Tab` | 减少缩进 | | `Mod+D` | 复制当前行 | | `Shift+Mod+K` | 删除当前行 | | `Alt+↑` / `Alt+↓` | 上下移动当前行 | | `Ctrl+↑` / `Ctrl+↓`（Windows/Linux），`Ctrl+Alt+↑` / `Ctrl+Alt+↓`（macOS） | 编辑器上下滚动一行，不移动光标或选区 | | `Shift+Alt+↑` / `Shift+Alt+↓` | 向上/下复制当前行 | | `Mod+Shift+U` | 切换选中内容大小写（首次默认转为大写） | | `Shift+Alt+U` / `Shift+Alt+L` | 选中内容转大写/小写 | | `Shift+Alt+C` | 切换选中内容的命名风格（camelCase → PascalCase → snake\_case → SCREAMING\_SNAKE\_CASE → kebab-case） | | `Mod+.` | 折叠或展开代码块 | | `Mod+Shift+A` | 把选中内容发送给 AI | 当前 registry 没有“执行全部 SQL”的默认 action。需要运行多条语句时，选中范围执行或使用编辑器提供的多语句执行入口，不要依赖旧文档中的 `Ctrl/Cmd+Shift+Enter`。 ### 表格和数据 | 默认键 | 操作 | | -------- | ------- | | `F5` | 刷新当前数据 | | `Mod+D` | 复制当前行 | | `Delete` | 标记删除当前行 | | `Tab` | 切换转置视图 | 普通复制/粘贴仍遵循平台标准按键，但“复制当前行”“删除当前行”和“切换转置”是 DBX 可配置 action。 「聚焦 WHERE 条件输入框」默认不绑定快捷键。可在 **设置 → 快捷键 → 数据表格** 中自行设置，按下已配置的快捷键后将光标移至当前表数据标签页的 WHERE 输入框，保留现有条件且不执行查询。WHERE 输入框不可用时不生效。 网格还有两个固定手势（不可自定义）：光标停在当前显示的最后一行时按 `↓` 会在结果末尾追加一行（与「新增行」按钮不同，按钮跟随「插入位置」设置）；编辑器内的 `Esc` 只取消本次输入，焦点回到网格后按 `Esc` 会撤掉未填写过的新增行，否则把当前单元格回退为原值。详见[数据表格](/cn/docs/data-grid)。 ### 全局和导航 | 默认键 | 操作 | | ----------------------------- | -------------- | | `Mod+T` | 新建查询 | | `Mod+P` | 快速打开 | | `Mod+W` | 关闭当前标签页 | | `Ctrl+Alt+←` / `Ctrl+Alt+→` | 后退/前进标签页访问历史 | | `Shift+Mod+[` / `Shift+Mod+]` | 左侧/右侧标签页 | | `Mod+1` … `Mod+9` | 切换到指定标签页 | | `Mod+B` | 显示或隐藏侧边栏 | | `Mod+=` / `Mod+-` / `Mod+0` | 放大、缩小、重置 UI 缩放 | 侧边栏还提供可配置的复制、粘贴、编辑连接和按住修饰键在新标签页打开数据等 action。 ## 快速打开 按 `Mod+P` 搜索当前工作区中的连接、数据库、Schema、表、视图和保存的 SQL。结果来自已加载和可搜索的对象；大型连接尚未加载元数据时，先展开或刷新对应节点。 ## 自定义和冲突 1. 打开 **设置 → 快捷键** 2. 选择 action 并进入录制 3. 按下新组合键；也可以清空不需要的绑定 4. 处理冲突后保存 DBX 会检测同一作用域中的冲突。编辑器、表格、搜索、侧边栏和全局 action 具有不同作用域，但浏览器、操作系统、输入法或辅助功能仍可能先占用按键。 快捷键页签的搜索框还支持**键盘录入**：点击搜索框右侧的键盘图标，直接按下组合键即可筛出绑定该组合的 action；跨作用域共用同一组合的 action 会一并列出，排查冲突时不必先知道组合键的写法。录入期间按下的组合键不会触发真实命令；`Esc` 退出录入，`Backspace` 清空已录入的组合。也可以在搜索框里直接输入文本形式，`Ctrl+T` 与 `Ctrl + T` 都能命中。 **被系统抢占的组合无法录入**：`Alt+F4`、`Win` 键、`Ctrl+Alt+Del`、macOS 的 `⌘Tab` 这类按键先被操作系统或窗口管理器处理，DBX 收不到，录制时不会有任何结果（也不是录入失败）。这类组合即使手工配置了绑定也不会触发，排查时请改用文本搜索。 Web 形态还要多一层：浏览器自己保留的按键（`Ctrl+W` / `Ctrl+Shift+W` / `Ctrl+T` / `Ctrl+N` 等，macOS 的 `⌘W`）由浏览器直接处理，页面拿不到事件。桌面形态没有这条限制——`Ctrl+Shift+W` 是「关闭窗口」的默认键，`Ctrl+W` 是「关闭标签页」的默认键，都可以正常录入。 Windows/Linux 上 `Ctrl+Alt` 可能被键盘布局当作 AltGr；DBX 对相关组合采取更保守的匹配。macOS 的 Option+字母可能产生变形字符，DBX 会在安全情况下使用物理键位回退。 ## 相关页面 ### [SQL 编辑器](/cn/docs/query-editor) 了解执行范围、多结果标签页和编辑器行为。 ### [SQL 快捷操作](/cn/docs/sql-quick-actions) 选中表名或将光标放在表名上后，执行内置或自定义 SQL。 ### [SQL 格式化](/cn/docs/sql-formatter) 配置格式化规则和格式化设置编辑器快捷键。 --- # MCP 集成 > 通过 Model Context Protocol 让 AI 编程助手在 DBX 权限策略内读取元数据、查询数据和使用有状态会话。 Source: https://dbxio.com/cn/docs/mcp Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/mcp. 把 AI 助手连接到 DBX，即可查看数据库结构、查询数据，并在 DBX 中打开结果。 ## 什么是 MCP？ MCP（Model Context Protocol）是让 AI 客户端调用外部工具的开放协议。DBX MCP 可以让 AI 助手使用 DBX 中已经配置好的数据库连接。 ```text AI 助手 → DBX MCP → 你的数据库 → 返回结果 ↘ DBX 桌面端（打开或展示结果） ``` ## 原生安装（推荐） 无需 Node.js。macOS 或 Linux 执行： ```bash curl -fsSL https://dbxio.com/install-mcp | sh ``` Windows 在 PowerShell 中执行： ```powershell irm https://dbxio.com/install-mcp.ps1 | iex ``` 脚本校验下载内容，将 `dbx-mcp` 安装到 `~/.dbx/bin`，并打印 Claude Code、Cursor、Codex、ZCode 和通用 MCP 配置。请使用输出中**展开后的可执行文件绝对路径**，不要填写 `~` 或裸命令 `dbx-mcp`：GUI 客户端不一定继承 shell 的 PATH。已有的 `DBX_DATA_DIR` 等环境配置继续有效。DBX 桌面设置优先使用发现的原生二进制，找不到时保留原有 npm 启动方式。 重跑同一安装命令即可升级；版本相同时提示 `already up to date`。版本优先读取 `dbx-mcp --version`，旧版二进制不支持时回退读取 `~/.dbx/bin/.dbx-mcp-version`。断网时安装失败但不会替换现有二进制。下载源依次为 npmjs、npmmirror、GitHub Releases；内容校验不匹配时立即拒绝安装。 macOS 和 Linux 也可以使用 Homebrew： ```bash brew install t8y2/tap/dbx-mcp brew upgrade t8y2/tap/dbx-mcp ``` Homebrew 安装后，客户端配置使用 `echo "$(brew --prefix)/bin/dbx-mcp"` 输出的绝对路径。此通道只安装 MCP 服务器，不安装独立的 `dbx` CLI。 npm/npx 通道保持兼容。DBX 桌面端现在默认安装独立原生服务，并为已有 npm 用户显示推荐的原生迁移入口。迁移会保留 npm 包作为兜底，也不会自动改写外部客户端文件：请将启动命令替换为页面生成的原生绝对路径，删除 Node/npx 参数并保留 `env`。仍可选择执行 `npm rm -g @dbx-app/mcp-server` 清理旧包。桌面端可以更新和卸载当前的独立原生或 Homebrew 安装；卸载独立原生版本后，保留的 npm 安装会重新成为兜底。 macOS 上，Shell 安装器还会在替换二进制前验证官方 Developer ID 签名及稳定的 `com.dbx.app.mcp` designated requirement。未签名、临时签名、签名身份不符或绑定单次构建哈希的安装包会被拒绝，已安装的程序和版本标记保持不变。此校验针对 Shell 安装器，Homebrew 和 npm 保持各自的安装流程。 ## npm 快速开始 ### 安装 MCP Server ```bash npm install -g @dbx-app/mcp-server ``` npm 会自动安装当前平台需要的依赖。不要使用 `--no-optional`。 ### 配置 AI 助手 在项目目录创建 `.mcp.json`： ```json { "mcpServers": { "dbx": { "command": "npx", "args": ["-y", "@dbx-app/mcp-server"] } } } ``` 如果使用全局安装，可将 `command` 改为 `dbx-mcp-server`。连接 allowlist 和执行权限统一在 **DBX 设置 → MCP** 中管理，常规客户端配置不需要权限环境变量。Windows 便携版请将 `DBX_DATA_DIR` 设置为 `DBX.exe` 同级的 `data` 目录。 ### 开始使用 在 AI 助手中直接使用自然语言： * "列出我的数据库连接" * "查看 local-pg 上有哪些表" * "查看 users 表的结构" * "查询最近 7 天的订单数量" * "打开 orders 表"（需要 DBX 运行中） ## 支持的 AI 助手 | AI 助手 | 配置方式 | | ----------------- | ----------------------------------------------- | | Claude Code | `.mcp.json` | | Cursor | `.cursor/mcp.json` | | Windsurf | MCP 配置 | | VS Code + Copilot | MCP 扩展/配置 | | DeepSeek Harness | `$DSH_HOME/profiles//cordis.patch.yml` | ### DeepSeek Harness DeepSeek Harness 通过 Cordis 插件条目加载 MCP Server，不读取 `mcpServers` JSON。安装 `@dbx-app/mcp-server` 后，为 `web` profile 将以下条目合并到 `$DSH_HOME/profiles/web/cordis.patch.yml`：未设置 `DSH_HOME` 时默认为 `~/.dsh`。 ```yaml - insert: - id: mcp-dbx name: '@deepseek-ai/dsh-mcp-client' config: serverName: dbx transport: stdio command: dbx-mcp-server ``` 保留最外层的 `- insert:`，不要覆盖文件中已有的 patch 条目。使用其他 DSH profile 时，将路径中的 `web` 替换为对应 profile 名称。DSH 进程的 `PATH` 必须能找到 `dbx-mcp-server`；必要时请改用可执行文件的绝对路径。 运行 `dsh web --dump-config` 检查组合后的配置，再重启 DSH 或等待热加载应用该 patch。模型侧工具名为 `mcp__dbx__`。请保持 `serverName: dbx` 稳定，避免工具名和权限规则发生变化。连接访问范围和执行模式仍统一在 **DBX 设置 → MCP** 中管理。 ## 工具列表 DBX MCP 当前提供以下工具（具体可用工具取决于构建功能及权限设置）： | 工具 | 说明 | | ------------------------------ | -------------------------------------------------------------------- | | `dbx_list_connections` | 列出当前 MCP 会话可见的连接，包括已保存的备注 | | `dbx_list_databases` | 列出连接中可通过 MCP 访问的数据库，并遵守该连接的数据库范围 | | `dbx_add_connection` | 添加连接到 DBX 存储 | | `dbx_duplicate_connection` | 复制一个连接及其完整配置 | | `dbx_remove_connection` | 从 DBX 存储删除连接 | | `dbx_list_tables` | 列出表、视图或集合 | | `dbx_describe_table` | 返回列定义和表元数据 | | `dbx_list_routines` | 列出 Schema 中的存储过程和函数，支持可选的 `routine_type` 过滤（PROCEDURE 或 FUNCTION） | | `dbx_get_routine_source` | 按名称返回存储过程或函数的源码，重载场景可用可选的 `signature` 区分 | | `dbx_get_schema_context` | 返回适合 AI 使用的紧凑 Schema 上下文 | | `dbx_execute_query` | 执行 SQL 或支持的 MongoDB shell 命令，默认返回 100 行，可用 `max_rows` 参数提高到最多 1000 行 | | `dbx_execute_batch` | 一次执行包含多条语句的 SQL 脚本，按语句返回结果（多语句脚本搭配 `use_transaction` 时返回单个合并结果） | | `dbx_open_session` | 为 SQL 连接打开固定后端连接的有状态查询会话 | | `dbx_begin_transaction` | 在已启用事务的原生 MySQL 会话上开始事务 | | `dbx_commit_transaction` | 在 MySQL 确认 `COMMIT` 后提交当前会话事务 | | `dbx_rollback_transaction` | 回滚当前会话事务 | | `dbx_close_session` | 关闭会话并释放固定连接资源 | | `dbx_execute_redis_command` | 执行 Redis 命令 | | `dbx_salesforce_current_user` | 显示连接背后的 Salesforce 用户与组织，包括简档是否具有 “Modify All Data” | | `dbx_salesforce_prepare_write` | 准备一条 Salesforce 记录写入，返回摘要和一次性确认令牌 | | `dbx_salesforce_apply_write` | 使用确认令牌应用已准备的 Salesforce 写入 | | `dbx_peek_messages` | 读取 Kafka 消息，不提交消费位点 | | `dbx_send_message` | 向支持的消息队列 Topic 或队列发送消息 | | `dbx_open_table` | 在运行中的 DBX 桌面端打开表 | | `dbx_execute_and_show` | 执行查询并在 DBX 中展示结果 | `dbx_list_connections` 和 `dbx://connections` 会返回已保存的连接备注，不受侧边栏显示开关影响。可访问该连接的 MCP 客户端也能看到备注，请勿在备注中保存密码或其他敏感信息。 `dbx_execute_query` 返回行数： * `max_rows`：取值 1–1000，默认 100。越界值会被夹取到范围内，而不是报错。仅对 SQL 连接生效——MongoDB shell 命令始终最多返回 100 行，路由到批量执行器的多语句脚本每条语句最多返回 100 行。 启用连接作用域后，修改连接和桌面 UI 工具会被隐藏。 ## 插件工具 实现了 `mcp/tools` 桥接协议的 DBX 插件 sidecar，其工具可由 `dbx` MCP 服务器合并进 `tools/list`，无需在客户端逐个配置插件的 `--mcp` 进程。该机制按作者声明加入：只有 manifest 中声明了 `mcp` 贡献且 `external_tools: true` 的插件（SSH、Files、Kafka、LDAP 等均可）才会暴露工具： * 工具名为 `dbx_<插件前缀>__<工具名>`，前缀取插件 id 的最后一段：`io.dbx.ssh` → `dbx_ssh__sftp_list_dir`，`io.dbx.kafka` → `dbx_kafka__kafka_topics_list`； * 连接由宿主绑定：工具 schema 中的 `connectionId` / `connectionName` 会被移除，改由可选的 `dbx_connection` 参数选择该插件**已保存且被 MCP 设置放行**的连接；只有一个可用连接时省略该参数即可自动绑定；凭据由宿主从保存的连接生成 lifecycle 注入，永不经过模型或客户端； * 作用域会话（`DBX_MCP_SCOPE_*`）与全局 MCP 设置（工具 allowlist、连接 allowlist）同样约束插件工具； * 工具白名单按精确名称匹配：启用插件工具后，请把要暴露的 `dbx_<前缀>__<工具名>` 逐个加入白名单（或清空白名单以全部放行）； * Web / Docker 后端不提供插件工具。 ### 懒发现（`DBX_MCP_PLUGIN_TOOLS`） 插件较多时，平铺的 `tools/list` 会在参数 schema 上消耗大量上下文。设置 `DBX_MCP_PLUGIN_TOOLS=lazy` 只暴露三个元工具——`dbx_plugin_list`（可过滤的插件目录）、`dbx_plugin_tools`（按**插件 id** 查看某插件的工具与 schema）、`dbx_plugin_call`（按插件 id + 工具名调用）——schema 在需要时才进入上下文。`both` 同时平铺与元工具。默认仍为 `flat`。 ## Resources 支持 MCP Resources 的客户端可以读取连接目录，并通过模板获取数据库元数据： | Resource URI | 说明 | | ------------------------------------------------------------------------ | ---------------------- | | `dbx://connections` | 当前 MCP 范围内可见的连接 | | `dbx://connections/{connection_id}/databases` | 指定连接中可见的数据库 | | `dbx://connections/{connection_id}/tables{?database,schema}` | 可选数据库或 Schema 中的表和视图 | | `dbx://connections/{connection_id}/table-schema{?database,schema,table}` | 指定表的字段定义；`table` 为必填参数 | Resource 的发现和读取会复用对应 Tool 的白名单，以及连接、分组、数据库和运行时范围限制。查询参数值必须进行 URI 编码。SQL 执行和所有可写操作仍只通过 Tool 提供。 ## 读取 Kafka 消息 包含 `mq-admin` 的构建在本地和 Web 模式下均提供 `dbx_peek_messages`。通过 `connection_id` 或 `connection_name` 选择已保存的 Kafka 连接，并指定 `topic`。工具遵守 MCP 连接范围及工具白名单，允许读取只读连接和生产连接，不提交消费位点。 ```json { "connection_name": "Kafka", "topic": "events", "count": 20, "start_position": "offset", "partition": 0, "offset": 120 } ``` * `count`：1–100，默认 20。 * `start_position`：`latest`（默认）、`earliest` 或 `offset`。仅 `offset` 模式必须且允许传入非负 `offset`。 * `partition`：可选的非负分区号。不传时跨分区读取；offset 模式下从各分区的该位点开始读取。 * JSON 结果包含 `messages`，保留 base64 消息体、可无损解码时的 UTF-8 预览、消息 ID 和元数据。`incomplete` 表示读取达到超时或扫描上限；`outputTruncated` 表示为满足 256 KiB 消息输出预算而省略了整条消息。如果首条消息过大，可能返回空列表并标记 `outputTruncated: true`，不会静默截断消息体。 该工具读取有限条消息快照，不提供持续订阅或全 Topic 文本搜索。其他消息队列类型会被拒绝。 ## 批量 SQL 执行 `dbx_execute_batch` 在单次调用内执行包含多条语句的 SQL 脚本。默认（自动提交）模式下按语句返回结果，因此调用方可以清楚看到哪条失败、每条影响多少行、各自返回什么；使用 `use_transaction` 且脚本包含多条语句时，只返回一个合并的事务结果。 * 脚本通过方言感知的解析器拆分成独立语句，字符串、注释、存储过程中出现分号也不会破坏批次。 * 默认遇到第一条失败语句即停止；传入 `continue_on_error` 可让批内在单条语句出错后继续执行（连接级错误仍会终止）。 * 传入 `use_transaction` 可把多条语句放入同一个 `BEGIN … COMMIT`，使整批要么全部成功要么回滚；这要求脚本包含多条语句（单语句脚本会忽略该选项，按普通自动提交执行）。此模式下调用只返回一个合并结果（而非逐语句结果），且 `use_transaction` 不能与 `session_id` 同时使用——事务批处理运行在池连接上，会丢弃会话状态；也不能与 `continue_on_error` 同时使用——事务批处理在第一条失败时即回滚并停止。当当前后端无法提供可回滚事务时，DBX 会拒绝该选项。MySQL 系连接对含 DDL 的脚本会拒绝 `use_transaction`，因为 MySQL 的 DDL 会隐式提交、无法回滚。 * SQL 策略（只读、危险 SQL、生产保护、切换数据库）作为整体在匹配前重新检查，与 `dbx_execute_query` 一致；只要批内含一条写入或 DDL，在只读策略下整次调用都会被拒绝。 * 每个批次在其完整执行期间都会使用独占连接，因此临时表和 `SET` 状态可在批内语句之间保留。若要跨多次 MCP 调用保留这些状态，先用 `dbx_open_session` 打开会话，再传入其 `session_id`。 * Redis 和 MongoDB 连接不支持 `dbx_execute_batch`。 ## 有状态查询会话 普通 `dbx_execute_query` 调用彼此独立。需要保持数据库 Session 状态时，先调用 `dbx_open_session`，再把返回的 `sessionId` 传给后续 `dbx_execute_query` 或 `dbx_execute_batch`： * `USE` 或数据库上下文切换 * 临时表 * Session 变量和设置 * 需要固定连接的显式事务或多步诊断 会话只支持 SQL 连接，并固定到一个连接和数据库。未知、已关闭或过期的 `sessionId` 会失败，不会静默退化为普通查询。完成后应调用 `dbx_close_session`；会话默认空闲 30 分钟后回收，同时最多允许 32 个并发会话。在 MCP 宿主进程设置 `DBX_SESSION_IDLE_TTL_SECS=43200` 可将空闲时间延长为 12 小时，事务专属连接也使用此配置。值必须为正整数秒；未设置、非法值、零、负数或无法表示的时长均保留默认 1800 秒。修改后需重启宿主。使用嵌入式 DBX Web MCP 时，在 Web 服务端设置；使用独立启动器时，在启动器环境中设置。 有状态会话不会放宽 SQL 策略。 `USE` 只有在会话中才有意义，但写入、DDL、生产保护、连接只读和数据库权限仍按每次请求重新检查。 ### 原生 MySQL 显式事务 调用 `dbx_open_session` 时传入 `enable_transactions: true`，DBX 会立即保留一条物理原生 MySQL 连接。随后依次调用 `dbx_begin_transaction`、带该 `session_id` 的一个或多个 `dbx_execute_query`/`dbx_execute_batch`，最后调用 `dbx_commit_transaction` 或 `dbx_rollback_transaction`。事务前后的查询仍使用同一条受管连接。`use_transaction` 仍不能与 `session_id` 同时使用；它是前文所述的独立原子批处理功能。 该 opt-in 模式仅支持本地原生 MySQL 连接。DBX Web/`DBX_WEB_URL`、外部驱动 profile、兼容引擎及其他数据库类型会返回 `TRANSACTION_UNSUPPORTED`，不会静默退化为自动提交。事务会话每次操作只接受一条经过解析的 `SELECT`（含锁定读）、`INSERT`、`UPDATE`、`DELETE` 或 `REPLACE`；原始事务控制、DDL/临时 DDL、`CALL`、`LOAD`、表锁、`SET`、`USE`、XA、文件/输出子句、可执行注释、优化器 hint 及多语句均会被拒绝。完整批次持有同一个操作槽位，并为每条语句返回执行后的事务状态。 响应包含 `transaction_state`（`idle`、`active` 或 `unknown`），并在适用时包含 `transaction_outcome`（`committed`、`rolled_back` 或 `unknown`）。普通 MySQL 语句错误可能仍让事务保持 active；DBX 会在同一连接上重新探测服务器状态后再返回。超时、取消、传输故障或丢失 `COMMIT` 确认会把结果永久标为 `unknown`，禁止该会话继续执行 SQL，并在不重放语句或 `COMMIT` 的前提下销毁连接。显式正值的连接查询超时同样用于事务操作；当连接配置为“无限制”（`0`）时，事务 owner 仍使用默认 300 秒操作上限，确保 busy 操作保持有界。关闭、过期和服务退出会对状态已知的 active 事务执行有界回滚，然后销毁连接。会话的回收途径是 `dbx_close_session`、空闲超时或 MCP 服务退出。HTTP 传输层不持有任何会话，因此没有传输会话可供 `DELETE` 结束、也不会因空闲而丢失；承载状态的只有 `session_id` 句柄本身。 回滚保证依赖 InnoDB 等事务型存储。触发器、存储函数、非事务表及外部副作用可能产生 MySQL 无法回滚的效果。DBX 会在排队完成后重新检查当前连接/数据库范围、工具 allowlist、只读与生产保护以及已确认 SQL。即使写权限被撤销，仍允许原会话执行回滚和关闭以完成清理。 ## Salesforce SOQL 与 DML Salesforce 连接使用 SOQL 而非 SQL，DBX 据此调整了 MCP 的行为： * `dbx_list_tables` 列出组织中的对象，`dbx_describe_table` 列出对象字段，`dbx_execute_query` 执行 SOQL（例如 `SELECT Id, Name FROM Account LIMIT 10`）。 * `dbx_list_databases` 会说明一个 Salesforce 组织就是一个作用域，而不会虚构数据库。 * `dbx_execute_batch` 与 `dbx_open_session` 会被拒绝：SOQL 只读，不存在需要批处理的多语句脚本；每次调用都是无状态 REST 请求，没有可固定的会话，也没有可开启的事务。 * 写入记录永远不会走查询通道。`dbx_execute_query` 会以 `SALESFORCE_DML_REQUIRES_CONFIRMATION` 拒绝写入尝试，因此下面的确认流程无法被绕过。 ### 写入确认 写入分为两次调用，且只有当人看到第一步的摘要后第二步才可能执行： 1. 调用 `dbx_salesforce_prepare_write`，传入 `connection_id`（或 `connection_name`）、`op`（`insert`、`update` 或 `delete`）、`object`（API 名称，如 `Account` 或 `Invoice__c`）；`update`/`delete` 需要记录 `id`，`insert`/`update` 需要 `fields`。此时不会向 Salesforce 发送任何请求。 2. 把返回的摘要展示给用户：操作、对象、记录 Id、每个字段值、连接，以及该变更所归属的身份。 3. 调用 `dbx_salesforce_apply_write`，传入第 1 步返回的 `confirm_token`。 令牌只能使用一次，签发 5 分钟后过期，并与那一条语句绑定——写入内容变了就必须重新准备。重放、过期或从未签发的令牌会以 `CONFIRM_TOKEN_INVALID` 失败。DBX 在应用阶段会重新检查连接范围、工具白名单、只读与生产保护以及 DML 开关，因此两次调用之间撤销权限会立即生效。 Salesforce 写入不是事务性的。 `dbx_salesforce_apply_write` 返回后，组织中的记录已经改变，DBX 无法回滚。每次调用只影响一条记录： `upsert` 、批量与 composite 写入会在准备阶段以 `SALESFORCE_DML_INVALID` 拒绝。准备写入需要 **设置 → MCP** 中该连接的 **允许 DML** 开关，它默认关闭，未开启时返回 `SALESFORCE_DML_DISABLED` ；执行模式为只读时该开关一律无效。 ### 写入归属的身份 `dbx_salesforce_current_user` 返回当前连接用户、简档、组织显示名，以及该简档是否具有 **Modify All Data**——这个标志决定字段级安全和记录共享规则是否生效。准备写入前先调用它，也可以用它区分权限失败与记录 Id 错误。`dbx_salesforce_prepare_write` 的摘要中包含同样的身份信息；若查询失败，摘要会写明身份未知并仍然完成准备，把是否应用的决定权留给用户。 ## 数据库访问 ### DBX Desktop 原生 Streamable HTTP Desktop 可以选择直接托管 Streamable HTTP MCP 服务。该服务**默认关闭**；在 **设置 → MCP → HTTP 服务**启用后，默认仅监听 `127.0.0.1:5225/mcp`。监听服务由 Desktop 进程管理，会生成本地 Bearer Token，页面提供可复制的客户端配置；服务异常退出时会由 Desktop 自动重新拉起。 本机 MCP 客户端的接入步骤： 1. 打开 **设置 → MCP → HTTP 服务**，开启 **Streamable HTTP 服务**。除非确实需要让其他设备访问，否则保持默认本机回环地址。 2. 点击 **保存并应用**。该按钮会保存配置，并根据开关状态启动、重启或停止服务；修改地址、端口或路径时会自动重启服务。 3. 将页面展示的服务地址和 Bearer Token 复制到 MCP 客户端。 不同客户端的字段名称可能不同，但核心配置如下： ```json { "type": "http", "url": "http://127.0.0.1:5225/mcp", "headers": { "Authorization": "Bearer " } } ``` 本机客户端建议保留默认回环监听。绑定到局域网地址时，必须开启 **允许远程访问**，并填写精确的允许 `Host`；浏览器客户端还必须填写精确的 `Origin`。客户端通过非默认端口访问时，允许的 Host 应写成 `host:port`。轮换 Token 会立即使旧凭证失效。 同一个端点同时响应两代 MCP 协议，任何版本的 Agent 都无需特殊配置即可连接： | Agent | 握手方式 | 传输状态 | | ----- | ---------------------------------- | ----------------------------------- | | 旧版客户端 | `initialize`（协议 `2025-11-25` 及更早） | 无状态：响应不返回 `Mcp-Session-Id`，每个请求独立处理 | | 新版客户端 | `server/discover`（协议 `2026-07-28`） | 无状态：每个请求在 `_meta` 中自带协议版本与能力 | 两代客户端都以无状态方式服务，因此端点只接受 `POST`：`GET` 与 `DELETE` 返回 `405 Method Not Allowed`。DBX 不依赖任何 HTTP 层会话，所以客户端无论空闲多久再连接都能正常工作，不会撞上已被服务端回收的会话。 DBX 的有状态会话在两种情况下都可用，因为它是**显式句柄**：`dbx_open_session` 返回的 `session_id` 由 Agent 在后续调用中作为普通工具参数回传。该句柄独立于传输层、有自己的空闲 TTL，负责让固定连接、`USE`/`SET` 状态、临时表或已开启的事务跨请求保持。 ### 本地连接 这是默认模式。MCP 使用 DBX 中保存的连接配置。原生可执行的连接不要求 DBX 桌面端保持运行；需要 Desktop bridge 或已安装 Agent/驱动的连接仍依赖对应运行时。 常见的本地数据库文件路径： | 平台 | 默认路径 | | ------- | -------------------------------------------------- | | macOS | `~/Library/Application Support/com.dbx.app/dbx.db` | | Linux | `~/.local/share/com.dbx.app/dbx.db` | | Windows | `%APPDATA%\com.dbx.app\dbx.db` | `DBX_DATA_DIR` 必须指向包含 `dbx.db` 的目录，而不是数据库文件本身。Windows 便携版通常是 `DBX.exe` 同级的 `data` 目录。 原生 SQL、独立 Redis 和 MongoDB 等路径可以由 MCP 直接执行。SSH、集群、厂商专用、外部驱动以及 Agent/JDBC 连接是否可用，取决于连接配置和本机已安装的 DBX 组件；不要从“DBX 支持该数据库”推断 MCP 原生包已经内置全部运行时。 DuckDB 使用独立的 DBX DuckDB 驱动。通过本地 MCP 查询 DuckDB 前，需要先在 **DBX Driver Manager** 中安装该驱动。MCP 二进制只包含 sidecar 客户端，不会内置 DuckDB 引擎。 ### Agent/JDBC 数据库 Oracle、金仓KingbaseES 和虚谷需要匹配的 DBX 原生 Agent，但不需要 JRE。达梦、DB2、Hive、Trino、Snowflake、SAP HANA 等 JDBC Agent 数据库需要匹配的 Agent、JDBC 驱动和 JRE。请先在 DBX 中安装所需组件，再使用 MCP。 ### DBX Web / Docker 模式 设置 `DBX_WEB_URL` 后，MCP 会使用部署的 DBX Web 后端，而不是读取本机连接。如果 Web 登录启用了密码保护，还要设置 `DBX_WEB_PASSWORD`，值为 Web 登录页使用的密码。 DBX Web 请求遵循标准系统代理环境变量：https 地址读取 `HTTPS_PROXY`/`https_proxy`，http 地址读取 `HTTP_PROXY`/`http_proxy`，`ALL_PROXY`/`all_proxy` 作为兜底，`NO_PROXY`/`no_proxy`（逗号分隔的主机列表，例如 `localhost,127.0.0.1,.internal.example`）作为绕过列表。代理值为空或未设置时直连（不走代理）。支持 HTTP、HTTPS 与 SOCKS5 代理（`http://127.0.0.1:7890` 或 `socks5://127.0.0.1:1080`）；需要认证的代理使用标准 `user:password@host:port` URL 形式，例如 `http://admin:admin123@127.0.0.1:7890`。如需为每次 DBX Web 请求附加自定义请求头（例如网关前的令牌认证），将 `DBX_WEB_HEADERS` 设置为 JSON 对象，键为请求头名称、值为字符串，例如 `{"Authorization":"Bearer "}`。目标为自签名 HTTPS 时，证书验证默认开启：设置 `DBX_WEB_INSECURE_SKIP_VERIFY=1` 可跳过验证，或设置 `DBX_WEB_CA_CERT` 指向 PEM/DER CA 文件以信任私有 CA。同样的变量在 DBX CLI 的 Web 模式下同样生效。 DBX Web 和 Docker 同样需要独立 DuckDB 驱动。首次启动后可通过 Driver Manager 安装；Docker 会把驱动保存到 `/app/data/agents`，挂载 `/app/data` 数据卷后升级容器不会丢失。 ### DBX Web 原生 Streamable HTTP DBX Web 可以直接托管 MCP，复用现有 Web 监听器和 `/mcp` 路径，因此 Docker 和反向代理部署不需要额外暴露第二个端口。单实例、已启用 Web 登录密码的部署可在 **设置 → MCP → HTTP 服务**填写允许的 Host 并启用服务；DBX 自动生成 Bearer Token，使用现有加密 Secret 存储，可在页面复制、轮换或禁用，修改立即对新请求生效。未启用时页面不会把 `/mcp` 显示为可连接地址。无 Web 登录密码时，页面管理的 MCP 不会生效；演示部署禁用 MCP。 部署环境变量仍然优先：配置 `DBX_WEB_MCP_TOKEN` 或 `DBX_WEB_MCP_TOKEN_FILE` 后，页面只读显示状态，不会覆盖部署 Secret。此前启用的页面 Token 仍会保留；移除部署 Token 并重启 Web 后，它会重新生效。将 `DBX_WEB_MCP_ALLOWED_HOSTS` 配置为客户端在 `Host` 请求头中发送的公网访问地址；如有端口映射，必须包含映射后的端口。多实例部署应使用一致的部署 Secret 与白名单，而不是页面管理模式。生产环境请使用 `DBX_WEB_MCP_TOKEN_FILE` 或部署平台的 Secret 管理能力，不要把真实 Token 提交到 Compose 文件中。 例如容器映射为 `4225:4224` 时，MCP 地址为 `http://localhost:4225/mcp`： ```yaml environment: DBX_WEB_MCP_TOKEN: replace-with-a-long-random-secret DBX_WEB_MCP_ALLOWED_HOSTS: localhost:4225 ports: - "4225:4224" ``` 客户端必须携带 `Authorization: Bearer `。浏览器客户端还需要在 `DBX_WEB_MCP_ALLOWED_ORIGINS` 中填写精确 Origin，例如 `https://mcp.example.com`；原生客户端通常不会发送 `Origin` 请求头。若反向代理添加了公网路径前缀，请设置 `DBX_PUBLIC_BASE_PATH=/dbx`，此时原生端点为 `/dbx/mcp`。原生 HTTP 与现有的 `DBX_WEB_URL` stdio 适配方式可以同时使用：两者共享 DBX 连接和 MCP 策略，后者仍适合只支持 stdio 的客户端。 ### 桌面 UI 工具 `dbx_open_table` 和 `dbx_execute_and_show` 要求 DBX 桌面端正在运行，并且在 Web 模式或连接作用域隐藏 UI 工具时不可用。其他工具是否需要 Desktop 取决于该连接是原生执行还是 bridge/Agent 路径。 ## 安全和环境变量 DBX 在 **设置 → MCP** 中保存一份权威策略，并在每次请求时重新读取： | 权限模式 | 允许的操作 | | ---- | --------------------------------------------------------- | | 只读 | 查询和元数据读取 | | 数据读写 | 普通插入、带有效过滤条件的更新/删除、范围明确的 MongoDB 修改和普通 Redis 写入 | | 完全访问 | 额外允许大范围更新/删除、DDL、`TRUNCATE`、MongoDB 破坏性操作和 Redis `FLUSH*` | `WHERE TRUE`、`WHERE 1 = 1`、`_id: {$exists: true}` 或不透明 MongoDB 过滤器仍按高风险处理。连接自身只读、生产库保护、数据库账号权限和 MCP 连接 allowlist 在任何模式下都是权限上限。 对于已暴露给 MCP 的连接，**设置 → MCP** 可以设置连接默认执行权限：继承全局、只读、安全写入或高风险写入。选择指定数据库后，还可为单个数据库设置执行权限。执行权限按范围由小到大回退：**单库设置 → 连接默认 → 全局默认**；例如全局和连接默认均为“数据读写”时，可为单个数据库设置“完全访问”。连接自身只读、生产库保护、数据库范围和数据库账号权限仍是独立的硬性限制，不能被单库设置绕过。 同一页面还可只暴露选定的 MCP 工具。这项限制在服务端的每一次调用中都会强制执行，不只是客户端的展示偏好；即使客户端缓存了旧工具列表，也会在服务端 allowlist 更新后被拒绝。 ### 按顺序配置授权范围 在 **设置 → MCP** 中建议按以下顺序定义最终权限范围： 1. 选择 MCP 可见的是**所有连接**（包括以后新增的连接），还是仅**指定连接**。 2. 为每个已暴露连接选择**全部数据库**、**仅指定数据库**或**不允许访问**。指定数据库名按精确名称匹配；可先调用 `dbx_list_databases` 获取当前允许使用的名称，并为选中的数据库按需设置执行权限。 3. 为每个连接设置默认执行权限。未配置单库覆盖、或选择全部数据库时，该默认值就是连接内数据库的执行权限。 4. 仅选择客户端实际需要的 MCP 工具，再设置全局默认执行权限模式。 执行权限由最具体的设置决定，但已允许的工具仍不能绕过隐藏连接、数据库范围、连接只读、生产库保护或数据库账号本身的权限。请求未被选中数据库时，服务会返回 `DATABASE_OUT_OF_SCOPE`；配置单库执行权限时，跨库 SQL 和 MongoDB 聚合写入会被拒绝，避免绕过数据库级限制。 升级时，未带执行策略版本的已保存连接规则继续使用旧的权限上限语义，不会放大全局权限。只有当前设置页面保存的规则会标记为范围覆盖语义；编辑旧规则时，系统会先固化其实际生效的权限上限，再启用新的覆盖行为。 新版 Server 不允许 `DBX_MCP_ALLOW_WRITES` 或 `DBX_MCP_ALLOW_DANGEROUS_SQL` 放宽 DBX 中央策略。为兼容升级，在中央策略首次保存前，旧配置中的 `DBX_MCP_ALLOW_WRITES=0`（或 `false`）仍会保持 MCP 只读；策略保存后仅以中央策略为准，并忽略旧权限变量。旧连接 scope 变量只能进一步收窄 DBX allowlist。 | 变量 | 用途 | | ------------------------------------------ | ------------------------------------------------------------------------------ | | `DBX_DATA_DIR` | 覆盖本地 DBX 数据目录 | | `DBX_SESSION_IDLE_TTL_SECS` | 有状态会话空闲超时，单位为正整数秒，默认 `1800`。非法值、零、负数或无法表示的时长回退默认值；同样适用于事务专属连接。修改后需重启 MCP 宿主进程。 | | `DBX_WEB_URL` | 使用 DBX Web/Docker 后端 | | `DBX_WEB_PASSWORD` | 登录 DBX Web | | `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` | DBX Web 请求的标准系统代理变量；空值表示不走代理。认证格式 `http://user:pass@host:port` | | `NO_PROXY` | 上述代理的标准绕过列表（逗号分隔主机） | | `DBX_WEB_HEADERS` | DBX Web 请求附加的请求头 JSON 对象，例如 `{"Authorization":"Bearer token"}` | | `DBX_WEB_INSECURE_SKIP_VERIFY` | `1`/`true` 时跳过 TLS 证书验证（用于自签名 DBX Web 后端；默认验证） | | `DBX_WEB_CA_CERT` | DBX Web TLS 验证时信任的 PEM/DER CA 文件 | | `DBX_WEB_MCP_TOKEN` | 使用该 Bearer Token 启用原生 Web Streamable HTTP MCP | | `DBX_WEB_MCP_TOKEN_FILE` | 从文件读取原生 Web MCP Token；不能与 `DBX_WEB_MCP_TOKEN` 同时设置 | | `DBX_WEB_MCP_ALLOWED_HOSTS` | 原生 Web MCP 必填：允许的公网 Host authority，逗号分隔 | | `DBX_WEB_MCP_ALLOWED_ORIGINS` | 原生 Web MCP 的浏览器 Origin allowlist，逗号分隔 | | `DBX_MCP_ALLOW_WRITES` | 仅用于升级兼容：`0`/`false` 使尚未配置的策略保持只读 | | `DBX_MCP_SCOPE_CONNECTION_ID` | 兼容旧配置：限制为一个连接 ID | | `DBX_MCP_SCOPE_CONNECTION_IDS` | 兼容旧配置：限制为多个连接 ID | | `DBX_MCP_SCOPE_CONNECTION_NAME` | 限制为一个连接名称 | | `DBX_MCP_SCOPE_DATABASE` | 限制为一个数据库 | | `DBX_MCP_DEBUG_SQL` | 临时诊断时输出 SQL | ## 常见问题 ### 升级后的凭据访问 独立 macOS MCP 在后台运行时不弹出钥匙串对话框。已有加密密钥被锁定或拒绝访问时，启动会保留 `KEYRING_ACCESS_FAILED`（可能包含在 `SECRET_KEY_UNAVAILABLE` 中），而不是反复要求输入密码。先解锁登录钥匙串；对于旧版绑定构建哈希的授权，在终端对 **MCP 客户端实际使用的同一个官方程序**执行一次： ```bash "$HOME/.dbx/bin/dbx-mcp" --authorize-keychain ``` Homebrew 或 npm 安装需要替换为对应的二进制路径。该命令先验证运行程序的官方签名和稳定 designated requirement，再读取已有 DBX 钥匙串条目；不会打开数据库、启动 MCP 传输、创建或替换密钥、导出密钥，也不会自行改写 ACL。macOS 首次迁移时可能要求确认一次，对已验证的 DBX 程序选择 **始终允许**（不要选 **允许**）。随后命令会用一个全新的非交互进程再读取一次密钥；若授权未被保留，会以 `KEYRING_ACCESS_FAILED` 报错，因此看到成功提示即表示后台启动可用。最后重启 MCP 客户端。已获授权的程序应直接成功。稳定签名使普通正式升级继续沿用授权，但不能绕过签名团队变更或用户撤销权限。 不要将 `--authorize-keychain` 添加到 MCP 客户端的启动参数，它是执行后立即退出的一次性恢复命令。缺失的密钥仍需通过 Desktop 数据安全设置处理，该命令不能恢复丢失的密钥。Windows 和 Linux 不使用此 macOS 命令；应恢复同一系统用户的凭据库访问（或配置的无界面密钥文件），再重启 MCP。凭据库拒绝访问或密钥损坏时，不应自动生成替代加密密钥。 ### npm 没有安装当前平台包 不要使用 `--no-optional` ，重新安装 `@dbx-app/mcp-server` ，并用 `node -p 'process.platform + "-" + process.arch'` 检查平台。Alpine Linux 默认使用 musl，目前不在 Linux 发布包支持范围内。 ### 找不到 dbx.db 将 `DBX_DATA_DIR` 设置为包含 `dbx.db` 的目录。Windows 便携版通常是 `DBX.exe` 旁边的 `data` 目录。 ### 提示 DBX 未运行 只有 `dbx_open_table` 和 `dbx_execute_and_show` 需要桌面端运行；本地查询工具可以在 DBX 关闭时执行。 ### Desktop HTTP 客户端提示 ERR_CONNECTION_REFUSED 进入 **设置 → MCP → HTTP 服务** ，确认服务已开启并点击 **保存并应用** 。客户端应使用页面展示的地址、路径和当前 Bearer Token。默认的 `127.0.0.1` 只接受同一台电脑上的连接。 ### Desktop 提示 HTTP 地址已被占用 已有其他进程监听了所选地址和端口。请在 **设置 → MCP → HTTP 服务** 中改用未被占用的端口，再保存配置以重启服务。不要让两个 DBX Desktop 实例使用相同 HTTP 端点。 ### 请求返回 DATABASE_OUT_OF_SCOPE 该连接虽然已暴露给 MCP，但请求的数据库不在它的 MCP 数据库范围内。请在 **设置 → MCP** 中添加精确的数据库名称，或在合适时将该连接设为全部数据库。指定范围时，应先调用 `dbx_list_databases` ，再使用返回的名称。 ### 之前可见的工具现在被拒绝 该工具已不在 **设置 → MCP** 的选中范围内，或当前权限策略不允许它。修改工具 allowlist 后请刷新 MCP 客户端的工具列表；服务端同样会拒绝缓存的旧工具调用。 ### Docker 或反向代理下 MCP 请求失败 请使用公网访问地址，包括映射后的端口和 `DBX_PUBLIC_BASE_PATH` 前缀。 `DBX_WEB_MCP_ALLOWED_HOSTS` 必须与实际 `Host` authority 精确一致；浏览器客户端还必须在 `DBX_WEB_MCP_ALLOWED_ORIGINS` 中配置精确 Origin。 ### Agent/JDBC 数据库无法启动 在 DBX Driver Manager 中安装或更新匹配的 Agent、JDBC 驱动和 JRE。厂商专有驱动不会随 MCP 原生包发布。 ### DuckDB 连接无法启动 在 DBX Driver Manager 中安装或更新 DuckDB 驱动。本地 MCP、DBX Web 和 Docker 都通过独立驱动运行 DuckDB，不会内置 DuckDB 引擎。 ### 出现 better-sqlite3 或 Node ABI 错误 MCP 不需要 `better-sqlite3` 。请先升级 `@dbx-app/mcp-server` ；如果错误来自 `@dbx-app/cli` ，请按照 CLI 的安装要求处理，因为它们是两个独立的包。 ## 系统要求 * Node.js 18.18.0 或更高版本 * 已安装 DBX，并至少配置一个数据库连接 * Agent/JDBC 数据库需要匹配的 Agent、驱动和 JRE * 使用两个桌面 UI 工具时，需要保持 DBX 桌面端运行 --- # MongoDB 工作台 > 浏览、筛选、编辑和复制 MongoDB 文档，并管理集合、索引和 GridFS。 Source: https://dbxio.com/cn/docs/mongodb Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/mongodb. MongoDB 工作台围绕数据库、Collection、文档、索引和 GridFS 组织，不把文档强制转换成关系型表。它提供表格视图和完整 JSON 视图，并保留 `ObjectId`、日期、长整数等 Extended JSON 类型。 ## 连接与驱动 推荐使用标准 `mongodb://` 或 `mongodb+srv://` 连接字符串，并在 URL 中包含副本集、认证库、TLS 和其他参数。Atlas、Replica Set 和直连部署都使用同一个连接入口。 DBX 优先使用原生 MongoDB 路径。当服务端或认证协议需要旧驱动时，可以选择或自动回退到 `mongodb-legacy` Agent。旧驱动的管理和修改能力可能少于原生驱动。 ## 数据库与 Collection 对象树可以： * 列出数据库、Collection、索引和 GridFS Bucket * 显示 Collection 文档数、大小和其他可获取统计 * 创建、重命名或删除 Collection（原生驱动且连接可写时） * 删除数据库、单个索引或除 `_id_` 外的可删除索引 * 从 Collection 打开文档浏览器或查询编辑器 删除和重命名会显示目标和请求预览，并受只读与生产保护约束。 ## 文档浏览与分页 文档浏览器支持： * 分页读取和估算总数 * 表格视图与完整文档视图 * 顶层和嵌套字段列，例如 `address.city` * 可搜索字段选择器、隐藏列和持久化列布局 * 快速过滤器以及多个字段条件 * 数据库侧排序和 Collection 查询 MongoDB 的总数可能使用估算值。数据持续写入时，翻页过程中的总数和最后一页可能变化。 ## 过滤与命令 可以在文档浏览器中构建字段过滤，也可以在 MongoDB 查询标签中输入 shell 风格命令。日期类型的过滤值除 RFC 3339 外也接受 `2025-04-01 19:46:03` 或 `2025-04-01`，不带时区的文本按本地时区解析。编辑器会根据数据库、Collection、字段、查询运算符、更新运算符、聚合阶段和游标方法提供补全。 常见命令包括： ```javascript db.users.find({ status: "active" }).sort({ createdAt: -1 }) ``` ```javascript db.orders.aggregate([ { $match: { status: "paid" } }, { $group: { _id: "$customerId", total: { $sum: "$amount" } } } ]) ``` `use ` 会切换当前 MongoDB 查询上下文。在 `use ` 之后以及 `db.getSiblingDB("…")` 内部会补全数据库名。 ## 表格编辑 表格视图把常见字段展开成列。支持： * 编辑顶层或嵌套字段 * 新增和删除字段 * 新建、克隆和删除文档 * 复制选中文档为 JSON、Markdown 或 MongoDB Shell 语句 * 排除 `_id` 后复制为新文档模板 * 在保存前查看待执行更新或删除目标 字段结构差异很大的 Collection 更适合使用完整文档视图，避免隐藏字段在表格列中被忽略。 ### 查询结果编辑 当查询标签中只有一条不带投影的 `find` 或 `findOne`、且结果包含 `_id` 时，结果表格可以直接编辑：可以修改字段、选中并删除行，保存前查看将要执行的 `updateOne` 和 `deleteOne` 语句，删除后表格会自动重新加载。结果表格不支持新增行，请使用 `insertOne` 或文档浏览器。聚合、带投影的查询以及多条命令的脚本保持只读，因为它们的行无法对应到单个文档。 ## JSON 文档编辑 文档详情可以在字段树和完整 JSON 源码之间切换： * 新建文档时粘贴完整 JSON * 保存前校验 JSON 语法和根对象结构 * 格式化、折叠和复制嵌套对象/数组 * 保留 `$oid`、`$date`、`$numberLong` 等 Extended JSON * 修改 `_id` 时按新标识创建文档，并删除旧文档 * 完整 JSON 保存按整文档替换语义处理 整文档替换会写回完整对象。编辑前确认当前 JSON 包含需要保留的所有字段，尤其是并发修改频繁的 Collection。 ## 索引 在对象树或 Collection 结构中可以查看索引名称、字段、唯一性和其他元数据。原生驱动支持时，可以删除单个索引、批量删除可删除索引，或从结构入口管理索引。 MongoDB 会保留 `_id_` 索引；分片键等服务端规则也可能阻止删除其他索引。最终结果以服务端响应为准。 ## GridFS GridFS 工作台用于管理 Bucket 和文件： * 浏览、创建和删除 Bucket * 上传、下载、预览和删除文件 * 查看文件名、大小、上传时间、Chunk 和 Metadata * 按字段过滤和排序文件 * 导出文件列表或 Metadata 删除 Bucket 会删除其中的文件和 Chunk。生产环境执行前先确认 Bucket 名称和备份。 ## 导入与导出 Collection 文档提供独立的 CSV/JSON/NDJSON 与 BSON 导入导出，和关系型 Table Import 不是同一条工作流。CSV 每一行生成一个文档，嵌套值保持嵌套，BSON 备份保留原生 BSON 类型。 ### 导入数据 1. 在集合上右键选择「导入数据」。 2. 先明确选择格式，再选择 `.csv`、`.json`、`.ndjson`/`.jsonl`、`.bson` 或 `.bson.gz` 文件。桌面端读取本地路径，Web 端上传到临时文件；更换文件不会覆盖已选择的格式。 3. 对照预览检查数据。文本格式支持编码和类型设置，CSV 可逐列覆盖推断类型；BSON 导入不应用 CSV 文本转换。 4. 确认以追加方式写入。重复 `_id` 会停止导入，已提交的批次不会回滚。 CSV 按 MongoDB Compass：首行表头，嵌套字段用点号路径（`address.city`），数组索引（`tags[0]`、`matrix[0][1]`），ObjectId 写成 24 位十六进制，日期为 ISO-8601，空单元格为 null。导入采样前 1000 行推断列类型；`_id` 的十六进制会还原为 ObjectId，`recognizeObjectIdHex` 可将此规则扩展到其他列。JSON/NDJSON 使用 Extended JSON（`$oid`、`$date`）。全部按字符串会把每个单元格当文本。 CSV 类型保真：`Double` 导出再导入会变为 `Decimal128`（十进制文本无损）。非 `_id` 的 ObjectId 字段会往返为 String，除非打开 `recognizeObjectIdHex`。小的 `Int64` 可能收窄为 `Int32`；ISO 日期格式的字符串会变为 `DateTime`。Extended JSON 类型（`$binary`、`$regularExpression`、`$timestamp`、`$minKey`、`$maxKey`、`$code`）通过 JSON 文本单元格往返。空数组 `[]` 和空对象 `{}` 往返正确。 集合导入限制：只支持追加（无清空或 upsert），CSV 导出从前 10000 个文档发现字段（之后的字段会被静默丢弃；变化 schema 请改用 NDJSON 或 BSON），无 JSON 数组导出格式，不支持 Excel/GridFS 导入，失败批次不会自动重试。集合级 BSON 导入只恢复文档，不恢复配套元数据和索引。 ### 导出数据 * 在集合上右键选择「导出数据」，再选 CSV、NDJSON、BSON 或 Gzip BSON，会像表导出一样直接打开保存文件对话框。 * CSV 嵌套对象写为点号列（`address.city`），数组写为索引列（`tags[0]`、`tags[1]`）。NDJSON 每行一个规范 Extended JSON 文档。 * 字段数超过 256 的 Collection 请改用 NDJSON 或 BSON。 ### 数据库备份与恢复 在数据库节点右键选择「备份数据库」或「恢复数据库」。数据库备份包含选中集合、集合选项、索引和视图。原生驱动和 `mongodb-legacy` Agent 均支持；Agent 路径需要较新的 Agent 版本（支持 find 游标），以保证 BSON 类型在传输中不丢失。 * 桌面端支持官方目录布局与 MongoDB archive 格式，均可使用 gzip。Web 端导出 archive 文件，恢复时支持 archive 或上传目录。 * 目录备份包含 `<数据库>/<集合>.bson` 和 `.metadata.json`，或对应的 `.gz` 文件。MongoDB archive 是独立的流式格式，不是 ZIP 或 tar。 * 格式与 gzip 选项需明确选择。目录恢复的「读取备份」只读取清单和元数据；确认源库、目标库和集合后，才上传选中的数据文件。 * 恢复按单遍流式读取和写入进行。可选的 `objcheck` 默认关闭，开启后在同一遍读取中逐文档校验；BSON 边界、gzip 完整性和 archive 校验和检查始终保留。 * 默认追加写入。「恢复前删除选中的目标同名集合」只删除并重建这些集合。已有 `_id` 可能导致 `E11000`；失败或取消不会回滚此前的写入。 * Web 上传复用服务端 `DBX_MAX_UPLOAD_MB` 配置。桌面端直接读取本地文件，无需 HTTP 上传。 上述格式可与官方 `mongodump`/`mongorestore` 对支持的集合双向互通。本流程不提供 oplog 回放、时间点一致性保证、UUID 保留，也不处理内部数据库、时间序列集合和加密集合；这些场景请使用官方工具。 如果只需要当前可见选择，仍可从表格复制当前文档、选中文档或字段值为普通 JSON 或 Extended JSON。 ## 安全与兼容边界 * 只读连接会阻止文档、字段、索引、Collection、数据库和 GridFS 修改 * 生产环境保护会在可识别写入前要求确认 * MCP“数据读写”只允许范围明确的 MongoDB 修改；不透明或近似全量过滤按高风险处理 * 旧版 Agent 可能不支持 Collection/索引管理等原生能力 * Atlas 权限、认证库、TLS 和 IP allowlist 都由 MongoDB 服务端决定 * 分页总数可能为估算值，不能作为强一致统计 ### [生产写入保护](/cn/docs/production-safety) 了解 MongoDB 过滤范围、只读连接和 MCP 策略。 ### [连接与驱动](/cn/docs/driver-management) 管理原生与 legacy Agent，并排查驱动启动问题。 ### [专项工作台](/cn/docs/specialized-workspaces) 查看 Redis、搜索、向量、HBase、消息队列和配置中心。 --- # 对象浏览器 > 使用列表或网格集中查看数据库对象、统计信息、源码和批量操作。 Source: https://dbxio.com/cn/docs/object-browser Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/object-browser. 对象浏览器把当前数据库或 Schema 中的对象集中到一个可搜索的列表/网格中。它适合对象数量很多、需要按类型和元数据筛选，或需要批量处理多个对象的场景。 ## 适合的场景 * 在一个页面查看大量表、视图、过程、函数、序列和其他对象 * 按名称、类型、Schema、注释或统计信息筛选 * 比较表大小、行数、创建/更新时间等驱动可提供的信息 * 多选对象后执行打开、复制、导出、删除或其他批量操作 * 在不展开深层对象树的情况下快速查看 DDL 或源码 ## 打开方式 从连接、数据库或 Schema 的上下文菜单打开**对象浏览器**。DBX 会根据当前节点确定 Catalog、数据库和 Schema 范围。 对象浏览器可以作为主标签页或侧边面板打开。侧边面板适合一边查看对象列表，一边保留当前查询或数据标签。 ## 视图与筛选 | 功能 | 说明 | | ------ | --------------------------- | | 列表视图 | 适合查看名称、类型、Schema、注释、行数和大小等列 | | 网格视图 | 适合快速扫描对象卡片和主要摘要 | | 对象类型筛选 | 默认优先显示表，也可以切换视图、例程和其他类型 | | 搜索 | 按对象名称、Schema、类型和部分元数据过滤 | | 列调整 | 调整列宽、显示列和滚动位置；视口状态可以保留 | 统计列只在驱动能够可靠读取时显示。大型数据库读取行数或大小可能有额外开销，必要时关闭不需要的统计信息。 ## 对象操作 单击或双击对象可以按类型打开： * 表和视图数据 * 表结构、字段、索引、外键、触发器和 DDL * 视图、过程、函数、触发器等对象源码 * 数据库专属管理界面 上下文菜单还可以提供： * 复制名称、限定名称或 DDL * 生成查询 SQL * 导入、导出、传输和结构相关入口 * 打开 ER 图、字段血缘或 Schema 对比 * 重命名、清空、删除或管理对象 具体操作由数据库 capability、连接只读状态和当前权限决定。 ## 多选与批量操作 对象浏览器支持复选框多选。批量操作可能包括： * 打开或复制多个对象名称 * 批量导出或生成 SQL * 删除、清空或截断所选表 * 删除所选索引 * 对 PostgreSQL 等数据库使用带 `CASCADE` 的批量对象操作 批量删除、清空和截断可能影响大量对象。生产环境先确认所选范围、生成 SQL、备份和依赖关系。 ## DDL 与源码 * **查看 DDL**优先读取数据库或驱动提供的定义 * **对象源码**用于视图、过程、函数、触发器和其他可编辑对象 * 源码视图支持搜索；数据库和对象允许时，可以打开到编辑器修改 * 保存源码或执行 DDL 前会进入只读、生产保护和危险操作检查 DBX 显示的是当前驱动能获取到的定义。格式、是否包含权限/注释/存储属性，以及能否直接编辑，都会因数据库而异。 ## 与对象树的区别 | 对象树 | 对象浏览器 | | ------------- | --------------- | | 适合层级导航和固定常用对象 | 适合集中筛选和比较大量同级对象 | | 展开后查看字段和子节点 | 通过列、卡片和侧面板查看摘要 | | 强调上下文菜单和拖拽 | 强调搜索、多选和批量操作 | 两者共享对象身份和元数据。可以从对象浏览器打开对象，再回到对象树定位对应节点。 ## 功能边界 * 不同数据库公开的对象类型和统计列不同 * 行数和大小可能是估算值或缓存值 * 系统对象是否显示取决于可见 Schema 和系统 Schema 设置 * 只读连接仍可查看对象、DDL 和源码，但修改入口会被禁用或拒绝 * 大量对象首次加载时，驱动可能分批读取元数据 ### [对象树](/cn/docs/schema-browser) 使用层级导航、固定、拖拽和数据库专属上下文菜单。 ### [表结构](/cn/docs/table-structure) 可视化编辑字段和索引并预览 DDL。 ### [字段血缘](/cn/docs/field-lineage) 从外键、视图和历史 SQL 中追踪字段关系。 --- # 开发和提交 DBX 插件 > 从 CLI、Manifest、Workbench 和 Sidecar 开始开发 DBX 插件，完成本地调试、打包、自动上架和官方签名发布。 Source: https://dbxio.com/cn/docs/plugin-development Language: zh-CN Relative links resolve against https://dbxio.com/cn/docs/plugin-development. DBX 插件是独立安装的 `.dbxp` 包，可以提供连接类型、工作台、文件系统和原生 Sidecar。插件源码、DBX 插件框架和官方商店目录由不同仓库负责。 **推荐路径：** 使用 `dbx-plugin create` 创建项目，在自己的仓库开发并发布未签名候选包； `dbx-store` 会为已注册的插件自动创建或更新候选 PR，维护者审核并签名后才会进入官方目录。 **插件上架 Pull Request 提交到 [`t8y2/dbx-store`](https://github.com/t8y2/dbx-store)，不是 `t8y2/dbx`。** 插件自己的功能代码通常保留在开发者自己的源码仓库；只有修改 DBX Host、SDK、CLI、协议、Schema、文档或官方示例时，才向 [`t8y2/dbx`](https://github.com/t8y2/dbx) 提交 PR。 ## 插件快捷入口 在 **插件中心 → 设置 → 全局配置** 中管理快捷入口。默认开启并显示在右侧顶部；可选择左侧或右侧的顶部/底部优先、连接树底部，或更新按钮左侧的浮动栏。浮动栏默认显示 3 个图标，可设置 0–10 个，空间不足的入口放入下拉菜单，以图标和名称逐行显示。 连接树底部区域的「插件」标题栏右上角默认提供「插件设置」入口，其他显示位置则将该入口固定在末尾，点击直达插件中心的设置页，不参与拖动排序。浮动栏溢出时，该入口位于下拉菜单末尾。在「全局配置」中关闭「显示“插件设置”快捷入口」可隐藏它；仍可从插件中心的「设置」页重新开启。没有可显示的插件快捷入口时，整个快捷区域（包括设置入口）隐藏，不占用布局空间。 每个功能有独立图标，可以拖动排序；显示开关按插件生效，关闭后隐藏该插件的所有入口。所有位置共用保存的顺序。隐藏或卸载不会删除已有排序记录，重新出现的相同入口恢复原位置，未记录的入口排列在已保存入口之后。排序标识由插件 ID、入口类型和功能 ID 组成，修改这些 ID 会被视为新入口。 拖动预览跟随光标，靠近窗口边缘时自动调整方向和位置；右侧停靠优先显示在光标左侧，长名称会根据可用宽度省略显示。 选择「插件中心右侧（下拉）」可通过插件中心按钮旁的箭头展开全部快捷入口，每行显示图标和名称，支持拖动排序；该位置不受浮动栏显示数量限制。 连接树底部采用左侧图标、右侧名称的单列列表，行样式和字号与连接树一致。默认按入口数量显示所需行数，最多五行，超出后竖向滚动。拖动分隔线可保存自定义高度，双击恢复自动高度。拖动图标时按 Esc、切换窗口或在区域外释放会取消排序；保存失败会提示并回滚。 快捷入口保留 `appToolbar` 声明的可见条件及命令执行条件。无连接类型的插件还可从快捷栏打开已有工作台；有对应命令时优先执行命令，没有命令体系的旧式插件也可显示文件浏览入口。连接型插件只显示明确声明的全局命令，不自动生成缺少连接上下文的工作台入口。不兼容插件不展示。 显示位置只决定图标位置，内容继续按原有 `panel/tab` 语义打开。隐藏快捷栏、切换位置或隐藏插件均不会关闭已打开的会话。面板快捷入口仅切换当前选中且匹配的命令面板，恢复时保留该实例。无需修改插件 Manifest 或后端协议；旧 `left/right` 设置迁移为对应侧顶部优先。 ## 应该提交到哪个仓库 | 你要修改的内容 | 提交位置 | 是否向 DBX 官方提 PR | | -------------------------------------------------------- | ----------------------------------------------------- | ----------------------- | | 你的插件前端、Rust/Go 后端、测试和发布脚本 | 插件自己的源码仓库 | 不向 `dbx` 提交；在自己的仓库开发和发布 | | 新插件上架、版本更新、商店图标和介绍 | [`t8y2/dbx-store`](https://github.com/t8y2/dbx-store) | 是，目标分支为 `main` | | DBX 插件 Host、Manifest/Marketplace Schema、SDK、CLI、Packager | [`t8y2/dbx`](https://github.com/t8y2/dbx) | 是，目标分支为 `main` | | DBX 官方示例或插件开发文档 | [`t8y2/dbx`](https://github.com/t8y2/dbx) | 是 | | 某个第三方插件自身的 Bug | 该插件的源码仓库 | 不要提交到 `dbx-store` | | 自定义或企业私有仓库 | 你的私有仓库 | 不需要向官方商店提交 | | 数据库厂商 JDBC Driver JAR | 不提交到 Git 仓库 | 用户在本机或服务器中导入 | DBX 官方维护但需要独立发布节奏的插件，通常也应使用独立源码仓库。只有与 Host 强耦合的最小示例、SDK 验证项目或维护者明确同意的组件才放进 `t8y2/dbx`。 ## 插件由哪些部分组成 ```text my-plugin/ ├── manifest.json ├── dbx-plugin.toml ├── assets/ ├── ui/ ├── backend/ # frontend 模板没有此目录 ├── .github/workflows/ │ └── plugin-release.yml └── dist/ # 构建输出，不提交到 Git ``` * `manifest.json` 声明插件身份、版本、权限、入口和 Contributions。 * `ui/` 在沙箱工作台中运行，通过 Host API 与 DBX 交互。 * `backend/` 是可选的原生 Sidecar，可以使用 Rust、Go 或其他能够实现 DBX JSON-RPC 协议的语言。 * `.dbxp` 是安装包，不是源码仓库。 * 前端插件可以发布一个 `universal` 包；包含原生 Sidecar 的插件需要按操作系统和 CPU 架构分别构建。 ## Manifest 完整说明 `manifest.json` 是运行时契约，文件必须位于插件包根目录。Manifest v1 不接受未声明字段，建议在编辑器中引用仓库内的 [`plugins/manifest.schema.json`](https://github.com/t8y2/dbx/blob/main/plugins/manifest.schema.json)。最小的纯前端 Manifest 如下： ```json { "$schema": "https://raw.githubusercontent.com/t8y2/dbx/main/plugins/manifest.schema.json", "manifest_version": 1, "id": "com.example.files", "name": "Example Files", "version": "0.1.0", "publisher": "example", "description": "Browse files from an example service.", "icon": "assets/plugin.svg", "source": "https://github.com/example/dbx-plugin-files", "homepage": "https://github.com/example/dbx-plugin-files", "engines": { "host_api": "1" }, "permissions": [], "entrypoints": { "ui": { "root": "ui", "entry": "ui/index.html" } }, "contributions": [{ "type": "workbench", "id": "com.example.files.main", "label": "Files", "icon": "assets/plugin.svg" }] } ``` Manifest 中的路径相对于包根目录，不能以 `/` 开头、不能包含 `..`、反斜杠或重复斜杠。`ui.entry` 必须位于 `ui.root` 内：当 root 为 `ui` 时，入口写 `ui/index.html`，不是 `index.html`。`signingKeyId` 属于商店 artifact metadata，不是 Manifest 字段。 | 字段 | 必需 | 说明 | | ------------------ | -- | ----------------------------------------------------------------------- | | `$schema` | 否 | 编辑器使用的 JSON Schema 地址，不参与身份校验。 | | `manifest_version` | 是 | 当前必须为数字 `1`。 | | `id` | 是 | 全局稳定 ID，只能使用小写字母、数字、`.`, `_`, `-`，例如 `io.github.example.files`；发布后不要更改。 | | `name` | 是 | 默认显示名称。 | | `icon` | 否 | 插件默认图标的包内相对路径；推荐 SVG 或 PNG。 | | `version` | 是 | `major.minor.patch` 语义化版本，可带 prerelease/build 后缀。相同 ID 和版本的正式包不能覆盖。 | | `publisher` | 是 | 发布者标识；首次上架后应保持不变。 | | `description` | 否 | 插件说明。 | | `source` | 否 | 源码仓库 HTTPS 地址，安装后可在插件信息中查看。 | | `homepage` | 否 | 项目主页、文档或支持地址。 | | `engines` | 是 | 运行时兼容范围，至少包含 `host_api`。 | | `permissions` | 否 | 最小权限集合，见下文。 | | `entrypoints` | 否 | UI 和原生 Sidecar 入口；贡献点存在时按需声明。 | | `contributions` | 否 | 连接、工作台、文件系统、连接右键菜单、结果视图、命令/菜单和 MCP 工具面声明。 | | `localizations` | 否 | 按 locale 覆盖名称、说明、贡献点、字段和动作文案。 | ### `engines`、权限和入口 ```json { "engines": { "dbx": ">=0.6.0", "host_api": "1" }, "permissions": [ "host.workbench", "host.events", "host.filesystem", "host.binary", "host.plans:read", "host.schema:read", "host.storage", "host.clipboard:read", "host.data:read", "host.connections:read", "host.network:https://s3.example.com:443" ], "entrypoints": { "ui": { "root": "ui", "entry": "ui/index.html" }, "backend": { "protocol_versions": [1], "transport": "stdio-jsonl", "executable": "bin/linux-x64/backend" } } } ``` * `engines.dbx` 是可选的 DBX 版本范围；`engines.host_api` 是必需的 Host API 版本声明。 * `host.workbench` 允许打开另一个工作台，`host.events` 接收宿主事件，`host.binary` 使用二进制通道，`host.filesystem` 使用文件系统入口。 * `host.plans:read` 允许针对 DBX 自己的连接读取估算执行计划（见 [估算执行计划](#估算执行计划)）。它是只读权限：不授予普通 SQL 执行、写操作、DDL 或真实执行计划，且这是唯一存在的计划类权限。 * `host.schema:read` 允许通过 `host.getTableMetadata` 读取已打开连接的窄化 table schema metadata；它不会授予任意 SQL、写入或隐式重连（见 [Table Schema Metadata](#table-schema-metadata)）。 * `host.storage` 为工作台 UI 提供本插件独享的持久化键值存储（见 [持久化 UI 状态](#持久化-ui-状态)）；数据只落在插件自己的插件数据目录里。 * `host.ai` 允许插件接入 DBX 全局 AI 面板：可以打开 Ask 快照对话、选择性打开使用实时插件工具的 Agent 对话，以及注册当前工作台的推荐问题。旧版 DBX 会在安装时因未知权限而失败，需要兼容旧宿主的插件应把 `host.ai` 作为可选能力，并通过 `capabilities.ai` / `capabilities.aiRecommendations` 判断运行时支持。 * `host.clipboard:read` 允许工作台 UI 读取系统剪贴板（见 [系统剪贴板](#系统剪贴板)）。写剪贴板不需要权限；读取会把用户数据（密码、令牌）交给插件代码，因此需要门控。 * `host.data:read` 允许 `window.dbxPlugin.queryData` 在用户授权给插件的连接上执行一条只读 SQL（见 [只读数据查询](#只读数据查询)）。每个连接都需要用户同意；它不会授予写入、DDL 或重连。 * `host.connections:read` 允许通过 `window.dbxPlugin.getConnections()` 或 `window.dbxPlugin.connections.list()` 获取当前所有已配置连接的只读脱敏信息（见 [连接信息读取](#连接信息读取)）。 * `host.network:https://host[:port]` 声明浏览器可访问的 HTTPS origin，DBX 将它加入 CSP 的 `connect-src`；最多 8 个，不允许路径、通配符或 Token。仍受目标服务 CORS 规则约束。该权限不是原生 Sidecar 的网络防火墙。 * `backend.transport` 默认是 `stdio-jsonl`；需要二进制帧时使用 `stdio-framed`，并同时声明 `host.binary`。 * `backend.executable`、`ui.root` 和 `ui.entry` 必须指向包内文件；带原生后端的包必须为每个目标平台提供对应可执行文件。 ### Connection Provider 连接 Provider 负责声明连接表单，DBX 负责渲染表单和保存生命周期；插件只处理自己的连接协议。`binding` 决定字段语义：`config` 写入外部配置，`secret` 写入 Secret Store，`name`、`host`、`port`、`username`、`password`、`database` 映射到标准连接字段。 ```json { "type": "connection-provider", "id": "com.example.files.connection", "label": "Example Service", "icon": "assets/connection.svg", "database_type": "example-files", "description": "Connect to an Example Service.", "fields": [ { "key": "display_name", "label": "Name", "type": "text", "binding": "name", "required": true }, { "key": "endpoint", "label": "Endpoint", "type": "text", "binding": "host", "required": true }, { "key": "port", "label": "Port", "type": "number", "binding": "port", "default": 443 }, { "key": "region", "label": "Region", "type": "radio", "options": [ { "label": "US", "value": "us" }, { "label": "EU", "value": "eu" } ], "binding": "config" }, { "key": "token", "label": "Access token", "type": "password", "binding": "secret", "required": true } ], "workbench": "com.example.files.main", "capabilities": ["test", "connect", "disconnect"], "actions": [{ "id": "refresh", "label": "Refresh metadata", "variant": "outline", "when": "edit", "requires_valid_form": true, "timeout_ms": 30000 }] } ``` 字段类型为 `text`、`password`、`number`、`boolean`、`select`、`radio` 或 `textarea`；`select`/`radio` 必须提供非空 `options`，每项包含 `label` 和字符串 `value`。`binding: "port"` 必须使用 `number`。不要把密码、Token 或私钥放进 `config`、Workbench context、事件或日志。 每个字段必须声明 `key`、`label`、`type`，可选 `description`、`placeholder`、`required`、`default`、`options` 和 `binding`；默认值必须符合字段类型。省略 binding 的 `password` 字段默认按 `secret` 处理。`database_type` 是插件自定义类型标识，不会给 DBX 内置数据库枚举添加成员。 字段还支持条件显隐/条件必填。`visible_when` 与 `required_when` 接受单条子句 `{ "field": "mode", "one_of": ["custom"] }`（引用字段取到列表中的值时命中，按字符串比较，因此 `[false]` 与 `["false"]` 都能匹配布尔 `false`），并用 `all_of` / `any_of` / `not` 组合： ```json { "key": "sudo_command", "label": "Sudo command", "type": "text", "visible_when": { "all_of": [ { "field": "sudo_source", "one_of": ["custom"] }, { "field": "read_only", "one_of": [false] } ] } } ``` 条件会级联：子句引用的字段自身处于隐藏状态时该子句不参与判定，因此隐藏容器的默认值不会把孙级字段点亮；未填写或空值永不命中；组合树最多 8 层、64 个节点。DBX 在对话框与保存/测试/连接校验中使用同一套求值，不会出现「表单放行、宿主拒绝」的分歧。 `text`、`password`、`textarea` 字段可以用 `picker` 声明**本机文件选择**（例如 SSH 私钥、keystore）： ```json { "key": "private_key_path", "label": "Private key path", "type": "text", "binding": "config", "picker": { "kind": "file", "accept": [".pem", ".key"], "content_field": "private_key" } } ``` 桌面端打开系统文件选择器，把选中的**绝对路径**写回该字段（插件后端同机运行，可自行读取文件）；网页端拿不到客户端路径，同一操作变成**上传**：DBX 读取文件内容写入声明的 `content_field` 兄弟字段，并清空路径字段。两者互相清除——选了路径就丢弃已上传内容，上传内容就清空路径，避免同时存在两份互相矛盾的来源。`kind` 还支持 `directory`（仅桌面端），`accept` 最多 16 条扩展名或 MIME 过滤，上传上限 1 MiB。 插件在连接过程中需要用户输入时（堡垒机登录期 keyboard-interactive 验证码、主机密钥确认、账号选择等），可以调用 Host API 1.1 新增的 `host/requestUserInput`，通过 DBX 同一个阻塞对话框拿到用户输入，`连接测试` 与真实连接走同一条通道： ```json { "jsonrpc": "2.0", "id": "prompt-1", "method": "host/requestUserInput", "params": { "prompt": "Verification code (6 digits)", "title": "JumpServer login", "echo": false, "timeoutSecs": 300 } } ``` 返回值为 `{ "action": "submit", "value": "123456" }`、`{ "action": "cancel" }` 或 `{ "action": "timeout" }`；只有 `submit` 带值，其余必须按「没有答案」处理并失败关闭。插件发起的请求使用字符串 id，DBX 自己的请求与响应继续使用数字 id；提示期间 DBX 会暂停等待该回答的请求超时计时，用户输入验证码不会被误判成连接超时。错误码 `-32001` 表示没有可用的用户界面（headless/MCP），`-32602` 参数非法，`-32601` 宿主不支持该方法，三种情况都要优雅降级。调用前请确认 `plugin/initialize` 通告的 `hostApiVersion` 为 `1.1.0`（或 `host.features` 含 `host.requestUserInput`）；Rust SDK 对应 `dbx_plugin_sdk::host_client()` 与 `HostClient::supports("host/requestUserInput")`、`HostClient::request_user_input(&UserInputPrompt::secret("Verification code"))`。 连接生命周期使用固定的 `connection/test`、`connection/connect`、`connection/disconnect`，自定义表单动作使用 `connection/action`，参数包含 `provider`、`connection`、`runtime`；动作额外包含 `action: { id }`。后端使用 `connection.id` 保存会话，并使用 `runtime.host`/`runtime.port` 连接经过 DBX 隧道或代理转换后的端点。仅在后端生命周期请求中接收补齐 Secret 的连接；前端通过 `connectionId` 使用已经建立的会话。 多端点协议（Kafka `advertised.listeners`、集群发现等）在贡献点上声明 `proxy_route`。配置了传输层后，DBX 会在 payload 中下发 SOCKS5 路由而非静态转发：`runtime.host`/`runtime.port` 保留逻辑端点，插件通过 `runtime.proxy`（`{ "type": "socks5", "host": "...", "port": 1080, "username": "...", "password": "..." }`）拨号每个广播端点——SSH 末层暴露其动态 SOCKS5 端点，SOCKS5 代理层直接使用；代理凭据与连接 Secret 走同一加密通道，插件不得记录日志。未声明该旗标时传输层保持静态转发行为，要求标准 `host`/`port` 字段给出单一远端端点；对会隧道到空端点的插件连接，DBX 直接给出可行动的报错而非静默超时。 动作的 `when` 可为 `always`、`create`、`edit`；`variant` 可为 `default`、`outline`、`secondary`、`destructive`、`ghost`；`timeout_ms` 为 1–120000。`requires_valid_form` 决定是否要求完整表单，`close_on_success` 决定成功后是否关闭。返回 `{ "success": true, "message": "...", "fieldValues": { "port": 443 } }` 可以更新已声明的字段；返回 `success: false` 表示失败。 ### 其他 Contributions | 类型 | 必需字段 | 用途 | | --------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | `workbench` | `type`, `id`, `label` | 注册可从侧边栏或插件入口打开的工作台。 | | `filesystem-provider` | `type`, `id`, `label`, `schemes` | 注册虚拟文件系统；`root_uri` 例如 `s3://bucket`，能力可选 `read`、`write`、`delete`、`rename`、`mkdir`。 | | `context-menu` | `type`、`id`、`label`、`menu: "connection"` 或 `"table"`、可选 `action` | 向 Sidebar Tree 的连接或 table 右键菜单增加后端动作，或打开已声明的 Workbench。 | | `result-view` | `type`, `id`, `label` | 注册查询或任务结果视图。 | `menu: "table"` contribution 当前只在用户对 Sidebar Tree 中的具体 table 节点打开右键菜单时生效。未声明 `action` 的旧式 contribution 会通过必需的 backend entrypoint 调用 `contextMenu/`，并传递 table identity： ```json { "table": { "connectionId": "connection-id", "database": "example", "schema": "public", "table": "users" } } ``` `database` 和 `schema` 是可选字段；不可用时会省略，不会强制传递空字符串。该 context 只包含对象 identity，不包含 credential、connection string 或原始连接配置。Object Browser 后续可以复用相同 identity contract，但本次版本没有把它作为 table 菜单入口。 context-menu 也可以声明由 Host 处理的 Workbench action： ```json { "type": "context-menu", "id": "vendor.example.generate", "label": "生成测试数据", "menu": "table", "action": { "type": "open-workbench", "workbench": "vendor.example.main" } } ``` `action.workbench` 必须引用同一插件 manifest 中声明的 `workbench`。Host 会直接打开该 Workbench，不调用 sidecar，并将当前 invocation context 作为 Workbench context 传入。`menu: "table"` 传入上面的 `TableContext` 对象本身（不是 backend 的 `{ "table": ... }` envelope）；`menu: "connection"` 传入现有的非敏感 connection summary（`id`、`dbType`、`name`、`database`）。Host 还可能提供用于 tab 关联的标准 `connectionId`。两者都不会暴露 host、port、username、password、connection string 或原始连接配置。再次打开同一个 Workbench 时会用最新 invocation context 刷新其 context。 只有未声明 `action` 的旧式 context-menu 才要求 backend entrypoint；其返回的 `{ "message": "..." }` 仍会显示为 toast。 同一插件内通过 `id` 互相引用：Connection Provider 的 `workbench` 必须指向一个已声明的工作台，`filesystem_provider` 必须指向一个已声明的文件系统 Provider。图标优先使用 Contribution 的 `icon`，缺失时回退到插件级 `icon`。 自定义文件浏览器应使用 `workbench`：列表、虚拟滚动、预览、右键菜单和分栏由插件前端实现。只有希望使用 DBX 通用文件管理器时才选择 `filesystem_provider`；同时声明两者时默认打开工作台。未声明 `action` 的旧式 `context-menu` 调用后端 `contextMenu/`；声明式 `open-workbench` action 则由 Host 直接打开同插件 Workbench。`result-view` 在工作台 context 中接收结果快照。SDK 会在初始化后通过 `dbxPlugin.contributionId` 暴露 Host 选中的 contribution id，因此单个 UI 入口可以为多个工作台和结果视图服务；具体负载见[完整贡献点协议](https://github.com/t8y2/dbx/blob/main/plugins/README.md)。 ### 文件系统协议 使用 DBX 通用文件管理器时，后端实现以下方法；自定义工作台也可以自行通过 RPC 使用这些方法，但不能把声明 Contribution 当成已经实现业务逻辑。 | 方法 | 参数与返回 | | ---------------------------- | --------------------------------------------------------------------------------------- | | `filesystem/list` | `providerId`、可选 `connectionId`、`uri`、可选 `cursor`、`limit`；返回 `{ entries, nextCursor? }`。 | | `filesystem/read` | 同上身份字段、`uri`、`maxBytes`；返回 `{ dataBase64, contentType?, truncated, etag? }`。 | | `filesystem/write` | `uri`、`dataBase64`、`create`、`overwrite`、可选 `etag`；需声明 `write`。 | | `filesystem/createDirectory` | `uri`；需声明 `mkdir`。 | | `filesystem/delete` | `uri`、`recursive`；需声明 `delete`。 | | `filesystem/rename` | `sourceUri`、`targetUri`、`overwrite`；需声明 `rename`。 | 所有方法都携带 `providerId` 和可选 `connectionId`。目录项包含单个文件名 `name`、完整 `uri`、`kind`（`file`、`directory`、`symlink`、`other`）以及可选 `size`、`modifiedAt`、`contentType`。`name` 不能包含 `/`、`\\` 或是 `.`/`..`；完整路径放在 `uri`。最后一页省略 `nextCursor`，不要返回已经使用的 cursor。图片预览应返回实际 MIME 和 base64 字节，不能把二进制当作 UTF-8 文本。 写操作返回 `{ success, message?, entry? }`；内联读写限制为 4 MiB。大文件传输应采用分块与进度/取消协议，而不是一个巨大的 JSON/base64 值。 ### 国际化 `localizations` 的 key 使用 `zh-CN`、`en` 等 locale。可覆盖插件名称、说明以及每个 Contribution 的 `label`、`description`、字段和动作文案；它不会翻译插件 UI 自己的文本。 ```json { "localizations": { "zh-CN": { "name": "示例文件", "contributions": { "com.example.files.connection": { "label": "示例服务", "fields": { "token": { "label": "访问令牌" } } } } } } } ``` ## Workbench 上下文契约 Workbench 上下文跨越 DBX 与插件边界时是 JSON 数据快照。宿主会递归移除 Vue 响应式包装并发送独立副本，因此插件不能依赖 Vue ref、Proxy、DOM 节点、函数、组件实例或凭据。 上下文可以包含 `null`、布尔值、有限数字、字符串、数组和普通对象。对象中的 `undefined` 字段会省略，数组中的 `undefined` 会转换为 `null`。Date、Map、Set、Symbol、BigInt、非有限数字、循环引用和自定义 class 实例会被拒绝并返回错误。上下文 UTF-8 编码后的大小上限为 2 MiB。 连接 Provider 使用 `binding: "config"` 的字段会保存到 `external_config`；使用 `binding: "secret"` 的字段会保存到 Secret Store。插件连接的 `external_config` 会在新建、编辑、保存和重新连接流程中保留。 宿主还会为每个 workbench 上下文写入三个保留字段：`workbenchId`（宿主生成的稳定实例 id）、`restored` 和 `surface`。`surface` 表示当前 UI 跑在哪种容器里——`"tab"`（主多标签工作台）、`"dock"`（底部面板）或 `"window"`（桌面浮动小组件窗口，见[浮动窗口](#浮动窗口)）。同一个插件的同一个 contribution 可以同时开在多个 surface 上，各自拥有独立的上下文和生命周期；遇到未知取值应退化成 `"tab"` 的行为。 ## 前端 Host API UI 在隔离的 iframe 中运行，DBX 通过 `window.dbxPlugin` 提供桥接对象。不要导入 DBX 的 Vue/Tauri 模块，也不要假设浏览器页面能直接访问 Node.js、文件系统或网络。 多个 Workbench 或 result-view contribution 共用同一个 UI 入口时，可通过 Host 选中的 identity 路由页面： ```js await window.dbxPlugin.ready; const contributionId = window.dbxPlugin.contributionId; ``` `contributionId` 与 `context` 相互独立；例如从 Plugin Center 打开的 Workbench，其 context 可以是空对象 `{}`。SDK 会在 resolve `ready` 前记录 identity，因此 `await dbxPlugin.ready` 后可确定性地读取。为兼容旧插件，`dbx-plugin-init` 仍会携带完整 init payload 并作为通知派发；但该事件只派发一次，不应成为读取权威状态的唯一来源。 以下自定义 `objects/list` 和 `objects/changed` 需要由插件后端实现，资源示例假设包内存在 `ui/assets/empty-state.svg`： ```js await window.dbxPlugin.ready; const contributionId = window.dbxPlugin.contributionId; const context = window.dbxPlugin.context; const result = await window.dbxPlugin.invoke("objects/list", { prefix: "docs/" }, { timeoutMs: 30000 }); const off = window.dbxPlugin.onContext((nextContext) => render(nextContext)); await window.dbxPlugin.notify("objects/changed", { count: result.items.length }); const assetUrl = await window.dbxPlugin.readAssetUrl("assets/empty-state.svg"); ``` | API | 作用 | | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ready` | 等待 Host 完成初始化；应用启动逻辑放在 `await dbxPlugin.ready` 之后。 | | `contributionId` | Host 打开的 contribution 的只读 identity；`await ready` 后可读取，且与 `context` 独立。 | | `context` / `onContext(fn)` | 读取或监听当前工作台上下文。 | | `locale` | 读取当前语言；插件 UI 需自行完成翻译。 | | `theme` | 读取 `appearance` 和 DBX 设计 tokens，适配明暗主题。 | | `request(method, params)` | 调用 Host API；常用内部方法包括 `host.getContext`、`ui.readAsset`。 | | `invoke(method, params, { timeoutMs })` | 向自己的 Sidecar 发送有响应的 RPC。 | | `notify(method, params)` | 向 Sidecar 发送无需返回业务结果的通知。 | | `sendBinary(channel, data)` / `onBinary(fn)` | 发送或接收二进制数据；需要 `stdio-framed` 和 `host.binary`。 | | `readAsset(path)` / `readAssetUrl(path)` | 读取包内资源；路径不能越出插件资源根目录。 | | `openWorkbench(id, context)` | 打开本插件的另一个工作台；需要 `host.workbench`。 | | `setTitle(title)` | 修改当前工作台页签标题（传入 `null` 恢复默认）；需要 `host.workbench`。 | | `getTitle()` | 读取当前工作台页签标题；需要 `host.workbench`。 | | `closeWorkbench()` | 关闭承载当前 UI 的表面——工作台标签、dock 面板条目，或本插件的浮动窗口。与 `Ctrl/Cmd+W` 快捷键走同一条路径，因此插件可以提供自己的关闭或最小化按钮。 | | `executeCommand(commandId, context?)` | 执行本插件自己声明的命令，与菜单执行完全同径——重新检查 `enablement`、按单例复用，并遵循声明的 `presentation`（panel 停靠底部面板，tab 打开工作台标签页）。`context` 合并到命令上下文之上，并解析 `instance_key` 的 `{{path}}` 占位符（如 `instance_key: "logs:{{connectionId}}"` 即每个连接一个面板实例）。预期结果通过 `{ error }` 返回；需要 `host.workbench`。 | | `openFilesystem(id, context)` | 打开本插件的文件系统入口；需要 `host.filesystem`。 | | `getPlanCapabilities(connectionId)` | 读取宿主与该连接能提供什么计划能力；需要 `host.plans:read`。 | | `explainPlan({ connectionId, database?, schema?, sql, mode, timeoutMs? })` | 返回 `sql` 的估算执行计划；需要 `host.plans:read`。 | | `getTableMetadata({ connectionId, database?, schema?, table })` | 读取已打开连接的窄化 table schema metadata；需要 `host.schema:read`。 | | `queryData({ connectionId, database?, schema?, sql, maxRows?, timeoutMs? })` | 在用户授权给插件的连接上执行一条只读 SQL；需要 `host.data:read`。 | | `capabilities` | 来自 init 消息的 `{ downloadFile, planApi, schemaMetadataApi, dataApi, storage, ai, aiRecommendations, clipboardWrite, clipboardRead, floating, workbenchTitle }`。字段缺失或为 `false` 表示当前宿主不支持该组 Host API，应据此关闭功能而不是用真实请求试探。 | | `ai.openConversation({ title, prompt, context, send?, mode? })` | 在内置 AI 面板新建插件对话；`send` 默认 `false`，`mode` 默认 `ask`。`mode: "agent"` 会在 context 包含已打开插件连接时使用实时插件工具；需要 `host.ai`，并以 `capabilities.ai` 广播。 | | `ai.setRecommendations({ context, items })` | 覆盖当前工作台的默认推荐问题并立即刷新全局 AI 面板；每次最多 5 条，支持 `{{path.to.value}}` 占位符；需要 `host.ai` 和 `capabilities.aiRecommendations`。 | | `ai.clearRecommendations()` | 清空当前工作台的推荐问题；需要 `host.ai` 和 `capabilities.aiRecommendations`。 | | `onInit(fn)` / `onEvent(fn)` | 监听初始化、环境变化或后端事件；转发后端事件需要 `host.events`。 | | `storage` | 本插件独享的持久化键值状态；需要 `host.storage`；见下文。 | | `fileTransfer` | 本地文件流式传输、下载与（桌面端）系统拖放；见下文。 | | `clipboard` | 沙箱内的系统剪贴板访问；见下文。 | | `floating` | 打开并控制桌面浮动小组件窗口（仅桌面宿主）；见[浮动窗口](#浮动窗口)。 | 调用失败会以 Promise rejection 返回，处理时应展示可理解的错误并允许重试。通过 `request` 调用的宿主方法、参数和返回值以当前 Host API 版本为准，不要调用未在协议中声明的 DBX 内部函数。 `readAsset` 的路径相对于 `ui.root`，所以这里的 `assets/empty-state.svg` 对应包内 `ui/assets/empty-state.svg`。资源不用时调用 `URL.revokeObjectURL(assetUrl)`；组件销毁时调用 `onContext`/`onEvent` 等返回的取消订阅函数，避免重复监听。 ### 估算执行计划 插件可以在不自带驱动、连接池和凭据的前提下读取一条查询的**估算**执行计划。插件只传自己的原始 SQL 和连接引用；DBX 用自己已有的方言规则生成 `EXPLAIN` 语句、应用与自身计划视图完全相同的只读安全校验，并在宿主连接上执行。插件只拿到原始计划，由自己完成解析、归一化和可视化。 ```json { "permissions": ["host.plans:read"] } ``` ```js if (window.dbxPlugin.capabilities.planApi) { const capabilities = await window.dbxPlugin.getPlanCapabilities(connectionId); if (capabilities.supports.estimatedPlan) { const plan = await window.dbxPlugin.explainPlan({ connectionId, database, sql, mode: "estimated", timeoutMs: 15000 }); render(plan.rawPlan, plan.format); } } ``` `getPlanCapabilities(connectionId)` 返回 `{ dbType, dbVersion?, supports: { estimatedPlan }, limits: { maxTimeoutMs, maxPlanBytes } }`： * `supports.estimatedPlan` 为 `false` 表示该连接的方言在 DBX 中没有估算计划路径；应直接禁用功能，而不是调用 `explainPlan`。 * `limits.maxTimeoutMs` 已经考虑该连接自身的查询超时，请求里的 `timeoutMs` 会被夹到该上限；`limits.maxPlanBytes` 限制计划负载大小。 * `dbVersion` 只在 DBX 已经知道该连接产品版本时才存在；宿主不会为了插件去探测服务器。 * 该调用只读取已保存的连接配置，不会建立连接；但连接必须已经打开：已保存但当前已断开的连接会被拒绝，而不是替插件重新建连。 `explainPlan(request)` 返回 `{ dbType, dbVersion?, format, rawPlan, truncated, warnings }`： * `format` 为 `json`、`xml`（SQL Server `ShowPlanXML`）或 `text`。`format` 为 `json` 时 `rawPlan` 是已解析的 JSON 文档，其余情况是计划文本。 * `warnings` 可能包含：`plan_not_json`（服务端返回的内容不是 JSON，负载会如实标记为 `text`，而不是假装可解析）、`plan_truncated`（宿主为遵守 `maxPlanBytes` 截断了计划）、`plan_rows_truncated`（驱动达到计划行数上限）。只要发生过任一截断，`truncated` 都是 `true`。 计划 API 的边界： * **只做估算计划。** `mode` 必须是 `"estimated"`，其它取值一律拒绝。真实执行计划（`EXPLAIN ANALYZE`、`SET STATISTICS XML`）会真正执行语句，不属于本 API。 * **插件不能自己提供要执行的 SQL。** 只接受原始 `sql`，`EXPLAIN` 语句完全由宿主生成，因此插件无法传入 `EXPLAIN` 文本、驱动命令或执行模式。 * **只允许只读目标。** DBX 自身计划视图使用的同一道校验会拒绝多语句、DDL、DML 和危险关键字。Oracle 是唯一例外：DBX 也会为它规划 DML，因为 `EXPLAIN PLAN FOR` 并不会执行该语句。 * **不涉及凭据，也不返回结果集。** 返回体只有计划和元信息，密码、凭据、连接串、驱动内部结构都不会越过这条边界。 * **连接必须已经打开。** DBX 不会替插件建立连接，也不会为插件创建连接。`getPlanCapabilities` 与 `explainPlan` 对「已保存但已断开」的连接都会以 `Connection is not open` 拒绝；只有 DBX 当前已经打开的连接才能规划。 判断能力时请读 `dbxPlugin.capabilities.planApi`（旧宿主不会带这个字段），再用 `getPlanCapabilities` 确认这条连接是否支持，最后才调用 `explainPlan`。自行拼 `EXPLAIN` 文本既没必要，也不会被接受。 计划 API 属于 Host API 1.2。无法离开它工作的插件应在 manifest 里声明下限：`"engines": { "host_api": "^1.2" }`。manifest 里的版本范围是兼容下限，`capabilities.planApi` 是运行期探测，两者都保留。 ### Table Schema Metadata（表结构元数据） 插件可以读取当前 DBX 已打开连接中某个 table 的窄化 schema metadata，而不需要拥有驱动、连接池、凭据或自己拼 SQL。请求复用现有的 `PluginTableContext`，只允许 table identity： ```json { "permissions": ["host.schema:read"] } ``` ```js if (window.dbxPlugin.capabilities.schemaMetadataApi) { const metadata = await window.dbxPlugin.getTableMetadata({ connectionId, database, schema, table: "users", }); for (const column of metadata.columns) { renderColumn(column.name, column.dataType, column.nullable); } } ``` `getTableMetadata({ connectionId, database?, schema?, table })` 返回： ```json { "columns": [ { "name": "id", "dataType": "integer", "nullable": false, "precision": 32, "default": "nextval('users_id_seq'::regclass)" } ], "fieldCapabilities": { "length": "supported", "precision": "supported", "scale": "supported", "default": "supported" } } ``` * `columns` 只包含 `name`、`dataType`、`nullable`、可选的 `length`、`precision`、`scale` 和 `default`。不会返回 comment、key/index、credential、连接串、驱动内部对象或任意 SQL 结果。 * 可选值在没有值时保持 `null` 或直接省略，绝不会被伪造为 `0` 或空字符串。`fieldCapabilities` 用 `supported`、`unsupported`、`unknown` 区分提供方支持、明确不支持和宿主没有可靠 provenance 的情况；`unknown` 不应被插件当成支持。 * `database` 和 `schema` 可选；不可用时省略，不要把空字符串当作 public identity。`connectionId` 和 `table` 必须是非空且不超过 256 个字符的 identity 值。 * 这是只读 API。DBX 只复用已打开的 Host connection/session，禁止插件隐式重连、创建连接池或执行任意 SQL。已保存但当前断开的连接会以 `Connection is not open` 拒绝；请求的 database 没有对应已打开 session 时也会拒绝，而不是切换到别的连接。 该 API 属于 Host API 1.3。无法离开它工作的插件应声明：`"engines": { "host_api": "^1.3" }`；同时仍应读取 `capabilities.schemaMetadataApi`，因为旧宿主不会提供该字段。没有 `host.schema:read` 时，宿主会在请求到达 backend 前拒绝调用。 ### 只读数据查询 插件可以在用户授权给它的 DBX 连接上执行一条只读 SQL，而不需要驱动、连接池、凭据或连接串。声明权限，并按能力位决定是否调用： ```json { "engines": { "host_api": "^1.4" }, "permissions": ["host.data:read"] } ``` ```js if (window.dbxPlugin.capabilities.dataApi) { const result = await window.dbxPlugin.queryData({ connectionId, database, sql: "SELECT status, count(*) AS total FROM orders GROUP BY status", maxRows: 200, }); renderChart(result.columns, result.rows); } ``` `queryData({ connectionId, database?, schema?, sql, maxRows?, timeoutMs? })` 返回： ```json { "dbType": "postgres", "columns": [ { "name": "status", "dataType": "text" }, { "name": "total", "dataType": "int8" } ], "rows": [ ["paid", 1204], ["refunded", 37] ], "truncated": false, "elapsedMs": 12 } ``` * **按连接征求同意。** 插件第一次查询某个连接时，宿主会弹窗写明插件名和连接名。用户允许后授权会持久保存，并显示在「插件中心 → 已安装」该插件下，用户可随时撤销；拒绝会在本次工作台会话内被记住。插件无法自行授权。 * **只读且单条语句。** 宿主只接受一条被 DBX SQL 风险分类器判定为只读的语句——与 MCP 只读模式和 AI Agent 使用同一道闸门。写入、DDL、`SELECT … FOR UPDATE`、多条语句以及 `USE` 这类切换会话数据库的语句都会被拒绝；请改用 `database` 参数。 * **只用已打开的连接。** 与执行计划和表结构元数据 API 一样，DBX 不会替插件发起连接：已保存但未打开的连接会以 `Connection is not open` 拒绝。Redis、MongoDB、搜索引擎等非 SQL 连接不提供该能力。 * **有上限。** `maxRows` 默认 500、最多 5000；序列化后的行数据上限 8 MiB；`timeoutMs` 会被限制在连接自身超时和 60 秒上限之内。只要有行被截断，`truncated` 就为 `true`。 * **不含凭据。** 响应只包含列和行。授权被撤销后，调用会返回以 `PLUGIN_DATA_ACCESS_NOT_GRANTED` 开头的错误，下一次查询会重新征求用户同意。 该 API 属于 Host API 1.4。请同时保留 `engines.host_api` 下限和 `capabilities.dataApi` 运行时检查；无法弹出确认框的 Web 宿主会拒绝请求，而不会静默授权。 ### 连接信息读取 需要展示连接下拉框或根据连接执行特定任务（例如通过 `host.data:read` 查询数据）的插件，可以通过 `host.connections:read` 权限枚举当前配置的所有连接列表： ```json { "permissions": ["host.connections:read"] } ``` ```js await window.dbxPlugin.ready; if (window.dbxPlugin.capabilities.connectionsApi) { const connections = await window.dbxPlugin.getConnections(); // 也可通过 window.dbxPlugin.connections.list(); for (const conn of connections) { console.log(conn.id, conn.name, conn.dialect, conn.connected); } } ``` 返回的每个连接对象包含： * `id`: 连接唯一标识，可直接传给 `queryData`、`getPlanCapabilities` 等； * `name`: 连接名称； * `dialect` / `dbType`: 数据库方言/类型（如 `mysql`, `postgres`, `sqlite` 等）； * `connected` / `isConnected`: 当前是否已建立物理连接； * `readOnly`: 是否为只读连接； * `database` / `schema`: 默认数据库或模式（如有）。 > **安全边界**：返回列表完全脱敏，不包含密码、用户名、主机、端口或连接串等敏感凭据。 ### 系统剪贴板 插件沙箱是 opaque origin 且没有剪贴板权限，`navigator.clipboard` 在里面不可用。宿主代为桥接系统剪贴板： * `window.dbxPlugin.copy(text)` / `window.dbxPlugin.clipboard.writeText(text)` 写系统剪贴板。两者走同一条无权限门控的桥接方法：写操作的输入就是用户数据本身，是低风险的一半。 * `window.dbxPlugin.clipboard.readText()` 读系统剪贴板。它需要 `host.clipboard:read` 权限——读取会把用户数据（密码、令牌）交给插件代码，且没有后续用户交互兜底——属于 Host API 1.3：离开它无法工作的插件应声明 `"engines": { "host_api": "^1.3" }`。 读剪贴板请看 init 能力而不是试探：`capabilities.clipboardRead`（写对应 `capabilities.clipboardWrite`）在旧宿主上缺失即为 falsy。读被拒绝（缺权限、Web 宿主没有原生剪贴板访问）时 Promise 会 reject——请优雅降级，例如回落到键盘粘贴路径，而不是让交互直接失败。 ```js await window.dbxPlugin.ready; const canRead = !!window.dbxPlugin.capabilities.clipboardRead; const canWrite = !!window.dbxPlugin.capabilities.clipboardWrite; async function pasteFromClipboard() { if (!canRead) return null; try { return await window.dbxPlugin.clipboard.readText(); } catch { // 缺权限或读取失败：保留键盘粘贴路径。 return null; } } ``` ### 文件传输与系统拖放 桌面端宿主通过 `window.dbxPlugin.fileTransfer` 把本地文件流式接入插件沙箱。句柄只在用户明确同意后打开：原生打开/保存对话框（`pick` / `beginSave`），或从系统拖放到本插件工作台区域内的文件（`onDrop`）。传输按分块进行，多 GB 文件也不会整体载入内存。 ```js const fileTransfer = window.dbxPlugin.fileTransfer; if (!fileTransfer) { // Web 宿主：回退到 和 sidecar 落盘。 } // 上传：用户在原生对话框选择文件，插件把分块推给自己的 sidecar。 const { files } = await fileTransfer.pick({ multiple: true }); for (const file of files) { let offset = 0; for (;;) { const chunk = await fileTransfer.read(file.handleId, offset, 256 * 1024); await uploadChunk(file.name, offset, chunk.dataBase64); // 你自己的 RPC if (chunk.eof) break; offset += chunk.length; } await fileTransfer.cancel(file.handleId); } // 下载：打开保存目标，分块写入，最后 finish 落盘。 const target = await fileTransfer.beginSave({ name: "export.csv", size }); await fileTransfer.write(target.handleId, 0, bytes); await fileTransfer.finish(target.handleId); // 系统拖放（仅桌面端）：被拖入的文件以已打开的句柄送达。 const offDrop = fileTransfer.onDrop((files) => uploadAll(files)); const offDrag = fileTransfer.onDragState((active) => showDropOverlay(active)); ``` | API | 用途 | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `pick({ multiple })` | 原生打开对话框；返回已打开的读句柄 `{ handleId, name, size, contentType }`。 | | `read(handleId, offset, length?)` | 从读句柄流式读取一个分块 `{ dataBase64, length, eof }`。 | | `beginSave({ name, contentType?, size? })` | 原生保存对话框 + 写句柄；返回 `{ handleId, chunkBytes }`，用户取消时为 `null`。 | | `write(handleId, offset, data)` | 写入一个分块（二进制 transfer 或 base64）；返回 `{ written, nextOffset }`。 | | `finish(handleId)` / `cancel(handleId)` | 冲洗并关闭写句柄 / 丢弃任意句柄。 | | `onDrop(fn)` | 拖入本工作台的文件以读句柄送达；拖入文件夹会被展开为其中包含的文件（`.git` 等点开头文件与目录会被跳过），每个文件额外携带 `relativePath`（以 `/` 分隔、以拖入文件夹自身名字开头的路径，如 `folder/nested/a.csv`），可用于还原拖入的目录结构，也能区分不同拖入根目录下的同名文件。监听器签名为 `(files, { dropId, truncated })`：`dropId` 标识本次拖入的整组条目（取消与进度记账的分组键），`truncated` 为 `true` 表示展开因 2000 文件或 8 层深度上限被截断。 | | `onDragState(fn)` | 是否有系统拖拽悬在本工作台上方；用它驱动拖放遮罩。 | 桌面端与网页端的行为差异：请以 init 消息里 additive 的 `capabilities.fileTransfer` 标志位（`pick`、`beginSave`、`read`、`drop`、`folderExpansion`）做能力探测，不要靠试调用。桌面端 `pick` / `beginSave` 走原生对话框、`onDrop` 接收系统拖放（句柄由宿主惰性打开，读时分块流式，因此超大文件夹与大文件都不会占满句柄；选取文件数超过共享句柄池时自动降级为惰性条目，不会静默丢弃）。网页端 `pick` 回退到浏览器文件选择器、`beginSave` 回退为内存缓冲加浏览器下载、`onDrop` / `onDragState` 不会触发（`drop`/`folderExpansion` 为 `false`）、句柄也没有 `relativePath`。`onDrop` 只在拖放落点位于本插件工作台区域内时触发；落点在宿主其他区域时保持宿主自身的行为。 ### 持久化 UI 状态 沙箱是 opaque origin，`localStorage` 在里面会直接抛错。需要跨重载或跨应用重启保留状态的工作台（最近访问的目录、面板尺寸、草稿等）改用 `window.dbxPlugin.storage`。它需要 `host.storage` 权限，并以 init 消息里的 `capabilities.storage` 广播；使用前请同时探测这两者。 ```js if (window.dbxPlugin.capabilities.storage) { const storage = window.dbxPlugin.storage; await storage.set("layout", { sidebar: "collapsed", sort: "name" }); const layout = await storage.get("layout"); // { sidebar: "collapsed", sort: "name" }，未设置时为 null await storage.delete("layout"); } ``` | API | 用途 | | ----------------- | -------------------------------------- | | `get(key)` | 返回存储的 JSON 值；键未设置时返回 `null`。 | | `set(key, value)` | 持久化任意 JSON 值（`undefined` 归一化为 `null`）。 | | `delete(key)` | 删除一个键；删除不存在的键同样成功。 | 键为不超过 256 字符的字符串；单个值序列化后上限 256 KiB，整库上限 1 MiB——这是 UI 状态存储，不是数据落盘通道。数据保存在插件自己的 `plugin-data/` 目录里，按插件隔离，版本升级和卸载后都保留。大批量数据、缓存以及 Sidecar 产生的任何文件请放进 Sidecar 的数据目录（见 [原生 Sidecar 和 RPC](#原生-sidecar-和-rpc)）。Web 宿主上同一 API 由浏览器本地存储支撑，两端代码完全一致。 ### 在 DBX AI 中分析插件数据 在 manifest 中声明 `"permissions": ["host.ai"]`。插件可以直接打开全局 AI 面板，也可以为每个 Workbench 注册快捷推荐问题。两种能力都沿用 DBX 的模型选择、历史、追问、停止和导出功能。 #### 声明 Workbench 的默认推荐问题 在 `workbench` contribution 下增加可选的 `ai.recommendations`。`label` 显示在 DBX 全局 AI 面板，`prompt` 是点击后发送给 AI 的文本；`order` 越小越靠前。 ```json { "type": "workbench", "id": "com.example.files.main", "label": "Files", "ai": { "recommendations": [ { "id": "health", "label": "检查 {{resource.name}} 健康状态", "prompt": "分析 {{resource.kind}}/{{resource.name}} 的健康状态和风险", "order": 10 } ] } } ``` 占位符从当前 Workbench context 读取，支持对象属性和数组下标，例如 `{{resource.name}}`、`{{items.0.status}}`。无法解析的占位符会使该条推荐被隐藏；`__proto__`、`prototype` 和 `constructor` 等路径会被拒绝。推荐问题最多显示 5 条。 #### 根据资源变化更新推荐问题 插件切换页面或资源时，可以提交运行时推荐问题。运行时 `items` 会覆盖 manifest 默认值；传入空数组表示清空当前推荐。运行时 context 通常只需要提交资源字段，Host 会保留当前 Workbench 的 `connectionId`、数据库和实例标识，确保点击推荐问题后仍绑定到正确的插件连接。 ```js function updateRecommendations(resource) { if (!dbxPlugin.capabilities.aiRecommendations) return; return dbxPlugin.ai.setRecommendations({ context: { resource }, items: [ { id: "health", label: `检查 ${resource.name} 健康状态`, prompt: "分析 {{resource.kind}}/{{resource.name}} 的健康状态和风险", order: 10, }, { id: "events", label: "查看最近事件", prompt: "列出这个资源最近的重要事件并给出处理建议", order: 20, }, ], }); } await dbxPlugin.ai.clearRecommendations(); ``` 推荐问题显示在 DBX 全局 AI 对话窗口中，而不是插件页面内新增一个 AI 入口。用户点击后，DBX 会使用当前推荐文本创建新的 Agent 对话并立即发送；Agent 会通过当前已打开的插件连接调用插件工具获取实时数据。推荐列表本身只属于当前 Workbench 上下文，不会写入对话历史；用户点击后发送的实际问题会正常保存。 #### 直接打开 Ask 或 Agent 对话 `ai.openConversation` 仍适合插件按钮或其他明确动作。默认 `mode` 为 `ask`，宿主会复制插件提供的 JSON 快照；快照会随对话保存，后续资源刷新不会改变已经创建的对话。需要实时工具时显式使用 `mode: "agent"`，并在 context 中提供当前已打开插件连接的 `connectionId`： ```js await dbxPlugin.ai.openConversation({ title: "Watchlist analysis", prompt: "Compare the current quotes and explain risks and missing data.", context: { connectionId, resource: { kind: "watchlist", name: "primary" }, dataTimestamp, }, mode: "agent", send: true, }); ``` `title` 最多 200 字符，`prompt` 最多 32000 字符，`context` 必须是纯 JSON 对象，上限 2 MiB。Agent 只能使用宿主为该插件连接公开的工具；插件不会收到模型回复或模型配置，也不能借此获得数据库执行能力。旧插件不声明推荐问题时仍可正常使用原有 AI API；旧宿主缺少新增 capability 字段时，插件应关闭对应入口并继续提供其他功能。 ### 浮动窗口 浮动窗口把插件的某个 workbench 放进一个独立的无边框、置顶桌面窗口，而不是塞在 DBX 外壳里——这正是小型常驻小组件需要的表面（播放器胶囊、会话状态徽章、快捷选择器）。它会盖在其他应用之上，可以被拖到桌面任意位置。在屏幕中间松手就停在落点；落到或越过工作区边缘（不管怼得多用力）都会齐着那条边吸附并停靠。停靠不会在落下的那一刻就把小组件藏起来：它先保持整颗可读的胶囊，光标离开约 2.5 秒后才滑到屏外只留一条细边，光标碰到细边就滑回来。重新打开一个上次吸在边上的小组件也是这套时序（先胶囊、后收起）；刚唤出的小组件即使默认落点就贴着边，也只停在胶囊态。使用前先判断 `capabilities.floating`：Web 宿主没有窗口，桌面宿主也可能不支持窗口管理。 ```js if (window.dbxPlugin.capabilities.floating) { // 在标签或 dock 工作台里：打开小组件。 // 一个（插件, workbench contribution）只会有一个窗口，重复调用只是把已有窗口带到前台。 const { windowId } = await window.dbxPlugin.floating.open({ contributionId: "capsule", title: "Now playing", width: 260, height: 60, context: { queueId: currentQueueId }, }); } // 在小组件内部（context.surface === "window"）：控制自己所在的窗口。 grip.addEventListener("pointerdown", (event) => { grip.setPointerCapture(event.pointerId); dragging = false; }); grip.addEventListener("pointermove", async (event) => { if (dragging || Math.hypot(event.clientX - downX, event.clientY - downY) < 4) return; dragging = true; // 从这一刻起窗口归宿主移动：它自己读原生光标，不需要插件逐帧上报。 await window.dbxPlugin.floating.beginDrag(); }); grip.addEventListener("pointerup", async () => { if (!dragging) return; dragging = false; await window.dbxPlugin.floating.endDrag(); // 吸附并记住位置 }); ``` | API | 作用 | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `floating.open(options)` | 为本插件的某个 `workbench` contribution 打开（或前置）浮动窗口。`options`：`contributionId`（必填）、`title`、逻辑像素的 `width`/`height`、物理屏幕像素的 `x`/`y`、`alwaysOnTop`（默认 `true`）、`skipTaskbar`（默认 `true`）、`resizable`（默认 `false`）、`context`。返回 `{ windowId, reused }`；需要 `host.workbench`。 | | `floating.close(contributionId?)` | 关闭本插件的浮动窗口——指定某个 contribution，或省略 id 关闭本插件的全部浮动窗口。在小组件内部不带参数调用即关闭自己。 | | `floating.beginDrag()` | 把窗口交给宿主的拖动循环。在 `pointermove` 里、自己的拖动阈值越过之后调用（此时按键还按住）。之后由宿主自己读原生光标，插件没有逐帧调用要做。 | | `floating.endDrag({ snap? })` | 结束拖动。`snap`（默认 `true`）时宿主把窗口齐着它到达或越过的工作区边缘吸附并停靠在那（先保持整颗胶囊，光标离开一会儿才收起到屏外、只留一条悬停细边），落点在屏幕中间则完整夹回屏内；位置与停靠边都会记住，供下次打开使用。返回物理像素的最终矩形。实践中可不调：宿主在光标静止后也会自己收尾，收不到 pointerup 的小组件不会把窗口一直粘在光标上。 | | `floating.setSize(width, height)` | 以逻辑像素调整所在窗口大小；宿主会夹到自己的上下限内。 | 小组件决定拖动**何时**开始（哪个元素是拖拽把手、指针要先走多远）；窗口由宿主移动，吸附与位置记忆也归宿主。刻意没有逐帧的桥调用：宿主轮询原生光标，webview 忙不过来时小组件也照样贴着指针走，光标静止即收尾，pointerup 丢了也不会一直拖下去。几何类调用（`beginDrag`/`endDrag`/`setSize`）只在浮动窗口内部有效，在其他表面调用会被拒绝，因此标签页永远无法移动它不在其中的窗口。 几条规则让这个表面的行为可预期： * **一个 contribution 只有一个窗口。** 窗口 id 由插件 id 和 contribution id 推导，所以 `floating.open` 是幂等的：第二次调用会把已开的窗口带到前台，而不是叠出更多小组件。 * **窗口是不透明的。** 宿主自己不画任何外壳，用户看到的就是小组件本身：给页面一个背景加圆角，配合宿主按内容收好的窗口尺寸，读起来就是浮在桌面上的一张卡片。刻意不提供逐像素透明（带镂空角的塑形小组件）——透明区域还收不收鼠标事件各平台不一致，而一个要给用户拖的小组件必须处处点得动。 * **外壳导航会被转发。** 浮动窗口没有标签栏、dock 和面板，所以从它发起的 `openWorkbench` 和 `openFilesystem` 会在 DBX 主窗口里打开，主窗口会自行前置。`executeCommand` 在这个表面完全不提供：每个命令动作都要打开一个外壳表面，调用会成功返回但什么都看不见。 * **位置跨重启保留**，按插件和 contribution 分别记录；当记录的位置已经不在任何已连接的显示器上时会被丢弃（拔掉显示器后退化为工作区默认位置，而不是开到屏幕外）。 * **小组件就是一个完整工作台。** 它拿到和标签页相同的桥、权限、上下文契约和 sidecar RPC；`context.surface` 为 `"window"`，`context.workbenchId` 为窗口 id。它启动的是你 UI 的另一份实例，所以共享状态必须走 sidecar（或 `storage`），不能指望模块内存。 ### 主题、布局和静态资源 DBX 将主题 tokens 注入文档根元素，并更新 `data-dbx-theme`。自定义组件库（包括 Svelte、shadcn-svelte）应使用这些变量，不要依赖父页面 CSS 自动穿透 iframe： ```css body { margin: 0; background: var(--color-background, #fff); color: var(--color-foreground, #18181b); } button { background: var(--color-primary, #2563eb); color: var(--color-primary-foreground, #fff); cursor: pointer; } ``` 使用 `window.addEventListener("dbx-plugin-env", handler)` 响应语言或主题变化。先读取 `dbxPlugin.locale`/`theme` 初始化，再在事件中刷新自己的状态。DBX 提供轻量 `dbx-btn`、`dbx-input` 等样式，但开发宿主不模拟完整组件 kit，自定义 token 样式在两者中更一致。 #### 主题负载携带什么 env 消息的 `theme` 结构为 `{ appearance, tokens, editor? }`。`appearance` 是 `"light" | "dark"`；`tokens` 是按前缀扫取的根节点设计变量（`--color-*`、`--radius-*`、`--font-*`）；`editor` 是无 CSS 令牌载体的 SQL 编辑器设置结构化快照。投递矩阵： | DBX 设置 | 投递形式 | | ------------------ | ----------------------------------------------- | | 浅色/深色/跟随系统 | `theme.appearance` | | 调色板 + 自定义配色 | `--color-*` tokens | | 圆角风格 | `--radius-*` tokens | | UI 字体 | `--font-sans` token | | 编辑器（等宽）字体 | `--font-mono` token + `theme.editor.fontFamily` | | 编辑器字号 | `theme.editor.fontSize` | | SQL 编辑器语法主题 | `theme.editor.theme` | | UI 缩放（宿主窗口级） | 不投递——插件自管缩放 | | 数据网格字体/类型配色、编辑器背景图 | 不投递——DB 域（`--dbx-*` 不在扫取范围） | 字体"字号"类关注点归插件所有：宿主不规定你的字号；如适合你的 UI，可把 `theme.editor.fontSize` 当默认值消费。所有负载变化都经 env 通道实时推送——字体族变更走主题修订号，字号/语法主题走显式监听——无需刷新。 UI 必须构建为包内静态资源，不要把 Vite 开发服务器或 CDN 的脚本地址写入发行包。宿主把入口及资源转换成沙箱可加载内容；CSP 报错时检查构建产物是否存在、路径是否落在 `ui.root` 内，并使用匹配版本的 CLI 复现。用插件自己的对话框组件处理删除/重命名，不要依赖沙箱中的原生 `alert`/`confirm`/`prompt`。 #### 懒加载与代码分割 宿主会把入口脚本内联进沙箱文档，`ui/` 下的其余资源在运行时通过 `dbx-plugin` 协议保持可寻址：`dbx-plugin://localhost/<插件id>/`（WebView2 上映射为 `http://dbx-plugin.localhost/<插件id>/…`）。宿主会把平台对应的形式注入为沙箱文档的 ``，并放行资源类 CSP，因此打包后的插件可以正常动态 `import()` 代码分割的 chunk——前提是构建产物使用**相对**资源地址：Vite 设 `base: "./"`、webpack 设 `publicPath: "./"`，让 chunk 和 CSS 资源地址基于注入的 base 解析而不是宿主 origin。绝对路径 `/assets/…` 携带不了插件 id，会 404。该协议只读文件、限定在每个插件的 `ui.root` 内，且插件更新后不会沿用旧缓存。 #### 内联后的样式表 宿主会读取所有指向 `ui.root` 内部的 ``，替换成带同样属性的 `