diff --git a/docs/content/docs/1panel.cn.mdx b/docs/content/docs/1panel.cn.mdx index 070a06b9d5..7b886c0223 100644 --- a/docs/content/docs/1panel.cn.mdx +++ b/docs/content/docs/1panel.cn.mdx @@ -5,6 +5,10 @@ description: 使用 1Panel 应用商店安装、访问和更新 DBX Web 版。 1Panel 应用商店提供了 DBX 官方 Docker 镜像，可以直接在服务器上完成安装和更新，不需要手动编写 Docker 命令。 + + 1Panel 安装的是 DBX Web 版。数据库查询、对象浏览、数据编辑、导入导出、AI 和驱动管理等核心能力在服务器端运行；本机文件选择、Deep Link、本机 CLI Agent 和桌面版定时数据库备份不属于 Web 运行方式。 + + ## 可选的服务器方案 如果你还没有用于部署 DBX 的服务器，可以了解[雨云](https://www.rainyun.com/MTE5Mjc4Ng==_)。雨云是面向开发者和站长的云服务提供商，提供云服务器、物理服务器、游戏云和配套基础设施服务。当然，任何满足 Docker 和 1Panel 运行要求的服务器都可以部署 DBX。 @@ -50,7 +54,7 @@ http://192.168.1.100:4224 ## 持久化与更新 -DBX 的应用数据保存在 1Panel 应用目录的 `data` 目录，并挂载到容器内的 `/app/data`。重启容器或更新 DBX 时，连接配置和其他应用数据会继续保留。 +DBX 的应用数据保存在 1Panel 应用目录的 `data` 目录，并挂载到容器内的 `/app/data`。这里包含 DBX 自身的存储数据库、已保存连接、插件、驱动和其他持久化状态。重启容器或更新 DBX 时，只要挂载目录未被删除，这些数据就会继续保留。 更新时，在 1Panel 的 **已安装** 应用中打开 DBX，选择可用的新版本并执行更新。更新前建议先确认数据目录已经纳入服务器备份。 @@ -58,6 +62,23 @@ DBX 的应用数据保存在 1Panel 应用目录的 `data` 目录，并挂载到 不要直接删除 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 容器必须能够访问目标数据库： @@ -69,3 +90,22 @@ DBX 的应用数据保存在 1Panel 应用目录的 `data` 目录，并挂载到 `4224` 是 DBX Web 服务端口，不是目标数据库端口。连接数据库时仍需填写 MySQL、PostgreSQL、Redis 等目标数据库自身的端口。 + +## 生产部署建议 + +- 使用足够长且唯一的访问密码，不要保留示例值； +- 通过 1Panel 反向代理配置 HTTPS，并限制安全组和主机防火墙暴露范围； +- 需要受控升级时固定版本，更新前备份 `/app/data` 并阅读[更新日志](/cn/changelog)； +- 为 DBX 使用独立、最小权限的数据库账号，生产连接优先启用只读保护； +- 定期检查驱动和插件来源，不要把不受信任的 JAR 或可执行文件放入数据目录。 + +更多连接、写入、AI 和 API 边界见[生产安全](/cn/docs/production-safety)。 + + + + 安装 Web 版需要的 DuckDB、JDBC 和 Agent 驱动，并查看运行状态。 + + + 了解桌面版定时备份的支持范围，以及 Web 部署为什么需要外部备份方案。 + + diff --git a/docs/content/docs/1panel.mdx b/docs/content/docs/1panel.mdx index fcad3f1dab..e994d65d05 100644 --- a/docs/content/docs/1panel.mdx +++ b/docs/content/docs/1panel.mdx @@ -5,6 +5,10 @@ description: Install, access, and update the DBX web edition from the 1Panel app The 1Panel app store provides the official DBX Docker image, so you can install and update the DBX web edition without writing Docker commands manually. + + 1Panel installs DBX Web. Core database querying, object browsing, data editing, import/export, AI, and driver management run on the server. Local file pickers, deep links, the local CLI Agent, and scheduled Desktop database backups are not part of the Web runtime. + + ## Optional server choice If you still need a server for DBX, you can take a look at [RainYun](https://www.rainyun.com/MTE5Mjc4Ng==_). RainYun is a cloud service provider offering cloud servers, physical servers, game hosting, and developer-friendly infrastructure services. Any server that meets the Docker and 1Panel requirements can host DBX as well. @@ -50,7 +54,7 @@ Enter the **Access Password** from the installation form. If the page does not o ## Persistence and updates -DBX application data is stored in the 1Panel app directory's `data` directory and mounted at `/app/data` inside the container. Restarting or updating the container preserves saved connections and other application data. +DBX application data is stored in the 1Panel app directory's `data` directory and mounted at `/app/data` inside the container. It contains DBX's storage database, saved connections, plugins, drivers, and other persistent runtime state. Restarting or updating the container preserves that data as long as the mounted directory is not removed. To update DBX, open it under **Installed** apps in 1Panel, select an available version, and start the update. Confirm that the data directory is included in your server backup before updating. @@ -58,6 +62,23 @@ To update DBX, open it under **Installed** apps in 1Panel, select an available v Do not delete DBX's application data directory unless you intend to remove saved connections and other local data. Back up the directory before uninstalling the app. + + Backing up `/app/data` protects DBX application configuration and runtime data only. It does not back up business data inside MySQL, PostgreSQL, or other target databases. Web does not provide Desktop's scheduled database-backup jobs; use native database backups, cloud snapshots, or a dedicated backup system. + + +DuckDB is not embedded in the `dbx-web` image. Install it separately from [Driver Manager](/en/docs/driver-management) after the first launch. The driver is stored under `/app/data/agents`, so it is preserved by the same data mount. + +## Web Paths and Files + +In a 1Panel deployment, the DBX backend reads the server or container filesystem: + +- An SSH private-key path must be readable inside the container, not merely available on the browser computer. +- JDBC JARs, plugins, Agents, and downloaded drivers live in the server-side data directory. +- Browser uploads are copied to a controlled server-side directory before a task reads them. +- Database-file connections and server paths must be evaluated from the container's point of view. + +Do not enter a personal computer's absolute path simply because the UI is open in that computer's browser. See [What Is DBX?](/en/docs/what-is-dbx) for the full Desktop/Web boundary. + ## Connect to a database After signing in, click **New Connection** and enter the target database type, address, port, username, and database password. The DBX container must be able to reach the target database: @@ -69,3 +90,22 @@ After signing in, click **New Connection** and enter the target database type, a `4224` is the DBX Web service port, not the target database port. Enter the database's own port when creating a MySQL, PostgreSQL, Redis, or other connection. + +## Production Deployment Guidance + +- Use a long, unique access password instead of an example value. +- Configure HTTPS through a 1Panel reverse proxy and restrict security-group and host-firewall exposure. +- Pin a version when controlled upgrades matter; back up `/app/data` and read the [Changelog](/en/changelog) before updating. +- Use a dedicated least-privilege database account and prefer read-only protection for production connections. +- Review driver and plugin sources; do not place untrusted JARs or executables in the data directory. + +See [Production Safety](/en/docs/production-safety) for the database, write, AI, and API boundaries. + + + + Install DuckDB, JDBC, and Agent drivers needed by Web, and inspect their runtime state. + + + Understand Desktop scheduled-backup support and why Web deployments need an external backup plan. + + diff --git a/docs/content/docs/ai-assistant.cn.mdx b/docs/content/docs/ai-assistant.cn.mdx index 435c1b1252..2443ebcb43 100644 --- a/docs/content/docs/ai-assistant.cn.mdx +++ b/docs/content/docs/ai-assistant.cn.mdx @@ -1,186 +1,188 @@ --- title: AI 助手 -description: 配置 AI 供应商后，在 DBX 中生成 SQL、解释查询、优化语句并辅助修复错误。 +description: 配置云端、兼容 API 或本地 CLI 模型，在 Schema 上下文中生成 SQL、分析数据并执行受控 Agent 工作流。 --- -AI 助手用于辅助 SQL 工作。它会结合当前连接的数据库元数据理解表结构和字段，再根据你的描述生成 SQL、解释查询、给出优化建议或帮助修复错误。 +AI 助手把当前数据库、Schema、SQL、错误、结果预览和用户点名的对象组合成上下文，用于生成 SQL、解释查询、优化语句、修复错误和分析数据。 -AI 生成的 SQL 不会自动执行。请在执行前检查表名、字段名、筛选条件和影响范围，尤其是在生产环境连接上。 +Ask 模式只生成建议；Agent 模式在用户明确要求真实数据时可以调用查询工具。任何模型输出都可能错误。执行 SQL 前仍应检查目标连接、字段、过滤条件、参数和影响范围。 -## 配置 +## 支持的模型接入方式 + +### API 供应商 + +DBX 内置以下配置预设： + +- Claude +- OpenAI +- Gemini +- DeepSeek +- Qwen +- MiniMax +- Ollama +- OpenAI Compatible +- Anthropic Compatible +- Custom + +兼容或自定义配置可以设置端点、模型、API 风格、认证方式、代理和上下文窗口。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 设置 - 进入 DBX 设置页，找到 AI 相关配置。 + 在编辑器设置中进入 AI，添加一个命名配置。可以为同一供应商保存多套端点或凭据。 - ### 选择供应商 + ### 选择供应商和模型 - 选择 Anthropic、OpenAI 或兼容 OpenAI API 的自定义端点。 + 使用预设、兼容 API、自定义端点或本地 CLI。模型列表可发现时从供应商或本地 CLI 读取，也可以手动填写。 - ### 填写凭据 + ### 配置认证和推理参数 - 输入 API Key。使用自定义端点时，还需要填写接口地址和模型名称。 + API 模式填写 API Key、认证方式、端点和代理。支持的模型可以选择 effort、reasoning 或 thinking；具体选项来自供应商能力，而不是对所有模型统一显示。 - ### 保存并测试 + ### 测试并保存 - 保存配置后回到编辑器，尝试用自然语言生成一条简单查询。 + 测试会报告成功、延迟、实际模型和认证、限流、超时、模型不存在等错误类别。 -如果没有配置 API Key，AI 功能应向用户提示需要先完成设置，而不是静默失败。 +API Key、CLI 环境变量和自定义端点可能具有敏感性。不要把设置截图、导出的配置或调试日志发送到不可信位置。 -## Ask 模式与 Agent 模式 +## Ask 和 Agent -| 模式 | 行为 | 执行 | -| ----- | ------------------------------------------------ | ---------------------------------------- | -| Ask | 生成 SQL、解释、修复、优化、方言转换或样例数据 | 不暗示已经执行 | -| Agent | 当用户明确要求查询数据时，优先生成一条可执行 SQL | DBX 会先评估生成 SQL，再决定是否尝试执行 | +| 模式 | 适合任务 | 工具和执行行为 | +| --- | --- | --- | +| Ask | 生成、解释、优化、修复、转换 SQL，或基于已有上下文给建议 | 不主动执行数据库查询；最终答案应明确区分建议和已验证结果 | +| Agent | “查出结果”“对比真实数据”“先看表结构再回答”等需要迭代取证的任务 | 可以列表、读字段、取样和执行只读查询；写入必须经过精确确认 | -## Thinking 模式 +Agent 只有在原始请求明确要求真实数据/结果时才应执行查询。仅要求“写一条 SQL”时，即使处于 Agent 模式，也应返回 SQL 而不是自动运行。 -对于支持扩展推理的供应商和模型（如启用了 thinking 的 Claude），DBX 在 AI 设置中提供了 **Thinking** 开关。启用后： +## Agent 轮次和重试 -- 模型在生成 SQL 前会花费更多时间推理 -- 复杂查询、多表 JOIN 和优化建议受益最大 -- 响应时间会增加，但对于非简单任务的输出质量会提高 +- **最大 Agent 轮次**：默认 30，可配置 5–500。它限制模型、工具调用和修复循环的总轮数，防止复杂任务无限运行 +- **最大 API 重试次数**：默认 2，可配置 0–10。只用于限流、超时和临时网络错误；Claude Code、Codex 和 Pi CLI 不使用这个 API 重试设置 +- 达到轮次上限、用户取消、连接失败或工具策略拒绝时，Agent 会停止并保留已有步骤和错误 -可按任务开关 Thinking。简单查询和解释可关闭；复杂 Schema 推理、优化或调试时可启用。 +提高轮次上限会增加时间、数据库读取次数和模型成本。应先通过明确提示、表提及和缩小任务范围减少无效探索。 -## 表提及 +## Schema、表和 SQL 文件上下文 -在提示中使用 `@table` 或 `@schema.table` 告诉 AI 哪些表最重要： +AI 上下文可以包含： -- `@users` — 在上下文中包含 `users` 表结构 -- `@public.orders` — 包含特定 schema 限定的表 -- 多个提及：`@users @orders @products` 同时包含三张表 +- 数据库类型、连接名称、数据库和 Schema +- 当前编辑器 SQL、选中 SQL 和最近错误 +- 表、字段、索引、外键和少量样例数据 +- 当前结果集的有限预览 +- 用户选择的提示模板 +- 被提及的保存 SQL 文件内容 -表提及是控制 Schema 上下文最可靠的方式。即使完整 Schema 太大无法全部包含，它也能正常工作。 +在输入框键入 `@` 可以搜索表和保存的 SQL 文件： -## 提示输入历史导航 +- `@users`：优先加入 `users` 的元数据 +- `@public.orders`：指定 Schema 中的表 +- 同时选择多张表或 SQL 文件：把相关上下文一起交给模型 -使用方向键浏览之前的 AI 提示： +完整 Schema 过大时会截断。表提及比让模型在所有对象中猜测更可靠，也能减少 token 和元数据请求。 -- 按 **↑**（上箭头）循环浏览之前的提示 -- 按 **↓**（下箭头）在提示历史中向前移动 -- 在 Ask 和 Agent 模式中都有效 -- 在迭代类似查询或解释时节省时间 +## 全局指令和提示模板 -提示历史按会话保存，帮助你快速重用或修改之前的 AI 请求而无需重新输入。 +设置中可以维护： -## Schema 上下文 +- **全局指令**：每次 AI 请求都注入，例如命名规范、时区、软删除字段和生产约束 +- **提示模板**：按场景保存可复用规则，例如“只生成 PostgreSQL 兼容 SQL”或“分析必须包含索引建议” -AI 提示可以包含当前数据库类型、连接名称、数据库、当前 SQL、最近错误、结果预览和 Schema 上下文。Schema 上下文包含表、字段、索引和外键。 +助手中可以同时选择多个模板。DBX 在发送时冻结当前全局指令和模板快照，因此请求开始后修改设置不会改变已经运行的任务。 -当 Schema 很大时，DBX 会截断上下文。使用表提及来告诉 AI 优先围绕哪些表进行推理。 +模板会进入模型上下文，应避免放入密码、令牌或不必要的业务数据。规则冲突时，模型未必能按预期选择优先级，应保持全局指令和模板简短、明确且互不矛盾。 -## SQL 安全策略 +## 写入和生产安全 -| SQL 类型 | DBX 行为 | -| ------------------------------------------------------------------ | -------------------------------------------- | -| `SELECT`、`WITH`、`SHOW`、`DESCRIBE`、`DESC`、`EXPLAIN` 等只读语句 | 用户明确表达查询意图时，Agent 模式可自动执行 | -| `INSERT` 或按键限定的 `UPDATE` 等低风险写入 | 只在明确非生产环境自动执行；其他情况需要确认 | -| 多语句、`DELETE`、`MERGE`、`REPLACE`、`CREATE` 或未知 SQL | 执行前需要确认 | -| `DROP`、`TRUNCATE`、`ALTER`、`RENAME` 或大范围 `UPDATE` 等危险语句 | 会被 AI 执行策略阻止 | +AI Agent 的执行边界是后端强制的，不只是提示词： -连接名、主机或数据库名看起来像生产环境时，DBX 会更保守。AI 生成的 SQL 仍然是模型输出，请像审查代码一样审查它。 +1. 只读工具可以按任务调用 +2. 非只读 SQL 必须先作为明确的 SQL 提案展示 +3. 用户确认后，授权只绑定到同一连接、同一数据库和完全相同的 SQL 文本 +4. 授权只对下一次运行有效，不会变成永久写入权限 +5. 生产数据库上的写入和 DDL 不会授权给 AI Agent；模型只能返回 SQL 供用户在 DBX 中人工审阅执行 -## 常见用法 +连接只读保护、生产保护和数据库账号权限仍是上限。即使用户确认，目标变化、SQL 变化、空确认或后端风险分类不通过都会使授权失效。 + +AI Agent 不会获得“以后都可以写”的授权，也不会绕过 MCP 策略、连接只读保护或数据库权限。更多边界见 [生产环境安全](/cn/docs/production-safety)。 + +## 推理强度和 Thinking + +不同供应商使用不同机制：枚举 effort、reasoning level、布尔 thinking、整数预算或自定义文本。DBX 按当前模型能力展示可用选项，并记住每个配置/模型的选择。 + +- 简单生成或解释可使用供应商默认或较低强度 +- 多表推理、复杂优化和错误诊断可提高强度 +- 更高强度通常增加延迟和费用，但不保证答案正确 + +不要把 UI 中的统一标签理解为所有供应商拥有相同推理语义。 + +## 对话、历史和导出 + +- 输入框支持使用 ↑ / ↓ 浏览当前提示历史 +- 对话可以按连接和数据库保存，便于继续上下文 +- 每条最终 AI 分析可以导出为 Markdown，文件包含连接名、时间和最终回答 +- Markdown 导出只包含最终分析内容，不会把内部 reasoning 或 Agent 步骤附加到文件中 + +导出内容仍可能包含表名、SQL、结果片段和业务数据，分享前请审阅和脱敏。 + +## 常见任务 ### 生成 SQL -用自然语言描述目标，AI 会结合当前连接的元数据生成查询： +> 根据 `@orders` 和 `@customers` 生成最近 30 天客户销售额 Top 10 查询，只返回 SQL，不执行。 -> 查看最近 30 天订单金额最高的 10 个客户 +明确写出“不执行”可以让意图更清晰。检查时间函数、Schema 限定、JOIN 键、空值和返回行数。 -可能生成： +### 分析真实数据 -```sql -SELECT c.name, SUM(o.amount) AS total_amount -FROM customers c -JOIN orders o ON c.id = o.customer_id -WHERE o.created_at >= NOW() - INTERVAL 30 DAY -GROUP BY c.id, c.name -ORDER BY total_amount DESC -LIMIT 10; -``` +> 查询 `@orders` 最近 7 天每天的订单数，执行只读查询并解释异常峰值。 -生成后建议检查： - -- 是否使用了正确的表和字段 -- 时间范围是否符合预期 -- 聚合和排序逻辑是否正确 -- 是否需要限制返回行数 - -### 解释 SQL - -选中一段 SQL 后，可以让 AI 解释它的结构： - -- 每个子查询的作用 -- `JOIN` 条件如何关联表 -- `WHERE` 条件过滤了什么 -- 聚合、分组和排序的意义 - -这适合阅读历史查询、接手报表 SQL 或理解复杂视图。 - -### 优化 SQL - -AI 可以根据 SQL 和表结构给出优化方向，例如： - -- 是否可能发生全表扫描 -- 是否缺少合适索引 -- 子查询是否可以改写为 `JOIN` -- 排序、去重或聚合是否可以减少 - -AI 的优化建议是参考信息。真正的性能判断仍应结合数据库的执行计划、数据量和索引情况。 +这类请求适合 Agent 模式，因为它明确要求真实结果。 ### 修复错误 -当 SQL 执行失败时，可以把错误信息和当前 SQL 交给 AI 辅助分析。常见修复包括： +把失败 SQL、数据库错误和涉及的表一起提供。AI 可以读取字段和方言信息，但版本特有行为、权限、锁和运行计划仍需人工验证。 -- 语法错误 -- 表名或字段名拼写错误 -- `GROUP BY` 字段缺失 -- 类型不匹配 -- 不同数据库方言之间的语法差异 +## 隐私和故障排查 -## 支持的供应商 +- 云端供应商会收到发送给模型的提示、Schema 摘要、SQL 和有限结果上下文；以供应商隐私条款为准 +- Ollama 和本地 CLI 可以在本机运行，但模型进程和 CLI 插件仍可能有自己的联网或日志行为 +- 代理、兼容端点和自定义网关可能记录请求内容 +- 测试失败时先检查端点、认证方式、模型名、代理和模型是否支持当前 API 风格 +- Agent 反复失败时减少上下文、点名目标表、降低任务范围，并查看具体工具错误，而不是只提高轮次上限 -DBX 提供了改进的**可搜索模型下拉框**，让你可以轻松地在所有支持的供应商中查找并选择可用模型。 +## 相关功能 - - - 适合使用 Claude 系列模型。填写 API Key 后，在可搜索的下拉框中选择或填写你要使用的模型。 - - - 适合使用 OpenAI 模型。填写 API Key 后，在模型输入框中选择或填写你要使用的模型。 - - - 适合兼容 OpenAI Chat Completions API 的服务，例如本地模型服务、企业网关或第三方模型平台。 - - 需要配置： - - - Endpoint URL - - Model - - API Key（仅需要鉴权的服务必填） - - - - -## 隐私与安全 - -AI 请求通常会包含你的问题、相关 SQL、错误信息，以及必要的表结构上下文。使用前请确认： - -- 当前供应商是否允许发送这些信息 -- 是否包含敏感字段名、业务规则或样例数据 -- 团队是否对第三方模型调用有合规要求 - -如果希望 AI 直接通过工具查询数据库，可以继续阅读 [MCP 集成](/cn/docs/mcp)。 + + + 查看 AI、MCP、只读连接和生产保护的统一边界。 + + + 让外部 AI 编程助手通过 DBX 访问数据库。 + + + 了解 AI 所使用的当前 SQL、结果和元数据上下文。 + + diff --git a/docs/content/docs/ai-assistant.mdx b/docs/content/docs/ai-assistant.mdx index 4b1854fe1d..42cf6dce26 100644 --- a/docs/content/docs/ai-assistant.mdx +++ b/docs/content/docs/ai-assistant.mdx @@ -1,186 +1,188 @@ --- title: AI Assistant -description: Configure an AI provider to generate SQL, explain queries, suggest optimizations, and help fix errors in DBX. +description: Connect cloud, compatible API, or local CLI models to generate SQL, analyze data, and run controlled Agent workflows with schema context. --- -The AI assistant helps with SQL work. It uses metadata from the active connection to understand tables and columns, then helps generate SQL, explain queries, suggest optimizations, or diagnose errors. +The AI Assistant combines the active database, schema, SQL, errors, result preview, and explicitly mentioned objects into context for SQL generation, explanation, optimization, error repair, and data analysis. -AI-generated SQL is not executed automatically. Review table names, columns, filters, and affected rows before running it, especially on production connections. +Ask mode produces suggestions. Agent mode can call query tools when the user explicitly requests real data. Any model output can be wrong. Review the target, fields, filters, parameters, and affected scope before executing SQL. -## Configuration +## Model Integrations + +### API Providers + +DBX includes presets for: + +- Claude +- OpenAI +- Gemini +- DeepSeek +- Qwen +- MiniMax +- Ollama +- OpenAI Compatible +- Anthropic Compatible +- Custom + +Compatible and custom configurations can set the endpoint, model, API style, authentication method, proxy, and context window. API styles include OpenAI-style completions, the Responses API, and Anthropic Messages. When supported, DBX discovers models and filters out endpoints that are not suitable for assistant or Agent use. + +### Local CLI Agents + +Desktop can also invoke locally installed and authenticated: + +- Claude Code CLI +- Codex CLI +- Pi Coding Agent + +You can configure the executable path and additional environment variables. CLI Agents run on the Desktop computer and access the active database through DBX-scoped MCP tools. Docker/Web hides these local CLI providers because the server cannot assume the browser computer has the commands installed. + +## Add a Configuration - ### Open Settings + ### Open AI Settings - Open DBX settings and find the AI configuration section. + Add a named AI configuration in editor settings. Multiple endpoints or credentials can be saved for the same provider. - ### Choose a Provider + ### Choose Provider and Model - Select Anthropic, OpenAI, or a custom endpoint compatible with the OpenAI API. + Use a preset, compatible API, custom endpoint, or local CLI. Models are discovered from the provider or CLI when possible and can otherwise be entered manually. - ### Enter Credentials + ### Configure Authentication and Reasoning - Enter your API key. For custom endpoints, also enter the endpoint URL and model name. + API modes accept an API key, auth method, endpoint, and proxy. Supported models expose effort, reasoning, or thinking controls based on provider capabilities rather than one universal setting. - ### Save and Test + ### Test and Save - Save the configuration, return to the editor, and try generating a simple query from natural language. + The test reports success, latency, effective model, and categorized failures such as authentication, rate limit, timeout, or missing model. -When no API key is configured, AI features should prompt the user to complete setup instead of failing silently. +API keys, CLI environment variables, and custom endpoints may be sensitive. Do not share configuration screenshots, exports, or debug logs with untrusted parties. -## Ask Mode And Agent Mode +## Ask and Agent -| Mode | Behavior | Execution | -| ----- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------- | -| Ask | Generates SQL, explanations, fixes, optimizations, dialect conversions, or sample data | Does not imply anything has run | -| Agent | Prioritizes one executable SQL statement when the user clearly asks DBX to query data | DBX evaluates the generated SQL before attempting execution | +| Mode | Best for | Tool and execution behavior | +| --- | --- | --- | +| Ask | Generate, explain, optimize, repair, or translate SQL, and provide advice from existing context | Does not proactively query the database; final answers should distinguish suggestions from verified results | +| Agent | Requests such as “get the result,” “compare real data,” or “inspect schema first” that require iterative evidence | Can list tables, read columns, sample data, and run read-only queries; writes require exact confirmation | -## Thinking Mode +Agent should execute a query only when the original request explicitly asks for real data or results. A request to “write a query” should return SQL without running it, even in Agent mode. -For providers and models that support extended reasoning (such as Claude with thinking enabled), DBX exposes a **Thinking** toggle in AI settings. When enabled: +## Agent Turns and Retries -- The model spends more time reasoning before generating SQL -- Complex queries, multi-table joins, and optimization suggestions benefit most -- Response time increases, but output quality improves for non-trivial tasks +- **Maximum Agent turns** defaults to 30 and can be set from 5 to 500. It bounds model, tool, and repair-loop iterations +- **Maximum API retries** defaults to 2 and can be set from 0 to 10 for rate limits, timeouts, and transient network errors. Claude Code, Codex, and Pi CLI providers do not use this API retry setting +- The Agent stops when it reaches the turn limit, is cancelled, loses the connection, or is rejected by tool policy, while retaining completed steps and errors -Toggle Thinking on or off per task. Leave it off for simple queries and explanations; enable it for complex schema reasoning, optimization, or debugging. +Increasing the turn limit raises latency, database reads, and model cost. Prefer clear prompts, explicit table mentions, and narrower scope before raising the limit. -## Table Mentions +## Schema, Table, and SQL File Context -Use `@table` or `@schema.table` mentions in your prompt to tell the AI which tables matter most: +AI context can include: -- `@users` — includes the `users` table schema in context -- `@public.orders` — includes a specific schema-qualified table -- Multiple mentions: `@users @orders @products` includes all three tables +- Database type, connection name, database, and schema +- Current or selected editor SQL and the latest error +- Tables, columns, indexes, foreign keys, and limited sample rows +- A bounded preview of the current result +- Selected prompt templates +- Referenced saved SQL file content -Table mentions are the most reliable way to control schema context. They work even when the full schema is too large to include entirely. +Type `@` in the prompt to search tables and saved SQL files: -## Prompt Input History Navigation +- `@users` prioritizes metadata for `users` +- `@public.orders` selects a schema-qualified table +- Multiple tables or SQL files can be selected together -Navigate through your previous AI prompts using arrow keys: +Large schemas are truncated. Explicit mentions are more reliable than asking the model to guess among every object, and they reduce tokens and metadata requests. -- Press **↑** (Up Arrow) to cycle through previous prompts -- Press **↓** (Down Arrow) to move forward in prompt history -- Works in both Ask and Agent modes -- Saves time when iterating on similar queries or explanations +## Global Instructions and Prompt Templates -The prompt history is preserved per session and helps you quickly reuse or modify previous AI requests without retyping. +Settings can store: -## Schema Context +- **Global instructions** injected into every request, such as naming rules, time zone, soft-delete conventions, or production constraints +- **Prompt templates** for reusable scenarios, such as “PostgreSQL-compatible SQL only” or “include index recommendations in every analysis” -AI prompts can include the current database type, connection name, database, current SQL, recent error, result preview, and schema context. Schema context contains tables, columns, indexes, and foreign keys. +Multiple templates can be active at once. DBX snapshots the selected templates and global instructions when the request is sent, so later edits do not alter an already running task. -When a schema is large, DBX truncates context. Use table mentions to prioritize the tables you want AI to reason about. +Templates enter model context. Do not put passwords, tokens, or unnecessary business data in them. Keep rules concise and non-conflicting because models may not resolve contradictory instructions as expected. -## SQL Safety Policy +## Writes and Production Safety -| SQL Category | DBX Behavior | -| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -| Read-only statements such as `SELECT`, `WITH`, `SHOW`, `DESCRIBE`, `DESC`, `EXPLAIN` | Can be auto-executed in Agent mode when the user clearly asks to query | -| Scoped low-risk writes such as `INSERT` or keyed `UPDATE` | Auto-execute only in clearly non-production environments; otherwise confirm | -| Multiple statements, `DELETE`, `MERGE`, `REPLACE`, `CREATE`, or unknown SQL | Confirm before execution | -| Dangerous statements such as `DROP`, `TRUNCATE`, `ALTER`, `RENAME`, or broad `UPDATE` | Blocked by the AI execution policy | +AI Agent execution boundaries are enforced by the backend, not only by prompting: -Production-like connection names, hosts, or database names make DBX more conservative. Generated SQL is still text from an AI model; review it like code before trusting it. +1. Read-only tools can be called as needed +2. Non-read-only SQL must first be shown as an explicit proposal +3. User confirmation binds authorization to the same connection, same database, and exact SQL text +4. Authorization applies only to the next run and never becomes a permanent write grant +5. AI Agents cannot receive write or DDL authorization for production databases; they can only return SQL for manual review in DBX -## Common Uses +Connection read-only protection, production protection, and database credentials remain upper bounds. A target change, SQL change, empty confirmation, or failed backend risk classification voids the grant. + +AI Agent never receives “write from now on” permission and cannot bypass MCP policy, connection read-only protection, or database privileges. See [Production Safety](/en/docs/production-safety) for the complete boundary. + +## Reasoning Effort and Thinking + +Providers expose different mechanisms: enumerated effort, reasoning levels, boolean thinking, integer budgets, or free-text options. DBX shows controls from the active model capability and remembers the selection per configuration and model. + +- Use provider default or lower effort for simple generation and explanation +- Increase effort for multi-table reasoning, difficult optimization, or error diagnosis +- Higher effort usually increases latency and cost without guaranteeing correctness + +Do not assume one UI label has identical semantics across providers. + +## Conversations, History, and Export + +- Use ↑ and ↓ to navigate prompt history +- Conversations can be saved with connection and database context +- Final AI analysis messages can be exported as Markdown with connection name and timestamp +- Markdown export contains the final answer only; internal reasoning and Agent steps are not appended + +Exports can still contain table names, SQL, result snippets, and business data. Review and redact them before sharing. + +## Common Tasks ### Generate SQL -Describe the result you want, and the assistant generates SQL using metadata from the current connection: +> Using `@orders` and `@customers`, generate a top-10 customer revenue query for the last 30 days. Return SQL only and do not execute it. -> Show the top 10 customers by order amount in the last 30 days +Explicitly saying “do not execute” clarifies intent. Review date functions, schema qualification, join keys, null handling, and row limits. -Example output: +### Analyze Real Data -```sql -SELECT c.name, SUM(o.amount) AS total_amount -FROM customers c -JOIN orders o ON c.id = o.customer_id -WHERE o.created_at >= NOW() - INTERVAL 30 DAY -GROUP BY c.id, c.name -ORDER BY total_amount DESC -LIMIT 10; -``` +> Query daily order counts from `@orders` for the last seven days, run the read-only query, and explain unusual spikes. -Before running generated SQL, check: +This is appropriate for Agent mode because it explicitly requests real results. -- Whether the tables and columns are correct -- Whether the time range matches your intent -- Whether aggregation and ordering are correct -- Whether the result should be limited +### Repair an Error -### Explain SQL +Provide the failed SQL, database error, and related tables. AI can inspect columns and dialect context, but version-specific behavior, privileges, locks, and execution plans still require human verification. -Select SQL and ask the assistant to explain its structure: +## Privacy and Troubleshooting -- What each subquery does -- How `JOIN` conditions connect tables -- What the `WHERE` clause filters -- How aggregation, grouping, and sorting work +- Cloud providers receive the prompt, schema summary, SQL, and bounded result context sent to the model; their privacy terms apply +- Ollama and local CLI can run locally, but the model process or CLI plugins may still have their own network and logging behavior +- Proxies, compatible endpoints, and custom gateways may log request content +- For connection-test failures, check endpoint, auth method, model name, proxy, and API-style compatibility +- When Agent repeatedly fails, reduce context, mention exact tables, narrow the task, and inspect tool errors instead of only increasing the turn limit -This is useful for reading legacy queries, reports, or complex views. +## Related Features -### Optimize SQL - -The assistant can suggest optimization directions, such as: - -- Possible full table scans -- Missing indexes -- Subqueries that may be rewritten as `JOIN` -- Sorting, deduplication, or aggregation that could be reduced - -AI optimization suggestions are advisory. Confirm performance with the database execution plan, data volume, and index design. - -### Fix Errors - -When SQL fails, send the error and query to the assistant for diagnosis. Common fixes include: - -- Syntax errors -- Misspelled table or column names -- Missing `GROUP BY` columns -- Type mismatches -- Dialect differences between database engines - -## Supported Providers - -DBX features an improved **searchable model dropdown** that makes it easy to find and select from available models across all supported providers. - - - - Use this for Claude models. Enter your API key, then choose or type the model you want to use from the searchable dropdown. - - - Use this for OpenAI models. Enter your API key, then choose or type the model you want to use. - - - Use this for services compatible with the OpenAI Chat Completions API, such as local model servers, enterprise gateways, or third-party model platforms. - - Configure: - - - Endpoint URL - - Model - - API key (required only when the service uses authentication) - - - - -## Privacy and Security - -AI requests may include your prompt, SQL, error messages, and the schema context needed to answer. Before using an external provider, confirm: - -- Whether sending this information is allowed -- Whether it includes sensitive field names, business logic, or sample data -- Whether your team has compliance rules for third-party model calls - -If you want AI agents to query databases through tools, continue with [MCP Integration](/en/docs/mcp). + + + Review the shared boundaries for AI, MCP, read-only connections, and production protection. + + + Connect external AI coding assistants to databases through DBX. + + + Understand the SQL, result, and metadata context available to AI. + + diff --git a/docs/content/docs/cli.cn.mdx b/docs/content/docs/cli.cn.mdx index e81717028d..5f6ddc6c22 100644 --- a/docs/content/docs/cli.cn.mdx +++ b/docs/content/docs/cli.cn.mdx @@ -1,6 +1,6 @@ --- title: DBX CLI -description: 在终端、脚本、CI 和 Codex 中使用 DBX 连接。 +description: 使用原生 DBX CLI 在终端、脚本、CI 和 Codex 中读取连接、Schema、查询结果和 AI 上下文。 --- DBX CLI 是独立命令行包，适合终端、脚本和 AI 编程助手工作流。它与 MCP Server 共享 DBX 连接存储和 SQL 安全规则。 @@ -78,7 +78,30 @@ dbx capabilities dbx capabilities --json ``` -当前直接执行支持 PostgreSQL/Redshift、MySQL 兼容数据库（MySQL、Doris、StarRocks）和 SQLite。其它数据库类型会使用 DBX 桌面端 bridge 或 DBX Agent/JDBC 基础设施。 +当前原生直连清单由 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 自动化入口。 ## 默认连接 @@ -101,7 +124,7 @@ dbx query local "select id, name from users" --format csv ## 查询控制 -`dbx query` 执行单条 SQL，默认只读。 +`dbx query` 对 SQL 连接执行一条 SQL，对 MongoDB 连接接受受支持的 Mongo shell 命令。Redis 不通过这个命令执行，需使用 MCP Redis 工具或 DBX 专用工作区。默认只读。 ```bash dbx query local "select * from users" --limit 50 --timeout 10s --json @@ -115,7 +138,9 @@ dbx query local "select * from users" --limit 50 --timeout 10s --json dbx query local "update users set name = 'Ada' where id = 1" --allow-writes ``` -`DROP`、`TRUNCATE`、`ALTER` 等危险 SQL 需要同时显式使用 `--allow-writes` 和 `--allow-dangerous-sql`。 +`DROP`、`TRUNCATE`、`ALTER` 等危险 SQL 需要同时显式使用 `--allow-writes` 和 `--allow-dangerous-sql`。显式事务语句仍会被 CLI 阻止；需要多步固定 Session 时使用 [MCP 有状态会话](/cn/docs/mcp#有状态查询会话) 或 DBX 编辑器。 + +生产数据库上的写入和 DDL 即使传入两个允许参数也会被阻止。CLI 使用连接/数据库生产识别、SQL 风险分类、连接只读保护和数据库权限形成多层边界；允许参数不是绕过生产保护的开关。 ## 以短横线开头的 SQL diff --git a/docs/content/docs/cli.mdx b/docs/content/docs/cli.mdx index 49c670b388..f15f1ca92c 100644 --- a/docs/content/docs/cli.mdx +++ b/docs/content/docs/cli.mdx @@ -1,6 +1,6 @@ --- title: DBX CLI -description: Use DBX connections from terminals, scripts, CI, and Codex. +description: Use the native DBX CLI to read connections, schemas, query results, and AI context from terminals, scripts, CI, and Codex. --- DBX CLI is a dedicated command line package for terminal, script, and coding-agent workflows. It shares DBX connection storage and SQL safety rules with the MCP server. @@ -80,7 +80,30 @@ dbx capabilities dbx capabilities --json ``` -Direct execution currently supports PostgreSQL/Redshift, MySQL-compatible databases (MySQL, Doris, StarRocks), and SQLite. Other database types use the DBX Desktop bridge or DBX Agent/JDBC infrastructure. +The CLI binary currently lists PostgreSQL, Redshift, MySQL, Doris, StarRocks, Manticore Search, SQLite, rqlite, KWDB, and QuestDB as direct-query types. `dbx capabilities` is authoritative for the installed version. Other types require a running DBX Desktop bridge or their Agent/external-driver infrastructure. + +## Execution Modes + +### Local Storage + +By default, CLI reads the same `dbx.db` connection store used by Desktop and MCP. `DBX_DATA_DIR` must point to the directory containing `dbx.db`. + +- Direct-query types can run while Desktop is closed +- Bridge types require Desktop to be running and discoverable through the bridge port file in the data directory +- Agent/JDBC, DuckDB, and other external-driver paths still require matching components installed through DBX +- `dbx open` is always a Desktop UI operation and returns `DBX_NOT_RUNNING` when the app is unavailable + +### DBX Web and Docker + +Set `DBX_WEB_URL` to use a deployed DBX Web backend instead of local connection storage: + +```bash +DBX_WEB_URL=https://dbx.example.com \ +DBX_WEB_PASSWORD='your-login-password' \ +dbx connections list --json +``` + +`DBX_WEB_PASSWORD` is the Web login password. In Web mode, connections, permissions, drivers, and file paths belong to the server environment. `dbx open` still targets a local Desktop bridge and should not be treated as a remote Web automation API. ## Default Connection @@ -103,7 +126,7 @@ Errors are written to stderr and return a non-zero exit code. ## Query Controls -`dbx query` executes one SQL statement. It is read-only by default. +`dbx query` executes SQL for SQL connections and accepts supported Mongo shell commands for MongoDB connections. Redis is not executed through this command; use the MCP Redis tool or the DBX workspace instead. Query mode is read-only by default. ```bash dbx query local "select * from users" --limit 50 --timeout 10s --json @@ -117,7 +140,9 @@ Use `--allow-writes` for non-dangerous write statements: dbx query local "update users set name = 'Ada' where id = 1" --allow-writes ``` -Dangerous SQL such as `DROP`, `TRUNCATE`, and `ALTER` requires both `--allow-writes` and `--allow-dangerous-sql`. +Dangerous SQL such as `DROP`, `TRUNCATE`, and `ALTER` requires both `--allow-writes` and `--allow-dangerous-sql`. Explicit transaction statements remain blocked by CLI; use [MCP stateful sessions](/en/docs/mcp#stateful-query-sessions) or the DBX editor for pinned multi-step sessions. + +Writes and DDL against production databases remain blocked even when both flags are present. Production detection, SQL risk classification, connection read-only protection, and database privileges form independent upper bounds; the flags are not a production bypass. ## SQL Starting With a Dash diff --git a/docs/content/docs/cloud-sync.cn.mdx b/docs/content/docs/cloud-sync.cn.mdx index 8cbf1bf2bf..a3e4a76292 100644 --- a/docs/content/docs/cloud-sync.cn.mdx +++ b/docs/content/docs/cloud-sync.cn.mdx @@ -1,12 +1,14 @@ --- -title: 云同步与备份 -description: 使用 WebDAV、GitHub Gist 或 Gitee 代码片段同步 DBX 连接、设置和 SQL 库。 +title: DBX 配置云同步 +description: 使用 WebDAV、GitHub Gist 或 Gitee 代码片段同步 DBX 连接、设置和保存的 SQL。 --- DBX 可以把连接配置、界面设置和保存的 SQL 组成一个快照，上传到 WebDAV 或私有代码片段，并在另一台设备恢复。 +云同步备份的是 DBX 配置，不会读取或备份连接中的业务数据库。表结构和数据请使用 [数据库导出](/cn/docs/database-export)；Desktop 定时 MySQL/PostgreSQL 备份请使用 [数据库备份](/cn/docs/database-backup)。 + 在 **设置 → 同步** 中选择同步方式： - **WebDAV**：适合已有 NAS、Nextcloud、坚果云或其他 WebDAV 服务的用户，支持定时自动上传。 diff --git a/docs/content/docs/cloud-sync.mdx b/docs/content/docs/cloud-sync.mdx index d72d5969fc..3cd5c07926 100644 --- a/docs/content/docs/cloud-sync.mdx +++ b/docs/content/docs/cloud-sync.mdx @@ -1,5 +1,5 @@ --- -title: Cloud Sync and Backup +title: DBX Configuration Cloud Sync description: Sync DBX connections, settings, and saved SQL with WebDAV, GitHub Gist, or Gitee snippets. --- @@ -7,6 +7,8 @@ description: Sync DBX connections, settings, and saved SQL with WebDAV, GitHub G DBX can package connections, application settings, and saved SQL into a snapshot, upload it to WebDAV or a private code snippet, and restore it on another device. +Cloud Sync backs up DBX configuration. It does not read or back up the business databases behind your connections. Use [Database Export](/en/docs/database-export) for schema and data, or [Database Backup](/en/docs/database-backup) for scheduled Desktop MySQL/PostgreSQL backups. + Choose a provider under **Settings → Sync**: - **WebDAV**: Best when you already use a NAS, Nextcloud, or another WebDAV service. Supports scheduled uploads. diff --git a/docs/content/docs/config-export.cn.mdx b/docs/content/docs/config-export.cn.mdx index 7e72fb5a74..105a6bad3a 100644 --- a/docs/content/docs/config-export.cn.mdx +++ b/docs/content/docs/config-export.cn.mdx @@ -5,6 +5,8 @@ description: 导出数据库连接配置（AES-256-GCM 加密），安全地在 导出你的数据库连接配置（含加密密码），用 AES-256-GCM 加密保护，安全地在不同电脑之间迁移。 +这里导出的是 DBX 连接配置，不包含业务数据库的表结构或数据，也不是数据库备份。数据库内容请使用 [数据库导出](/cn/docs/database-export) 或 [数据库备份](/cn/docs/database-backup)。 + ## 导出 @@ -41,5 +43,6 @@ description: 导出数据库连接配置（AES-256-GCM 加密），安全地在 | URL 参数、SSL、SSH、代理、可见数据库设置 | 包含 | | 数据库密码、SSH 密码、SSH 密钥密码、连接字符串 | 包含，并在导出文件中加密 | | 厂商 JDBC 驱动 JAR 文件 | 不包含；目标机器需要重新安装或导入 | +| 已保存 SQL、界面/编辑器设置和侧边栏布局 | 不包含；需要迁移这些内容时使用 [云同步](/cn/docs/cloud-sync) | 如果要迁移 JDBC 连接，先在这里导出连接配置，再在目标机器通过 [JDBC 插件](/cn/docs/plugins) 安装插件并导入驱动 JAR。 diff --git a/docs/content/docs/config-export.mdx b/docs/content/docs/config-export.mdx index 419780bc1b..cdfcf9e782 100644 --- a/docs/content/docs/config-export.mdx +++ b/docs/content/docs/config-export.mdx @@ -5,6 +5,8 @@ description: Export database connections with AES-256-GCM encrypted passwords. M Export your database connections with encrypted passwords (AES-256-GCM). Securely migrate between machines. +This exports DBX connection configuration, not business database schema or data, and it is not a database backup. Use [Database Export](/en/docs/database-export) or [Database Backup](/en/docs/database-backup) for database contents. + ## Export @@ -41,5 +43,6 @@ Import also supports plain JSON files from older versions (without passwords) an | URL parameters, SSL, SSH, proxy, visible database settings | Yes | | Database password, SSH password, SSH key passphrase, connection string | Yes, encrypted in the export file | | Vendor JDBC driver JAR files | No; reinstall or re-import drivers on the target machine | +| Saved SQL, UI/editor settings, and sidebar layout | No; use [Cloud Sync](/en/docs/cloud-sync) to migrate them | For JDBC migrations, export the connection settings here, then use [JDBC Plugin](/en/docs/plugins) to install the plugin and import driver JARs on the destination machine. diff --git a/docs/content/docs/connection-import.cn.mdx b/docs/content/docs/connection-import.cn.mdx index b85b6cc257..e13c1601be 100644 --- a/docs/content/docs/connection-import.cn.mdx +++ b/docs/content/docs/connection-import.cn.mdx @@ -1,6 +1,6 @@ --- title: 连接导入 -description: 从 Navicat 和 DBeaver 导入连接，切换工具时无需重新输入连接信息。 +description: 从 Navicat、DBeaver 和 DataGrip 导入连接、分组和可识别的数据库类型。 --- DBX 可以从其他数据库工具导入连接，在切换工具时无需手动重新创建大量连接。 @@ -11,6 +11,7 @@ DBX 可以从其他数据库工具导入连接，在切换工具时无需手动 | ------- | --------------- | ---------------------------------------- | | Navicat | `.ncx` 导出文件 | 主机、端口、用户名、数据库类型、连接名称 | | DBeaver | 连接配置文件 | 主机、端口、用户名、数据库类型、连接名称 | +| DataGrip | `dataSources.xml` 等项目/全局配置 | JDBC URL、驱动、连接名称、分组和可读取凭据 | 导入的连接保留原始连接名称和类型。其他工具以加密格式存储的密码无法解密——导入后需要重新输入密码。 @@ -32,6 +33,15 @@ DBX 可以从其他数据库工具导入连接，在切换工具时无需手动 ### 检查并完成 DBX 从配置中提取连接信息。重新输入无法解密的密码。 +## 导入 DataGrip 连接 + + + ### 选择配置 在 DBX 中选择**导入 DataGrip**，再选择 DataGrip 项目或全局配置中的 `dataSources.xml`；同目录的 local 配置会用于补充字段。 + ### 检查类型识别 DBX 会结合 driver reference、数据库产品名、JDBC subprotocol 和驱动类识别数据库。KingBase 等数据库会映射到对应 DBX profile，未知驱动保留为通用 JDBC。 + ### 检查分组 DataGrip 的分组路径会导入为 DBX 连接分组，方便保留项目组织方式。 + ### 补充凭据 macOS 上 DBX 会在允许时读取 DataGrip 钥匙串密码；其它加密或不可访问的凭据仍需手动填写。 + + ## 导入后 导入的连接与手动创建的连接一同出现在侧边栏中。你应该： @@ -50,3 +60,5 @@ DBX 可以从其他数据库工具导入连接，在切换工具时无需手动 | SSH 隧道密钥 | 密钥文件路径可能因机器而异，需要重新选择密钥文件 | | 自定义驱动配置 | 驱动路径和版本是工具特定的 | | 代理设置 | 在连接的代理标签页中重新配置 | + +导入只创建连接草稿，不证明连接一定可用。保存前检查数据库 profile、JDBC URL、SSL、SSH、代理和数据库名，保存后逐个执行连接测试。 diff --git a/docs/content/docs/connection-import.mdx b/docs/content/docs/connection-import.mdx index e85168367d..1a8207df85 100644 --- a/docs/content/docs/connection-import.mdx +++ b/docs/content/docs/connection-import.mdx @@ -1,6 +1,6 @@ --- title: Connection Import -description: Import connections from Navicat and DBeaver so you can switch to DBX without re-entering connection details. +description: Import connections, groups, and recognized database profiles from Navicat, DBeaver, and DataGrip. --- DBX can import connections from other database tools, saving you from manually re-creating dozens of connections when switching tools. @@ -11,6 +11,7 @@ DBX can import connections from other database tools, saving you from manually r | ------- | ------------------------------ | ---------------------------------------------------- | | Navicat | `.ncx` export files | Host, port, username, database type, connection name | | DBeaver | Connection configuration files | Host, port, username, database type, connection name | +| DataGrip | Project or global files such as `dataSources.xml` | JDBC URL, driver, connection name, groups, and readable credentials | Imported connections preserve the original connection name and type. Passwords stored in encrypted format by other tools cannot be decrypted — you will need to re-enter passwords after import. @@ -32,6 +33,15 @@ DBX can import connections from other database tools, saving you from manually r ### Review and Complete DBX extracts connection details from the configuration. Re-enter any passwords that could not be decrypted. +## Import DataGrip Connections + + + ### Select Configuration Choose **Import DataGrip** in DBX and select `dataSources.xml` from a DataGrip project or global configuration. A matching local file in the same directory can supply additional fields. + ### Review Type Detection DBX combines driver references, database product names, JDBC subprotocols, and driver classes. Databases such as KingBase map to their DBX profile; unknown drivers remain generic JDBC. + ### Review Groups DataGrip group paths are imported as DBX connection groups so project organization is preserved. + ### Complete Credentials On macOS, DBX reads DataGrip Keychain passwords when available. Other encrypted or inaccessible credentials must be entered manually. + + ## After Import Imported connections appear in the sidebar alongside manually created ones. You should: @@ -50,3 +60,5 @@ Imported connections appear in the sidebar alongside manually created ones. You | SSH tunnel keys | Key file paths may differ between machines; re-select the key file | | Custom driver configurations | Driver paths and versions are tool-specific | | Proxy settings | Re-configure in the connection's Proxy tab | + +Import creates connection drafts; it does not prove they are reachable. Review the database profile, JDBC URL, SSL, SSH, proxy, and database fields before saving, then test every imported connection. diff --git a/docs/content/docs/contributing.cn.mdx b/docs/content/docs/contributing.cn.mdx index 605893a69a..9f67487b57 100644 --- a/docs/content/docs/contributing.cn.mdx +++ b/docs/content/docs/contributing.cn.mdx @@ -253,6 +253,15 @@ 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 前端： diff --git a/docs/content/docs/contributing.mdx b/docs/content/docs/contributing.mdx index 1368032b0e..382c70877c 100644 --- a/docs/content/docs/contributing.mdx +++ b/docs/content/docs/contributing.mdx @@ -253,6 +253,15 @@ docs/content/docs/meta.json docs/content/docs/meta.cn.json ``` +Run the fast content check and then the full documentation build before submitting: + +```bash +pnpm --dir docs content:check +make docs-build +``` + +`content:check` verifies bilingual page pairs, navigation coverage and ordering, frontmatter, duplicate titles, and internal links. `make docs-build` runs the check again and validates the Next.js production build. + ### Path B: Change the Desktop Frontend Frontend code lives in `apps/desktop/src/`. Run the full desktop app or start only the web frontend: diff --git a/docs/content/docs/data-grid.cn.mdx b/docs/content/docs/data-grid.cn.mdx index 90a81a84d8..d650f8cf74 100644 --- a/docs/content/docs/data-grid.cn.mdx +++ b/docs/content/docs/data-grid.cn.mdx @@ -1,166 +1,177 @@ --- title: 数据表格 -description: 在 DBX 中浏览、筛选、编辑、预览 SQL 并导出表数据。 +description: 在 DBX 中浏览、筛选、编辑、校验、复制和导出查询结果或表数据。 --- -数据表格用于查看查询结果或表数据。它适合处理两类场景：快速浏览数据，以及在确认 SQL 后进行小范围数据修改。 +数据表格用于显示查询结果和表数据。它同时覆盖只读分析和小范围数据修改：浏览大结果集、筛选排序、检查复杂值、批量复制，以及在 DBX 能可靠识别目标行时生成并预览 `INSERT`、`UPDATE` 或 `DELETE`。 -## 浏览数据 +Redis、MongoDB、向量数据库、HBase 等系统使用各自的专项数据界面。这里主要说明关系型和兼容 SQL 数据源的结果表格。 -DBX 使用虚拟滚动渲染表格，只渲染当前可视区域内的行。大表浏览时，滚动和选择操作不会因为一次性渲染所有行而明显变慢。 +## 浏览与布局 -常用浏览操作： +DBX 使用虚拟滚动，只渲染当前可视区域。常用浏览操作包括： -- 拖拽列边缘调整列宽 -- 双击列边缘根据内容自适应列宽 -- 点击列头排序 -- 使用行号定位数据 -- 打开单元格详情查看长文本、JSON 或其他复杂值 +- 拖拽列边缘调整宽度，或双击按内容自适应 +- 拖拽列头重排顺序，并按表或查询保存布局 +- 冻结左侧或右侧列，横向滚动时保留关键字段 +- 显示、隐藏和搜索列；搜索可以同时匹配列名和字段注释 +- 调整表格字体、字号、行高和列宽密度 +- 在标准视图与转置视图之间切换 +- 查看连接名、结果来源、字段类型和字段注释 -## 过滤与排序 +列宽、列顺序、冻结状态和多个显示选项可以跨会话保留。需要恢复时，在视图选项中重置当前表格布局。 -| 功能 | 适合场景 | -| -------- | ---------------------------------------- | -| 搜索 | 在当前结果中快速定位包含关键字的行 | -| WHERE | 在数据库层面筛选数据，适合大表和精确条件 | -| ORDER BY | 在数据库层面排序，适合稳定复现查询结果 | +## 过滤、搜索与排序 -大表场景优先使用 `WHERE` 和 `ORDER BY`。它们在数据库层面执行，通常比客户端搜索更稳定。 +| 方式 | 执行位置 | 适合场景 | +| --- | --- | --- | +| 表格搜索 | 当前已加载结果 | 快速定位文本、字段值或字段注释 | +| 本地值过滤 | 当前已加载结果 | 临时勾选值、列表或范围，不重新查询数据库 | +| `WHERE` | 数据库 | 大表、精确条件、可使用索引的筛选 | +| `ORDER BY` | 数据库 | 跨页稳定排序和可复现结果 | +| 当前页排序 | 客户端当前页 | 临时比较已加载数据，不改变数据库查询 | -## 行内编辑 +`WHERE` 和 `ORDER BY` 输入支持较长表达式、折叠/展开和基于字段元数据的条件补全。可以在设置中配置打开表时的默认排序。 -可以直接在表格里修改数据： - -- **修改单元格**：双击单元格进入编辑状态 -- **新增行**：在表格中添加一行待插入记录 -- **删除行**：选中行后标记为待删除 -- **设置 NULL**：在单元格详情面板中明确写入 `NULL` - -所有修改都会先暂存在本地。保存前，DBX 会展示即将执行的 SQL。 +面对大表时，优先使用数据库侧 `WHERE` 和 `ORDER BY`。客户端搜索、值过滤和当前页排序不会减少数据库实际返回的数据量。 ## 什么时候可以编辑 -当 DBX 能识别目标表，并且有足够的键信息生成可审查的 `UPDATE`、`INSERT` 或 `DELETE` 语句时，结果才可编辑。直接打开表数据通常可以编辑；临时 join、聚合、表达式或没有可用主键/行标识的结果会视为只读。 +只有当 DBX 能识别目标表，并有足够的主键或行标识生成可审查 SQL 时，结果才可编辑。 -| 结果类型 | 通常行为 | -| -------------------------- | ------------------------------------ | -| 打开的表数据 | 数据库和表支持时可编辑 | -| 简单 `SELECT * FROM table` | 有主键或行标识时通常可编辑 | -| Join、聚合、计算列 | 只读结果 | -| Redis 或 MongoDB 视图 | 使用对应专用编辑器，不走关系型行 SQL | +| 结果类型 | 通常行为 | +| --- | --- | +| 从对象树直接打开的表数据 | 数据库和表支持时可编辑 | +| 简单 `SELECT` | 能解析单一目标表且有可靠行标识时可编辑 | +| Join、聚合、表达式、计算列 | 通常只读 | +| 没有主键或可靠唯一标识 | 通常只读，避免生成不安全条件 | +| 连接被标记为只读 | 所有可识别修改都被拒绝 | -## SQL 预览 +只读单元格仍可以打开详情、复制和导出。需要了解无法编辑的原因时，查看数据表头和单元格详情中的只读说明。 -数据修改不会在编辑后立即写入数据库。点击保存前，请先检查 SQL 预览，尤其是在生产环境连接上。 +## 编辑、新增与删除 -SQL 预览会展示 `UPDATE`、`INSERT` 或 `DELETE` 语句。这个步骤可以帮助你确认： +- **修改单元格**：双击进入编辑，或在详情面板中处理长文本 +- **新增行**：创建一行或多行待插入记录 +- **批量粘贴**：把制表符分隔的数据直接粘贴到新增行区域 +- **克隆行**：复制选中记录作为新行，并按需要排除主键 +- **删除行**：把选中记录标记为待删除 +- **设置 NULL**：明确写入数据库 `NULL`，与空字符串区分 +- **使用默认值**：让新增字段使用数据库默认值（数据库和字段支持时） +- **生成值**：为选中单元格使用内置数据生成器填充测试值 -- 更新条件是否正确 -- 新增行的字段是否完整 -- 删除操作是否命中预期行 -- `NULL`、空字符串和默认值是否符合预期 +日期时间、枚举、JSON 和其他类型会在可识别时使用专用编辑控件。批量编辑前应确认所选区域和目标字段类型一致。 -如果预览 SQL 的影响范围过大，请取消保存，先缩小筛选条件或选择范围。 +## SQL 预览与保存 -## 单元格详情 +所有关系型数据修改先保存在本地待提交状态。点击保存时，DBX 会展示生成的 `INSERT`、`UPDATE` 和 `DELETE` SQL。 -点击单元格可以打开详情面板。它适合处理表格内不方便直接编辑的值： +保存前重点检查： -- 长文本 -- JSON -- SQL 片段 -- 多行内容 -- 需要显式设置为 `NULL` 的字段 +- `UPDATE` 和 `DELETE` 的主键或条件是否只命中目标行 +- 新增行是否遗漏必填字段 +- `NULL`、空字符串、默认值和自动生成值是否符合预期 +- 批量操作是否包含了未注意到的行 +- 当前连接和数据库是否正确 + +生产环境保护启用后，保存仍会进入统一的生产写入确认。完整规则见 [生产环境与写入安全](/cn/docs/production-safety)。 + +SQL 预览是最后检查点，不是事务审批系统。重要生产变更仍应使用最小权限账号、备份和团队变更流程。 + +## 单元格详情与复杂值预览 + +单元格详情用于表格内不适合直接显示或编辑的值： + +- 长文本、多行文本、SQL 和带语法高亮的 JSON +- JSON 格式化、压缩和路径查看 +- 二进制值的十六进制与 ASCII 查看 +- 图片 URL、图片二进制或可识别图像数据预览 +- 日期、时间和带时区值的专用编辑与格式化 +- 几何/空间数据的文本、坐标和地图预览，包括可识别的 SRID +- 被截断值、只读值和字段元数据说明 + +详情面板中的格式化和预览通常只影响显示；真正修改值时，仍会进入待保存状态并生成 SQL。 ## 转置视图 -切换转置视图可互换行和列。适用场景： +转置视图交换行列，适合： -- 表有很多列但行数较少 -- 需要并排比较列的元数据（类型、默认值、可空标志） -- 查看具有宽列的单个行 +- 单行但字段很多的记录 +- 并排查看字段类型、注释、默认值和可空状态 +- 对比少量记录的大字段 -转置视图保留所有表格功能：排序、过滤、编辑和导出均可正常使用。 +转置视图支持选择、复制、详情、编辑和导航。排序与数据库侧过滤仍以原始结果方向为准。 ## 列格式化器 -自定义列格式化器让你控制特定列值的显示方式： +列格式化器只改变显示，不修改底层数据。常见选项包括： -- **日期时间格式化**：为日期和时间列选择显示格式 -- **JSON 路径提取**：使用 JSONPath 表达式从 JSON/JSONB 列中提取特定字段 -- **值掩码**：隐藏或部分掩码敏感值 -- **自定义模板**：为列定义自己的显示模板 +- 全局或列级日期/时间格式 +- JSON 路径提取 +- 值掩码 +- 自定义显示模板 +- 数字、布尔值和数据库类型对应的显示方式 -从列头菜单配置格式化器。格式化器仅影响显示——不会更改底层数据。 +如果需要恢复原始值，清除当前列格式化器即可。 -## 单元格详情编辑器 +## 选择、复制与导航 -单元格详情面板为单个单元格值提供完整的编辑器： +表格支持单元格、矩形区域、整行和多行选择。选择后可以： -- **值编辑器**：在更大的文本区域中编辑单元格内容，JSON 和 SQL 具有语法高亮 -- **设置 NULL**：将单元格显式设置为 NULL -- **图片预览**：当单元格包含图片 URL 时，详情面板会显示渲染后的预览 -- **时间编辑器**：日期和时间单元格使用专用的日期/时间选择器 +- 查看数量、求和等选择摘要（适用于可计算值） +- 复制为 TSV、CSV、JSON、Markdown、SQL `INSERT` 或 `UPDATE` +- 复制单元格、选中区域、整行或带表头结果 +- 选择列名引用方式，包括数据库标识符引号 +- 使用字段注释作为复制列名（适合面向业务的表格） +- 为多行生成单条批量 `INSERT`，或逐行 `INSERT` +- 排除主键后复制为新记录模板 -## 多行操作 +当字段存在可识别外键关系时，可以从单元格跳转到被引用记录。这个入口依赖元数据和目标连接权限。 -选中多行执行批量操作： +## 导出 -- **批量克隆**：一次性复制多行 -- **批量删除**：一次性标记多行为待删除 -- **批量复制**：以 TSV、CSV、JSON、Markdown 或 INSERT 语句格式复制多行 -- **复制为 INSERT**：生成包含多行值的单条 `INSERT` 语句 -- **复制为 UPDATE**：为选中的行生成 `UPDATE` 语句 -- **复制不含主键**：生成排除自增主键的 INSERT 语句 +| 格式 | 适合场景 | +| --- | --- | +| CSV / TSV | 电子表格、脚本和文本交换 | +| JSON | API 调试和程序处理 | +| Markdown | Issue、PR、文档和聊天 | +| XLSX | Excel 交付；超出单工作表上限时会拆分工作表 | +| SQL | 复用选中数据生成 `INSERT` 或 `UPDATE` | -## 列头控件 +导出查询结果时，DBX 会按当前结果和选择范围处理。导出前确认当前页面、筛选、排序和选择区域，避免把“当前可见数据”误认为完整表。 -列头提供快速操作入口： +## 自动刷新、分页与大结果集 -- **排序**：点击切换升序、降序或清除排序。右键点击可打开排序上下文菜单。 -- **列可见性**：从可搜索的清单中显示或隐藏列 -- **本地列过滤**：通过勾选特定值在当前结果集中过滤 -- **紧凑模式**：在设置中启用后，列头操作（排序、格式化、过滤）收起为单个下拉菜单，给列名留出更多空间 -- **紧凑过滤构建器**：在紧凑 UI 中使用多个条件构建复杂的客户端过滤 -- **拖放列重排序**：点击并拖动列头即可重新排序。列顺序按表/查询保存，跨会话持久化 +- 打开表时的分页大小可以配置并持久化 +- 自动刷新适合监控变化较快的小结果集 +- 查询执行结果可以保留多个运行记录或固定需要对比的结果 +- 大结果集只在可视区域渲染，但数据库查询和传输成本仍取决于实际返回行数 +- 排序、过滤或自动刷新会重新获取数据，未保存编辑可能阻止或影响刷新 -## 单元格详情编辑器 +自动刷新不适合正在编辑的数据，也不能替代监控系统。大表请先缩小查询范围，再提高刷新频率。 -单元格详情面板为单个单元格值提供完整的编辑器： +## 常见问题 -- **值编辑器**：在更大的文本区域中编辑单元格内容，JSON 和 SQL 具有语法高亮 -- **设置 NULL**：将单元格显式设置为 NULL -- **图片预览**：当单元格包含图片 URL 时，详情面板会显示渲染后的预览 -- **时间编辑器**：日期和时间单元格使用专用的日期/时间选择器 -- **二进制数据十六进制查看器**：以十六进制格式查看二进制数据，同时显示十六进制和 ASCII 表示，便于检查原始二进制内容 +| 现象 | 检查项 | +| --- | --- | +| 结果只能查看不能编辑 | 是否为 Join/聚合；是否有主键；连接是否只读；驱动是否支持编辑 | +| 过滤后行数没有减少 | 使用的是客户端搜索/过滤，而不是数据库侧 `WHERE` | +| 排序只影响当前页 | 当前使用了本地排序；需要跨页稳定排序时改用 `ORDER BY` | +| 粘贴后列错位 | 剪贴板列数、当前选中起始列、隐藏列和字段顺序 | +| 图片或空间数据没有预览 | 值格式、MIME/二进制类型、几何编码或 SRID 无法识别 | +| 导出数量和预期不同 | 当前页、选择区域、客户端过滤和数据库查询范围 | -## 导出与复制 - -| 格式 | 用途 | -| -------- | ------------------------------------------------------ | -| CSV | 给 Excel、Numbers 或其他表格工具使用 | -| JSON | 给脚本、接口调试或程序处理使用 | -| Markdown | 粘贴到 Issue、PR、文档或聊天中 | -| INSERT | 将选中行复制为可执行的 `INSERT` 语句（支持单行或批量） | -| UPDATE | 将选中行复制为可执行的 `UPDATE` 语句 | -| XLSX | 从表格上下文菜单直接导出为 Excel 格式 | - -### 复制带表头 - -DBX 支持在复制数据时包含列头： - -- **复制列名**：只复制当前选择的列名 -- **复制选择区域与表头**：复制选中的单元格及其列头 -- **复制为带表头的 TSV/CSV**：在制表符分隔或逗号分隔输出中包含表头 - -这在将数据粘贴到电子表格、文档或分享查询结果时特别有用，可以保留列的上下文信息。 - -导出前建议先确认当前筛选和排序条件，避免导出范围和预期不一致。 - -## 分页与大结果集 - -DBX 会通过分页和虚拟滚动让大结果集保持响应。面对大表时，优先使用数据库侧的 `WHERE` 和 `ORDER BY`，不要只依赖客户端搜索；数据库可以利用索引，并返回更小的结果集。分页大小可配置并跨会话持久化。 - -### 行号显示 - -数据表格在最左侧列显示行号。在翻页浏览大结果集时，行号会反映当前页面位置，帮助你跟踪正在查看的记录。当应用排序或筛选时，行号会自动调整。 + + + 使用补全、执行目标、多结果和查询历史生成数据表格。 + + + 从 CSV、TSV、JSON 或 Excel 导入大量数据。 + + + 在不同连接或数据库引擎之间复制表数据。 + + + 配置只读连接、生产确认和 MCP 权限。 + + diff --git a/docs/content/docs/data-grid.mdx b/docs/content/docs/data-grid.mdx index ee38f22044..d39cc0ee28 100644 --- a/docs/content/docs/data-grid.mdx +++ b/docs/content/docs/data-grid.mdx @@ -1,166 +1,177 @@ --- title: Data Grid -description: Browse, filter, edit, preview SQL, and export table data in DBX. +description: Browse, filter, edit, validate, copy, and export query results or table data in DBX. --- -The data grid displays query results and table data. It is designed for two common workflows: inspecting data quickly and making small, reviewable edits. +The data grid displays query results and table data. It covers both read-only analysis and small, controlled changes: browsing large result sets, filtering and sorting, inspecting complex values, bulk copying, and generating previewable `INSERT`, `UPDATE`, or `DELETE` statements when DBX can reliably identify the target rows. -## Browse Data +Redis, MongoDB, vector databases, HBase, and other systems use their own specialized data interfaces. This page focuses on relational and SQL-compatible result grids. -DBX uses virtual scrolling, rendering only the rows visible on screen. Large tables remain responsive because the grid does not render every row at once. +## Browsing and Layout -Common browsing actions: +DBX uses virtual scrolling and renders only the visible area. Common browsing operations include: -- Drag column borders to resize columns -- Double-click a column border to auto-fit width -- Click column headers to sort -- Use row numbers to locate records -- Open cell details for long text, JSON, or other complex values +- Dragging column edges to resize, or double-clicking to fit content +- Dragging headers to reorder columns and saving the layout per table or query +- Freezing columns on the left or right while scrolling horizontally +- Showing, hiding, and searching columns by name or comment +- Adjusting grid font, font size, row height, and column-width density +- Switching between the standard and transposed views +- Inspecting the connection name, result source, data types, and column comments -## Filter and Sort +Column widths, order, frozen state, and several display preferences can persist across sessions. Use view options to reset the current grid layout. -| Feature | Best For | -| -------- | --------------------------------------------------------------- | -| Search | Finding rows in the current result set | -| WHERE | Database-level filtering for large tables or precise conditions | -| ORDER BY | Database-level ordering for reproducible results | +## Filtering, Search, and Sorting -For large tables, prefer `WHERE` and `ORDER BY`. They run in the database and are usually more reliable than client-side search. +| Method | Execution location | Best for | +| --- | --- | --- | +| Grid search | Currently loaded result | Quickly locating text, values, or column comments | +| Local value filter | Currently loaded result | Temporary value, list, or range filtering without another database query | +| `WHERE` | Database | Large tables, precise conditions, and index-backed filtering | +| `ORDER BY` | Database | Stable cross-page sorting and reproducible results | +| Current-page sort | Client page | Temporary comparison of loaded rows without changing the query | -## Inline Editing +The `WHERE` and `ORDER BY` inputs support long expressions, collapse/expand behavior, and metadata-based condition suggestions. The default sort used when opening tables can be configured in settings. -You can edit data directly in the grid: +For large tables, prefer database-side `WHERE` and `ORDER BY`. Client search, value filters, and current-page sorting do not reduce the amount of data returned by the database. -- **Update a cell**: double-click a cell and edit its value -- **Insert a row**: add a pending row in the grid -- **Delete rows**: select rows and mark them for deletion -- **Set NULL**: explicitly write `NULL` from the cell detail panel +## When Results Are Editable -All changes are staged locally first. Before saving, DBX shows the SQL it is about to execute. +Results are editable only when DBX can identify the target table and has enough key or row-identity information to generate reviewable SQL. -## When Editing Is Available +| Result type | Typical behavior | +| --- | --- | +| Table data opened from the object tree | Editable when the database and table support it | +| Simple `SELECT` | Editable when one target table and reliable row identity can be resolved | +| Joins, aggregates, expressions, computed columns | Usually read-only | +| No primary key or reliable unique identity | Usually read-only to avoid unsafe conditions | +| Connection marked read-only | All recognizable mutations are rejected | -Editing is available when DBX can identify the target table and enough key information to generate reviewable `UPDATE`, `INSERT`, or `DELETE` statements. Simple table browsing is usually editable. Ad-hoc joins, aggregates, expressions, or result sets without usable keys are treated as read-only. +Read-only cells can still open details, copy, and export. Check the data header or cell details for the reason a result cannot be edited. -| Result Type | Typical Behavior | -| ----------------------------------- | ---------------------------------------------------------- | -| Opened table data | Editable when the database and table support edits | -| Simple `SELECT * FROM table` | Often editable if primary key or row identity is available | -| Joins, aggregates, computed columns | Read-only result set | -| Redis or MongoDB views | Use their dedicated editors instead of relational row SQL | +## Editing, Inserting, and Deleting -## SQL Preview +- **Edit a cell** by double-clicking or using the detail panel for long content +- **Add rows** as one or more pending inserts +- **Paste in bulk** from tab-separated clipboard data into new rows +- **Clone rows** as new records, optionally excluding primary keys +- **Delete rows** by marking selected records for deletion +- **Set NULL** explicitly instead of writing an empty string +- **Use defaults** for new fields where the database and column support it +- **Generate values** with built-in test-data generators for selected cells -Edits are not written to the database immediately. Before saving, review the SQL preview carefully, especially on production connections. +DBX uses specialized controls for recognizable date/time, enum, JSON, and related types. Before bulk editing, verify that the selected region matches the target column types. -The preview shows `UPDATE`, `INSERT`, or `DELETE` statements. Use it to confirm: +## SQL Preview and Save -- Update conditions target the intended rows -- Inserted rows contain the expected fields -- Delete operations match the expected records -- `NULL`, empty strings, and default values are handled correctly +Relational mutations remain local until saved. DBX then shows the generated `INSERT`, `UPDATE`, and `DELETE` statements. -If the preview looks too broad, cancel the save and narrow the filter or selection first. +Review these details before saving: -## Cell Details +- Whether `UPDATE` and `DELETE` conditions identify only the intended rows +- Whether new rows contain every required field +- Whether `NULL`, empty strings, defaults, and generated values are correct +- Whether a bulk selection includes unnoticed rows +- Whether the active connection and database are correct -Click a cell to open the detail panel. It is useful for values that are awkward to edit directly inside a table: +When production protection is active, saving still enters the shared production-write confirmation flow. See [Production and Write Safety](/en/docs/production-safety). -- Long text -- JSON -- SQL fragments -- Multi-line content -- Fields that should be explicitly set to `NULL` +SQL preview is a final review point, not a change-approval system. Important production changes still need least-privilege accounts, backups, and team processes. -## Transpose View +## Cell Details and Complex Value Preview -Toggle the transpose view to swap rows and columns. This is useful when: +Cell details handle values that do not fit well in the grid: -- A table has many columns but few rows -- You want to compare column metadata (types, defaults, nullable flags) side by side -- You are inspecting a single row with wide columns +- Long or multiline text, SQL, and syntax-highlighted JSON +- JSON formatting, compacting, and path inspection +- Binary data shown as hexadecimal and ASCII +- Image URLs, image binaries, and recognizable image data +- Dedicated editing and formatting for dates, times, and timezone-aware values +- Text, coordinate, and map previews for geometry/spatial values, including recognizable SRIDs +- Truncated values, read-only explanations, and column metadata -The transpose view preserves all grid features: sorting, filtering, editing, and export work the same way. +Formatting and preview actions usually affect display only. Actual edits still become pending changes and generate SQL. + +## Transposed View + +The transposed view swaps rows and columns and works well for: + +- A single record with many fields +- Comparing data types, comments, defaults, and nullability +- Inspecting a few records with wide values + +Selection, copying, details, editing, and navigation remain available. Database-side sorting and filtering still use the original result orientation. ## Column Formatters -Custom column formatters let you control how specific column values are displayed: +Column formatters change display without mutating data. Options include: -- **Datetime formatting**: Choose a display format for date and time columns -- **JSON path extraction**: Extract a specific field from JSON/JSONB columns using a JSONPath expression -- **Value masking**: Hide or partially mask sensitive values -- **Custom templates**: Define your own display template for a column +- Global or per-column date/time formats +- JSON path extraction +- Value masking +- Custom display templates +- Numeric, boolean, and database-type-specific presentation -Configure formatters from the column header menu. Formatters only affect display — they do not change the underlying data. +Clear the formatter to return to the original value display. -## Cell Detail Editor +## Selection, Copy, and Navigation -The cell detail panel provides a full editor for individual cell values: +The grid supports individual cells, rectangular ranges, full rows, and multiple row selections. You can then: -- **Value editor**: Edit cell content in a larger text area with syntax highlighting for JSON and SQL -- **Set NULL**: Explicitly write NULL to a cell -- **Image preview**: When a cell contains an image URL, the detail panel shows a rendered preview -- **Temporal editor**: Date and time cells use a dedicated date/time picker +- View selection summaries such as count or sum for compatible values +- Copy as TSV, CSV, JSON, Markdown, SQL `INSERT`, or `UPDATE` +- Copy cells, ranges, rows, or results with headers +- Choose identifier quoting for copied column names +- Use column comments as copied names for business-facing extracts +- Generate one multi-row `INSERT` or separate `INSERT` statements +- Exclude primary keys when creating a template for new records -## Multi-Row Operations +When DBX can resolve a foreign-key relationship, a cell can navigate to the referenced record. This depends on metadata and target-connection permissions. -Select multiple rows to perform batch operations: +## Export -- **Batch clone**: Duplicate multiple rows at once -- **Batch delete**: Mark multiple rows for deletion in one action -- **Batch copy**: Copy multiple rows as TSV, CSV, JSON, Markdown, or INSERT statements -- **Copy as INSERT**: Generate a single `INSERT` statement with multiple value rows -- **Copy as UPDATE**: Generate `UPDATE` statements for selected rows -- **Copy without primary keys**: Generate INSERT statements that exclude auto-increment primary keys +| Format | Best for | +| --- | --- | +| CSV / TSV | Spreadsheets, scripts, and text exchange | +| JSON | API debugging and programmatic processing | +| Markdown | Issues, pull requests, documentation, and chat | +| XLSX | Excel delivery; additional worksheets are created when one sheet reaches its limit | +| SQL | Reusing selected data as `INSERT` or `UPDATE` statements | -## Header Controls +Query-result export follows the current result and selection scope. Before exporting, verify the current page, filters, sorting, and selection so visible data is not mistaken for the full table. -Column headers provide quick access to actions: +## Auto Refresh, Pagination, and Large Results -- **Sort**: Click to toggle ascending, descending, or clear sort. Right-click for context menu with sort options. -- **Column visibility**: Show or hide columns from a filterable checklist -- **Local column filter**: Filter values within the current result set by checking specific values -- **Compact mode**: When enabled in Settings, header actions (sort, format, filter) collapse into a single dropdown menu, giving column names more space -- **Compact filter builder**: Build complex client-side filters with multiple conditions in a compact UI -- **Drag-and-drop column reordering**: Click and drag column headers to reorder them. Column order is saved per table/query and persists across sessions +- The page size used when opening tables is configurable and persistent +- Auto refresh is useful for small, frequently changing result sets +- Query results can retain multiple runs or pin results for comparison +- Virtual rendering keeps the UI responsive, but database and transfer cost still depend on returned row count +- Sorting, filtering, or refreshing may reload data and can be blocked or affected by unsaved edits -## Cell Detail Editor +Do not use auto refresh while editing data, and do not treat it as a monitoring system. Narrow large queries before increasing refresh frequency. -The cell detail panel provides a full editor for individual cell values: +## Troubleshooting -- **Value editor**: Edit cell content in a larger text area with syntax highlighting for JSON and SQL -- **Set NULL**: Explicitly write NULL to a cell -- **Image preview**: When a cell contains an image URL, the detail panel shows a rendered preview -- **Temporal editor**: Date and time cells use a dedicated date/time picker -- **Binary data hex viewer**: View binary data in hexadecimal format with both hex and ASCII representations, making it easy to inspect raw binary content +| Symptom | Check | +| --- | --- | +| Result is view-only | Join or aggregate, missing primary key, read-only connection, or unsupported driver editing | +| Row count does not shrink after filtering | A client search/filter was used instead of database-side `WHERE` | +| Sorting affects only the current page | Local sorting is active; use `ORDER BY` for stable cross-page ordering | +| Pasted columns are offset | Clipboard column count, selected starting column, hidden columns, and field order | +| Image or spatial preview is unavailable | Value encoding, MIME/binary type, geometry encoding, or unknown SRID | +| Export count differs from expectations | Current page, selection, client filter, and database query scope | -## Export and Copy - -| Format | Use Case | -| -------- | ------------------------------------------------------------------------ | -| CSV | Excel, Numbers, or spreadsheet tools | -| JSON | Scripts, API debugging, or programmatic processing | -| Markdown | Issues, PRs, documentation, or chat | -| INSERT | Copy selected rows as executable `INSERT` statements (single or batched) | -| UPDATE | Copy selected rows as executable `UPDATE` statements | -| XLSX | Export directly to Excel format from the table context menu | - -### Copy with Headers - -DBX supports copying data with column headers included: - -- **Copy column names**: Copy just the column names from the current selection -- **Copy selection with headers**: Copy selected cells along with their column headers -- **Copy as TSV/CSV with headers**: Include headers in tab-separated or comma-separated output - -This is especially useful when pasting data into spreadsheets, documentation, or sharing query results where column context is important. - -Before exporting, check the active filters and sort order so the exported data matches what you expect. - -## Pagination And Large Results - -DBX can page result sets and keep large grids responsive with virtual scrolling. For large tables, prefer database-side `WHERE` and `ORDER BY` clauses instead of relying only on client search, because the database can use indexes and return a smaller result set. Page size is configurable and persists across sessions. - -### Row Number Display - -The data grid shows row numbers in the leftmost column. When paging through large result sets, row numbers reflect the current page position and help you track which records you're viewing. Row numbers automatically adjust when you apply sorting or filtering. + + + Use completion, execution targets, multiple results, and history to produce grids. + + + Import large datasets from CSV, TSV, JSON, or Excel. + + + Copy table data between connections or database engines. + + + Configure read-only connections, production confirmation, and MCP permissions. + + diff --git a/docs/content/docs/data-transfer.cn.mdx b/docs/content/docs/data-transfer.cn.mdx index db27b03e83..d3e22048a2 100644 --- a/docs/content/docs/data-transfer.cn.mdx +++ b/docs/content/docs/data-transfer.cn.mdx @@ -1,96 +1,127 @@ --- title: 数据传输 -description: 在不同连接或不同数据库引擎之间迁移表数据。 +description: 在不同连接、数据库、Schema 或数据库引擎之间批量复制表数据，并跟踪每张表的结果。 --- -数据传输用于把表数据从一个连接复制到另一个连接。它适合开发、测试、迁移和数据整合场景，但不应该替代正式的数据同步链路。 +数据传输把一个数据源中的表或集合复制到另一个连接、数据库或 Schema。它适合环境迁移、测试数据准备和一次性数据整合，不是持续复制、CDC 或双向同步方案。 -## 适合的场景 +跨引擎传输会经过 DBX 的字段和类型转换层。目标数据库的权限、约束、触发器、默认值和类型语义仍会影响结果。重要迁移应先在测试环境演练并做行数与关键字段校验。 -- 把生产库的一部分数据复制到开发环境 -- 在 MySQL、PostgreSQL、SQLite、SQL Server 等引擎之间迁移数据 -- 将多个数据源整理到同一个分析库 -- 为测试环境准备一份可复现的数据集 +## 两个入口 -跨引擎传输会涉及类型映射、默认值、约束和自增字段差异。传输完成后请抽样检查数据，重要迁移建议先在测试环境演练。 +### 数据传输向导 -## 使用流程 +向导适合一次传输多张表。你可以分别选择源和目标连接、Catalog、数据库和 Schema，再配置建表、写入模式、目标表名大小写和批大小。 + +### 侧边栏复制与粘贴 + +在对象树中复制一张或多张表后，可以粘贴到目标位置： + +- 同一上下文中可选择“结构和数据”“仅结构”或“仅数据”，并逐表修改目标名称 +- 粘贴到另一个连接、数据库或 Schema 时，DBX 会自动打开数据传输向导并带入源表和目标位置 +- 表数据复制会跳过生成列或计算列，并对 PostgreSQL identity、SQL Server identity 等路径应用相应写入处理 + +## 向导流程 - ### 选择源连接 + ### 选择源位置 - 源连接是数据读取的位置。确认账号有读取目标表的权限。 + 选择源连接、Catalog（如适用）、数据库和 Schema。DBX 只列出可传输的基础表；MongoDB 路径列出集合。 - ### 选择目标连接 + ### 选择目标位置 - 目标连接是数据写入的位置。确认账号有写入权限，并确认目标库环境无误。 + 选择另一个连接、数据库或 Schema。源和目标不能是完全相同的位置。 ### 选择表 - 可以传输全部表，也可以只选择需要的表。大表建议分批处理。 + 可以全选、搜索或只选择部分表。一次请求中的表必须来自同一个源位置。 - ### 开始传输 + ### 配置传输选项 - DBX 会按表读取数据，并根据所选模式写入目标数据库。可选择是否创建目标表。 + 确认是否创建目标表、写入模式、目标表名大小写和批大小。 - ### 检查结果 + ### 后台执行并检查结果 - 传输完成后检查行数、错误列表和关键字段。 + 对话框关闭后任务继续运行。进度中心显示当前表、表序号、行数、耗时、失败表和取消状态。 -## 传输过程 - -DBX 会在传输过程中展示： - -- 当前正在处理的表 -- 已传输行数 -- 总体进度 -- 错误信息和对应表名 - -如果某张表失败，当前传输会停止并展示错误信息。修正表结构、权限或约束问题后，可以重新发起传输。 - ## 传输选项 -| 选项 | 说明 | -| ---------- | ------------------------------------------ | -| 创建目标表 | 目标库没有对应表时，尝试根据源表结构创建 | -| 追加 | 将数据插入目标表现有数据之后 | -| 覆盖 | 先清空目标表，再写入源数据 | -| Upsert | 在目标数据库路径支持时使用基于键的写入行为 | -| 批大小 | 控制每批写入的行数 | +| 选项 | 说明 | +| --- | --- | +| 创建目标表 | 目标表不存在时，根据源元数据和目标数据库能力生成表结构 | +| 追加 | 保留目标表已有数据并插入源数据 | +| 覆盖 | 在传输该表前清空目标表，再写入源数据 | +| Upsert | 目标路径支持且能确定键时，按键更新或插入 | +| 表名大小写 | 保持原样、转小写或转大写；转换后的目标名必须互不冲突 | +| 批大小 | 控制分页读取和分批写入，默认 1000，可在界面中调整 | + +如果关闭“创建目标表”，目标表必须已经存在且字段可兼容。即使开启建表，跨引擎 DDL 也可能因目标数据库不支持某些类型、默认值、约束或对象而需要人工调整。 + +## PostgreSQL 结构和所有者 + +PostgreSQL 到 PostgreSQL 且启用创建表时，DBX 会在能力允许时处理序列、索引、外键以及部分 Schema 级对象和依赖。若源对象所有者在目标实例中不存在，开始前会提示选择： + +- 跳过相关所有者信息 +- 把缺失所有者重新分配为目标当前用户 +- 取消并先在目标实例创建所需角色 + +这不等价于完整的 `pg_dump` / `pg_restore`。扩展、权限、策略、触发器或依赖复杂时，仍应使用 PostgreSQL 原生迁移工具验证。 + +## 失败处理 + +多表任务不会因为第一张表失败就立即丢弃整个队列。DBX 会记录该表的错误并继续尝试后续表，最后以成功或带失败的终态结束。 + +- 进度中保存每张失败表及错误摘要 +- 失败数量较多时，界面只展示有限条目并报告被省略的数量 +- 同一目标表已有传输任务运行时，新任务会被阻止，避免并发覆盖 +- 取消会停止后续读取和写入，但已提交的数据不会自动撤销 + +因此“任务完成”不代表所有表都成功；应检查最终状态、失败列表、目标行数和关键字段。 ## 数据库覆盖范围 -基于 SQL 的数据传输支持 MySQL、PostgreSQL、SQLite、SQL Server、Oracle、ClickHouse、DuckDB、DM 和 GaussDB。跨引擎传输会经过 DBX 的类型映射层，传输后请检查行数和关键字段值。 +DBX 按驱动能力清单过滤源和目标连接。当前实现同时包含 SQL 到 SQL、MongoDB 到 MongoDB，以及部分 MongoDB 与 SQL 之间的转换路径；并非所有已支持连接都提供数据传输。 + +不同组合的能力也不完全相同，例如： + +- 某些引擎只能传输表数据，不能复用源 DDL +- Upsert 依赖目标数据库和可识别的键 +- Catalog、Schema、identity、数组、JSON 和二进制值的处理因引擎而异 +- 专用搜索、向量、消息队列和配置中心连接不使用此通用表传输入口 + +如果连接未出现在下拉列表中，表示当前驱动没有声明数据传输能力，而不是仅仅缺少 UI 入口。 ## 传输前检查 -| 检查项 | 原因 | -| -------- | ---------------------------------------- | -| 目标环境 | 避免误写生产库或错误环境 | -| 表结构 | 字段名、类型、主键和唯一约束会影响写入 | -| 数据量 | 大表可能需要更长时间，也可能触发超时 | -| 约束 | 外键、唯一约束、非空字段可能导致写入失败 | -| 敏感数据 | 从生产复制到低环境前，确认是否需要脱敏 | +- 目标连接是否开启只读保护；只读目标会被直接阻止 +- 源和目标账号是否分别具有读取、建表和写入权限 +- 目标表名大小写转换后是否冲突 +- 主键、唯一约束、外键、触发器和非空字段是否会拒绝数据 +- 从生产环境复制到低环境前是否需要脱敏 +- 大表是否更适合数据库原生导出、导入或在线迁移工具 ## 相关功能 - 从 CSV、TSV、JSON 或 Excel 导入到单张表。 + 从文件导入现有表，或按文件批量创建新表。 - 将数据库导出为 SQL 文件，便于备份或离线迁移。 + 生成可审阅和离线传递的 SQL 文件。 + + + 了解只读保护、生产保护和权限边界。 diff --git a/docs/content/docs/data-transfer.mdx b/docs/content/docs/data-transfer.mdx index a801bad875..36b523f582 100644 --- a/docs/content/docs/data-transfer.mdx +++ b/docs/content/docs/data-transfer.mdx @@ -1,96 +1,127 @@ --- title: Data Transfer -description: Move table data between connections or database engines. +description: Copy tables between connections, databases, schemas, or database engines and track the result of each table. --- -Data Transfer copies table data from one connection to another. Use it for development, testing, migration, and consolidation workflows. It is not a replacement for a production-grade replication pipeline. +Data Transfer copies tables or collections from one source into another connection, database, or schema. Use it for environment migration, test data preparation, and one-off consolidation. It is not continuous replication, CDC, or bidirectional synchronization. -## Use Cases +Cross-engine transfer passes through DBX field and type conversion. Target privileges, constraints, triggers, defaults, and engine semantics still determine the result. Rehearse important migrations and validate row counts and key fields afterward. -- Copy part of production data into a development environment -- Move data between engines such as MySQL, PostgreSQL, SQLite, and SQL Server -- Consolidate multiple sources into an analysis database -- Prepare reproducible datasets for testing +## Two Entry Points -Cross-engine transfer involves type mapping, defaults, constraints, and auto-increment differences. Validate transferred data afterward, and rehearse important migrations in a test environment first. +### Data Transfer Wizard -## Workflow +The wizard is designed for multiple tables. Select the source and target connection, catalog, database, and schema, then configure table creation, write mode, target-name case, and batch size. + +### Sidebar Copy and Paste + +After copying one or more tables in the object tree, paste them at a target location: + +- Within the same context, choose structure and data, structure only, or data only, and edit each target name +- Pasting into another connection, database, or schema opens the Data Transfer wizard with the source tables and target prefilled +- Whole-row copy excludes generated or computed columns and applies path-specific handling for PostgreSQL identity and SQL Server identity columns + +## Wizard Workflow ### Select the Source - The source connection is where data is read from. Confirm the account can read the selected tables. + Choose the source connection, catalog when applicable, database, and schema. DBX lists transferable base tables; MongoDB paths list collections. ### Select the Target - The target connection is where data is written. Confirm write permissions and verify the target environment. + Choose another connection, database, or schema. Source and target cannot be the exact same location. ### Choose Tables - Transfer all tables or select only the tables you need. For large tables, consider transferring in smaller batches. + Select all, search, or choose a subset. A single request can only contain tables from one source context. - ### Start Transfer + ### Configure Options - DBX reads rows table by table and writes them to the target database using the selected mode. You can also choose whether target tables should be created. + Review target-table creation, write mode, target-name case, and batch size. - ### Check Results + ### Run in Background and Review - After transfer, inspect row counts, errors, and key fields. + The task keeps running after the dialog closes. The progress center reports the current table, table index, rows, duration, failed tables, and cancellation state. -## During Transfer - -DBX shows: - -- Current table -- Rows transferred -- Overall progress -- Errors and the table that caused each error - -If a table fails, the current transfer stops and shows the error. Fix the structure, permission, or constraint issue, then start the transfer again. - ## Transfer Options -| Option | Details | -| ------------------- | ------------------------------------------------------------------------------- | -| Create target table | Try to create the target table from the source structure when it does not exist | -| Append | Insert data after existing target rows | -| Overwrite | Clear the target table before writing source rows | -| Upsert | Use key-aware write behavior where the target database path supports it | -| Batch size | Control how many rows are written per batch | +| Option | Details | +| --- | --- | +| Create target tables | Generates target structure from source metadata when the table does not exist and the path supports it | +| Append | Keeps existing target rows and inserts source rows | +| Overwrite | Clears each target table before writing its source rows | +| Upsert | Updates or inserts by key when the target path supports it and a usable key is available | +| Target table name case | Preserve, lowercase, or uppercase; transformed target names must remain unique | +| Batch size | Controls paged reads and batched writes; the UI default is 1000 | + +If table creation is disabled, compatible target tables must already exist. Even with table creation enabled, cross-engine DDL may require manual changes when the target does not support a source type, default, constraint, or object. + +## PostgreSQL Structure and Ownership + +For PostgreSQL-to-PostgreSQL transfers with table creation enabled, DBX handles supported sequences, indexes, foreign keys, and selected schema-level objects and dependencies. If source owners do not exist on the target instance, DBX prompts you to: + +- Skip the affected ownership metadata +- Reassign missing owners to the current target user +- Cancel and create the required target roles first + +This is not a full replacement for `pg_dump` and `pg_restore`. Use native PostgreSQL tooling when extensions, grants, policies, triggers, or dependency graphs are complex. + +## Failure Handling + +A multi-table task does not discard the entire queue after the first table failure. DBX records the failure, attempts later tables, and finishes either successfully or with a terminal error summary. + +- Progress keeps per-table failure details +- When failures exceed the display limit, the UI reports how many entries were omitted +- A new task is rejected if another active transfer already targets the same table +- Cancellation stops later reads and writes, but committed target data is not automatically reverted + +As a result, a finished task does not necessarily mean every table succeeded. Check the terminal state, failure list, target row counts, and key fields. ## Database Coverage -SQL-based transfer is available for MySQL, PostgreSQL, SQLite, SQL Server, Oracle, ClickHouse, DuckDB, DM, and GaussDB. Cross-engine transfers use DBX's type mapping layer, so always verify row counts and important column values after transfer. +DBX filters source and target connections through the driver capability manifest. The implementation includes SQL-to-SQL, MongoDB-to-MongoDB, and selected MongoDB/SQL conversion paths. Not every connectable database supports Data Transfer. -## Before You Transfer +Capabilities also vary by combination: -| Check | Why It Matters | -| ------------------ | ----------------------------------------------------------------------- | -| Target environment | Avoid writing to the wrong database | -| Table structure | Field names, types, primary keys, and unique constraints affect inserts | -| Data volume | Large tables may take longer or hit timeouts | -| Constraints | Foreign keys, unique constraints, and NOT NULL fields may fail writes | -| Sensitive data | Production data may need masking before copying into lower environments | +- Some engines transfer rows but cannot reuse source DDL +- Upsert depends on the target engine and discoverable keys +- Catalogs, schemas, identity columns, arrays, JSON, and binary values are engine-specific +- Specialized search, vector, message queue, and configuration-center connections do not use this generic table-transfer entry point + +If a connection is absent from the selector, its current driver has not declared Data Transfer support; it is not merely a hidden UI action. + +## Before Transferring + +- Check whether the target connection has read-only protection; read-only targets are blocked +- Confirm source read privileges and target create/write privileges +- Check for target-name collisions after case conversion +- Review primary keys, unique constraints, foreign keys, triggers, and required fields +- Decide whether production data must be masked before entering a lower environment +- Use native export/import or online migration tools when the dataset is too large for an interactive transfer ## Related Features - Import CSV, TSV, JSON, or Excel into a single table. + Import files into an existing table or create new tables in batches. - Export a database as SQL for backup or offline migration. + Produce reviewable SQL files for offline transfer. + + + Understand read-only protection, production protection, and privilege boundaries. diff --git a/docs/content/docs/database-backup.cn.mdx b/docs/content/docs/database-backup.cn.mdx new file mode 100644 index 0000000000..3dde2d728c --- /dev/null +++ b/docs/content/docs/database-backup.cn.mdx @@ -0,0 +1,137 @@ +--- +title: 定时数据库备份 +description: 在 DBX 桌面端为 MySQL 和 PostgreSQL 创建可手动运行或按小时、每天、每周执行的 SQL 备份计划。 +--- + +定时数据库备份使用 DBX 的数据库导出引擎，为 MySQL 和 PostgreSQL 连接生成 SQL 文件。它适合开发、测试和中小型数据库的周期性逻辑备份，并提供表范围、保留数量、运行历史和手动执行。 + +定时备份当前仅支持 DBX 桌面端，并要求应用保持运行。它不是数据库服务器上的独立调度器，也不能替代物理备份、Point-in-Time Recovery、WAL/binlog 归档或云厂商备份服务。 + +## 支持范围 + +| 项目 | 当前行为 | +| --- | --- | +| 数据库 | MySQL、PostgreSQL | +| 平台 | DBX 桌面端 | +| 输出 | 每个数据库/Schema 对应的 `.sql` 文件 | +| 频率 | 每隔若干小时、每天指定时间、每周指定星期和时间 | +| 内容 | 表结构、表数据、数据库对象、可选 `DROP TABLE IF EXISTS` | +| 表范围 | 全部、按模式包含、按模式排除 | +| 保留 | 按计划保留最近若干次成功备份文件 | + +## 创建计划 + + + + ### 打开备份设置 + + 在设置中进入数据库备份页面，创建新的备份计划。 + + + + ### 选择连接和数据库 + + 选择 MySQL 或 PostgreSQL 连接。可以备份所有非系统数据库，也可以选择指定数据库。 + + + + ### 配置表范围 + + 选择全部表、只包含匹配模式的表，或排除匹配模式的表。模式支持 `*` 和 `?`，并可以匹配 `schema.table` 或 `database.schema.table`。 + + + + ### 设置目录与频率 + + 选择本机目标目录，并设置每小时、每天或每周计划。界面会预览下次运行时间。 + + + + ### 选择内容和保留数量 + + 选择结构、数据、对象和 `DROP TABLE IF EXISTS`，然后设置要保留的历史备份数量。 + + + + ### 保存并验证 + + 保存后先点击**立即运行**，确认连接权限、表范围、目标目录和生成文件都符合预期，再启用计划。 + + + + +## 表匹配模式 + +表模式可以使用逗号、分号或换行分隔。例如： + +```text +public.* +audit_* +orders_202? +``` + +- **包含**只导出匹配表 +- **排除**导出其他表并跳过匹配表 +- PostgreSQL 名称按大小写区分 +- MySQL 会结合 `lower_case_table_names` 判断匹配是否区分大小写 + +如果没有任何表匹配包含规则，运行会失败，不会生成空的成功备份。 + +## 一致性与执行方式 + +每次备份会在数据库会话中建立一致性快照，再按数据库/Schema 运行导出。完成后回滚只读快照事务，不提交业务修改。 + +备份任务会显示在统一导出任务区，并提供： + +- 当前数据库和对象 +- 成功、失败或取消状态 +- 手动或计划触发来源 +- 生成文件列表 +- 错误信息和运行时间 + +取消只会停止后续导出。失败或取消时，DBX 会尽量删除本次已经生成的部分文件，避免把不完整结果误当成成功备份。 + +## 保留与历史 + +每个计划可以设置保留数量。超过数量的旧运行会从历史中清理，并删除相应文件。也可以手动删除某次备份记录和文件。 + +目标目录仍应纳入操作系统、NAS 或对象存储的独立备份。单机同盘保存无法防止磁盘损坏、勒索软件或整机丢失。 + +## 恢复演练 + +生成的 `.sql` 文件可以通过 [SQL 文件执行](/cn/docs/sql-file) 导入。建议定期在隔离环境验证： + +- 文件可以完整读取和执行 +- 表结构、索引、对象和数据量符合预期 +- 字符集、时区、序列/自增值和权限需要的额外步骤 +- 应用可以连接恢复后的数据库 + +备份成功只代表文件生成完成，不代表已经验证可恢复。 + +## 选择定时备份还是数据库导出 + +| 功能 | 适合场景 | +| --- | --- | +| [数据库导出](/cn/docs/database-export) | 一次性迁移、变更前备份、手动选择当前范围 | +| 定时数据库备份 | 固定连接和范围的周期性逻辑备份 | +| 数据库原生备份 | 大型生产库、PITR、增量/物理备份、高可用与合规要求 | + +## 安全建议 + +- 使用只具备备份所需读取权限的数据库账号 +- 目标目录按敏感数据级别控制权限和加密 +- 不要把包含业务数据的 SQL 文件提交到公开仓库 +- 计划中数据库或表改名后，重新检查范围 +- DBX 桌面端未运行、电脑休眠或目标目录不可用时，计划不会像服务器调度器一样可靠执行 + + + + 手动选择结构、数据、对象和数据库范围。 + + + 执行备份文件并查看语句级进度与错误。 + + + 使用只读账号、生产保护和最小权限策略。 + + diff --git a/docs/content/docs/database-backup.mdx b/docs/content/docs/database-backup.mdx new file mode 100644 index 0000000000..d7846a4978 --- /dev/null +++ b/docs/content/docs/database-backup.mdx @@ -0,0 +1,137 @@ +--- +title: Scheduled Database Backups +description: Create manual, hourly, daily, or weekly SQL backup schedules for MySQL and PostgreSQL in DBX Desktop. +--- + +Scheduled database backups use the DBX database-export engine to generate SQL files for MySQL and PostgreSQL connections. They are useful for recurring logical backups of development, test, and small or medium databases and include table scope, retention, run history, and manual execution. + +Scheduled backups currently require DBX Desktop to remain running. They are not an independent server scheduler and do not replace physical backups, point-in-time recovery, WAL/binlog archiving, or cloud-provider backup services. + +## Support Scope + +| Item | Current behavior | +| --- | --- | +| Databases | MySQL and PostgreSQL | +| Platform | DBX Desktop | +| Output | One `.sql` file per database/schema target | +| Frequency | Every N hours, daily at a time, or weekly on a weekday and time | +| Contents | Table structure, data, database objects, and optional `DROP TABLE IF EXISTS` | +| Table scope | All, include by pattern, or exclude by pattern | +| Retention | Keep a configured number of recent successful backup files | + +## Create a Schedule + + + + ### Open backup settings + + Open the database backup page in Settings and create a schedule. + + + + ### Choose connection and databases + + Select a MySQL or PostgreSQL connection. Back up all non-system databases or choose specific databases. + + + + ### Configure table scope + + Choose all tables, include matching patterns, or exclude matching patterns. Patterns support `*` and `?` and can match `schema.table` or `database.schema.table`. + + + + ### Set directory and frequency + + Select a local destination directory and configure hourly, daily, or weekly timing. DBX previews the next run. + + + + ### Choose contents and retention + + Select structure, data, objects, and `DROP TABLE IF EXISTS`, then choose how many historical backups to retain. + + + + ### Save and verify + + Run the schedule manually first. Verify connection permissions, table scope, destination directory, and generated files before enabling automatic execution. + + + + +## Table Patterns + +Separate patterns with commas, semicolons, or newlines. For example: + +```text +public.* +audit_* +orders_202? +``` + +- **Include** exports only matching tables +- **Exclude** exports everything else and skips matching tables +- PostgreSQL names are case-sensitive +- MySQL matching follows `lower_case_table_names` + +If an include rule matches no tables, the run fails instead of reporting an empty successful backup. + +## Consistency and Execution + +Each backup establishes a consistent snapshot session before exporting database/schema targets. DBX rolls back the read-only snapshot transaction afterward and does not commit business changes. + +Backup runs appear in the shared export task area and show: + +- Current database and object +- Success, failure, or cancelled status +- Manual or scheduled trigger +- Generated file list +- Error details and timestamps + +Cancellation stops remaining exports. On failure or cancellation, DBX attempts to remove partial files from the run so incomplete output is not mistaken for a successful backup. + +## Retention and History + +Each schedule has a retention count. Older runs beyond the limit are pruned from history and their files are deleted. Individual backup runs and files can also be removed manually. + +The destination directory still needs independent OS, NAS, or object-storage backup. Saving to another folder on the same disk does not protect against disk failure, ransomware, or loss of the machine. + +## Restore Drills + +Generated `.sql` files can be imported through [SQL File Execution](/en/docs/sql-file). Regularly verify in an isolated environment that: + +- The complete file can be read and executed +- Schema, indexes, objects, and row counts are correct +- Charset, timezone, sequence/identity values, and privileges have any required follow-up steps +- The application can connect to the restored database + +A successful backup run means file generation completed; it does not prove restore readiness. + +## Scheduled Backup vs. Database Export + +| Feature | Best for | +| --- | --- | +| [Database Export](/en/docs/database-export) | One-time migration, pre-change backup, and manual scope selection | +| Scheduled Database Backup | Recurring logical backups for a fixed connection and scope | +| Native database backup | Large production databases, PITR, incremental/physical backup, HA, and compliance requirements | + +## Safety Guidance + +- Use a database account with only the read privileges required for backup +- Protect and encrypt the destination according to the data sensitivity level +- Never commit SQL files containing business data to a public repository +- Recheck scope after databases or tables are renamed +- If DBX Desktop is closed, the computer sleeps, or the destination is unavailable, schedules do not run with server-scheduler reliability + + + + Manually choose structure, data, objects, and database scope. + + + Execute backup files with statement-level progress and errors. + + + Use read-only accounts, production protection, and least-privilege policies. + + diff --git a/docs/content/docs/database-export.cn.mdx b/docs/content/docs/database-export.cn.mdx index 41e0669980..5064cda301 100644 --- a/docs/content/docs/database-export.cn.mdx +++ b/docs/content/docs/database-export.cn.mdx @@ -1,78 +1,124 @@ --- title: 数据库导出 -description: 将数据库结构和数据导出为 SQL 文件，用于备份、迁移或创建测试数据集。 +description: 将一个或多个数据库的结构、数据和可读取对象流式导出为 SQL 文件。 --- -数据库导出会把表结构和表数据写入 SQL 文件。它适合在执行高风险操作前备份、迁移小型数据库，或为开发测试准备可复现的数据集。 +数据库导出会生成可审阅的 SQL 脚本，用于小型备份、迁移、测试数据准备或高风险操作前留档。它可以导出单个数据库/Schema，也可以按连接批量导出多个数据库。 -## 导出内容 +SQL 导出是逻辑导出，不等同于数据库原生物理备份。大型生产库、时间点恢复、增量备份或严格一致性要求，应优先使用数据库官方备份工具；MySQL 和 PostgreSQL 的定时一致性备份可参阅 [数据库备份](/cn/docs/database-backup)。 -| 内容 | 说明 | -| -------- | ----------------------------------------------- | -| 表结构 | `CREATE TABLE`、字段、主键、索引、约束等 DDL | -| 表数据 | 以 `INSERT` 语句形式导出 | -| 批量插入 | 多行合并为一条 `INSERT`，减少文件体积和导入成本 | -| 对象 | 数据库可提供源码时导出视图、存储过程和函数 | +## 可以导出的内容 -示例： +| 内容 | 说明 | +| --- | --- | +| 表结构 | `CREATE TABLE`、字段、主键、索引、约束以及驱动可读取的 DDL | +| 表数据 | 按批读取并生成 `INSERT` 语句，不需要先把整表加载到内存 | +| 数据库对象 | 视图、序列、扩展、存储过程和函数等；具体范围取决于数据库和源码可见性 | +| 创建数据库 | MySQL 可选生成 `CREATE DATABASE IF NOT EXISTS` 和 `USE` 前导脚本 | +| 导入辅助语句 | 根据引擎生成外键检查、identity 写入、例程分隔符等必要的 setup/收尾语句 | -```sql -INSERT INTO users (id, name, email) VALUES - (1, '张三', 'zhangsan@example.com'), - (2, '李四', 'lisi@example.com'), - (3, '王五', 'wangwu@example.com'); -``` +启用“仅选中表”时，表结构和数据只处理所选表。例程等 Schema 级对象不会因为选择少量表而被一并带出；对象导出始终受当前数据库能力限制。 -## 使用流程 +## 单库导出 ### 选择连接和数据库 - 选择要导出的连接和数据库，确认当前环境无误。 + 选择数据库以及 Schema（如适用），再勾选需要导出的表。 - ### 设置导出选项 + ### 配置内容和 DDL 选项 - 选择是否包含结构、数据和数据库对象。可以导出全部表，也可以只导出选中的表。 + 选择结构、数据、对象、删除已存在表、MySQL 创建数据库和自增起始值处理。 - ### 选择保存位置 + ### 选择输出位置 - 选择 `.sql` 文件保存路径。 + Desktop 选择本地 `.sql` 路径；Docker/Web 在服务器临时目录生成文件，完成后由浏览器下载。 - ### 开始导出 + ### 后台生成并检查结果 - DBX 会生成 SQL 文件，并展示当前对象、进度、行数、错误和取消状态。 + 进度显示准备阶段、当前对象、对象序号、导出行数、错误和取消状态。任务可以保留在进度中心继续观察。 -## 批量与选择 +Desktop 导出成功后可以从任务结果直接在文件管理器中打开输出文件所在目录。Web 下载完成后，服务器临时文件会被清理。 -DBX 会分批读取表数据，并把生成的 `INSERT` 语句写入输出文件。如果没有设置批大小，默认每批 1000 行。 +## 导出所有数据库 -选择部分表导出时，DBX 会先过滤表列表，再生成 DDL 和数据。视图、存储过程、函数等对象只会在启用对象导出且没有限定表子集时一起导出。 +启用“导出所有数据库”后，可以搜索并选择当前连接中的多个数据库： -MySQL 导出会在表内容前写入 `SET FOREIGN_KEY_CHECKS = 0`，并在文件末尾重新启用。 +- 非 Schema 型数据库通常每个数据库生成一个 `.sql` 文件 +- PostgreSQL 等 Schema 感知数据库会为选中数据库下的每个 Schema 建立导出计划；一个数据库包含多个 Schema 时，文件名包含数据库和 Schema +- Desktop 选择输出目录，文件按计划逐个写入 +- Docker/Web 在服务器逐个生成文件并触发浏览器下载 +- 任一计划项失败或被取消时，后续计划停止；已完成的文件不会自动删除 -## 取消与错误 +“所有数据库”是多个逻辑导出的串行编排，不是单个跨库事务，也不提供整个实例的一致时间点快照。 -导出可以在对象之间或行批次之间取消。如果某张表或某个对象无法导出，DBX 会在 SQL 文件中写入包含错误的注释，并在可能的情况下继续导出剩余内容。 +## 结构选项 -## 导入导出文件 +### 删除已存在表 -导出的 `.sql` 文件可以通过 [SQL 文件执行](/cn/docs/sql-file) 导入到数据库中。 +启用后，会在对应 `CREATE TABLE` 前写入数据库适配的 `DROP TABLE IF EXISTS`。执行导出文件时，这会删除目标表及其数据，应谨慎使用。 -导出文件可能包含敏感数据、账号信息、业务标识或用户隐私。分享前请确认是否需要脱敏。 +### MySQL 创建数据库 -## 使用建议 +MySQL 可以在文件开头加入 `CREATE DATABASE IF NOT EXISTS` 和 `USE`。导入账号需要相应权限；默认关闭，避免脚本意外创建或切换数据库。 -- 高风险 Schema 操作前先导出备份 -- 迁移前先在测试库验证导入结果 -- 大型生产库或需要完整备份的场景更适合使用数据库原生备份工具 -- 导出的 SQL 文件建议妥善保存，避免提交到公开代码仓库 +### 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` +- 账号是否有建表、对象创建和数据写入权限 +- 导入后表数、行数、索引、约束、序列和关键对象是否符合预期 + +导出文件可能包含密码哈希、令牌、个人信息和业务敏感数据。不要把未脱敏文件提交到公开仓库或发送到不可信环境。 + +## 相关功能 + + + + 在 Desktop 中为 MySQL 和 PostgreSQL 配置定时一致性 SQL 备份。 + + + 预览、批量执行并检查 SQL 文件结果。 + + + 不落地 SQL 文件，直接在连接之间复制表数据。 + + diff --git a/docs/content/docs/database-export.mdx b/docs/content/docs/database-export.mdx index 1a9735a10e..06d2ceed92 100644 --- a/docs/content/docs/database-export.mdx +++ b/docs/content/docs/database-export.mdx @@ -1,78 +1,124 @@ --- title: Database Export -description: Export database structure and data as SQL for backup, migration, or test datasets. +description: Stream structure, data, and readable database objects from one or more databases into SQL files. --- -Database Export writes table structure and table data into a SQL file. Use it before high-risk operations, for small database migrations, or to create reproducible development and test datasets. +Database Export creates reviewable SQL scripts for small backups, migrations, test datasets, or snapshots before risky changes. It can export one database/schema or orchestrate separate exports for multiple databases in a connection. -## What Gets Exported +SQL export is a logical export, not a database-native physical backup. Use official database tools for large production systems, point-in-time recovery, incremental backup, or strict consistency. For scheduled consistent MySQL and PostgreSQL exports, see [Database Backup](/en/docs/database-backup). -| Content | Details | -| --------------- | ------------------------------------------------------------------------------- | -| Structure | `CREATE TABLE`, columns, primary keys, indexes, constraints, and other DDL | -| Data | Rows exported as `INSERT` statements | -| Batched inserts | Multiple rows grouped into one `INSERT` to reduce file size and import overhead | -| Objects | Views, procedures, and functions where the database exposes source definitions | +## Exported Content -Example: +| Content | Details | +| --- | --- | +| Table structure | `CREATE TABLE`, columns, primary keys, indexes, constraints, and other DDL visible through the driver | +| Table data | Rows read in batches and written as `INSERT` statements without loading the entire table first | +| Database objects | Views, sequences, extensions, procedures, and functions where the engine exposes readable definitions | +| Database creation | Optional MySQL `CREATE DATABASE IF NOT EXISTS` and `USE` preamble | +| Import helpers | Engine-specific setup and cleanup for foreign-key checks, identity writes, routine delimiters, and similar requirements | -```sql -INSERT INTO users (id, name, email) VALUES - (1, 'Alice', 'alice@example.com'), - (2, 'Bob', 'bob@example.com'), - (3, 'Carol', 'carol@example.com'); -``` +When exporting only selected tables, structure and data are limited to that subset. Schema-wide routines are not pulled in merely because a few tables were selected. Object coverage always depends on the database and driver. -## Workflow +## Single-Database Export ### Select Connection and Database - Choose the database to export and verify the environment. + Choose a database and schema when applicable, then select the tables to include. - ### Configure Export Options + ### Configure Content and DDL - Choose whether to include structure, data, and database objects. You can export all tables or a selected table subset. + Select structure, data, objects, drop-existing-table behavior, MySQL database creation, and auto-increment handling. - ### Choose Output Location + ### Choose the Output - Select where the `.sql` file should be saved. + Desktop writes to a selected local `.sql` path. Docker/Web writes to temporary server storage and downloads the result through the browser. - ### Start Export + ### Generate in Background and Review - DBX generates a SQL file and reports the current object, progress, row counts, errors, and cancellation state. + Progress reports preparation, the current object, object index, exported rows, errors, and cancellation. The task remains visible in the progress center. -## Batching And Selection +After a successful Desktop export, the task result can reveal the output in the file manager. Web removes the temporary server file after download. -DBX reads table data in batches and writes generated `INSERT` statements into the output file. If batch size is not set, the export uses a default batch size of 1000 rows. +## Export All Databases -Selected-table export filters the table list before generating DDL and data. Routine objects such as procedures and functions are included only when object export is enabled and the export is not limited to a table subset. +Enable Export All Databases to search and select multiple databases from the current connection: -For MySQL exports, DBX temporarily writes `SET FOREIGN_KEY_CHECKS = 0` before table content and re-enables it at the end of the file. +- Non-schema engines normally produce one `.sql` file per database +- Schema-aware engines such as PostgreSQL build a plan per schema; when a database has multiple schemas, filenames include both database and schema +- Desktop writes each plan item into a selected output directory +- Docker/Web generates each file on the server and triggers browser downloads +- If one plan item fails or is cancelled, later items stop; already completed files are not removed automatically -## Cancellation And Errors +All-database export is serial orchestration of independent logical exports. It is not one cross-database transaction or an instance-wide consistent snapshot. -You can cancel an export between objects or row batches. If a specific table or object cannot be exported, DBX writes a SQL comment with the error and continues with the remaining export where possible. +## Structure Options -## Importing the Export +### Drop Existing Tables -The generated `.sql` file can be imported with [SQL File Execution](/en/docs/sql-file). +When enabled, DBX writes database-adapted `DROP TABLE IF EXISTS` statements before the matching `CREATE TABLE`. Running the script can delete target data, so review this option carefully. -Export files may contain sensitive data, account information, business identifiers, or user privacy data. Mask data before sharing when needed. +### MySQL Create Database -## Recommendations +MySQL exports can add `CREATE DATABASE IF NOT EXISTS` and `USE` at the beginning. The importing account needs appropriate privileges. The option is off by default to avoid unexpected database creation or context switching. -- Export a backup before high-risk schema operations -- Test imports in a non-production database before migration -- Use native database backup tools for large production databases or complete backups -- Keep exported SQL files out of public repositories +### MySQL Auto-Increment Start + +By default, table-level `AUTO_INCREMENT=N` is preserved. Omit Auto Increment removes only that table option; it does not remove the column's `AUTO_INCREMENT` attribute. This is useful when a fresh environment should choose its own starting sequence value. + +## Data Writing and Consistency + +DBX uses paged or streaming reads and writes rows incrementally. Interactive exports currently use a batch size of 1000 rows. Generated inserts may be multi-row or single-row depending on database capabilities. + +The export path attempts to: + +- Disable and later restore MySQL foreign-key checks +- Wrap explicit writes to supported identity columns when required +- Format strings, dates, JSON, arrays, binary values, and `NULL` for the target dialect +- Add routine delimiters or batch boundaries required by the database +- Use a stable session on supported connections to reduce drift between batches of the same table + +Interactive SQL export still cannot promise one global snapshot across every database and object. Use [Database Backup](/en/docs/database-backup) or native database tooling when consistency is required. + +## Errors and Cancellation + +- When a table or object cannot be read, regular export paths may write an error as an SQL comment and continue; metadata, connection, or file failures can terminate the task +- Cancellation takes effect between objects or row batches +- Desktop may leave a partial file that must be checked before reuse +- Web cleans temporary server files after failure or cancellation and does not trigger a successful download +- A successful export only confirms file generation, not a successful restore on another database + +## Restore and Validation + +Use [SQL File Execution](/en/docs/sql-file) to preview and run an exported script. Before restoring, check: + +- Target engine and version compatibility +- Whether the file contains `DROP TABLE`, `CREATE DATABASE`, or large insert batches +- Create, object, and data-write privileges +- Table counts, row counts, indexes, constraints, sequences, and critical objects after import + +Exported files may contain password hashes, tokens, personal information, and business-sensitive data. Do not commit unmasked exports to public repositories or send them to untrusted environments. + +## Related Features + + + + Schedule consistent MySQL and PostgreSQL SQL backups in Desktop. + + + Preview, batch-execute, and review SQL file results. + + + Copy table data directly between connections without an intermediate SQL file. + + diff --git a/docs/content/docs/databases.cn.mdx b/docs/content/docs/databases.cn.mdx index 29d2014b66..48aa46c959 100644 --- a/docs/content/docs/databases.cn.mdx +++ b/docs/content/docs/databases.cn.mdx @@ -1,203 +1,113 @@ --- title: 数据库支持 -description: 了解 DBX 可以连接哪些数据库，以及每类高级功能支持哪些引擎。 +description: 了解 DBX 的连接 profile、驱动运行时、专用工作区和按能力启用的高级功能。 --- -DBX 主应用会尽量使用 Rust 原生驱动。部分数据库通过 MySQL 或 PostgreSQL 兼容协议连接，部分数据库通过 Agent 驱动或可选的 [JDBC 插件](/cn/docs/plugins) 扩展。 +DBX 的新建连接窗口提供 70+ 数据库和服务 profile。Profile 决定默认端口、表单字段、图标和驱动入口，但“能建立连接”不等于“支持所有高级功能”。 + +当前版本的连接选择器和 `crates/dbx-core/assets/database-drivers.manifest.json` 是数据库类型与能力的权威来源。文档不维护容易过期的全量静态矩阵。 ## 连接类型 -新建连接窗口会提供带默认端口和驱动标签的预设类型。 +### SQL 和兼容协议 -| 分组 | 类型 | 说明 | -| ------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | -| 核心 SQL 数据库 | MySQL、PostgreSQL、SQLite、DuckDB、ClickHouse、SQL Server、Oracle、Redshift、DM、GaussDB、KWDB、Teradata、Vertica、Exasol、Firebird、SAP HANA、崖山 YashanDB、GBase | 直接出现在 DBX 连接选择器中 | -| 文档、键值、向量与配置服务 | Redis、MongoDB、Elasticsearch、Easysearch、Qdrant、Milvus、Weaviate、ChromaDB、etcd、Apache ZooKeeper、Nacos | 根据数据模型使用专门浏览器、管理控制台或查询流程，不完全等同于关系型表格 | -| MySQL 兼容类型 | MariaDB、TiDB、OceanBase、Doris、SelectDB、StarRocks、Manticore Search、GoldenDB、TDSQL、PolarDB、GreatSQL、自定义 MySQL | 复用 MySQL 风格连接能力 | -| PostgreSQL 兼容类型 | openGauss、KingBase、HighGo、Vastbase、CockroachDB、自定义 PostgreSQL | 复用 PostgreSQL 风格连接能力 | -| 文件型数据库 | SQLite、DuckDB、Microsoft Access、RQLite、Turso | 选择本地数据库文件或 HTTP 端点，不填写主机和端口 | -| 时序与边缘数据库 | Cloudflare D1、InfluxDB、IoTDB、TDengine、Databend、QuestDB | 托管 SQLite、时序、IoT 或边缘场景 | -| 分析与消息服务 | Apache Spark、Dremio、Apache Pulsar、Apache Kafka、Apache RocketMQ、RabbitMQ | 用于分布式分析、消息和流管理场景 | -| Agent/JDBC 扩展类型 | H2、Snowflake、Trino、PrestoSQL、Hive、DB2、Informix、Neo4j、Cassandra、BigQuery、Kylin、SunDB、OSCAR、XuguDB、UXDB、Databricks、IRIS、JDBC | 功能覆盖取决于对应驱动路径 | +- MySQL、PostgreSQL、SQLite、SQL Server、ClickHouse、Oracle、Redshift 等核心 SQL 数据库 +- MariaDB、TiDB、OceanBase、Doris、SelectDB、StarRocks、Manticore Search、GoldenDB 等 MySQL 协议或语法兼容 profile +- openGauss、GaussDB、KingBase、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 分析数据库 -## 默认端口 +兼容协议只说明连接和部分方言可以复用。数据库版本、系统表、DDL、权限和管理接口不同，DBX 会用独立 profile 或能力覆盖避免错误地启用功能。 -| 类型 | 默认端口 | -| ------------------------------------------- | -------: | -| MySQL / MariaDB / GoldenDB / TDSQL / PolarDB / GreatSQL | 3306 | -| PostgreSQL / openGauss / GaussDB / Vastbase | 5432 | -| Redis | 6379 | -| MongoDB | 27017 | -| ClickHouse | 8123 | -| SQL Server | 1433 | -| Oracle | 1521 | -| Elasticsearch / Easysearch | 9200 | -| Qdrant | 6333 | -| Milvus | 19530 | -| Weaviate | 8080 | -| ChromaDB | 8000 | -| TiDB | 4000 | -| OceanBase | 2881 | -| Doris / SelectDB / StarRocks / Databend | 9030 | -| Manticore Search | 9306 | -| Redshift | 5439 | -| CockroachDB | 26257 | -| DM | 5236 | -| KingBase | 54321 | -| HighGo | 5866 | -| UXDB | 52025 | -| KWDB | 26257 | -| 崖山 YashanDB | 1688 | -| GBase | 5258 | -| Firebird | 3050 | -| Teradata | 1025 | -| Vertica | 5433 | -| Exasol | 8563 | -| SAP HANA | 39015 | -| Databricks | 443 | -| Cloudflare D1 REST API | 443 | -| InfluxDB | 8086 | -| IoTDB | 6667 | -| etcd | 2379 | -| Apache ZooKeeper | 2181 | -| Nacos | 8848 | -| Nacos 控制台/admin API | 8085 | -| IRIS | 1972 | -| RQLite | 4001 | -| H2 | 9092 | -| Snowflake | 443 | -| Trino | 8080 | -| PrestoSQL | 8080 | -| Hive | 10000 | -| Apache Spark | 10015 | -| DB2 | 50000 | -| Informix | 9088 | -| Dremio | 31010 | -| Neo4j | 7687 | -| Cassandra | 9042 | -| BigQuery | 443 | -| Kylin | 7070 | -| SunDB | 22000 | -| OSCAR | 2003 | -| TDengine | 6041 | -| XuguDB | 5138 | -| QuestDB | 8812 | -| Apache Pulsar Admin API | 8080 | -| Apache Kafka | 9092 | -| Apache RocketMQ NameServer | 9876 | -| RabbitMQ AMQP | 5672 | +### 文件、边缘和托管数据库 -SQLite、DuckDB、Access 和 JDBC 在不需要网络端口时，会在连接模型中保存为端口 `0`。 +- SQLite、DuckDB、Microsoft Access +- Cloudflare D1、Turso、RQLite +- H2 和通过 JDBC URL 访问的本地数据库 -## 本地数据库测试环境 +Desktop 的文件路径属于本机。Docker/Web 的文件路径属于服务器容器或宿主机挂载目录；浏览器电脑上的路径不会自动映射到服务器。 -DBX 为 ClickHouse、MariaDB、MongoDB、MySQL、PostgreSQL 和 Redis 维护了固定版本、可重复创建的 Docker Compose 配方。需要干净的本地实例验证连接、驱动行为或 Bug 修复时可以直接使用。命令、安全默认值和支持版本请参阅[数据库测试实验室](/cn/docs/database-lab)。 +### 专用数据模型和服务 -## 功能矩阵 +- Redis、MongoDB +- Elasticsearch、Easysearch、Manticore Search +- Qdrant、Milvus、Weaviate、ChromaDB +- HBase +- Pulsar、Kafka、RocketMQ、RabbitMQ +- etcd、ZooKeeper、Nacos +- InfluxDB、IoTDB、TDengine 和其它时序/IoT profile -DBX 只会在具备足够元数据和 SQL 生成能力的数据库上启用高级功能。 +这些连接使用键值、文档、搜索、向量、消息或配置中心工作区，不应套用关系型表格和 SQL 的全部概念。入口详见 [专用工作区](/cn/docs/specialized-workspaces)。 -| 功能 | 支持类型 | -| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Schema 感知树 | PostgreSQL、SQL Server、Oracle、Redshift、DM、GaussDB、KWDB、KingBase、HighGo、UXDB、Vastbase、JDBC、H2、Snowflake、Trino、DB2、TDengine、XuguDB、Teradata、Vertica、Exasol、Firebird、SAP HANA、YashanDB、GBase | -| ER 图 | MySQL、PostgreSQL、SQLite、Cloudflare D1、SQL Server、Oracle、Redshift、DM、GaussDB、KWDB、KingBase、HighGo、UXDB、Vastbase、GoldenDB、Access、H2、DB2、Teradata、Vertica、Firebird、Exasol、GBase、YashanDB | -| 数据库搜索 | MySQL、PostgreSQL、SQLite、SQL Server、Oracle、Redshift、DuckDB、ClickHouse、DM、GaussDB、KWDB、KingBase、HighGo、UXDB、Vastbase、GoldenDB、Access、H2、Snowflake、Trino、Hive、DB2、Informix、Neo4j、Cassandra、BigQuery、Kylin、SunDB、TDengine、XuguDB、Databricks、Teradata、Vertica | -| 表数据导入 | MySQL、PostgreSQL、SQLite、Cloudflare D1、DuckDB、ClickHouse、SQL Server、Oracle、Doris、StarRocks、Redshift、DM、GaussDB、KWDB、KingBase、HighGo、UXDB、Vastbase、GoldenDB、Access、Databend | -| 几何字段地图预览 | PostgreSQL、HighGo、KingBase、Vastbase、openGauss、GaussDB（PostGIS `geometry` / `geography` 列在结果集中以 WKT 显示，并提供网格工具栏的"地图预览"按钮） | -| 表结构编辑器 | MySQL、PostgreSQL、SQLite、SQL Server、KWDB、UXDB | -| 创建数据库 | MySQL、PostgreSQL、SQL Server、ClickHouse、Oracle、DM、GaussDB、KWDB、Doris、StarRocks、Redshift、Teradata、Vertica | -| 字段血缘 | MySQL、PostgreSQL、SQLite、Cloudflare D1、SQL Server、Oracle、Redshift、DM、GaussDB、KWDB | -| 数据传输 | MySQL、PostgreSQL、SQLite、Cloudflare D1、SQL Server、Oracle、ClickHouse、DuckDB、DM、GaussDB、KWDB | -| 不支持 SQL 文件执行 | Redis、MongoDB、Elasticsearch、Easysearch、etcd、Nacos | +## 驱动运行时 -如果某个数据库可以连接，但没有出现在某个功能行中，该功能可能会被隐藏或受限。这是为了避免 DBX 生成无法可靠审查的 SQL。 +| 运行方式 | 说明 | 典型边界 | +| --- | --- | --- | +| 内置原生 | Rust 驱动编译进 DBX | 安装后可直接使用 | +| 原生 Agent / sidecar | DBX 管理独立 Go/Rust/外部进程 | 需要匹配平台文件；DuckDB、Oracle、KingBase、XuguDB、RabbitMQ 等路径可能使用独立运行时 | +| JDBC Agent | Java Agent 加厂商 JDBC 驱动 | 需要 JRE、Agent 和可合法获取的厂商 JAR | +| JDBC 插件 | 可选通用 JDBC 扩展 | 未识别数据库按通用 JDBC 能力运行 | -## 连接选项 +驱动的安装、更新、离线包和运行时监控见 [驱动管理](/cn/docs/driver-management)；自定义 JDBC 见 [JDBC 插件](/cn/docs/plugins)。 -大多数网络数据库支持主机、端口、用户名、密码、默认数据库、URL 参数、SSL、连接颜色和隧道/代理设置。文件型数据库会改为选择本地文件。 +## 能力等级 -DBX 也可以解析常见连接 URL，例如 MySQL、PostgreSQL、Redis、MongoDB、ClickHouse、SQL Server、Oracle、Elasticsearch、Easysearch、DM、GaussDB、KWDB、openGauss、TDengine、XuguDB、Access、Teradata、Vertica、Firebird、Exasol、GBase、YashanDB、SAP HANA、InfluxDB、QuestDB、IoTDB、etcd、Nacos、RQLite 和 Databricks。 +DBX 驱动清单使用从连接到操作的能力等级，并允许按数据库覆盖单项能力： -### Easysearch +| 能力层 | 含义 | +| --- | --- | +| Connect | 建立连接并执行该 profile 支持的基础查询 | +| Browse | 浏览数据库、Schema、表或专用对象 | +| Understand | 增加对象源码、搜索、关系理解等只读能力 | +| Operate | 增加表数据编辑等受控写入能力 | -DBX 提供独立的 Easysearch 连接类型，默认端口为 `9200`，通过 Elasticsearch 兼容的 HTTP REST API 连接。它复用 DBX 已有的 Elasticsearch 文档引擎，支持索引与文档浏览、Query DSL、REST 请求、常用 SQL 查询、分页与计数、文档增删改以及批量写入流程。 +具体功能还由独立 capability 控制，例如： -Easysearch 官方兼容基线面向 Elasticsearch 7.10 API 和生态，但这不表示所有 Elasticsearch 版本、X-Pack、ES|QL 或其他专有扩展都完全等价。HTTPS 实例请启用 SSL；使用自签名证书的测试环境也走同一 TLS 连接路径。 +- Schema 搜索和 ER 图 +- 表数据编辑和表结构编辑 +- 表导入和数据传输 +- SQL 文件执行 +- 字段血缘和执行计划 +- 创建数据库、用户管理和驱动管理 -### Cloudflare D1 +因此菜单是否出现比“数据库名称是否在支持列表中”更能反映当前路径。缺少入口时，应检查 DBX 版本、数据库 profile、驱动模式和已安装组件。 -新建 **Cloudflare D1** 连接时填写 Account ID、D1 Database ID（UUID）和 API Token。浏览元数据和查询至少需要 `D1 Read` 权限；插入、更新、DDL、导入或传输还需要 `D1 Write` 权限。DBX 会直接调用 Cloudflare HTTPS API，因此该类型不提供 SSH 或代理传输层。 +## 功能边界 -### Nacos 控制台 +### SQL 文件和关系型工具 -Nacos 连接会打开专用管理控制台，用于管理命名空间、配置、服务、实例、配置历史和 Raw API 请求。创建连接时请填写 Nacos 控制台/admin API 地址。Nacos 3 Docker 部署通常使用 `8085` 暴露控制台；旧版本也可能与服务端口共用 `8848`。 +Redis、MongoDB、搜索、向量、HBase、配置中心和消息队列工作区不会使用关系型 SQL 文件执行。部分 SQL 数据库只支持查询和浏览，不支持结构编辑、表导入或数据传输。 -### ClickHouse TLS +### 导入和传输 -ClickHouse 连接支持 TLS 加密。创建 ClickHouse 连接时，启用 TLS 开关即可通过 HTTPS 而非 HTTP 进行连接。建议对生产环境的 ClickHouse 实例或 ClickHouse Cloud 部署启用此选项。 +[表数据导入](/cn/docs/table-import) 与 [数据传输](/cn/docs/data-transfer) 都按 capability 过滤连接。跨引擎路径还受类型映射、键、identity、Schema 和目标 DDL 能力限制。 -### GaussDB 原生驱动 +### 备份和导出 -GaussDB 和 openGauss 现在使用原生 Rust 驱动（`rust-gaussdb`）而非 ODBC。之前使用 PostgreSQL 兼容路径的连接会自动迁移到 GaussDB 驱动。原生驱动提供更好的类型处理和针对 GaussDB 的元数据支持。 +- [数据库导出](/cn/docs/database-export) 是能力驱动的逻辑 SQL 导出 +- [数据库备份](/cn/docs/database-backup) 当前只在 Desktop 为 MySQL 和 PostgreSQL 提供定时一致性备份 +- 云同步和配置导出只迁移 DBX 配置，不会备份业务数据库 -### DuckDB 文件与内存模式 +### Desktop 和 Docker/Web -DuckDB 连接支持两种模式： +两种运行方式共享大部分 Rust 核心查询、元数据和安全策略，但并非功能完全相同。Desktop 才有本地 SQL 文件目录、系统文件选择、Deep Link、本机 CLI Agent 和定时数据库备份；Web 文件、驱动和 Agent 都位于服务器数据目录。 -- **文件模式**：选择 `.db` 或 `.duckdb` 文件进行持久化存储 -- **内存模式**：使用内存数据库进行临时分析。连接关闭后数据会丢失。 +## 默认端口和连接 URL -可以直接从连接表单创建新的 DuckDB 数据库文件，只需输入尚不存在的文件路径即可。 +连接 profile 会填入常见默认端口，例如 MySQL `3306`、PostgreSQL `5432`、Redis `6379`、MongoDB `27017`、SQL Server `1433`、Oracle `1521`、Elasticsearch `9200`、RabbitMQ AMQP `5672`。这些只是默认值，可以按部署修改。 -### DuckDB 连接初始化脚本 +RabbitMQ 等服务可能同时有业务端口和管理 API 端口；自定义 AMQP 端口不能用于推断 Management API 端口。SSH 隧道、HTTP 代理、TLS SNI 和实际拨号目标也应分别确认。 -DuckDB 连接支持在每次建立连接后执行一段 SQL 脚本，在连接对话框的**初始化脚本**中配置。典型用途包括加载扩展、创建密钥、调整会话参数以及附加额外的数据目录： +DBX 可以解析许多常见 DSN/URL，但不同数据库版本和云厂商参数差异很大。连接测试成功后仍应检查实际数据库、Schema、SSL 和权限范围。 -```sql -INSTALL quack; -LOAD quack; -ATTACH 'quack:analytics-host' AS remote (TOKEN 'your_token'); -``` +## 本地测试环境 -也可以附加 [DuckLake](https://ducklake.select/) 数据目录： +仓库提供 ClickHouse、MariaDB、MongoDB、MySQL、PostgreSQL 和 Redis 的固定 Docker Compose 测试环境，适合验证连接、驱动行为和回归。详见 [数据库测试实验室](/cn/docs/database-lab)。 -```sql -INSTALL ducklake; -LOAD ducklake; -ATTACH 'ducklake:/data/lake/meta.ducklake' AS lake (DATA_PATH '/data/lake/files'); -``` - -- 脚本中 ATTACH 的数据库（本地文件、DuckLake、远程 Quack 服务等）会像配置的附加数据库一样显示在侧边栏，并在每次重连时自动重新附加。建议显式指定 `AS 别名`，保持目录名稳定。 -- 语句按顺序执行；某条语句失败时连接会失败，并提示失败语句的序号和引擎报错，方便定位修改。 -- 脚本在每次建立新连接时都会执行，请优先使用可重复执行的语句，并在引擎或扩展支持时使用 `IF NOT EXISTS` 等保护条件。 -- 初始化脚本与连接密码同等对待：保存在本地密钥存储中，不会写入明文配置文件，云同步时只进入加密的敏感载荷——上例中 Quack 的 `TOKEN` 这类敏感内容不会出现在公开同步快照或导出里。 - -### SQLite 内存模式 - -SQLite 连接可以使用 `:memory:` 作为文件路径，创建临时的内存数据库。适用于快速实验或临时数据转换。 - -### Doris / StarRocks 多 Catalog - -Doris 与 StarRocks 作为 MPP 引擎，通过 Catalog 联邦访问外部数据源（`SHOW CATALOGS`）。DBX 会列出当前用户有权限读取的所有 Catalog，并以 `Catalog → 数据库 → 表` 的树形结构展示： - -- 内置的 `internal` Catalog 展示引擎自身的数据库与表。 -- 外部 Catalog（Hive、Iceberg、Hudi、Paimon、JDBC 等）同样列出其数据库与表。无权限访问的 Catalog 会被静默跳过。 -- 当只存在 `internal` Catalog 时，侧边栏保持扁平结构（不出现 Catalog 分组层），单 Catalog 部署不受影响。 - -从外部 Catalog 打开表时，数据预览使用三段式 `catalog.database.table` 名称，无需在会话中执行 `SWITCH`。外部 Catalog 仅支持表与视图——存储过程、序列、触发器、外键均不可用。 - -## 扩展支持 - -当目标数据库不在内置类型中，或团队必须使用厂商 JDBC 驱动时，可以使用 [JDBC 插件](/cn/docs/plugins)。JDBC 会把厂商驱动 JAR 放在 DBX 主应用之外，由你决定安装哪些驱动文件。 +## 相关页面 - - 安装 DBX、选择数据库类型并测试第一个连接。 - - - 安装可选 JDBC 插件并导入厂商驱动 JAR。 - - - 连接私有网络、跳板机、代理或 HTTP 隧道脚本后的数据库。 - + 查看非关系型、搜索、向量、消息和配置中心界面。 + 安装和诊断原生 Agent、sidecar、JDBC Agent 和 JRE。 + 了解数据库权限、只读保护、生产保护和自动化边界。 diff --git a/docs/content/docs/databases.mdx b/docs/content/docs/databases.mdx index dc75681b3b..70230eaad1 100644 --- a/docs/content/docs/databases.mdx +++ b/docs/content/docs/databases.mdx @@ -1,203 +1,113 @@ --- title: Database Support -description: Understand which databases DBX can connect to and which advanced features are available per engine. +description: Understand DBX connection profiles, driver runtimes, specialized workspaces, and capability-gated advanced features. --- -DBX uses native Rust drivers for the main app whenever possible. Some engines are compatibility profiles over MySQL or PostgreSQL protocols, and some are handled through Agent drivers or the optional [JDBC Plugin](/en/docs/plugins). +The new-connection picker provides more than 70 database and service profiles. A profile defines defaults, form fields, presentation, and a driver entry point, but being able to connect does not mean every advanced feature is available. -## Connection Profiles +The installed connection picker and `crates/dbx-core/assets/database-drivers.manifest.json` are authoritative for current types and capabilities. This page intentionally avoids a brittle exhaustive matrix. -The connection dialog exposes ready-to-use profiles with default ports and driver labels. +## Connection Families -| Group | Profiles | Notes | -| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | -| Core SQL engines | MySQL, PostgreSQL, SQLite, DuckDB, ClickHouse, SQL Server, Oracle, Redshift, DM, GaussDB, KWDB, Teradata, Vertica, Exasol, Firebird, SAP HANA, YashanDB, GBase | Available directly in the DBX connection picker | -| Document, key-value, vector, and config services | Redis, MongoDB, Elasticsearch, Easysearch, Qdrant, Milvus, Weaviate, ChromaDB, etcd, Apache ZooKeeper, Nacos | Use dedicated browsers, admin consoles, or query flows instead of the generic relational grid where appropriate | -| MySQL-compatible profiles | MariaDB, TiDB, OceanBase, Doris, SelectDB, StarRocks, Manticore Search, GoldenDB, TDSQL, PolarDB, GreatSQL, custom MySQL | Reuse MySQL-style connection handling where the engine speaks a compatible protocol | -| PostgreSQL-compatible profiles | openGauss, KingBase, HighGo, Vastbase, CockroachDB, custom PostgreSQL | Reuse PostgreSQL-style connection handling where the engine speaks a compatible protocol | -| File-based engines | SQLite, DuckDB, Microsoft Access, RQLite, Turso | Choose a local database file or HTTP endpoint instead of host and port | -| Time-series and edge | Cloudflare D1, InfluxDB, IoTDB, TDengine, Databend, QuestDB | Managed SQLite, time-series, IoT, or edge workloads | -| Analytics and messaging services | Apache Spark, Dremio, Apache Pulsar, Apache Kafka, Apache RocketMQ, RabbitMQ | Distributed analytics, messaging, and stream-management workloads | -| Agent/JDBC-oriented engines | H2, Snowflake, Trino, PrestoSQL, Hive, DB2, Informix, Neo4j, Cassandra, BigQuery, Kylin, SunDB, OSCAR, XuguDB, UXDB, Databricks, IRIS, JDBC | Feature coverage depends on the driver path used by that engine | +### SQL and Compatible Protocols -## Default Ports +- Core SQL engines such as MySQL, PostgreSQL, SQLite, SQL Server, ClickHouse, Oracle, and Redshift +- MySQL-protocol or syntax profiles such as MariaDB, TiDB, OceanBase, Doris, SelectDB, StarRocks, Manticore Search, and GoldenDB +- PostgreSQL-compatible profiles such as openGauss, GaussDB, KingBase, HighGo, Vastbase, and CockroachDB +- Vendor databases including DM, KWDB, YashanDB, GBase, Teradata, Vertica, Exasol, Firebird, and SAP HANA +- Agent/JDBC analytics engines such as Snowflake, Trino, PrestoSQL, Hive, Spark, DB2, Informix, Databricks, and BigQuery -| Profile | Default Port | -| ------------------------------------------- | -----------: | -| MySQL / MariaDB / GoldenDB / TDSQL / PolarDB / GreatSQL | 3306 | -| PostgreSQL / openGauss / GaussDB / Vastbase | 5432 | -| Redis | 6379 | -| MongoDB | 27017 | -| ClickHouse | 8123 | -| SQL Server | 1433 | -| Oracle | 1521 | -| Elasticsearch / Easysearch | 9200 | -| Qdrant | 6333 | -| Milvus | 19530 | -| Weaviate | 8080 | -| ChromaDB | 8000 | -| TiDB | 4000 | -| OceanBase | 2881 | -| Doris / SelectDB / StarRocks / Databend | 9030 | -| Manticore Search | 9306 | -| Redshift | 5439 | -| CockroachDB | 26257 | -| DM | 5236 | -| KingBase | 54321 | -| HighGo | 5866 | -| UXDB | 52025 | -| KWDB | 26257 | -| YashanDB | 1688 | -| GBase | 5258 | -| Firebird | 3050 | -| Teradata | 1025 | -| Vertica | 5433 | -| Exasol | 8563 | -| SAP HANA | 39015 | -| Databricks | 443 | -| Cloudflare D1 REST API | 443 | -| InfluxDB | 8086 | -| IoTDB | 6667 | -| etcd | 2379 | -| Apache ZooKeeper | 2181 | -| Nacos | 8848 | -| Nacos console/admin API | 8085 | -| IRIS | 1972 | -| RQLite | 4001 | -| H2 | 9092 | -| Snowflake | 443 | -| Trino | 8080 | -| PrestoSQL | 8080 | -| Hive | 10000 | -| Apache Spark | 10015 | -| DB2 | 50000 | -| Informix | 9088 | -| Dremio | 31010 | -| Neo4j | 7687 | -| Cassandra | 9042 | -| BigQuery | 443 | -| Kylin | 7070 | -| SunDB | 22000 | -| OSCAR | 2003 | -| TDengine | 6041 | -| XuguDB | 5138 | -| QuestDB | 8812 | -| Apache Pulsar Admin API | 8080 | -| Apache Kafka | 9092 | -| Apache RocketMQ NameServer | 9876 | -| RabbitMQ AMQP | 5672 | +Protocol compatibility covers only connection and selected dialect behavior. Versions, system catalogs, DDL, privileges, and management APIs differ, so DBX uses separate profiles and capability overrides instead of enabling features by family name alone. -SQLite, DuckDB, Access, and JDBC profiles use port `0` in the saved connection model when a network port is not part of the connection. +### File, Edge, and Hosted Databases -## Local database test environments +- SQLite, DuckDB, and Microsoft Access +- Cloudflare D1, Turso, and RQLite +- H2 and local databases reached through JDBC URLs -DBX maintains pinned, reproducible Docker Compose recipes for ClickHouse, MariaDB, MongoDB, MySQL, PostgreSQL, and Redis. Use them when you need a clean local instance to test a connection, driver behavior, or a bug fix. See the [Database Test Lab](/en/docs/database-lab) for commands, safe defaults, and the supported versions. +Desktop file paths belong to the local computer. Docker/Web paths belong to the server container or mounted host storage; a path on the browser computer is not mapped automatically. -## Feature Matrix +### Specialized Data Models and Services -DBX intentionally enables advanced workflows only where the app has enough metadata and SQL-generation support. +- Redis and MongoDB +- Elasticsearch, Easysearch, and Manticore Search +- Qdrant, Milvus, Weaviate, and ChromaDB +- HBase +- Pulsar, Kafka, RocketMQ, and RabbitMQ +- etcd, ZooKeeper, and Nacos +- InfluxDB, IoTDB, TDengine, and other time-series or IoT profiles -| Feature | Supported Types | -| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Schema-aware tree | PostgreSQL, SQL Server, Oracle, Redshift, DM, GaussDB, KWDB, KingBase, HighGo, UXDB, Vastbase, JDBC, H2, Snowflake, Trino, DB2, TDengine, XuguDB, Teradata, Vertica, Exasol, Firebird, SAP HANA, YashanDB, GBase | -| ER diagram | MySQL, PostgreSQL, SQLite, Cloudflare D1, SQL Server, Oracle, Redshift, DM, GaussDB, KWDB, KingBase, HighGo, UXDB, Vastbase, GoldenDB, Access, H2, DB2, Teradata, Vertica, Firebird, Exasol, GBase, YashanDB | -| Database search | MySQL, PostgreSQL, SQLite, SQL Server, Oracle, Redshift, DuckDB, ClickHouse, DM, GaussDB, KWDB, KingBase, HighGo, UXDB, Vastbase, GoldenDB, Access, H2, Snowflake, Trino, Hive, DB2, Informix, Neo4j, Cassandra, BigQuery, Kylin, SunDB, TDengine, XuguDB, Databricks, Teradata, Vertica | -| Table import | MySQL, PostgreSQL, SQLite, Cloudflare D1, DuckDB, ClickHouse, SQL Server, Oracle, Doris, StarRocks, Redshift, DM, GaussDB, KWDB, KingBase, HighGo, UXDB, Vastbase, GoldenDB, Access, Databend | -| Geometry map preview | PostgreSQL, HighGo, KingBase, Vastbase, openGauss, GaussDB (PostGIS `geometry` / `geography` columns are returned as WKT in the result grid and unlock the grid-toolbar map preview button) | -| Table structure editor | MySQL, PostgreSQL, SQLite, SQL Server, KWDB, UXDB | -| Create database | MySQL, PostgreSQL, SQL Server, ClickHouse, Oracle, DM, GaussDB, KWDB, Doris, StarRocks, Redshift, Teradata, Vertica | -| Field lineage | MySQL, PostgreSQL, SQLite, Cloudflare D1, SQL Server, Oracle, Redshift, DM, GaussDB, KWDB | -| Data transfer | MySQL, PostgreSQL, SQLite, Cloudflare D1, SQL Server, Oracle, ClickHouse, DuckDB, DM, GaussDB, KWDB | -| SQL file execution unavailable | Redis, MongoDB, Elasticsearch, Easysearch, etcd, Nacos | +These connections use key-value, document, search, vector, messaging, or configuration-center workspaces. They do not inherit every relational grid or SQL concept. See [Specialized Workspaces](/en/docs/specialized-workspaces). -If a database can connect but does not appear in a feature row, that feature may be hidden or limited for that engine. This prevents DBX from generating SQL it cannot review reliably. +## Driver Runtimes -## Connection Options +| Runtime | Description | Typical boundary | +| --- | --- | --- | +| Built-in native | Rust driver compiled into DBX | Available immediately after installation | +| Native Agent / sidecar | DBX-managed Go, Rust, or external process | Requires platform files; DuckDB, Oracle, KingBase, XuguDB, RabbitMQ, and similar paths may use separate runtimes | +| JDBC Agent | Java Agent plus a vendor JDBC driver | Requires a JRE, Agent, and legally obtained vendor JAR | +| JDBC plugin | Optional generic JDBC extension | Unknown engines run with generic JDBC capabilities | -Most network databases support host, port, username, password, default database, optional URL parameters, SSL, connection color, and tunnel / proxy settings. File-based engines replace host and port with a file picker. +See [Driver Management](/en/docs/driver-management) for installation, upgrades, offline packages, and runtime monitoring, and [JDBC Plugin](/en/docs/plugins) for custom JDBC. -DBX can also parse common connection URLs for engines such as MySQL, PostgreSQL, Redis, MongoDB, ClickHouse, SQL Server, Oracle, Elasticsearch, Easysearch, DM, GaussDB, KWDB, openGauss, TDengine, XuguDB, Access, Teradata, Vertica, Firebird, Exasol, GBase, YashanDB, SAP HANA, InfluxDB, QuestDB, IoTDB, etcd, Nacos, RQLite, and Databricks. +## Capability Levels -### Easysearch +The driver manifest uses capability levels from basic connection through controlled operations, with per-engine overrides: -DBX provides a dedicated Easysearch connection type on port `9200` and connects through its Elasticsearch-compatible HTTP REST API. It reuses DBX's existing Elasticsearch document engine for index and document browsing, Query DSL, REST requests, common SQL queries, pagination and counts, document CRUD, and bulk write flows. +| Level | Meaning | +| --- | --- | +| Connect | Establish a connection and run profile-supported basic queries | +| Browse | Browse databases, schemas, tables, or specialized objects | +| Understand | Add read-only source, search, and relationship workflows | +| Operate | Add controlled writes such as table data editing | -Easysearch documents compatibility with the Elasticsearch 7.10 API and ecosystem, but this does not imply complete equivalence with every Elasticsearch version, X-Pack feature, ES|QL, or other proprietary extension. Enable SSL for HTTPS endpoints; self-signed test deployments use the same TLS connection path. +Individual capabilities then control features such as: -### Cloudflare D1 +- Schema search and ER diagrams +- Table data and table structure editing +- Table import and data transfer +- SQL file execution +- Field lineage and query explain +- Database creation, user administration, and driver management -Create a **Cloudflare D1** connection with the Account ID, D1 Database ID (UUID), and an API Token. The token needs `D1 Read` permission for browsing and queries; add `D1 Write` for inserts, updates, DDL, imports, or transfers. DBX uses Cloudflare's HTTPS API directly, so SSH and proxy transport layers are not available for this profile. +Menu availability is therefore more meaningful than a static database name list. When an action is missing, check the DBX version, database profile, runtime mode, and installed components. -### Nacos Console +## Feature Boundaries -Nacos connections open a dedicated admin console for namespaces, configs, services, instances, config history, and raw API requests. Use the Nacos console/admin API address when creating the connection. Nacos 3 Docker deployments usually expose that console on `8085`; older deployments may share `8848` with the service port. +### SQL Files and Relational Tools -### ClickHouse TLS +Redis, MongoDB, search, vector, HBase, configuration-center, and message-queue workspaces do not use relational SQL file execution. Some SQL engines support query and browse workflows without structure editing, import, or transfer. -ClickHouse connections support TLS encryption. When creating a ClickHouse connection, enable the TLS toggle to connect over HTTPS instead of HTTP. This is recommended for production ClickHouse instances or any ClickHouse Cloud deployments. +### Import and Transfer -### GaussDB Native Driver +[Table Import](/en/docs/table-import) and [Data Transfer](/en/docs/data-transfer) filter connections by capability. Cross-engine paths also depend on type mapping, keys, identity columns, schemas, and target DDL support. -GaussDB and openGauss now use a native Rust driver (`rust-gaussdb`) instead of ODBC. Connections that previously used the PostgreSQL compatibility path are auto-migrated to the GaussDB driver. The native driver provides better type handling and metadata support specific to GaussDB. +### Backup and Export -### DuckDB File and Memory Modes +- [Database Export](/en/docs/database-export) is a capability-driven logical SQL export +- [Database Backup](/en/docs/database-backup) currently schedules consistent MySQL and PostgreSQL backups in Desktop only +- Cloud Sync and configuration export migrate DBX settings, not business database contents -DuckDB connections support two modes: +### Desktop and Docker/Web -- **File mode**: Select a `.db` or `.duckdb` file for persistent storage -- **Memory mode**: Use an in-memory database for temporary analysis. Data is lost when the connection is closed. +Both runtimes share most Rust core query, metadata, and safety policy, but are not feature-identical. Local SQL folders, system file selection, Deep Links, local CLI Agents, and scheduled database backup are Desktop-only. Web files, drivers, and Agents live in the server data directory. -Create a new DuckDB database file directly from the connection form by entering a path that does not yet exist. +## Default Ports and Connection URLs -### DuckDB Connection Init Script +Profiles prefill common defaults such as MySQL `3306`, PostgreSQL `5432`, Redis `6379`, MongoDB `27017`, SQL Server `1433`, Oracle `1521`, Elasticsearch `9200`, and RabbitMQ AMQP `5672`. These are defaults, not requirements. -DuckDB connections can run a SQL script every time the connection is established. Configure it in the **Init Script** field of the connection dialog. Typical uses are loading extensions, creating secrets, tuning session options, and attaching additional catalogs: +Services such as RabbitMQ may expose separate business and management ports. A custom AMQP port must not be used to infer the Management API port. SSH tunnels, HTTP proxies, TLS SNI, and physical dial targets should also be verified independently. -```sql -INSTALL quack; -LOAD quack; -ATTACH 'quack:analytics-host' AS remote (TOKEN 'your_token'); -``` +DBX parses many common DSNs and URLs, but parameters vary by version and cloud vendor. After a successful connection test, still verify the actual database, schema, SSL, and privilege scope. -Or attach a [DuckLake](https://ducklake.select/) catalog: +## Local Test Environments -```sql -INSTALL ducklake; -LOAD ducklake; -ATTACH 'ducklake:/data/lake/meta.ducklake' AS lake (DATA_PATH '/data/lake/files'); -``` +The repository includes pinned Docker Compose labs for ClickHouse, MariaDB, MongoDB, MySQL, PostgreSQL, and Redis. Use [Database Test Lab](/en/docs/database-lab) for connection, driver, and regression testing. -- Databases attached by the script (local files, DuckLake, remote Quack servers, ...) appear in the sidebar like configured attached databases, and are re-attached automatically on every reconnect. Prefer an explicit `AS alias` so catalog names stay stable. -- Statements run in order; when one fails, the connection fails with the statement number and the engine error so the script is easy to fix. -- The script runs on every new connection, so prefer statements that are safe to repeat, and use guards such as `IF NOT EXISTS` where the engine or extension supports them. -- The init script is stored like a connection password: it lives in the local secret store, is never written to plain-text config files, and only syncs inside the encrypted sensitive payload — tokens such as the Quack `TOKEN` above stay out of public sync snapshots and exports. - -### In-Memory SQLite - -SQLite connections can use `:memory:` as the file path for ephemeral, in-memory databases. This is useful for quick experiments or temporary data transformations. - -### Doris / StarRocks Multi-Catalog - -Doris and StarRocks are MPP engines that federate external data through catalogs (`SHOW CATALOGS`). DBX lists every catalog the current user can read and renders them as a `catalog → database → table` tree: - -- The built-in `internal` catalog shows the engine's own databases and tables. -- External catalogs (Hive, Iceberg, Hudi, Paimon, JDBC, etc.) list their databases and tables the same way. Catalogs you lack permission to read are skipped silently. -- When only the `internal` catalog is present, the sidebar stays flat (no catalog grouping layer) so single-catalog deployments are unaffected. - -Opening a table from an external catalog previews its data using the 3-part `catalog.database.table` name, so no session `SWITCH` is needed. External catalogs expose tables and views only — routines, sequences, triggers, and foreign keys are not available. - -## Extending Support - -Use the [JDBC Plugin](/en/docs/plugins) when a database is not covered by the built-in profiles or when your team must use a vendor JDBC driver. JDBC keeps vendor driver JARs outside the main DBX app, so you control which driver files are installed. +## Related Pages - - Install DBX, choose a database profile, and test the first connection. - - - Install the optional JDBC plugin and import vendor driver JARs. - - - Reach databases behind private networks, bastion hosts, proxies, or HTTP tunnel scripts. - + Review non-relational, search, vector, messaging, and configuration-center interfaces. + Install and diagnose native Agents, sidecars, JDBC Agents, and JREs. + Understand database privileges, read-only protection, production protection, and automation boundaries. diff --git a/docs/content/docs/driver-management.cn.mdx b/docs/content/docs/driver-management.cn.mdx index 0825c694e9..01a50aeb07 100644 --- a/docs/content/docs/driver-management.cn.mdx +++ b/docs/content/docs/driver-management.cn.mdx @@ -9,11 +9,11 @@ DBX 使用混合驱动架构：内置 Rust 驱动、独立原生 Agent，以及 | 驱动类型 | 工作方式 | 适用场景 | | ------------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| 原生（内置） | Rust 驱动编译进 DBX | MySQL、PostgreSQL、SQLite、SQL Server、Redis、MongoDB、DuckDB、ClickHouse 等 | -| 原生 Agent | DBX 管理的 Go/Rust 独立进程 | Oracle、KingBase、虚谷 XuguDB，以及存在成熟原生驱动的数据库 | +| 原生（内置） | Rust 驱动编译进 DBX | MySQL、PostgreSQL、SQLite、SQL Server、Redis、MongoDB、ClickHouse 等 | +| 原生 Agent / 外部驱动 | DBX 管理的 Go/Rust 独立进程或 sidecar | Oracle、KingBase、虚谷 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 只需对应平台的可执行文件，JDBC Agent 还需要 JRE。首次创建连接时 DBX 会自动安装匹配的组件。 +内置驱动可直接使用；原生 Agent/sidecar 需要对应平台文件，JDBC Agent 还需要 JRE。连接对话框会提示缺少的组件，但安装是否自动完成取决于网络、平台、驱动许可和当前设置。 ## 驱动商店 @@ -67,6 +67,12 @@ DBX 会定期检查驱动更新： - 点击**升级全部驱动**一次性更新所有已安装的驱动 - 单个驱动可从商店中对应条目升级 +## 运行时监控 + +驱动管理会汇总正在运行的外部驱动和 Agent，包括协议模式、活动 Session、PID、内存、CPU、运行时长和最后错误。支持控制的运行时可以在这里停止或重启；共享运行时可能服务多个连接，操作前应检查活动 Session。 + +RabbitMQ 等消息队列 Agent 还可能同时使用业务协议和管理 API。自定义 AMQP/管理端口、SSH 隧道和 TLS 目标必须分别配置，不能从一个端口推断另一个端口。 + ## 离线驱动导入 对于无法访问互联网的环境，DBX 支持离线驱动安装： diff --git a/docs/content/docs/driver-management.mdx b/docs/content/docs/driver-management.mdx index 6a6b00c330..f92339408d 100644 --- a/docs/content/docs/driver-management.mdx +++ b/docs/content/docs/driver-management.mdx @@ -9,11 +9,11 @@ DBX uses a hybrid driver architecture: built-in Rust drivers, standalone native | Driver Type | How It Works | Best For | | ----------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Native (built-in) | Rust drivers compiled into DBX | MySQL, PostgreSQL, SQLite, SQL Server, Redis, MongoDB, DuckDB, ClickHouse, and more | -| Native Agent | Standalone Go/Rust process managed by DBX | Oracle, KingBase, XuguDB, and databases with a mature native driver | +| Native (built-in) | Rust drivers compiled into DBX | MySQL, PostgreSQL, SQLite, SQL Server, Redis, MongoDB, ClickHouse, and more | +| Native Agent / external driver | Standalone Go/Rust process or sidecar managed by DBX | Oracle, KingBase, XuguDB, DuckDB, and connections such as RabbitMQ that require a separate runtime | | JDBC Agent | Java subprocess managed by DBX | Databases that require JDBC: GaussDB, openGauss, DM, HighGo, Vastbase, UXDB, Trino, Hive, DB2, Informix, Neo4j, TDengine, YashanDB, GoldenDB, Kylin, SunDB, and more | -Built-in drivers work immediately. Native Agents require only a platform-specific executable, while JDBC Agents also require a JRE. DBX handles the matching installation when you first create a connection. +Built-in drivers work immediately. Native Agents and sidecars need platform files, while JDBC Agents also need a JRE. The connection dialog prompts for missing components, but automatic installation depends on network access, platform, licensing, and current settings. ## Driver Store @@ -67,6 +67,12 @@ DBX checks for driver updates periodically: - Click **Upgrade All Drivers** to update all installed drivers at once - Individual drivers can be upgraded from their entry in the store +## Runtime Monitoring + +Driver Manager summarizes active external drivers and Agents, including protocol mode, active sessions, PID, memory, CPU, uptime, and the latest error. Supported runtimes can be stopped or restarted here. A shared runtime may serve multiple connections, so inspect active sessions first. + +Message-queue Agents such as RabbitMQ may use both a business protocol and a management API. Custom AMQP/management ports, SSH tunnels, and TLS targets must be configured independently; one port must not be inferred from the other. + ## Offline Driver Import For environments without internet access, DBX supports offline driver installation: diff --git a/docs/content/docs/field-lineage.cn.mdx b/docs/content/docs/field-lineage.cn.mdx index 4301f9a8b3..b2aa9e373e 100644 --- a/docs/content/docs/field-lineage.cn.mdx +++ b/docs/content/docs/field-lineage.cn.mdx @@ -1,51 +1,91 @@ --- title: 字段血缘 -description: 追踪字段之间的来源、引用和潜在关联，辅助理解数据库结构。 +description: 从外键、视图定义、查询历史和同名字段中分析字段的上游、下游与潜在影响范围。 --- -字段血缘用于回答一个常见问题：某个字段的数据从哪里来，又可能影响到哪里。它适合理解复杂库、排查影响范围和阅读历史结构。 +字段血缘用于回答“这个字段从哪里来、被谁使用、修改后可能影响什么”。DBX 会组合数据库元数据和本地查询历史，并按证据强度标记关系，而不是把所有同名字段都当成确定依赖。 -字段血缘目前支持 MySQL、PostgreSQL、SQLite、SQL Server、Oracle、Redshift、DM 和 GaussDB。其他引擎可能无法提供足够的关系元数据，因此不会展示完整血缘。 +## 打开方式 -## 能解决什么问题 +从字段节点、表结构或相关上下文菜单打开字段血缘。当前字段会作为中心目标，结果列表展示相关表、字段、视图或历史 SQL。 -- 修改字段前，查看哪些表、视图或查询可能依赖它 -- 接手陌生数据库时，快速理解字段之间的关系 -- 分析报表字段的来源和可能的上游数据 -- 发现没有显式外键但命名相似的潜在关系 +## 关系来源与可信度 -## 关系来源 +| 来源 | 默认可信度 | 说明 | +| --- | --- | --- | +| 外键 | 确定 | 数据库声明了当前字段与目标字段的约束关系 | +| 视图定义 | 高置信或可能 | 视图源码同时引用目标表和字段时置信度更高 | +| 查询历史 | 高置信或可能 | 历史 SQL 同时命中表和字段时更可信 | +| 同名字段 | 可能 | 仅根据字段名相同推断，需要业务确认 | -| 来源 | 可信度 | 说明 | -| -------- | ------ | ------------------------------------------------ | -| 外键 | 高 | 数据库中已经声明的外键约束 | -| 视图 | 高 | 从视图定义中分析字段映射 | -| 查询历史 | 中 | 从执行过的 SQL 中分析 `JOIN`、`WHERE` 等引用关系 | -| 同名字段 | 低到中 | 根据字段名称相似性推断可能关系 | +界面会区分**确定**、**高置信**和**可能相关**。筛选低置信结果可以先聚焦外键和明确源码引用。 -字段血缘是辅助分析工具，不等同于数据治理平台里的强一致血缘。对关键结论，请结合数据库约束、视图定义和业务代码确认。 +## 搜索与筛选 -## 查看方式 +- 搜索表、字段、视图或 SQL 片段 +- 按置信度过滤 +- 查看当前显示数量和总关系数 +- 复制表名或字段名 +- 打开目标表数据或结构 +- 从结果回到对应对象树位置 -- 搜索表名或字段名 -- 按置信度筛选关系 -- 点击表或字段跳转到数据浏览或结构查看 -- 从某个字段出发查看上游或下游关联 +血缘读取会按数据库能力加载外键、视图源码和相关元数据。大型 Schema 首次分析可能需要时间。 -## 使用建议 +## 查询历史的作用 -- 优先相信外键和视图来源 -- 对查询历史和同名字段推断保持审查 -- 修改字段前，结合 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) 的功能矩阵为准 + +关键结构变更仍应结合数据库约束、对象源码、应用代码搜索和实际业务负责人确认。字段血缘用于缩小调查范围，不替代变更影响分析。 - 查看表、字段、外键和注释。 + 查看字段、外键、注释和对象层级。 + + + 查看视图、过程、函数和触发器定义。 - 检查不同环境之间的结构差异。 + 检查不同环境之间的结构差异和部署脚本。 diff --git a/docs/content/docs/field-lineage.mdx b/docs/content/docs/field-lineage.mdx index 929a7a9b54..f060c51ef5 100644 --- a/docs/content/docs/field-lineage.mdx +++ b/docs/content/docs/field-lineage.mdx @@ -1,51 +1,91 @@ --- title: Field Lineage -description: Trace where columns come from, how they are referenced, and which relationships may exist. +description: Analyze upstream, downstream, and potential column impact from foreign keys, view definitions, query history, and matching names. --- -Field Lineage helps answer a common question: where does a column's data come from, and what might depend on it? Use it to understand complex schemas, inspect impact, and read legacy structures. +Field lineage helps answer where a column comes from, where it is used, and what a change might affect. DBX combines database metadata with local query history and labels evidence strength instead of treating every matching name as a confirmed dependency. -Field Lineage is enabled for MySQL, PostgreSQL, SQLite, SQL Server, Oracle, Redshift, DM, and GaussDB. Other engines may not expose enough relationship metadata for DBX to build useful lineage. +## Open Lineage -## What It Helps With +Open field lineage from a column node, table structure, or related context menu. The active column becomes the target, and results list related tables, columns, views, or historical SQL. -- Before changing a column, see which tables, views, or queries may depend on it -- Understand relationships in an unfamiliar database -- Trace where report fields may originate -- Discover possible relationships that are not declared as foreign keys +## Relationship Sources and Confidence -## Relationship Sources +| Source | Default confidence | Meaning | +| --- | --- | --- | +| Foreign key | Certain | The database declares a constraint between the current and target columns | +| View definition | Likely or possible | Confidence is higher when view source references both the target table and column | +| Query history | Likely or possible | Historical SQL is stronger evidence when both table and column are present | +| Same-name column | Possible | Name-based inference only and requires business confirmation | -| Source | Confidence | Details | -| ----------------- | ------------- | ---------------------------------------------------------------------------- | -| Foreign keys | High | Constraints declared in the database | -| Views | High | Field mappings analyzed from view definitions | -| Query history | Medium | Relationships inferred from executed SQL, including `JOIN` and `WHERE` usage | -| Same-name columns | Low to medium | Possible relationships inferred from similar column names | +The UI distinguishes **Certain**, **Likely**, and **Possible**. Filter lower-confidence results to focus on foreign keys and explicit source references first. -Field Lineage is an analysis aid, not a strongly governed lineage platform. For critical decisions, confirm results with database constraints, view definitions, and application code. +## Search and Filters -## Navigation +- Search tables, columns, views, or SQL fragments +- Filter by confidence +- See displayed and total relationship counts +- Copy table or column names +- Open target table data or structure +- Reveal the related object in the tree -- Search by table or column name -- Filter relationships by confidence -- Click a table or column to open data or structure views -- Start from one column and inspect upstream or downstream relationships +Lineage loads foreign keys, view source, and related metadata according to database capability. Initial analysis can take time in large schemas. -## Recommendations +## Query History as Evidence -- Treat foreign key and view relationships as the strongest signals -- Review query-history and same-name inferences carefully -- Before changing a column, combine lineage with schema diff and application code search -- For important business fields, add database constraints or documentation comments where possible +DBX uses executed queries as supporting evidence, including: -## Related Features +- Fields that appear together in a `JOIN` +- Target columns referenced in `WHERE`, `SELECT`, or expressions +- Historical repair or reporting SQL that uses a matching field + +History only represents SQL executed or saved in DBX. It does not cover all application code, ETL, BI, or other clients. + +Query history can contain sensitive table names, predicates, and literals. Review privacy before demonstrating lineage, exporting logs, or sharing screenshots. + +## View and Source Analysis + +View relationships use definitions returned by the database. Confidence can be lower with: + +- Dynamic SQL or generated procedure text +- Ambiguous tables or columns without explicit schema +- `SELECT *`, complex subqueries, or vendor extensions +- Databases that do not return complete view source + +Open a view result and inspect source in [Object Browser](/en/docs/object-browser) for manual confirmation. + +## Workflows + +### Before Changing a Column + +1. Review confirmed foreign-key relationships +2. Inspect likely views and historical SQL +3. Validate possible same-name relationships with business context +4. Continue searching application repositories, ETL, and BI assets +5. Use [Schema Diff](/en/docs/schema-diff) to review target-environment changes + +### Understanding an Unfamiliar Database + +Start with primary keys, business identifiers, user IDs, or time columns and follow related tables and views. Column comments and object source are usually stronger evidence than name matching alone. + +## Support and Boundaries + +- Lineage requires foreign keys, view source, or parseable query history, so coverage varies by database +- Without declared foreign keys, DBX can only provide view, history, and same-name clues +- Results are not a strongly consistent data-governance graph and do not include every application, message flow, ETL, or BI system +- Deleting history or clearing local data reduces the query-history source +- Use the [Database Support](/en/docs/databases) matrix for current engine coverage + +Important schema changes still need database constraints, source review, application-code search, and business-owner confirmation. Lineage narrows the investigation; it does not replace impact analysis. - - Inspect tables, columns, foreign keys, and comments. + + Inspect columns, foreign keys, comments, and object hierarchy. - - Compare structure differences across environments. + + Inspect view, procedure, function, and trigger definitions. + + + Review environment differences and deployment scripts. diff --git a/docs/content/docs/getting-started.cn.mdx b/docs/content/docs/getting-started.cn.mdx index 39dda4cfc4..9a6d9c67c4 100644 --- a/docs/content/docs/getting-started.cn.mdx +++ b/docs/content/docs/getting-started.cn.mdx @@ -124,12 +124,14 @@ description: 安装 DBX、创建第一个连接，并了解桌面版、Docker ## 桌面版还是 Docker -| 模式 | 适合场景 | 后端路径 | 存储位置 | -| ------------ | ------------------------------------------------------ | ----------------------------- | ------------------------------ | -| 桌面版 | 本机日常工作、本地文件、原生窗口、从 MCP 打开 DBX 界面 | Tauri 命令调用 Rust core | 本机应用数据目录 | -| Docker / Web | 服务器自托管、浏览器访问 | HTTP 路由调用同一套 Rust core | Docker 卷或服务器数据目录 | +| 模式 | 适合场景 | 存储位置 | 需要注意 | +| --- | --- | --- | --- | +| 桌面版 | 本机日常工作、本地数据库文件、完整工作台 | 本机应用数据目录 | 支持本地 SQL 文件树/SQL 库、桌面 Deep Link 和操作系统文件集成 | +| Docker / Web | 服务器自托管、远程浏览器访问 | Docker 卷或服务器数据目录 | 文件路径属于服务器；部分本地文件和桌面集成功能不可用 | -核心数据库能力保持一致，但通过 MCP 打开桌面窗口等集成需要 DBX 桌面版正在运行。 +桌面版和 Web 版共享大部分数据库工作流和 Rust 核心能力，但并非所有本地集成完全一致。需要 SQLite、DuckDB、Access、外部 SQL 文件或本机目录时，先确认文件实际位于哪台机器；Docker 中通常还需要把目录挂载进容器。 + +通过 MCP 打开表或展示查询结果等桌面 UI 工具，需要 DBX 桌面版正在运行。只使用查询类 MCP 工具时，可以直接读取本机 DBX 数据目录，或连接 DBX Web/Docker 后端。 ## 创建第一个连接 @@ -176,10 +178,14 @@ description: 安装 DBX、创建第一个连接，并了解桌面版、Docker ## 降低生产误操作 -- 给生产连接起明确名称，例如 `prod-orders`。 -- 用连接颜色区分生产、预发、测试和本地环境。 -- 一个服务器上数据库很多时，只显示当前需要的数据库。 +- 给生产连接起明确名称，例如 `prod-orders`，并使用颜色、分组和备注说明用途。 +- 查询专用连接同时启用数据库只读账号和 DBX **只读连接**。 +- 启用**生产环境保护**，按连接或指定数据库标记生产范围；写入时 DBX 会逐次要求明确确认。 +- 一个服务器上数据库或 Schema 很多时，只显示当前需要的对象，减少误选目标。 - 对编辑、导入、传输、SQL 文件执行或 Schema 同步生成的 SQL，先审查再执行。 +- 提供给 MCP 的连接使用 allowlist，并优先选择“只读”或“数据读写”，不要默认开放“完全访问”。 + +完整行为和推荐配置见 [生产环境与写入安全](/cn/docs/production-safety)。 ## 下一步可以做什么 diff --git a/docs/content/docs/getting-started.mdx b/docs/content/docs/getting-started.mdx index ffa5dcd95a..bd74dc4ddf 100644 --- a/docs/content/docs/getting-started.mdx +++ b/docs/content/docs/getting-started.mdx @@ -118,12 +118,14 @@ This guide gets you through three things: ## Desktop Or Docker -| Mode | Best For | Backend Path | Storage | -| ------------ | --------------------------------------------------------------------- | -------------------------------------- | -------------------------------------- | -| Desktop | Daily local work, local files, native windows, DBX UI opened from MCP | Tauri commands calling the Rust core | Local app data directory | -| Docker / Web | Self-hosted access from a server or browser | HTTP routes calling the same Rust core | Docker volume or server data directory | +| Mode | Best For | Storage | Important Boundary | +| --- | --- | --- | --- | +| Desktop | Daily local work, local database files, the complete workbench | Local app data directory | Supports the local SQL file tree/library, desktop deep links, and OS file integration | +| Docker / Web | Self-hosting on a server and remote browser access | Docker volume or server data directory | Paths belong to the server; some local-file and desktop integrations are unavailable | -The core database features are shared, but desktop-only integrations such as opening DBX windows from MCP require the desktop app to be running. +Desktop and Web share most database workflows and the Rust core, but their local integrations are not identical. For SQLite, DuckDB, Access, external SQL files, or local directories, verify which machine owns the file; Docker normally requires mounting the directory into the container. + +MCP tools that open a table or display results in the desktop UI require DBX Desktop to be running. Query-only MCP tools can read the local DBX data directory directly or connect to a DBX Web/Docker backend. ## Create Your First Connection @@ -170,10 +172,14 @@ This guide gets you through three things: ## Reduce Production Mistakes -- Give production connections a distinct name, for example `prod-orders`. -- Use connection colors so production, staging, and local databases are visually different. -- Use visible database filtering when a server contains many databases but you only need a few. +- Give production connections a distinct name such as `prod-orders`, and use colors, groups, and notes to describe their purpose. +- For query-only access, combine a database read-only account with DBX **Read-only connection**. +- Enable **Production protection** for the whole connection or selected databases; DBX requires a fresh explicit confirmation for writes. +- When one server contains many databases or schemas, show only the objects you currently need. - Review generated SQL before applying edits, imports, transfers, SQL files, or schema sync operations. +- Put MCP connections behind an allowlist and prefer Read only or Data read/write instead of enabling Full access by default. + +See [Production and Write Safety](/en/docs/production-safety) for complete behavior and recommended configurations. ## What To Try Next diff --git a/docs/content/docs/keyboard-shortcuts.cn.mdx b/docs/content/docs/keyboard-shortcuts.cn.mdx index 11bdc7b725..91d197f084 100644 --- a/docs/content/docs/keyboard-shortcuts.cn.mdx +++ b/docs/content/docs/keyboard-shortcuts.cn.mdx @@ -1,83 +1,78 @@ --- title: 快捷键 -description: 配置和使用键盘快捷键，高效导航 DBX、执行查询和编辑数据。 +description: 查看当前默认按键，并在设置中为编辑器、表格、侧边栏和全局操作自定义快捷键。 --- -DBX 为常用操作提供可配置的键盘快捷键。使用默认快捷键或自定义它们以匹配你的工作流程。 +DBX 的快捷键来自同一份可配置 action registry。**设置 → 快捷键**显示当前版本和当前平台的实际绑定，是默认键变化或用户自定义后的权威来源。 -## 默认快捷键 +`Mod` 表示 macOS 的 `Cmd`，Windows/Linux 的 `Ctrl`。 -### 查询编辑器 +## 常用默认快捷键 -| 快捷键 | 操作 | -| -------------------------------------- | ---------------- | -| `Ctrl+Enter` / `Cmd+Enter` | 执行当前查询 | -| `Ctrl+\` / `Cmd+\` | 在新结果标签页中执行 | -| `Ctrl+Shift+Enter` / `Cmd+Shift+Enter` | 执行所有查询 | -| `Ctrl+/` / `Cmd+/` | 切换行注释 | -| `Ctrl+F` / `Cmd+F` | 在编辑器中搜索 | -| `Ctrl+S` / `Cmd+S` | 保存当前标签页 | -| `Ctrl+A` / `Cmd+A` | 全选 | -| `Shift+Alt+U` | 选中内容转为大写 | -| `Shift+Alt+L` | 选中内容转为小写 | -| `Tab` | 缩进选中行 | -| `Shift+Tab` | 取消缩进选中行 | +### SQL 编辑器 -### 数据表格 +| 默认键 | 操作 | +| --- | --- | +| `Mod+Enter` | 执行当前语句或选中 SQL | +| `Mod+\` | 在新的结果标签页执行 | +| `Shift+Mod+F` | 格式化 SQL | +| `Mod+/` | 切换行注释 | +| `Mod+S` | 保存 SQL | +| `Tab` | 接受补全 | +| `Shift+Tab` | 减少缩进 | +| `Mod+D` | 复制当前行 | +| `Shift+Mod+K` | 删除当前行 | +| `Alt+↑` / `Alt+↓` | 上下移动当前行 | +| `Shift+Alt+↑` / `Shift+Alt+↓` | 向上/下复制当前行 | +| `Shift+Alt+U` / `Shift+Alt+L` | 选中内容转大写/小写 | +| `Mod+.` | 折叠或展开代码块 | +| `Mod+Shift+A` | 把选中内容发送给 AI | -| 快捷键 | 操作 | -| ------------------------------ | -------------------------- | -| `F5` | 刷新当前数据 | -| `Ctrl+C` / `Cmd+C` | 复制选中单元格 | -| `Ctrl+Shift+C` / `Cmd+Shift+C` | 将选中行复制为 INSERT | -| `Delete` | 删除选中行（标记为待删除） | +当前 registry 没有“执行全部 SQL”的默认 action。需要运行多条语句时，选中范围执行或使用编辑器提供的多语句执行入口，不要依赖旧文档中的 `Ctrl/Cmd+Shift+Enter`。 -### 导航 +### 表格和数据 -| 快捷键 | 操作 | -| ------------------------------ | ------------------ | -| `Ctrl+P` / `Cmd+P` | 快速打开数据库对象 | -| `Ctrl+N` / `Cmd+N` | 新建查询标签页 | -| `Ctrl+Shift+F` / `Cmd+Shift+F` | 聚焦侧边栏搜索 | -| `Ctrl+,` / `Cmd+,` | 打开设置 | -| `Ctrl+W` / `Cmd+W` | 关闭当前标签页 | -| `鼠标中键`（点击标签页） | 关闭标签页 | +| 默认键 | 操作 | +| --- | --- | +| `F5` | 刷新当前数据 | +| `Mod+D` | 复制当前行 | +| `Delete` | 标记删除当前行 | +| `Tab` | 切换转置视图 | -## 快速打开（Ctrl+P） +普通复制/粘贴仍遵循平台标准按键，但“复制当前行”“删除当前行”和“切换转置”是 DBX 可配置 action。 -按 **Ctrl+P**（macOS 上为 **Cmd+P**）可快速导航到数据库对象，无需使用侧边栏： +### 全局和导航 -- 输入文本搜索表、视图、schema 或数据库 -- 模糊匹配可以用部分名称找到对象 -- 按 Enter 打开选中的对象 -- 在工作区的所有连接中工作 +| 默认键 | 操作 | +| --- | --- | +| `Mod+T` | 新建查询 | +| `Mod+P` | 快速打开 | +| `Mod+W` | 关闭当前标签页 | +| `Shift+Mod+[` / `Shift+Mod+]` | 上一个/下一个标签页 | +| `Mod+1` … `Mod+9` | 切换到指定标签页 | +| `Mod+B` | 显示或隐藏侧边栏 | +| `Mod+=` / `Mod+-` / `Mod+0` | 放大、缩小、重置 UI 缩放 | -当处理大型数据库时，快速打开特别有用，滚动侧边栏树会很慢。 +侧边栏还提供可配置的复制、粘贴、编辑连接和按住修饰键在新标签页打开数据等 action。 -## 配置快捷键 +## 快速打开 -打开**设置 → 快捷键**来自定义按键绑定： +按 `Mod+P` 搜索当前工作区中的连接、数据库、Schema、表、视图和保存的 SQL。结果来自已加载和可搜索的对象；大型连接尚未加载元数据时，先展开或刷新对应节点。 -1. 在列表中找到要更改的操作 -2. 点击当前快捷键进入录制模式 -3. 按下新的按键组合 -4. 新快捷键自动保存 +## 自定义和冲突 -快捷键使用 Electron 风格的修饰键表示法：`Ctrl`（Windows/Linux 的 Control）、`Cmd`（macOS 的 Command）、`Shift` 和 `Alt`（macOS 的 Option）。 +1. 打开 **设置 → 快捷键** +2. 选择 action 并进入录制 +3. 按下新组合键；也可以清空不需要的绑定 +4. 处理冲突后保存 -## 复制快捷键 +DBX 会检测同一作用域中的冲突。编辑器、表格、搜索、侧边栏和全局 action 具有不同作用域，但浏览器、操作系统、输入法或辅助功能仍可能先占用按键。 -两个可配置的复制快捷键控制行级别的复制行为： +Windows/Linux 上 `Ctrl+Alt` 可能被键盘布局当作 AltGr；DBX 对相关组合采取更保守的匹配。macOS 的 Option+字母可能产生变形字符，DBX 会在安全情况下使用物理键位回退。 -- **复制当前行**：将当前行复制为制表符分隔的值 -- **删除当前行**：将当前行标记为待删除 +## 相关页面 -在**设置 → 快捷键**中设置它们以匹配你的偏好工作流程。 - -## 冲突解决 - -如果自定义快捷键与现有快捷键冲突： - -- DBX 会在保存前发出警告 -- 解决冲突前，DBX 不会应用已经修改的快捷键 -- 系统快捷键（如 macOS 的 `Cmd+Q`）无法被覆盖 + + 了解执行范围、多结果标签页和编辑器行为。 + 配置格式化规则和格式化设置编辑器快捷键。 + diff --git a/docs/content/docs/keyboard-shortcuts.mdx b/docs/content/docs/keyboard-shortcuts.mdx index caa182ece9..d78997b448 100644 --- a/docs/content/docs/keyboard-shortcuts.mdx +++ b/docs/content/docs/keyboard-shortcuts.mdx @@ -1,83 +1,78 @@ --- title: Keyboard Shortcuts -description: Configure and use keyboard shortcuts to navigate DBX, execute queries, and edit data efficiently. +description: Review current defaults and customize editor, grid, sidebar, and global actions in Settings. --- -DBX provides configurable keyboard shortcuts for common actions. Use the default shortcuts or customize them to match your workflow. +DBX shortcuts come from one configurable action registry. **Settings → Shortcuts** shows the effective binding for the installed version and current platform, making it authoritative after defaults change or the user customizes a key. -## Default Shortcuts +`Mod` means `Cmd` on macOS and `Ctrl` on Windows/Linux. -### Query Editor +## Common Defaults -| Shortcut | Action | -| -------------------------------------- | ------------------------------ | -| `Ctrl+Enter` / `Cmd+Enter` | Execute current query | -| `Ctrl+\` / `Cmd+\` | Execute in a new result tab | -| `Ctrl+Shift+Enter` / `Cmd+Shift+Enter` | Execute all queries | -| `Ctrl+/` / `Cmd+/` | Toggle line comment | -| `Ctrl+F` / `Cmd+F` | Search in editor | -| `Ctrl+S` / `Cmd+S` | Save current tab | -| `Ctrl+A` / `Cmd+A` | Select all text | -| `Shift+Alt+U` | Convert selection to uppercase | -| `Shift+Alt+L` | Convert selection to lowercase | -| `Tab` | Indent selected lines | -| `Shift+Tab` | Outdent selected lines | +### SQL Editor -### Data Grid +| Default | Action | +| --- | --- | +| `Mod+Enter` | Execute the current statement or selected SQL | +| `Mod+\` | Execute in a new result tab | +| `Shift+Mod+F` | Format SQL | +| `Mod+/` | Toggle line comment | +| `Mod+S` | Save SQL | +| `Tab` | Accept completion | +| `Shift+Tab` | Outdent | +| `Mod+D` | Duplicate current line | +| `Shift+Mod+K` | Delete current line | +| `Alt+↑` / `Alt+↓` | Move current line up/down | +| `Shift+Alt+↑` / `Shift+Alt+↓` | Copy current line up/down | +| `Shift+Alt+U` / `Shift+Alt+L` | Convert selection to uppercase/lowercase | +| `Mod+.` | Toggle code folding | +| `Mod+Shift+A` | Send selection to AI | -| Shortcut | Action | -| ------------------------------ | ---------------------------------------- | -| `F5` | Refresh current data | -| `Ctrl+C` / `Cmd+C` | Copy selected cells | -| `Ctrl+Shift+C` / `Cmd+Shift+C` | Copy selected rows as INSERT | -| `Delete` | Delete selected rows (mark for deletion) | +The current registry has no default “execute all SQL” action. Select a range or use the editor's multi-statement execution entry point instead of relying on the old `Ctrl/Cmd+Shift+Enter` documentation. -### Navigation +### Grid and Data -| Shortcut | Action | -| ------------------------------ | ----------------------------------- | -| `Ctrl+P` / `Cmd+P` | Quick open database objects | -| `Ctrl+N` / `Cmd+N` | New query tab | -| `Ctrl+Shift+F` / `Cmd+Shift+F` | Focus sidebar search | -| `Ctrl+,` / `Cmd+,` | Open settings | -| `Ctrl+W` / `Cmd+W` | Close current tab | -| `Middle Click` (on tab) | Close tab | +| Default | Action | +| --- | --- | +| `F5` | Refresh current data | +| `Mod+D` | Copy current row | +| `Delete` | Mark current row for deletion | +| `Tab` | Toggle transposed view | -## Quick Open (Ctrl+P) +Standard copy and paste still follow platform conventions. Copy Current Row, Delete Current Row, and Toggle Transpose are DBX-configurable actions. -Press **Ctrl+P** (or **Cmd+P** on macOS) to quickly navigate to database objects without using the sidebar: +### Global and Navigation -- Type to search for tables, views, schemas, or databases -- Fuzzy matching finds objects even with partial names -- Press Enter to open the selected object -- Works across all connections in your workspace +| Default | Action | +| --- | --- | +| `Mod+T` | New query | +| `Mod+P` | Quick open | +| `Mod+W` | Close current tab | +| `Shift+Mod+[` / `Shift+Mod+]` | Previous/next tab | +| `Mod+1` … `Mod+9` | Switch to a numbered tab | +| `Mod+B` | Toggle the sidebar | +| `Mod+=` / `Mod+-` / `Mod+0` | Zoom in, zoom out, reset UI zoom | -Quick open is especially useful when working with large databases where scrolling through the sidebar tree is slow. +The sidebar also has configurable actions for copy, paste, edit connection, and modifier-based opening in a new tab. -## Configuring Shortcuts +## Quick Open -Open **Settings → Shortcuts** to customize key bindings: +Press `Mod+P` to search connections, databases, schemas, tables, views, and saved SQL in the current workspace. Results come from loaded and searchable objects. For a large connection whose metadata is not loaded yet, expand or refresh the relevant node first. -1. Find the action you want to change in the list -2. Click the current shortcut to enter recording mode -3. Press the new key combination -4. The new shortcut is saved automatically +## Customization and Conflicts -Shortcuts use the Electron-style modifier key notation: `Ctrl` (Control on Windows/Linux), `Cmd` (Command on macOS), `Shift`, and `Alt` (Option on macOS). +1. Open **Settings → Shortcuts** +2. Choose an action and enter recording mode +3. Press a new key combination, or clear an unwanted binding +4. Resolve conflicts and save -## Copy Shortcuts +DBX detects conflicts within a scope. Editor, grid, search, sidebar, and global actions have separate scopes, but the browser, operating system, input method, or accessibility software may still reserve a key first. -Two configurable copy shortcuts control row-level copy behavior: +On Windows/Linux, `Ctrl+Alt` may represent AltGr, so DBX matches those combinations conservatively. On macOS, Option+letter can produce transformed characters, and DBX uses physical-key fallback only where safe. -- **Copy Current Row**: Copies the current row as tab-separated values -- **Delete Current Row**: Marks the current row for deletion +## Related Pages -Set these in **Settings → Shortcuts** to match your preferred workflow. - -## Conflict Resolution - -If a custom shortcut conflicts with an existing one: - -- DBX warns you before saving -- DBX blocks applying the changed shortcuts until the conflict is resolved -- System shortcuts (like `Cmd+Q` on macOS) cannot be overridden + + Review execution ranges, result tabs, and editor behavior. + Configure formatting rules and shortcuts for the formatter settings editor. + diff --git a/docs/content/docs/mcp.cn.mdx b/docs/content/docs/mcp.cn.mdx index 783e4522c9..ea03a17185 100644 --- a/docs/content/docs/mcp.cn.mdx +++ b/docs/content/docs/mcp.cn.mdx @@ -1,6 +1,6 @@ --- title: MCP 集成 -description: 通过 Model Context Protocol 让 AI 编程助手查询你的数据库。 +description: 通过 Model Context Protocol 让 AI 编程助手在 DBX 权限策略内读取元数据、查询数据和使用有状态会话。 --- 把 AI 助手连接到 DBX，即可查看数据库结构、查询数据，并在 DBX 中打开结果。 @@ -68,7 +68,7 @@ AI 助手 → DBX MCP → 你的数据库 → 返回结果 ## 工具列表 -DBX MCP 当前提供 10 个工具： +DBX MCP 当前提供 12 个工具： | 工具 | 说明 | | --- | --- | @@ -79,17 +79,32 @@ DBX MCP 当前提供 10 个工具： | `dbx_describe_table` | 返回列定义和表元数据 | | `dbx_get_schema_context` | 返回适合 AI 使用的紧凑 Schema 上下文 | | `dbx_execute_query` | 执行 SQL 或支持的 MongoDB shell 命令，最多返回 100 行 | +| `dbx_open_session` | 为 SQL 连接打开固定后端连接的有状态查询会话 | +| `dbx_close_session` | 关闭会话并释放固定连接资源 | | `dbx_execute_redis_command` | 执行 Redis 命令 | | `dbx_open_table` | 在运行中的 DBX 桌面端打开表 | | `dbx_execute_and_show` | 执行查询并在 DBX 中展示结果 | 启用连接作用域后，修改连接和桌面 UI 工具会被隐藏。 +## 有状态查询会话 + +普通 `dbx_execute_query` 调用彼此独立。需要保持数据库 Session 状态时，先调用 `dbx_open_session`，再把返回的 `sessionId` 传给后续 `dbx_execute_query`： + +- `USE` 或数据库上下文切换 +- 临时表 +- Session 变量和设置 +- 需要固定连接的显式事务或多步诊断 + +会话只支持 SQL 连接，并固定到一个连接和数据库。未知、已关闭或过期的 `sessionId` 会失败，不会静默退化为普通查询。完成后应调用 `dbx_close_session`；空闲 30 分钟的会话会被回收，同时最多允许 32 个并发会话。 + +有状态会话不会放宽 SQL 策略。`USE` 只有在会话中才有意义，但写入、DDL、生产保护、连接只读和数据库权限仍按每次请求重新检查。 + ## 数据库访问 ### 本地连接 -这是默认模式。MCP 使用 DBX 中保存的连接配置。执行数据库查询时不要求 DBX 桌面端保持运行。 +这是默认模式。MCP 使用 DBX 中保存的连接配置。原生可执行的连接不要求 DBX 桌面端保持运行；需要 Desktop bridge 或已安装 Agent/驱动的连接仍依赖对应运行时。 常见的本地数据库文件路径： @@ -101,7 +116,7 @@ DBX MCP 当前提供 10 个工具： `DBX_DATA_DIR` 必须指向包含 `dbx.db` 的目录，而不是数据库文件本身。Windows 便携版通常是 `DBX.exe` 同级的 `data` 目录。 -PostgreSQL、MySQL、SQLite、兼容 SQL 数据库、独立 Redis 和 MongoDB 可以直接查询。部分 SSH、集群、厂商专用以及 Agent/JDBC 连接需要先安装对应的 DBX 组件。 +原生 SQL、独立 Redis 和 MongoDB 等路径可以由 MCP 直接执行。SSH、集群、厂商专用、外部驱动以及 Agent/JDBC 连接是否可用，取决于连接配置和本机已安装的 DBX 组件；不要从“DBX 支持该数据库”推断 MCP 原生包已经内置全部运行时。 DuckDB 使用独立的 DBX DuckDB 驱动。通过本地 MCP 查询 DuckDB 前，需要先在 **DBX Driver Manager** 中安装该驱动。MCP 二进制只包含 sidecar 客户端，不会内置 DuckDB 引擎。 @@ -117,7 +132,7 @@ DBX Web 和 Docker 同样需要独立 DuckDB 驱动。首次启动后可通过 D ### 桌面 UI 工具 -`dbx_open_table` 和 `dbx_execute_and_show` 要求 DBX 桌面端正在运行。其他查询工具可以在 DBX 关闭时使用。 +`dbx_open_table` 和 `dbx_execute_and_show` 要求 DBX 桌面端正在运行，并且在 Web 模式或连接作用域隐藏 UI 工具时不可用。其他工具是否需要 Desktop 取决于该连接是原生执行还是 bridge/Agent 路径。 ## 安全和环境变量 diff --git a/docs/content/docs/mcp.mdx b/docs/content/docs/mcp.mdx index 2565f12c5e..e07f577800 100644 --- a/docs/content/docs/mcp.mdx +++ b/docs/content/docs/mcp.mdx @@ -1,6 +1,6 @@ --- title: MCP Integration -description: Let AI coding agents query your databases through the Model Context Protocol. +description: Let AI coding agents read metadata, query data, and use stateful sessions within DBX-managed Model Context Protocol policy. --- Connect your AI assistant to DBX and let it inspect schemas, query data, and open results in DBX. @@ -68,7 +68,7 @@ AI agent → DBX MCP → your database → results ## Tools -DBX MCP currently provides 10 tools: +DBX MCP currently provides 12 tools: | Tool | Description | | --- | --- | @@ -79,17 +79,32 @@ DBX MCP currently provides 10 tools: | `dbx_describe_table` | Return columns and table metadata | | `dbx_get_schema_context` | Return compact schema context for an AI model | | `dbx_execute_query` | Execute SQL or a supported MongoDB shell command, returning at most 100 rows | +| `dbx_open_session` | Open a stateful SQL query session pinned to one backend connection | +| `dbx_close_session` | Close a session and release its pinned connection resources | | `dbx_execute_redis_command` | Execute a Redis command | | `dbx_open_table` | Open a table in the running DBX desktop app | | `dbx_execute_and_show` | Execute a query and display the result in DBX | Connection-scoped sessions hide connection-mutating and desktop UI tools. +## Stateful Query Sessions + +Regular `dbx_execute_query` calls are independent. When a workflow must preserve database session state, call `dbx_open_session` first and pass its returned `sessionId` to later `dbx_execute_query` calls. Typical uses include: + +- `USE` or database-context changes +- Temporary tables +- Session variables and settings +- Explicit transactions or multi-step diagnostics that require one connection + +Sessions support SQL connections only and are bound to one connection and database. Unknown, closed, or expired IDs fail instead of silently falling back to an ordinary query. Call `dbx_close_session` when finished. Idle sessions are reclaimed after 30 minutes, and the server allows at most 32 concurrent sessions. + +A stateful session does not widen SQL policy. `USE` is meaningful only inside a session, while writes, DDL, production protection, connection read-only state, and database privileges are rechecked for every request. + ## Database Access ### Local connections -MCP uses the connections saved in DBX. DBX does not need to remain open for database queries. +MCP uses the connections saved in DBX. Connections that execute natively do not require the Desktop app to stay open; bridge-backed or installed Agent/driver paths still depend on their runtime. Common local paths include: @@ -101,7 +116,7 @@ Common local paths include: Set `DBX_DATA_DIR` to the directory containing `dbx.db`. Do not set it to the file itself. -PostgreSQL, MySQL, SQLite, compatible SQL databases, standalone Redis, and MongoDB can be queried locally. Some SSH, cluster, vendor-specific, and Agent/JDBC connections require their DBX components to be installed. +Native SQL, standalone Redis, and MongoDB paths can execute directly through MCP. SSH, cluster, vendor-specific, external-driver, and Agent/JDBC availability depends on the connection configuration and installed DBX components. Do not assume that every database supported by the DBX product is bundled into the standalone MCP binary. DuckDB uses the standalone DBX DuckDB driver. Install it from **DBX Driver Manager** before querying a DuckDB connection through local MCP. The MCP binary includes the sidecar client but does not bundle the DuckDB engine. @@ -117,7 +132,7 @@ DBX Web and Docker require the same standalone DuckDB driver. Install it from Dr ### Desktop UI tools -`dbx_open_table` and `dbx_execute_and_show` require the DBX desktop app to be running. Other query tools can run while DBX is closed. +`dbx_open_table` and `dbx_execute_and_show` require the DBX desktop app and are unavailable in Web mode or when scoped policy hides UI tools. Whether other tools need Desktop depends on whether the connection uses native execution or a bridge/Agent path. ## Safety and Environment Variables diff --git a/docs/content/docs/meta.cn.json b/docs/content/docs/meta.cn.json index e29ed90e2c..70f6ac45ba 100644 --- a/docs/content/docs/meta.cn.json +++ b/docs/content/docs/meta.cn.json @@ -3,42 +3,46 @@ "pages": [ "---介绍---", "what-is-dbx", - "changelog", "getting-started", - "1panel", "databases", - "database-lab", - "---核心功能---", + "changelog", + "---核心工作流---", "query-editor", "data-grid", "schema-browser", + "object-browser", "redis", "mongodb", - "object-browser", - "---高级功能---", - "schema-diff", + "specialized-workspaces", + "---数据与结构---", "data-transfer", "table-structure", + "schema-diff", "field-lineage", "table-import", "sql-file", "database-export", + "database-backup", "sql-snippets", "---AI 与自动化---", "ai-assistant", "cli", "mcp", "web-api", - "---社区---", - "contributing", - "---设置---", + "---部署与连接---", + "1panel", + "ssh-tunnel", "plugins", "driver-management", - "sql-formatter", - "keyboard-shortcuts", + "---安全与配置---", + "production-safety", "connection-import", "config-export", "cloud-sync", - "ssh-tunnel" + "sql-formatter", + "keyboard-shortcuts", + "---开发与社区---", + "database-lab", + "contributing" ] } diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json index 3ab903bf1e..9dd501d732 100644 --- a/docs/content/docs/meta.json +++ b/docs/content/docs/meta.json @@ -3,42 +3,46 @@ "pages": [ "---Introduction---", "what-is-dbx", - "changelog", "getting-started", - "1panel", "databases", - "database-lab", - "---Core Features---", + "changelog", + "---Core Workflows---", "query-editor", "data-grid", "schema-browser", + "object-browser", "redis", "mongodb", - "object-browser", - "---Advanced Features---", - "schema-diff", + "specialized-workspaces", + "---Data and Schema---", "data-transfer", "table-structure", + "schema-diff", "field-lineage", "table-import", "sql-file", "database-export", + "database-backup", "sql-snippets", "---AI & Automation---", "ai-assistant", "cli", "mcp", "web-api", - "---Community---", - "contributing", - "---Settings---", + "---Deployment and Connectivity---", + "1panel", + "ssh-tunnel", "plugins", "driver-management", - "sql-formatter", - "keyboard-shortcuts", + "---Safety and Configuration---", + "production-safety", "connection-import", "config-export", "cloud-sync", - "ssh-tunnel" + "sql-formatter", + "keyboard-shortcuts", + "---Development and Community---", + "database-lab", + "contributing" ] } diff --git a/docs/content/docs/mongodb.cn.mdx b/docs/content/docs/mongodb.cn.mdx index de840e861e..99ab2416d4 100644 --- a/docs/content/docs/mongodb.cn.mdx +++ b/docs/content/docs/mongodb.cn.mdx @@ -1,76 +1,130 @@ --- -title: MongoDB 浏览器 -description: 浏览 MongoDB 数据库和集合、查看文档，并使用内置 JSON 编辑器编辑数据。 +title: MongoDB 工作台 +description: 浏览、筛选、编辑和复制 MongoDB 文档，并管理集合、索引和 GridFS。 --- -DBX 支持浏览和编辑 MongoDB 数据库，提供专为 MongoDB 灵活 schema 模型设计的文档导向界面。 +MongoDB 工作台围绕数据库、Collection、文档、索引和 GridFS 组织，不把文档强制转换成关系型表。它提供表格视图和完整 JSON 视图，并保留 `ObjectId`、日期、长整数等 Extended JSON 类型。 -## 集合浏览器 +## 连接与驱动 -MongoDB 数据库和集合与关系型数据库一同显示在侧边栏中。浏览器支持： +推荐使用标准 `mongodb://` 或 `mongodb+srv://` 连接字符串，并在 URL 中包含副本集、认证库、TLS 和其他参数。Atlas、Replica Set 和直连部署都使用同一个连接入口。 -- 列出服务器上的所有数据库 -- 列出每个数据库中的集合 -- 集合文档的分页浏览 -- 文档查询的过滤和排序支持 -- **数据库和集合删除**：右键点击数据库或集合即可删除 -- **集合元数据**：查看集合统计信息，包括文档数、大小和索引 +DBX 优先使用原生 MongoDB 路径。当服务端或认证协议需要旧驱动时，可以选择或自动回退到 `mongodb-legacy` Agent。旧驱动的管理和修改能力可能少于原生驱动。 -MongoDB 连接同时支持标准连接字符串和旧版连接格式。对于副本集，请使用标准的 `mongodb://` 连接 URL 并指定副本集名称。 +## 数据库与 Collection -## 切换数据库 +对象树可以： -在 MongoDB 命令运行器中使用 `use ` 命令切换活动数据库。这相当于 MongoDB shell 的 `use` 命令，会更新后续操作的当前数据库上下文。 +- 列出数据库、Collection、索引和 GridFS Bucket +- 显示 Collection 文档数、大小和其他可获取统计 +- 创建、重命名或删除 Collection（原生驱动且连接可写时） +- 删除数据库、单个索引或除 `_id_` 外的可删除索引 +- 从 Collection 打开文档浏览器或查询编辑器 -## 表格视图 +删除和重命名会显示目标和请求预览，并受只读与生产保护约束。 -集合以表格视图展示，将文档结构扁平化： +## 文档浏览与分页 -- 顶层字段显示为列 -- 嵌套字段以点号表示（如 `address.city`） -- 各文档之间缺失的字段会被妥善处理 -- 列宽自动适应内容 +文档浏览器支持： -## 文档查看器 +- 分页读取和估算总数 +- 表格视图与完整文档视图 +- 顶层和嵌套字段列，例如 `address.city` +- 可搜索字段选择器、隐藏列和持久化列布局 +- 快速过滤器以及多个字段条件 +- 数据库侧排序和 Collection 查询 -点击任意文档可在详情面板中打开。JSON 查看器提供： +MongoDB 的总数可能使用估算值。数据持续写入时，翻页过程中的总数和最后一页可能变化。 -- 语法高亮的 JSON 显示 -- 可折叠的嵌套对象和数组 -- 复制单个字段或整个文档 +## 过滤与命令 -## 内联编辑 +可以在文档浏览器中构建字段过滤，也可以在 MongoDB 查询标签中输入 shell 风格命令。编辑器会根据 Collection、字段、查询运算符、更新运算符、聚合阶段和游标方法提供补全。 -直接从表格视图编辑文档： +常见命令包括： -- 双击单元格编辑其值 -- 更改会在本地暂存，保存前可预览 -- 应用前检查生成的更新命令 +```javascript +db.users.find({ status: "active" }).sort({ createdAt: -1 }) +``` -## JSON 编辑器 +```javascript +db.orders.aggregate([ + { $match: { status: "paid" } }, + { $group: { _id: "$customerId", total: { $sum: "$amount" } } } +]) +``` -在文档视图中，可在字段树编辑与整段 JSON 编辑之间切换： +`use ` 会切换当前 MongoDB 查询上下文。 -- 以完整 JSON 对象编辑或新建文档 -- 保存前对整段 JSON 做语法与结构校验 -- 新增文档时可直接粘贴整段 JSON -- 需要改单个字段时仍可使用字段编辑器 -- **更新时整文档替换**：JSON 保存会替换文档正文 -- **修改标识**：编辑 `_id` 会按新 id 新建文档，并删除旧文档 -- **日期与 Extended JSON 保留**：编辑过程中正确保留 `$date`、`$oid`、`$numberLong` 等值 +## 表格编辑 -## MongoDB 版本 +表格视图把常见字段展开成列。支持： -DBX 通过内置驱动支持 MongoDB 4.2 及以上版本。对于 4.2 之前版本的 MongoDB 实例，DBX 可以回退到 JDBC Agent 驱动。有关配置 Agent 驱动的详细信息，请参阅[驱动管理](/cn/docs/driver-management)。 +- 编辑顶层或嵌套字段 +- 新增和删除字段 +- 新建、克隆和删除文档 +- 复制选中文档为 JSON、Markdown 或 MongoDB Shell 语句 +- 排除 `_id` 后复制为新文档模板 +- 在保存前查看待执行更新或删除目标 -## 功能覆盖 +字段结构差异很大的 Collection 更适合使用完整文档视图，避免隐藏字段在表格列中被忽略。 -| 功能 | 支持情况 | -| ------------------ | ------------ | -| 列出数据库和集合 | 所有版本 | -| 分页文档浏览 | 所有版本 | -| 扁平化字段表格视图 | 所有版本 | -| 过滤和排序 | MongoDB 4.2+ | -| 内联编辑 | 所有版本 | -| JSON 文档编辑器 | 所有版本 | -| SSH 隧道 | 标准连接 | +## 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 名称和备份。 + +## 复制与导出 + +- 复制当前文档、选中文档或字段值 +- 复制为普通 JSON 或保留类型信息的 Extended JSON +- 从表格结果使用多格式复制和导出 +- MongoDB `find` 查询结果导出会继续读取完整结果范围，而不是只导出当前已显示页（受查询和导出限制约束） + +导出大型 Collection 前先缩小过滤范围，并关注服务端游标、网络和本地文件大小。 + +## 安全与兼容边界 + +- 只读连接会阻止文档、字段、索引、Collection、数据库和 GridFS 修改 +- 生产环境保护会在可识别写入前要求确认 +- MCP“数据读写”只允许范围明确的 MongoDB 修改；不透明或近似全量过滤按高风险处理 +- 旧版 Agent 可能不支持 Collection/索引管理等原生能力 +- Atlas 权限、认证库、TLS 和 IP allowlist 都由 MongoDB 服务端决定 +- 分页总数可能为估算值，不能作为强一致统计 + + + + 了解 MongoDB 过滤范围、只读连接和 MCP 策略。 + + + 管理原生与 legacy Agent，并排查驱动启动问题。 + + + 查看 Redis、搜索、向量、HBase、消息队列和配置中心。 + + diff --git a/docs/content/docs/mongodb.mdx b/docs/content/docs/mongodb.mdx index 2400883795..ffae6ba56b 100644 --- a/docs/content/docs/mongodb.mdx +++ b/docs/content/docs/mongodb.mdx @@ -1,76 +1,130 @@ --- -title: MongoDB Browser -description: Browse MongoDB databases and collections, view documents, and edit data with the built-in JSON editor. +title: MongoDB Workspace +description: Browse, filter, edit, and copy MongoDB documents and manage collections, indexes, and GridFS. --- -DBX supports browsing and editing MongoDB databases with a document-oriented interface designed for MongoDB's flexible schema model. +The MongoDB workspace is organized around databases, collections, documents, indexes, and GridFS instead of forcing documents into a relational model. It provides both a grid and full JSON view while preserving Extended JSON types such as `ObjectId`, dates, and long integers. -## Collections Browser +## Connections and Drivers -MongoDB databases and collections appear in the sidebar alongside relational databases. The browser supports: +Use a standard `mongodb://` or `mongodb+srv://` connection string and include replica set, authentication database, TLS, and other parameters in the URL when needed. Atlas, replica sets, and direct deployments share the same connection entry point. -- Listing all databases on the server -- Listing collections within each database -- Paginated document browsing within collections -- Filter and sort support for document queries -- **Database and collection deletion**: Right-click on a database or collection to delete it -- **Collection metadata**: View collection statistics including document count, size, and indexes +DBX prefers the native MongoDB path. When a server or authentication protocol requires the older driver, you can select or automatically fall back to the `mongodb-legacy` Agent. The legacy path may expose fewer administration and mutation capabilities. -MongoDB connections support both standard connection strings and legacy connection formats. For replica sets, use the standard `mongodb://` connection URL with the replica set name. +## Databases and Collections -## Switching Databases +The object tree can: -Use the `use ` command in the MongoDB command runner to switch the active database. This is equivalent to the MongoDB shell's `use` command and updates the current database context for subsequent operations. +- List databases, collections, indexes, and GridFS buckets +- Show document count, size, and other available collection statistics +- Create, rename, or drop collections when using the writable native path +- Drop databases, one index, or all deletable indexes except `_id_` +- Open a document browser or query editor from a collection -## Table View +Rename and destructive operations show the target and request preview and remain subject to read-only and production protection. -Collections are displayed in a table view that flattens the document structure: +## Document Browsing and Pagination -- Top-level fields appear as columns -- Nested fields are shown in dot notation (e.g., `address.city`) -- Missing fields across documents are handled gracefully -- Column widths auto-fit to content +The document browser supports: -## Document Viewer +- Paged reads with an estimated total +- Grid and full-document views +- Top-level and nested fields such as `address.city` +- Searchable field selection, hidden columns, and persistent column layout +- Quick filters plus multiple field conditions +- Database-side sorting and collection queries -Click any document to open it in the detail panel. The JSON viewer provides: +MongoDB totals may be estimated. In actively changing collections, the count and final page can shift while browsing. -- Syntax-highlighted JSON display -- Collapsible nested objects and arrays -- Copy individual fields or the entire document +## Filters and Commands -## Inline Editing +Build field filters in the document browser or use shell-style commands in a MongoDB query tab. Completion can suggest collections, fields, query operators, update operators, aggregation stages, and cursor methods. -Edit documents directly from the table view: +Examples: -- Double-click a cell to edit its value -- Changes are staged locally before saving -- Review the generated update command before applying +```javascript +db.users.find({ status: "active" }).sort({ createdAt: -1 }) +``` -## JSON Editor +```javascript +db.orders.aggregate([ + { $match: { status: "paid" } }, + { $group: { _id: "$customerId", total: { $sum: "$amount" } } } +]) +``` -In document view, switch between field-tree editing and whole-document JSON editing: +Use `use ` to switch the MongoDB query context. -- Edit or create a document as a full JSON object -- Validate the entire JSON payload before saving -- Paste complete documents when inserting new records -- Keep the field editor for targeted field changes -- **Whole-document replace on update**: saving JSON replaces the document body -- **Identity change**: editing `_id` inserts a document under the new id and deletes the previous one -- **Date and Extended JSON preservation**: `$date`, `$oid`, and `$numberLong` values are preserved correctly during edits +## Grid Editing -## MongoDB Versions +The grid expands common fields into columns and supports: -DBX supports MongoDB 4.2 and later through the built-in driver. For pre-4.2 MongoDB instances, DBX can fall back to the JDBC agent driver. See [Driver Management](/en/docs/driver-management) for details on configuring agent drivers. +- Editing top-level or nested fields +- Adding and removing fields +- Creating, cloning, and deleting documents +- Copying selected documents as JSON, Markdown, or MongoDB Shell statements +- Excluding `_id` when copying a new-document template +- Reviewing pending update or delete targets before saving -## Feature Coverage +Collections with very different document shapes are better handled in the full-document view so hidden fields are not overlooked. -| Feature | Support | -| --------------------------------- | -------------------- | -| List databases and collections | All versions | -| Document browsing with pagination | All versions | -| Table view with flattened fields | All versions | -| Filter and sort | MongoDB 4.2+ | -| Inline editing | All versions | -| JSON document editor | All versions | -| SSH tunnel | Standard connections | +## JSON Document Editing + +Document details can switch between a field tree and full JSON source: + +- Paste complete JSON when creating a document +- Validate JSON syntax and root-object structure before save +- Format, collapse, and copy nested objects or arrays +- Preserve Extended JSON such as `$oid`, `$date`, and `$numberLong` +- Change `_id` by creating the new document and removing the old one +- Save full JSON with whole-document replacement semantics + +Whole-document replacement writes the complete object back. Verify that the JSON contains every field that must be retained, especially in collections with concurrent updates. + +## Indexes + +The object tree and collection structure can show index name, fields, uniqueness, and other metadata. When the native driver supports it, you can drop one index, drop all deletable indexes, or manage indexes through structure actions. + +MongoDB preserves `_id_`, and sharding or other server rules may protect additional indexes. The server response is authoritative. + +## GridFS + +The GridFS workspace manages buckets and files: + +- Browse, create, and delete buckets +- Upload, download, preview, and delete files +- Inspect filename, size, upload time, chunks, and metadata +- Filter and sort files by fields +- Export file lists or metadata + +Dropping a bucket removes its files and chunks. Verify the bucket name and backup before doing this in production. + +## Copy and Export + +- Copy the current document, selected documents, or field values +- Copy as plain JSON or Extended JSON that preserves type information +- Use multi-format copy and export from the grid result +- Exporting a MongoDB `find` result continues through the full result scope instead of only the currently displayed page, subject to query and export limits + +Narrow filters before exporting a large collection and monitor server cursor use, network transfer, and local file size. + +## Safety and Compatibility Boundaries + +- Read-only connections block document, field, index, collection, database, and GridFS mutations +- Production protection requires confirmation before recognizable writes +- MCP Data read/write permits only scoped MongoDB mutations; opaque or effectively unbounded filters are high risk +- The legacy Agent may not support native collection and index administration +- Atlas permissions, authentication database, TLS, and IP allowlists are enforced by MongoDB +- Paginated totals may be estimates and should not be treated as strongly consistent counts + + + + Review MongoDB filter scope, read-only connections, and MCP policy. + + + Manage native and legacy Agents and troubleshoot driver startup. + + + Review Redis, search, vector, HBase, message queue, and configuration tools. + + diff --git a/docs/content/docs/object-browser.cn.mdx b/docs/content/docs/object-browser.cn.mdx index 22a3a4c8a2..91debf95fc 100644 --- a/docs/content/docs/object-browser.cn.mdx +++ b/docs/content/docs/object-browser.cn.mdx @@ -1,56 +1,102 @@ --- title: 对象浏览器 -description: 浏览视图、存储过程、函数以及表与结构之外的数据库对象。 +description: 使用列表或网格集中查看数据库对象、统计信息、源码和批量操作。 --- -对象浏览器将侧边栏的功能扩展到表和集合之外，集中展示那些通常需要单独查询才能查看的数据库对象。 +对象浏览器把当前数据库或 Schema 中的对象集中到一个可搜索的列表/网格中。它适合对象数量很多、需要按类型和元数据筛选，或需要批量处理多个对象的场景。 -## 对象浏览器展示的内容 +## 适合的场景 -| 对象类型 | 展示信息 | -| -------- | ------------------------------- | -| 视图 | 视图定义（DDL）、列列表、Schema | -| 存储过程 | 源代码、参数、语言 | -| 函数 | 返回类型、参数、源代码 | -| 触发器 | 时机、事件、关联表、源代码 | -| 例程 | 存储过程和函数的合并视图 | +- 在一个页面查看大量表、视图、过程、函数、序列和其他对象 +- 按名称、类型、Schema、注释或统计信息筛选 +- 比较表大小、行数、创建/更新时间等驱动可提供的信息 +- 多选对象后执行打开、复制、导出、删除或其他批量操作 +- 在不展开深层对象树的情况下快速查看 DDL 或源码 -对象浏览器的可用性取决于数据库引擎及其元数据支持。并非所有数据库都能通过标准 SQL 暴露源代码或例程元数据。 +## 打开方式 -## 打开对象浏览器 +从连接、数据库或 Schema 的上下文菜单打开**对象浏览器**。DBX 会根据当前节点确定 Catalog、数据库和 Schema 范围。 -从侧边栏打开对象浏览器： +对象浏览器可以作为主标签页或侧边面板打开。侧边面板适合一边查看对象列表，一边保留当前查询或数据标签。 -- **双击**数据库或 Schema 节点打开其对象浏览器 -- 右键点击并从上下文菜单中选择**对象浏览器** -- 对任意对象使用**查看 DDL** 操作查看其源定义 +## 视图与筛选 -## 查看 DDL +| 功能 | 说明 | +| --- | --- | +| 列表视图 | 适合查看名称、类型、Schema、注释、行数和大小等列 | +| 网格视图 | 适合快速扫描对象卡片和主要摘要 | +| 对象类型筛选 | 默认优先显示表，也可以切换视图、例程和其他类型 | +| 搜索 | 按对象名称、Schema、类型和部分元数据过滤 | +| 列调整 | 调整列宽、显示列和滚动位置；视口状态可以保留 | -**查看 DDL** 操作显示视图、存储过程或函数的完整 `CREATE` 语句： +统计列只在驱动能够可靠读取时显示。大型数据库读取行数或大小可能有额外开销，必要时关闭不需要的统计信息。 -- 在只读 SQL 查看器中以语法高亮显示 -- 复制 DDL 用于迁移脚本或文档 -- 跨环境比较定义差异 +## 对象操作 -## 编辑对象源代码 +单击或双击对象可以按类型打开： -对于支持 `CREATE OR REPLACE` 语义的数据库，可以直接编辑对象源代码： +- 表和视图数据 +- 表结构、字段、索引、外键、触发器和 DDL +- 视图、过程、函数、触发器等对象源码 +- 数据库专属管理界面 -- 存储过程和函数可编辑并保存 -- DBX 会生成适当的 `CREATE OR REPLACE` 或 `ALTER` 语句 -- 在应用更改前检查生成的 SQL +上下文菜单还可以提供： -在数据库中直接编辑对象可能会影响正在运行的应用程序。在保存更改前请验证对象的使用情况，尤其是在生产数据库上。 +- 复制名称、限定名称或 DDL +- 生成查询 SQL +- 导入、导出、传输和结构相关入口 +- 打开 ER 图、字段血缘或 Schema 对比 +- 重命名、清空、删除或管理对象 -## 对象时间戳 +具体操作由数据库 capability、连接只读状态和当前权限决定。 -当数据库提供时，对象浏览器会显示对象元数据时间戳： +## 多选与批量操作 -- 创建时间 -- 最后修改时间 -- 有助于追踪最近更改或发现过时对象 +对象浏览器支持复选框多选。批量操作可能包括： + +- 打开或复制多个对象名称 +- 批量导出或生成 SQL +- 删除、清空或截断所选表 +- 删除所选索引 +- 对 PostgreSQL 等数据库使用带 `CASCADE` 的批量对象操作 + +批量删除、清空和截断可能影响大量对象。生产环境先确认所选范围、生成 SQL、备份和依赖关系。 + +## DDL 与源码 + +- **查看 DDL**优先读取数据库或驱动提供的定义 +- **对象源码**用于视图、过程、函数、触发器和其他可编辑对象 +- 源码视图支持搜索；数据库和对象允许时，可以打开到编辑器修改 +- 保存源码或执行 DDL 前会进入只读、生产保护和危险操作检查 + +DBX 显示的是当前驱动能获取到的定义。格式、是否包含权限/注释/存储属性，以及能否直接编辑，都会因数据库而异。 + +## 与对象树的区别 + +| 对象树 | 对象浏览器 | +| --- | --- | +| 适合层级导航和固定常用对象 | 适合集中筛选和比较大量同级对象 | +| 展开后查看字段和子节点 | 通过列、卡片和侧面板查看摘要 | +| 强调上下文菜单和拖拽 | 强调搜索、多选和批量操作 | + +两者共享对象身份和元数据。可以从对象浏览器打开对象，再回到对象树定位对应节点。 ## 功能边界 -对象源代码编辑仅支持允许程序化替换源代码的数据库。只读数据库、某些旧版本和部分云数据库服务可能不提供可编辑的对象源代码。在这些情况下，可使用对象浏览器进行查看，并复制 DDL 进行手动执行。 +- 不同数据库公开的对象类型和统计列不同 +- 行数和大小可能是估算值或缓存值 +- 系统对象是否显示取决于可见 Schema 和系统 Schema 设置 +- 只读连接仍可查看对象、DDL 和源码，但修改入口会被禁用或拒绝 +- 大量对象首次加载时，驱动可能分批读取元数据 + + + + 使用层级导航、固定、拖拽和数据库专属上下文菜单。 + + + 可视化编辑字段和索引并预览 DDL。 + + + 从外键、视图和历史 SQL 中追踪字段关系。 + + diff --git a/docs/content/docs/object-browser.mdx b/docs/content/docs/object-browser.mdx index 18068bcae4..84ce7176ef 100644 --- a/docs/content/docs/object-browser.mdx +++ b/docs/content/docs/object-browser.mdx @@ -1,56 +1,102 @@ --- title: Object Browser -description: Browse views, procedures, functions, and other database objects beyond tables and schemas. +description: Use list or grid views to inspect database objects, statistics, source, and bulk actions. --- -The Object Browser extends the sidebar beyond tables and collections. It surfaces database objects that are often hidden or require separate queries to inspect. +The object browser collects objects from the active database or schema into one searchable list or grid. It is useful when a database contains many objects, when filtering by type or metadata matters, or when several objects need the same operation. -## What the Object Browser Shows +## When to Use It -| Object Type | Information Shown | -| ----------- | ------------------------------------------ | -| Views | View definition (DDL), column list, schema | -| Procedures | Source code, parameters, language | -| Functions | Return type, parameters, source code | -| Triggers | Timing, event, table, source | -| Routines | Combined view of procedures and functions | +- View many tables, views, procedures, functions, sequences, and other objects on one page +- Filter by name, type, schema, comment, or available statistics +- Compare table size, row count, creation/update time, and other driver-provided metadata +- Multi-select objects for open, copy, export, drop, or other bulk actions +- Inspect DDL or source without expanding a deep object tree -Object Browser availability depends on the database engine and its metadata support. Not all databases expose source code or routine metadata through standard SQL. +## Open the Browser -## Opening the Object Browser +Open **Object Browser** from a connection, database, or schema context menu. DBX derives the catalog, database, and schema scope from the selected node. -Open the Object Browser from the sidebar: +The browser can open as a main tab or a side panel. The side panel is useful when you want to inspect objects while keeping the current query or data tab visible. -- **Double-click** a database or schema node to open its Object Browser -- Right-click and choose **Object Browser** from the context menu -- Use the **View DDL** action on any object to see its source definition +## Views and Filters -## View DDL +| Feature | Behavior | +| --- | --- | +| List view | Best for name, type, schema, comment, row count, size, and related columns | +| Grid view | Best for scanning object cards and key summaries | +| Object-type filter | Prioritizes tables by default and can switch to views, routines, and other types | +| Search | Filters by object name, schema, type, and selected metadata | +| Column controls | Resize and show columns; viewport state can be retained | -The **View DDL** action shows the complete `CREATE` statement for a view, procedure, or function: +Statistics appear only when the driver can retrieve them reliably. Row counts and sizes can add cost in large databases, so disable unneeded statistics when necessary. -- Displayed in a read-only SQL viewer with syntax highlighting -- Copy the DDL to use in migration scripts or documentation -- Compare definitions between environments +## Object Actions -## Editing Object Source +Click or double-click an object to open a type-appropriate view: -For databases that support `CREATE OR REPLACE` semantics, you can edit object source directly: +- Table or view data +- Table structure, columns, indexes, foreign keys, triggers, and DDL +- Source for views, procedures, functions, triggers, and other objects +- Database-specific administration interfaces -- Procedures and functions can be edited and saved -- DBX generates the appropriate `CREATE OR REPLACE` or `ALTER` statement -- Review the generated SQL before applying changes +Context menus can also provide: -Editing database objects in place may affect running applications. Verify the object's usage before saving changes, especially on production databases. +- Copy name, qualified name, or DDL +- Generate query SQL +- Import, export, transfer, and schema entry points +- Open ER diagram, field lineage, or schema diff +- Rename, truncate, drop, or administer the object -## Object Timestamps +Available actions depend on database capabilities, connection read-only state, and account privileges. -When the database provides it, the Object Browser shows object metadata timestamps: +## Multi-Select and Bulk Actions -- Creation time -- Last modification time -- Useful for tracking recent changes or finding stale objects +Use checkboxes to select multiple objects. Depending on the database, bulk actions can include: -## Feature Boundaries +- Open or copy multiple object names +- Export or generate SQL in bulk +- Drop, empty, or truncate selected tables +- Drop selected indexes +- Use cascade-aware batch actions for PostgreSQL and similar databases -Object source editing is supported for databases that allow programmatic source replacement. Read-only databases, certain legacy versions, and some cloud database services may not expose editable object source. In those cases, use the Object Browser for inspection and copy the DDL for manual execution. +Bulk drop, empty, and truncate operations can affect many objects. In production, verify selection, generated SQL, backups, and dependencies first. + +## DDL and Source + +- **View DDL** prefers definitions returned by the database or driver +- **Object source** covers views, procedures, functions, triggers, and other editable objects +- Source views support search and can open in the editor when the database and object allow it +- Saving source or executing DDL passes through read-only, production, and dangerous-operation checks + +DBX shows the definition available from the active driver. Formatting, privileges/comments/storage properties, and direct edit support vary by database. + +## Object Tree vs. Object Browser + +| Object tree | Object browser | +| --- | --- | +| Best for hierarchy, pins, and frequent navigation | Best for filtering and comparing many peer objects | +| Expands columns and child nodes | Uses columns, cards, and a side panel for summaries | +| Emphasizes context menus and drag-and-drop | Emphasizes search, multi-select, and bulk actions | + +Both surfaces share object identity and metadata. Open an object from the browser, then reveal the same node in the object tree when needed. + +## Boundaries + +- Object types and statistic columns vary by database +- Row counts and sizes may be estimates or cached values +- System-object visibility depends on visible-schema and system-schema settings +- Read-only connections can inspect objects, DDL, and source, but mutation entry points are disabled or rejected +- Drivers may load large object sets in batches on first access + + + + Use hierarchical navigation, pins, drag-and-drop, and database-specific context menus. + + + Edit columns and indexes visually and review DDL. + + + Trace relationships from foreign keys, views, and query history. + + diff --git a/docs/content/docs/plugins.cn.mdx b/docs/content/docs/plugins.cn.mdx index 3b512ef665..b6a1cfc579 100644 --- a/docs/content/docs/plugins.cn.mdx +++ b/docs/content/docs/plugins.cn.mdx @@ -7,6 +7,10 @@ DBX 默认使用 Rust 原生数据库驱动。JDBC 是可选能力：当你需 JDBC 插件不会打包进 DBX 主应用，也不包含任何数据库厂商的 JDBC 驱动。你需要先安装 DBX JDBC 插件，再导入对应数据库的 JDBC driver JAR。 +“JDBC 能连接”不等于拥有原生 DBX profile 的全部能力。表树、对象源码、结构编辑、导入、传输和管理视图取决于 JDBC 元数据、识别出的实际数据库类型和驱动能力清单；未知数据库会按通用 JDBC 能力运行。 + +Desktop 导入的是本机 JAR；Docker/Web 中 JAR 和插件安装在服务器数据目录。浏览器电脑上的本地路径不能直接交给 Web 服务器使用，迁移配置时也不会自动携带驱动文件。 + ## 什么时候需要 JDBC 优先使用 DBX 内置数据库类型，例如 MySQL、PostgreSQL、SQLite、Redis、MongoDB、DuckDB、ClickHouse、SQL Server、Oracle、DM、GaussDB 等。 diff --git a/docs/content/docs/plugins.mdx b/docs/content/docs/plugins.mdx index 27d3048a69..0e8de964a8 100644 --- a/docs/content/docs/plugins.mdx +++ b/docs/content/docs/plugins.mdx @@ -7,6 +7,10 @@ DBX uses native Rust database drivers by default. JDBC is optional: install the The JDBC plugin is not bundled with the main DBX app, and it does not include vendor JDBC drivers. Install the DBX JDBC plugin first, then import the database vendor's JDBC driver JAR. +A successful JDBC connection does not imply every capability of a native DBX profile. Object trees, source definitions, structure editing, import, transfer, and admin views depend on JDBC metadata, the detected effective database type, and the driver capability manifest. Unknown engines run with generic JDBC capabilities. + +Desktop imports JARs from the local machine. Docker/Web installs JARs and the plugin in the server data directory; browser-local paths are not directly readable by the server, and configuration migration does not carry driver files automatically. + ## When to Use JDBC Prefer built-in DBX database types first, such as MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, ClickHouse, SQL Server, Oracle, DM, and GaussDB. diff --git a/docs/content/docs/production-safety.cn.mdx b/docs/content/docs/production-safety.cn.mdx new file mode 100644 index 0000000000..d58869e40f --- /dev/null +++ b/docs/content/docs/production-safety.cn.mdx @@ -0,0 +1,153 @@ +--- +title: 生产环境与写入安全 +description: 使用只读连接、生产环境保护、SQL 审查、AI 限制和 MCP 策略降低数据库误操作风险。 +--- + +DBX 将写入安全拆成多个相互独立的层级：数据库账号权限、连接只读、生产环境保护、危险操作确认、AI 执行规则和 MCP 策略。它们共同降低误操作风险，但不会替代数据库自身的权限、审计、备份和变更审批。 + +任何客户端侧保护都不是数据库权限的替代品。生产环境仍应使用最小权限账号、数据库审计、可靠备份和团队审批流程。 + +## 保护层级 + +| 层级 | 作用 | 是否可以被上层工具绕过 | +| --- | --- | --- | +| 数据库账号权限 | 由数据库服务器最终决定允许读取、写入和管理哪些对象 | 不可以 | +| 连接只读 | 在 DBX 核心查询路径阻止可识别的写入，并禁用多个修改入口 | AI、CLI、MCP 和普通界面都不能放宽 | +| 生产环境保护 | 对整个连接或指定数据库启用生产标记，写入时要求每次重新确认 | 普通确认和 Agent 授权不能永久跳过 | +| 危险 SQL/命令确认 | 对 DDL、无条件修改、Redis 高风险命令等额外提示或阻止 | 取决于对应设置，但不会放宽只读或生产保护 | +| MCP 全局策略 | 用连接 allowlist 和三档执行权限约束所有 MCP 客户端 | 客户端环境变量不能扩大已保存的中央策略 | + +## 配置只读连接 + +创建或编辑连接时，启用**只读连接**。保存后，DBX 会把该标记带入核心查询执行和数据库专属操作中。 + +只读连接适合： + +- 生产查询账号和只允许排查的共享连接 +- 只需要浏览 Schema、表数据、文档、键或监控指标的场景 +- 提供给 CLI、MCP 或 AI 使用，但不希望产生任何数据修改的连接 + +只读保护不只是隐藏按钮。对于可识别的 SQL 写入，DBX 会在核心执行路径拒绝请求；MCP、MongoDB、Redis、消息队列和多个专项工作台也会重新检查连接只读状态。 + +只读分类需要识别 SQL 或命令语义。最可靠的边界仍然是数据库账号本身没有写权限。 + +## 配置生产环境保护 + + + + ### 打开连接设置 + + 新建或编辑连接，在连接设置中找到**生产环境**。 + + + + ### 启用保护 + + 打开**启用生产环境保护**。单数据库连接会直接保护整个连接；支持多个数据库的连接可以选择保护全部数据库或指定数据库。 + + + + ### 检查保护范围 + + 如果只保护部分数据库，确认列表中包含实际生产库。数据库列表变化后应重新检查配置。 + + + + ### 验证写入提示 + + 在测试语句或测试环境中确认生产水印和写入确认对话框符合预期，再把同样的设置用于真实连接。 + + + + +生产保护启用后，工作区会显示生产环境提示。DBX 检测到当前连接、当前数据库或 SQL 显式目标属于生产范围且语句会修改数据或结构时，会打开统一确认对话框。 + +每次生产写入都需要新的明确决定。确认状态不会保存，也不会因为关闭普通危险 SQL 提示而被跳过。 + +## 不同入口如何处理写入 + +| 入口 | 只读连接 | 生产环境保护 | +| --- | --- | --- | +| SQL 编辑器 | 核心执行路径拒绝可识别写入 | 写入前显示目标连接、数据库、入口和 SQL，逐次确认 | +| 数据表格 | 禁用或拒绝保存、删除等修改 | 保存行、删除行等操作进入统一生产确认 | +| 表结构与对象操作 | 隐藏或禁用可识别的修改入口 | DDL、对象源码保存、数据库管理等进入统一确认 | +| Schema 对比、SQL 文件、数据生成 | 目标只读时不允许写入 | 执行生成 SQL 或脚本前进入统一确认 | +| Redis、MongoDB、etcd、消息队列等 | 按系统命令和操作重新检查只读 | 写入入口继续受生产保护和专项危险操作规则约束 | +| AI Ask | 不执行 SQL | 不执行 SQL | +| AI Agent | 不能绕过只读 | 生产 SQL 返回编辑器，由用户检查并手动执行 | +| MCP | 连接只读是所有权限模式的上限 | 生产保护始终是 MCP 策略的上限 | + +## AI 的执行边界 + +### Ask 模式 + +Ask 模式用于生成、解释、优化或修复 SQL。模型返回的 SQL 不会自动执行，可以复制或放入编辑器后再检查。 + +### Agent 模式 + +Agent 可以根据用户意图执行读取操作，并在满足策略时处理有限写入。即使用户对一次普通写入作出确认，授权也只对当前目标和当前操作生效。 + +当活动数据库处于生产保护范围时，Agent 不会获得自主写入权限。DBX 会把建议 SQL 放回编辑器，并要求用户在生产写入对话框中手动确认。 + +更多 SQL 分类和模式差异见 [AI 助手](/cn/docs/ai-assistant)。 + +## MCP 权限 + +DBX 在**设置 → MCP**中保存一份统一策略，所有 MCP 客户端请求都重新读取这份策略。 + +| 模式 | 允许的代表性操作 | +| --- | --- | +| 只读 | 查询、元数据读取、列出连接和对象 | +| 数据读写 | 普通插入、带有效过滤条件的更新/删除、范围明确的 MongoDB 修改、普通 Redis 写入和连接管理 | +| 完全访问 | 额外允许大范围更新/删除、DDL、`TRUNCATE`、清空数据和高风险管理命令 | + +除了执行模式，还应配置**允许的连接**。没有进入 allowlist 的连接不会暴露给 MCP。无论选择哪一档，以下限制始终有效： + +- 连接只读 +- 生产环境保护 +- 数据库账号权限 +- 已保存的连接 allowlist + +完整配置、客户端示例和兼容行为见 [MCP 集成](/cn/docs/mcp)。 + +## 危险 SQL 与专项命令 + +生产保护之外，DBX 还会对部分高风险操作应用额外规则： + +- 查询编辑器可以在执行危险 SQL 前显示确认对话框 +- Redis 可以阻止或确认高风险命令 +- 数据表格、表结构、Schema 对比和数据生成会尽量先展示 SQL +- MCP 的“数据读写”会拒绝无有效范围的更新/删除、DDL、`TRUNCATE` 和无法可靠分类的高风险请求 +- 跨引擎传输和批量导入需要单独检查类型映射、目标表和清空选项 + +## 推荐配置 + +| 场景 | 建议 | +| --- | --- | +| 本地开发库 | 使用普通连接；保留危险 SQL 确认；需要自动化时给 MCP“数据读写”而非“完全访问” | +| 测试/预发 | 设置明显的连接名称和颜色；开启危险 SQL 确认；限制 MCP allowlist | +| 生产只查 | 使用数据库只读账号，同时启用 DBX 只读和生产保护；MCP 使用“只读” | +| 生产变更 | 使用独立最小权限账号；启用生产保护；先预览 SQL；保留备份和审批记录；避免给 MCP“完全访问” | +| 共享 Docker | 设置登录密码、持久化 `/app/data`、限制网络访问，并为每个数据库使用独立账号权限 | + +## 已知边界 + +- SQL 和命令分类采用保守策略，但无法代替数据库服务器权限。 +- 存储过程、厂商扩展语法或动态 SQL 的真实影响范围可能无法仅通过文本完全判断。 +- 生产保护关注 DBX 内发起的操作；其他客户端仍需要独立权限和审计。 +- 配置同步和导出用于迁移 DBX 配置，不是业务数据库备份。 + + + + 从连接类型、网络路径、只读和生产范围开始配置。 + + + 了解行内编辑、删除、SQL 预览和保存流程。 + + + 查看 Ask、Agent、SQL 分类和生产环境行为。 + + + 设置连接 allowlist、执行权限和客户端接入方式。 + + diff --git a/docs/content/docs/production-safety.mdx b/docs/content/docs/production-safety.mdx new file mode 100644 index 0000000000..eaef7bb1a4 --- /dev/null +++ b/docs/content/docs/production-safety.mdx @@ -0,0 +1,153 @@ +--- +title: Production and Write Safety +description: Reduce database mistakes with read-only connections, production protection, SQL review, AI limits, and MCP policies. +--- + +DBX separates write safety into independent layers: database privileges, connection read-only state, production protection, dangerous-operation confirmation, AI execution rules, and MCP policy. Together they reduce mistakes, but they do not replace database permissions, auditing, backups, or change approval. + +No client-side safeguard replaces database permissions. Production systems should still use least-privilege accounts, database auditing, reliable backups, and team approval workflows. + +## Protection Layers + +| Layer | Purpose | Can a higher-level tool bypass it? | +| --- | --- | --- | +| Database account privileges | The database server ultimately decides which objects can be read, changed, or administered | No | +| Connection read-only | Blocks recognizable writes in the DBX core query path and disables multiple mutation entry points | AI, CLI, MCP, and the normal UI cannot widen it | +| Production protection | Marks an entire connection or selected databases as production and requires a fresh confirmation for writes | Normal confirmation and Agent authorization cannot permanently skip it | +| Dangerous SQL/command confirmation | Adds prompts or blocks for DDL, unbounded mutations, risky Redis commands, and similar operations | Controlled by its setting, but never widens read-only or production protection | +| Global MCP policy | Restricts all MCP clients through a connection allowlist and three execution modes | Client environment variables cannot widen the saved central policy | + +## Configure a Read-Only Connection + +Enable **Read-only connection** when creating or editing a connection. DBX carries the flag into core query execution and database-specific operations. + +Read-only connections are useful for: + +- Production query accounts and shared troubleshooting connections +- Workflows that only need to browse schemas, rows, documents, keys, or monitoring data +- Connections exposed to the CLI, MCP, or AI where no data changes should be possible + +Read-only protection is not only a hidden button. DBX rejects recognizable SQL writes in the core execution path, while MCP, MongoDB, Redis, message queues, and multiple specialized workspaces recheck the connection state. + +Read-only enforcement still depends on classifying SQL or commands. The most reliable boundary is a database account that has no write permission. + +## Configure Production Protection + + + + ### Open connection settings + + Create or edit a connection and find the **Production** section. + + + + ### Enable protection + + Turn on **Enable production protection**. Single-database connections protect the whole connection; multi-database connections can protect all or selected databases. + + + + ### Review the scope + + If only selected databases are protected, verify that every real production database is included. Recheck the list when databases are added or renamed. + + + + ### Verify the write prompt + + Use a harmless test or a test environment to confirm that the production watermark and write dialog behave as expected before relying on the setting for a real connection. + + + + +When production protection is active, the workbench shows a production indicator. If DBX detects that the active connection, active database, or explicit SQL target belongs to the protected scope and the operation mutates data or schema, it opens the shared confirmation dialog. + +Every production write requires a new explicit decision. Confirmation is not persisted and cannot be skipped by disabling the normal dangerous-SQL prompt. + +## Behavior Across Entry Points + +| Entry point | Read-only connection | Production protection | +| --- | --- | --- | +| SQL editor | The core execution path rejects recognizable writes | Shows the target connection, database, source, and SQL for per-operation confirmation | +| Data grid | Disables or rejects saves, deletes, and other mutations | Row saves and deletes enter the shared production confirmation flow | +| Table structure and object actions | Hides or disables recognizable mutation entry points | DDL, source saves, and database administration enter the shared confirmation flow | +| Schema diff, SQL files, and data generation | Cannot write to a read-only target | Generated SQL or scripts require production confirmation before execution | +| Redis, MongoDB, etcd, message queues, and similar systems | Rechecks read-only state for system-specific commands and actions | Mutation entry points remain subject to production and specialized danger rules | +| AI Ask | Does not execute SQL | Does not execute SQL | +| AI Agent | Cannot bypass read-only state | Returns production SQL to the editor for human review and manual execution | +| MCP | Connection read-only is an upper bound for every mode | Production protection remains an upper bound for MCP policy | + +## AI Execution Boundaries + +### Ask Mode + +Ask mode generates, explains, optimizes, or repairs SQL. Model output is not executed automatically and can be copied or placed into the editor for review. + +### Agent Mode + +Agent can execute reads based on user intent and can handle limited writes when policy permits. A write confirmation is scoped to the current target and operation. + +When the active database is protected as production, Agent does not receive autonomous write permission. DBX places the proposed SQL in the editor and requires manual confirmation through the production-write dialog. + +See [AI Assistant](/en/docs/ai-assistant) for SQL classification and mode details. + +## MCP Permissions + +DBX stores one central policy under **Settings → MCP**, and every MCP request reloads that policy. + +| Mode | Representative operations | +| --- | --- | +| Read only | Queries, metadata reads, and listing connections or objects | +| Data read/write | Regular inserts, effectively filtered updates/deletes, scoped MongoDB mutations, ordinary Redis writes, and connection management | +| Full access | Also allows broad mutations, DDL, `TRUNCATE`, data clearing, and high-risk administrative commands | + +Configure **Allowed connections** in addition to the execution mode. Connections outside the allowlist are not exposed to MCP. These limits remain active in every mode: + +- Connection read-only state +- Production protection +- Database account privileges +- The saved connection allowlist + +See [MCP Integration](/en/docs/mcp) for complete configuration, client examples, and compatibility behavior. + +## Dangerous SQL and Specialized Commands + +Outside production protection, DBX applies additional rules to selected high-risk operations: + +- The query editor can show a confirmation before dangerous SQL runs +- Redis can block or confirm risky commands +- The data grid, table structure, schema diff, and data generation flows show SQL first where possible +- MCP Data read/write rejects unbounded updates/deletes, DDL, `TRUNCATE`, and high-risk requests it cannot classify reliably +- Cross-engine transfer and bulk import require separate review of type mappings, target tables, and truncate options + +## Recommended Configuration + +| Scenario | Recommendation | +| --- | --- | +| Local development | Use a normal connection, keep dangerous-SQL confirmation, and prefer MCP Data read/write over Full access | +| Test or staging | Use obvious connection names and colors, keep dangerous-SQL confirmation, and limit the MCP allowlist | +| Production read-only | Use a database read-only account plus DBX read-only and production protection; keep MCP in Read only | +| Production changes | Use a separate least-privilege account, enable production protection, review SQL, retain backups and approvals, and avoid MCP Full access | +| Shared Docker | Set a login password, persist `/app/data`, restrict network access, and use separate database privileges for each target | + +## Known Boundaries + +- SQL and command classification is conservative but cannot replace server-side privileges. +- Stored procedures, vendor extensions, and dynamic SQL may have effects that cannot be determined from text alone. +- Production protection covers operations initiated through DBX; other clients require their own permissions and auditing. +- Configuration sync and export migrate DBX settings and are not backups of business databases. + + + + Configure the connection type, network path, read-only state, and production scope. + + + Understand inline edits, deletes, SQL preview, and the save flow. + + + Review Ask, Agent, SQL classification, and production behavior. + + + Set the connection allowlist, execution mode, and client integration. + + diff --git a/docs/content/docs/query-editor.cn.mdx b/docs/content/docs/query-editor.cn.mdx index 2f4b6d634e..54a62e7b47 100644 --- a/docs/content/docs/query-editor.cn.mdx +++ b/docs/content/docs/query-editor.cn.mdx @@ -1,108 +1,177 @@ --- title: 查询编辑器 -description: 使用 DBX 的 SQL 编辑器编写、补全、格式化、执行和复用查询。 +description: 使用 DBX 编写、理解、参数化、执行、分析和复用 SQL。 --- -查询编辑器用于完成日常 SQL 工作：编写查询、查看补全建议、格式化语句、执行选中片段，以及从历史记录中找回之前的 SQL。 +查询编辑器是 DBX 的 SQL 工作区。它把方言感知的高亮与补全、语义诊断、参数输入、执行进度、多结果、执行计划、查询历史、SQL 库和 AI 助手放在同一个标签页中。 ## 基本工作流 - ### 打开连接 + ### 选择连接上下文 - 从侧边栏选择一个数据库连接。DBX 会根据当前连接加载对应的数据库类型和元数据。 + 新建查询时选择连接、数据库和 Schema。也可以从对象树、快速打开、SQL 库或 SQL 文件创建带上下文的查询标签。 - ### 编写 SQL + ### 编写并检查 SQL - 在编辑器中输入 SQL。补全会结合 SQL 关键字、表、视图、字段和部分关系信息给出建议。 + 使用补全、悬停信息、语义诊断、格式化和代码折叠理解 SQL。`Ctrl/Cmd+Click` 可以按设置跳转到表数据或对象位置。 - ### 执行查询 + ### 明确执行范围 - 使用快捷键执行全部 SQL 或选中的 SQL 片段。结果会显示在编辑器下方的数据表格中。 + 选中要执行的 SQL，或使用当前语句/全部内容。多语句时可以通过执行目标选择器确认范围。 - ### 复用历史 + ### 查看结果或执行计划 - 通过查询历史找回之前执行过的语句，适合重复排查和调试。 + 结果区支持多个运行记录、横向标签或列表视图。需要分析性能时，使用执行计划入口读取树、摘要和标准表格。 + + + + ### 保存和复用 + + 把稳定查询保存到 SQL 库或外部 `.sql` 文件，并通过历史记录、快速打开或文件夹再次使用。 ## 执行 SQL -| 操作 | macOS | Windows / Linux | -| ---------------------- | ---------------------- | ----------------------- | -| 执行全部 SQL | `Cmd+Enter` | `Ctrl+Enter` | -| 执行选中 SQL | 选中文本后 `Cmd+Enter` | 选中文本后 `Ctrl+Enter` | -| 在新结果标签页中执行 | `Cmd+\` | `Ctrl+\` | +| 操作 | macOS | Windows / Linux | +| --- | --- | --- | +| 执行当前范围 | `Cmd+Enter` | `Ctrl+Enter` | +| 在新结果中执行 | `Cmd+\` | `Ctrl+\` | +| 停止执行 | 点击执行按钮变成的停止按钮 | 点击执行按钮变成的停止按钮 | -如果编辑器中有选中文本，DBX 只执行选中的 SQL；没有选中文本时，执行当前编辑器中的全部内容。 +有选中文本时，DBX 优先执行选中内容；没有选中时，根据当前语句和执行目标设置决定范围。快捷键可以在 [快捷键](/cn/docs/keyboard-shortcuts) 中修改。 -执行完成后，结果区域会展示返回行、耗时、影响行数或错误信息。多语句执行时，建议先选中要执行的片段，减少误操作。 +普通执行会更新当前激活结果。**在新结果中执行**适合保留旧结果进行对比。结果可以平铺为横向标签，也可以切换为列表；多次执行还会保留运行记录，并可以固定重要结果。 -普通执行会覆盖当前激活的结果。需要保留当前结果并对比下一次执行时，使用**在新结果标签页中执行 SQL**；DBX 默认把每次执行平铺为横向结果标签，可直接切换或关闭。标签较多时仅执行标签区横向滚动，当前表名会保持固定。也可以在结果工具栏的**视图选项**中把执行结果切换为列表。两种执行方式对选中 SQL 和当前语句的判定规则完全一致。 +多语句执行时，结果区显示当前语句、总语句数、完成状态和错误。驱动支持时，可以取消当前查询或后续语句。 -两种执行快捷键都可以在**设置 → 快捷键**中配置。DBX 会检测 SQL 编辑器作用域内的按键冲突，解决冲突后才能应用快捷键变更。 +查询取消取决于驱动和数据库能力。点击停止后，服务端可能仍需要时间中断正在执行的语句。 -DBX 也会跟踪查询会话，离开结果集时可以关闭会话；当数据库驱动支持取消时，正在执行的查询也可以从界面中取消。 +## 执行范围与目标选择器 -### SQL 执行目标选择器 +| 范围 | 如何确定 | 适合场景 | +| --- | --- | --- | +| 选中 SQL | 执行前高亮文本 | 多语句草稿中最明确、安全 | +| 当前语句 | 光标位于语句内 | 快速执行脚本中的一条语句 | +| 全部内容 | 没有选择且按设置执行整个编辑器 | 单用途短脚本 | -对于只包含单条语句的查询，DBX 可以直接执行而不显示目标选择器。当 SQL 包含多条语句时，DBX 会显示执行目标选择器并提供预览装饰，帮助你选择要执行的语句。 +执行目标选择器会在需要时标出可执行语句并展示预览。可以在设置中启用或关闭，但生产和复杂脚本建议保留。 -可以在设置中的 **显示执行目标选择器** 选项启用或禁用此功能。禁用后，DBX 会直接执行整个编辑器内容而不提示。 +大型 `.sql` 文件、需要逐语句进度或文件级统计的任务，应使用 [SQL 文件执行](/cn/docs/sql-file)。 -## 执行范围 +## 自动补全与语义诊断 -| 范围 | 如何确定 | 适合场景 | -| -------- | ---------------------- | ---------------------------- | -| 选中 SQL | 执行前先高亮文本 | 多语句草稿中最安全 | -| 当前语句 | 使用编辑器光标相关流程 | 不手动选择文本时运行单条语句 | -| 全部内容 | 没有选中文本时执行 | 单用途查询标签页或短脚本 | +补全会结合当前数据库方言和元数据提供： -DBX 可以执行批量 SQL 和脚本，但在查询编辑器里仍建议一次运行一条已审查语句。大型 `.sql` 文件请使用带进度跟踪的 [SQL 文件执行](/cn/docs/sql-file)。 +- SQL 关键字、函数、类型和数据库专属语法 +- 数据库、Schema、表、视图、字段和字段注释 +- 表别名、CTE、子查询作用域和可见字段 +- 基于外键或关系元数据的 JOIN 条件 +- MySQL、PostgreSQL、SQL Server、ClickHouse 等方言的函数和语法建议 +- 用户配置的 [SQL 代码片段](/cn/docs/sql-snippets) -## 自动补全 +语义诊断会标出部分无法解析的表、字段、别名和 SQL 结构。它用于提前发现问题，不代表数据库一定会拒绝或接受语句；厂商扩展语法仍以服务端结果为准。 -补全建议来自当前连接的数据库上下文： +刚创建或修改对象后，先刷新连接元数据。DBX 会缓存并按需加载表结构，以减少大型 Schema 的重复请求。 -- **SQL 关键字**：例如 `SELECT`、`FROM`、`WHERE`、`GROUP BY` -- **对象名称**：表、视图、Schema、数据库 -- **字段名称**：根据已经输入的表名或别名推断字段 -- **JOIN 建议**：基于外键或已知关系提示可关联表和关联条件 -- **SQL Server 语法**：SQL Server 连接下支持 `CROSS APPLY`、`OUTER APPLY` 等补全 +## 表和对象导航 -补全的准确性依赖当前连接的元数据。如果刚创建表或修改字段，可以刷新连接元数据后再试。 +- `Ctrl/Cmd+Click` 表名可以按设置打开表数据或定位对象 +- 从光标位置可以在侧边栏定位当前引用的表 +- 快速打开支持搜索连接、数据库、表、SQL 文件和 SQL 库 +- 对象源码视图支持搜索，并可以把 SQL 打开到编辑器继续修改 -## 格式化 SQL +导航依赖 SQL 解析和当前元数据。动态 SQL、同名对象或缺少 Schema 的引用可能需要手动确认目标。 -点击工具栏中的格式化按钮，可以统一缩进、换行和关键字风格。格式化适合在提交迁移脚本、分享查询或排查复杂 SQL 前使用。 +## SQL 参数与变量 -格式化只改变 SQL 文本，不会执行 SQL，也不会改变数据库内容。 +执行前，DBX 可以识别常见占位符并打开参数输入对话框： + +| 语法 | 示例 | +| --- | --- | +| 位置参数 | `?` | +| 命名参数 | `:user_id` | +| Shell 风格 | `${user_id}` | +| MyBatis 风格 | `#{user_id}` | +| SQL Server 风格 | `@user_id` | +| 脚本变量 | `@set user_id = 42;` | + +参数可以按字符串、数字、布尔、`NULL` 或原始 SQL 值输入。每种数据库可以在设置中关闭会与原生语法冲突的占位符形式。 + +“原始 SQL”参数不会自动加引号。只应填入经过审查的 SQL 片段，不要直接拼接不可信输入。 + +## 格式化、压缩与折叠 + +- **格式化 SQL**统一缩进、换行和关键字风格 +- **压缩 SQL**移除不必要的空白，适合复制或排查生成 SQL +- **代码折叠**收起长查询、子查询或过程块；折叠快捷键可以配置 +- 格式化选项和变量语法见 [SQL 格式化](/cn/docs/sql-formatter) + +格式化和压缩只修改编辑器文本，不会执行 SQL。 + +## 执行计划 + +执行计划入口只接受可安全分析的查询类 SQL，例如 `SELECT`、`WITH`、`TABLE` 或 `VALUES`。支持的数据库会返回： + +- 标准结果表格 +- 可展开的计划树 +- 节点、成本、预估行数、表和索引摘要 +- 数据库返回的原始详情 + +不同数据库的 `EXPLAIN` 语义不同，部分引擎只提供表格或文本结果。执行计划反映优化器估算，不等于真实生产性能；需要结合数据量、统计信息、索引和实际耗时判断。 ## 查询历史 -DBX 会记录已经执行过的 SQL，方便复用： +查询历史按连接保存已执行 SQL，并记录时间和相关上下文。可以： -- 每个连接独立保存查询历史 -- 可以按时间查看之前执行的语句 -- 点击历史记录可重新填入编辑器 -- 适合找回临时排查 SQL、报表查询和修复语句 -- 历史记录会保留足够上下文，用于区分手写查询和 AI 辅助操作 -- **执行时间范围过滤**：按日期范围过滤历史记录，查找特定时间段内执行的查询 +- 按日期范围过滤 +- 搜索并重新填入编辑器 +- 区分普通执行和 AI 辅助来源 +- 从历史 SQL 恢复或对比之前的排查过程 +- 在字段血缘中把历史 SQL 作为可能引用关系 -查询历史可能包含业务字段、表名或筛选条件。共享电脑或演示环境中，建议注意历史记录里的敏感信息。 +查询历史可能包含业务字段、表名、筛选条件或数据字面量。共享日志、截图或配置备份前先检查敏感信息。 -## 与数据表格配合 +## SQL 库与 SQL 文件 -查询结果会进入 [数据表格](/cn/docs/data-grid)。如果查询结果可编辑，DBX 会在保存前展示将要执行的 SQL；如果只是临时分析，可以直接导出 CSV、JSON 或 Markdown。 +| 方式 | 适合场景 | 平台边界 | +| --- | --- | --- | +| SQL 库 | 在 DBX 中按文件夹保存和搜索常用查询 | 桌面版支持完整本地 SQL 库管理；同步范围见云同步设置 | +| 外部 SQL 文件 | 与项目仓库、脚本目录或编辑器共享 `.sql` 文件 | 本地文件打开、保存和文件树属于桌面端能力 | +| 查询标签 | 临时分析和未完成草稿 | 可按设置恢复全部、仅固定标签或不恢复 | -## 与 AI 配合 +保存 SQL 时可以搜索或创建文件夹。快速打开会同时索引 SQL 库和 SQL 文件。 -编辑器可以把当前 SQL、连接类型、数据库名、最近错误、结果预览和已加载的 Schema 上下文发送给 [AI 助手](/cn/docs/ai-assistant)。Ask 模式只返回 SQL 和说明；Agent 模式会先经过 DBX 的执行策略，再决定是否尝试执行生成的 SQL。 +## 安全与边界 + +- 只读连接会在核心执行路径拒绝可识别写入 +- 生产环境保护会对写入逐次显示明确确认 +- 危险 SQL 确认和 Redis 命令安全是额外保护层 +- `USE` 或数据库切换会更新查询上下文，但仍应检查当前连接和目标数据库 +- 自动补全、语义诊断和执行计划都依赖当前驱动与元数据能力 + +完整规则见 [生产环境与写入安全](/cn/docs/production-safety)。 + + + + 了解数据表格、复制、导出和安全编辑。 + + + 执行大型脚本并查看文件和语句级进度。 + + + 创建可通过补全展开的个人 SQL 模板。 + + + 生成、解释、优化 SQL，并把结果放回编辑器审查。 + + diff --git a/docs/content/docs/query-editor.mdx b/docs/content/docs/query-editor.mdx index 48d1948aed..60ec476dab 100644 --- a/docs/content/docs/query-editor.mdx +++ b/docs/content/docs/query-editor.mdx @@ -1,108 +1,177 @@ --- title: Query Editor -description: Write, complete, format, execute, and reuse SQL in DBX. +description: Write, understand, parameterize, execute, analyze, and reuse SQL in DBX. --- -The query editor is where daily SQL work happens: writing queries, using completion, formatting statements, executing selected fragments, and returning to previous SQL through history. +The query editor is the SQL workspace in DBX. It combines dialect-aware highlighting and completion, semantic diagnostics, parameter input, execution progress, multiple results, execution plans, query history, the SQL library, and AI assistance in one tab. ## Basic Workflow - ### Open a Connection + ### Choose connection context - Select a database connection from the sidebar. DBX loads the database type and metadata for the active connection. + Select a connection, database, and schema when creating a query. You can also open a contextual query from the object tree, Quick Open, SQL Library, or SQL Files. - ### Write SQL + ### Write and inspect SQL - Type SQL in the editor. Completion suggestions use SQL keywords, tables, views, columns, and available relationship metadata. + Use completion, hover details, semantic diagnostics, formatting, and code folding. Depending on settings, `Ctrl/Cmd+Click` can navigate to table data or the related object. - ### Execute the Query + ### Make the execution scope explicit - Use the shortcut to execute all SQL or only the selected fragment. Results appear in the data grid below the editor. + Select the SQL to run or use the current statement or full editor. For multi-statement text, the execution target picker can confirm the exact range. - ### Reuse History + ### Inspect results or a plan - Open query history to bring back previously executed SQL for repeated debugging or analysis. + The result area supports multiple runs, horizontal tabs, or a list view. Use Explain Plan to inspect the plan tree, summary, and standard result table. + + + + ### Save and reuse + + Save stable queries to the SQL Library or external `.sql` files, then reopen them through history, Quick Open, or folders. ## Execute SQL -| Action | macOS | Windows / Linux | -| --------------------------- | ----------------------------- | ------------------------------ | -| Execute all SQL | `Cmd+Enter` | `Ctrl+Enter` | -| Execute selected SQL | Select text, then `Cmd+Enter` | Select text, then `Ctrl+Enter` | -| Execute in a new result tab | `Cmd+\` | `Ctrl+\` | +| Action | macOS | Windows / Linux | +| --- | --- | --- | +| Execute the current scope | `Cmd+Enter` | `Ctrl+Enter` | +| Execute in a new result | `Cmd+\` | `Ctrl+\` | +| Stop execution | Click the execution button after it changes to Stop | Click the execution button after it changes to Stop | -When text is selected, DBX executes only the selected SQL. When nothing is selected, it executes the full editor content. +When text is selected, DBX prioritizes the selection. Otherwise, the current-statement and execution-target settings determine the scope. Shortcuts can be changed under [Keyboard Shortcuts](/en/docs/keyboard-shortcuts). -After execution, the result area shows returned rows, duration, affected row count, or the error message. For multi-statement scripts, select the exact fragment you want to run to reduce mistakes. +Normal execution updates the active result. **Execute in a new result** preserves older results for comparison. Results can use horizontal tabs or a list view, and repeated executions can retain run history or pin important results. -Regular execution replaces the active result. Use **Execute SQL in new result tab** when you need to keep the current result and compare it with another run. By default, DBX tiles every run as a horizontal result tab that you can switch or close directly. When many runs are retained, only the run-tab strip scrolls while the current table label stays fixed. You can switch retained runs to a compact list under **View options** in the result toolbar. The selected SQL and current-statement rules are the same for both execution actions. +For multi-statement execution, the result area shows the current statement, total count, completion state, and errors. When the driver supports it, the active query or remaining statements can be cancelled. -Both execution shortcuts are configurable under **Settings → Shortcuts**. DBX reports conflicts within the SQL editor scope and requires them to be resolved before applying shortcut changes. +Cancellation depends on the driver and database. After Stop is clicked, the server may still need time to interrupt the current statement. -DBX also tracks query sessions so long-running result sets can be closed when you leave them, and active queries can be cancelled from the UI when the database driver supports cancellation. +## Execution Scope and Target Picker -### SQL Execution Target Picker +| Scope | How it is selected | Best for | +| --- | --- | --- | +| Selected SQL | Highlight text before execution | The clearest and safest option in a multi-statement draft | +| Current statement | Put the cursor inside a statement | Running one statement from a script quickly | +| Full editor | No selection and settings choose the full document | Short, single-purpose scripts | -For queries that contain a single statement, DBX can execute it directly without showing a target picker. When your SQL contains multiple statements, DBX displays an execution target picker with a preview decoration to help you choose which statement to run. +The execution target picker marks executable statements and shows a preview when needed. It can be disabled in settings, but it is useful for production and complex scripts. -Enable or disable the execution target picker in Settings under **Show execution target picker**. When disabled, DBX executes the entire editor content without prompting. +Use [SQL File Execution](/en/docs/sql-file) for large `.sql` files or tasks that need per-statement progress and file-level statistics. -## Execution Scope +## Completion and Semantic Diagnostics -| Scope | How It Is Chosen | Use Case | -| ----------------- | ------------------------------------------- | ------------------------------------------------- | -| Selected SQL | Highlight text before running | Safest option for multi-statement scratch pads | -| Current statement | Use editor cursor workflows where available | Run one statement without selecting text manually | -| Full editor | Run with no selection | Single-purpose query tabs and short scripts | +Completion uses the active database dialect and metadata to suggest: -DBX can execute batches and scripts, but the query editor is still safest when you run one reviewed statement at a time. Use [SQL File Execution](/en/docs/sql-file) for large `.sql` files that need progress tracking. +- SQL keywords, functions, types, and engine-specific syntax +- Databases, schemas, tables, views, columns, and column comments +- Table aliases, CTEs, subquery scope, and visible fields +- JOIN conditions based on foreign keys or relationship metadata +- Dialect-specific functions and syntax for MySQL, PostgreSQL, SQL Server, ClickHouse, and others +- User-defined [SQL Snippets](/en/docs/sql-snippets) -## Autocomplete +Semantic diagnostics flag selected unresolved tables, columns, aliases, and SQL structures. They help catch mistakes early but do not guarantee that vendor extensions will be accepted or rejected; the server result remains authoritative. -Completion suggestions come from the active database context: +Refresh connection metadata after creating or changing objects. DBX caches and lazy-loads table structure to reduce repeated requests in large schemas. -- **SQL keywords**: `SELECT`, `FROM`, `WHERE`, `GROUP BY`, and more -- **Object names**: tables, views, schemas, and databases -- **Column names**: inferred from referenced tables and aliases -- **JOIN suggestions**: related tables and join conditions from foreign keys or known relationships -- **SQL Server syntax**: `CROSS APPLY`, `OUTER APPLY`, and related completions for SQL Server connections +## Table and Object Navigation -Completion accuracy depends on connection metadata. If you just created a table or changed columns, refresh the connection metadata and try again. +- `Ctrl/Cmd+Click` a table name to open data or locate the object, depending on settings +- Locate the table referenced at the cursor in the sidebar +- Use Quick Open to search connections, databases, tables, SQL Files, and the SQL Library +- Search embedded object-source views and open SQL in the editor for further work -## Format SQL +Navigation depends on SQL parsing and current metadata. Dynamic SQL, ambiguous names, or references without a schema may require manual confirmation. -Use the format button in the toolbar to standardize indentation, line breaks, and keyword style. Formatting is useful before sharing a query, reviewing a migration script, or debugging a complex statement. +## SQL Parameters and Variables -Formatting only changes the editor text. It does not execute SQL or modify the database. +Before execution, DBX can recognize common placeholders and open a parameter-input dialog: + +| Syntax | Example | +| --- | --- | +| Positional | `?` | +| Named | `:user_id` | +| Shell style | `${user_id}` | +| MyBatis style | `#{user_id}` | +| SQL Server style | `@user_id` | +| Script variable | `@set user_id = 42;` | + +Parameters can be entered as strings, numbers, booleans, `NULL`, or raw SQL values. Per-database settings can disable placeholder forms that conflict with native syntax. + +Raw SQL parameters are not quoted automatically. Use them only for reviewed SQL fragments and never concatenate untrusted input. + +## Formatting, Compacting, and Folding + +- **Format SQL** normalizes indentation, line breaks, and keyword style +- **Compact SQL** removes unnecessary whitespace for copying or inspecting generated SQL +- **Code folding** collapses long queries, subqueries, or routine blocks and has configurable shortcuts +- See [SQL Formatting](/en/docs/sql-formatter) for formatter and variable-syntax settings + +Formatting and compacting only change editor text; they do not execute SQL. + +## Explain Plan + +Explain Plan accepts query-like SQL that is safe to analyze, such as `SELECT`, `WITH`, `TABLE`, or `VALUES`. Supported databases can return: + +- A standard result table +- An expandable plan tree +- Node, cost, estimated-row, relation, and index summaries +- Raw details returned by the database + +`EXPLAIN` semantics vary by database, and some engines provide only table or text output. A plan reflects optimizer estimates rather than real production performance; evaluate it together with data volume, statistics, indexes, and measured runtime. ## Query History -DBX records executed SQL so you can reuse it later: +Query history stores executed SQL per connection with time and context. You can: -- History is stored per connection -- Previous statements can be reviewed by time -- Clicking a history item loads it back into the editor -- Useful for investigation queries, reports, and repair statements -- History entries preserve enough context to identify manual queries and AI-assisted work -- **Execution time range filter**: Filter history entries by date range to find queries executed within a specific time period +- Filter by date range +- Search and restore SQL into the editor +- Distinguish normal and AI-assisted sources +- Recover or compare earlier troubleshooting work +- Use historical SQL as a possible reference source in field lineage -Query history may include business fields, table names, or filter values. Be mindful of sensitive information on shared machines or demo environments. +History can contain business fields, table names, predicates, or literal values. Review sensitive information before sharing logs, screenshots, or configuration backups. -## Working With the Data Grid +## SQL Library and SQL Files -Query results open in the [Data Grid](/en/docs/data-grid). If the result is editable, DBX shows the SQL before saving changes. For analysis-only results, you can export CSV, JSON, or Markdown. +| Method | Best for | Platform boundary | +| --- | --- | --- | +| SQL Library | Saving and searching reusable queries in folders inside DBX | Full local SQL Library management is available on Desktop; cloud-sync scope depends on settings | +| External SQL Files | Sharing `.sql` files with a repository, script directory, or editor | Local file open/save and the file tree are Desktop capabilities | +| Query tabs | Temporary analysis and unfinished drafts | Settings can restore all tabs, pinned tabs only, or none | -## Working With AI +The save dialog can search or create folders. Quick Open indexes both SQL Library entries and SQL Files. -The editor can send the current SQL, active connection type, database name, recent error, result preview, and loaded schema context to the [AI Assistant](/en/docs/ai-assistant). In Ask mode, AI returns SQL and explanations only. In Agent mode, DBX applies an execution policy before attempting to run generated SQL. +## Safety and Boundaries + +- Read-only connections reject recognizable writes in the core execution path +- Production protection requires a fresh explicit confirmation for writes +- Dangerous-SQL confirmation and Redis command safety are additional layers +- `USE` and database switches update query context, but the active connection and target database still need review +- Completion, diagnostics, and explain plans depend on the active driver and metadata support + +See [Production and Write Safety](/en/docs/production-safety) for the complete rules. + + + + Learn data-grid browsing, copying, export, and safe editing. + + + Execute large scripts with file- and statement-level progress. + + + Create personal SQL templates that expand through completion. + + + Generate, explain, and optimize SQL, then return it to the editor for review. + + diff --git a/docs/content/docs/redis.cn.mdx b/docs/content/docs/redis.cn.mdx index 8fd141846f..494207ff12 100644 --- a/docs/content/docs/redis.cn.mdx +++ b/docs/content/docs/redis.cn.mdx @@ -1,88 +1,134 @@ --- -title: Redis 浏览器 -description: 浏览 Redis 键、查看和编辑值、按模式搜索、以及跨所有 Redis 数据类型执行命令。 +title: Redis 工作台 +description: 浏览、搜索和编辑 Redis Key，管理 TTL、Stream 消费组、Pub/Sub、Slowlog 和实例状态。 --- -DBX 提供完整的 Redis 键浏览器，支持所有核心 Redis 数据类型。它将浏览、编辑、搜索和命令执行整合到一个视图中，无需在 Redis CLI 和 GUI 之间切换。 +Redis 工作台把 Key 浏览、类型专属编辑、命令执行、实例观察和高风险命令保护放在一个连接中。它使用 `SCAN` 等增量方式处理键空间，避免把大型 Redis 实例一次性全部加载到界面。 -## 键浏览器 +## 数据库与别名 -Redis 键浏览器以表格形式展示键，便于扫描和过滤： +Redis 连接会列出可用的数字数据库。可以为 `db0`、`db1` 等设置本地别名，例如“订单缓存”或“开发环境”。别名只影响 DBX 显示和搜索，Redis 命令仍使用数字数据库编号。 -- 键列表支持分页，避免在大型键空间上阻塞 -- 点击任意键可在详情面板中查看其值 -- 使用搜索栏按模式过滤键（如 `user:*`、`cache:*`） -- 内联显示键类型、TTL 和大小 +扫描页大小保存在连接配置中。键很多或网络延迟较高时，减小页大小；需要更快浏览小实例时可以适当增大。 -对于包含数百万键的 Redis 实例，建议在搜索栏中使用具体的键模式，而不是加载整个键空间。可在设置中调整扫描页大小，以控制每批获取的键数量。 +## Key 浏览与搜索 -## 值查看器与编辑器 +Key 列表可以显示名称、类型、值摘要、大小和 TTL。支持： -每种 Redis 数据类型都有专用的查看器和编辑器： +- 按 Redis 模式搜索，例如 `user:*` +- 使用模糊搜索，把普通关键词转换成包含匹配 +- 在树形分组和扁平列表之间浏览 +- 加载更多、获取全部或停止长时间扫描 +- 复制 Key 名称、选择多个 Key 或选择当前已加载分组 +- 按 Key、值或 Key + 值搜索 -| 类型 | 查看器 | 编辑方式 | -| ---------- | ----------------------- | -------------------- | -| String | 纯文本或 JSON 查看器 | 内联文本编辑 | -| Hash | 可调整列宽的字段/值表格 | 编辑单个字段 | -| List | 带索引的有序列表 | 添加、删除、重排元素 | -| Set | 带基数的成员列表 | 添加和删除成员 | -| Sorted Set | 带分数的成员列表 | 编辑成员和分数 | -| Stream | 带 ID 的条目列表 | 查看流条目 | +值搜索会读取匹配 Key 的内容，并针对 String、Hash 等类型做对应匹配。Hash 详情还可以单独搜索字段和值。 -## JSON 值查看器 +“获取全部”和值搜索可能访问大量 Key。生产实例先使用具体模式缩小范围，并观察 Redis 延迟、CPU 和网络流量。 -对于包含有效 JSON 的 String 键，DBX 会自动渲染结构化 JSON 查看器，支持节点折叠、语法高亮和复制功能。 +## 数据类型 -## 值搜索 +| 类型 | 主要能力 | +| --- | --- | +| String | 文本、JSON、多种显示格式；二进制字符串以转义文本只读展示 | +| Hash | 字段/值表格、搜索、排序、添加、编辑和删除字段 | +| List | 分页元素、索引、添加、编辑和删除 | +| Set | 成员浏览、添加和删除 | +| Sorted Set | 成员与分数浏览、编辑和删除 | +| Stream | 条目浏览、消费组、消费者、Pending、Lag 和投递详情 | +| RedisJSON | JSON 树/源码编辑、格式化和压缩；需要服务端 RedisJSON 模块 | -按内容搜索 Redis 值，而不仅仅是键： +大型集合类型会分页加载。数量、已加载数量和继续加载入口会显示在详情中。 -- 扫描 String 值中的匹配文本 -- 按值查找 Hash 字段 -- 对于大型键空间，结果会逐步流式返回 +## 创建与编辑 Key -值搜索会扫描匹配当前模式的所有键。在大型数据库上这可能会消耗大量资源。在开始值搜索之前，请先缩小键模式范围。 +创建 Key 时选择数据类型并填写初始内容。可设置正整数 TTL；留空或按界面选择可创建永不过期 Key。 -## 批量操作 +编辑现有值时，DBX 支持： -一次性对多个键执行批量操作： +- 保留原 TTL +- 设为永不过期 +- 设置相对 TTL 秒数 +- 选择本地绝对过期时间 +- JSON 源码格式化或压缩后保存 +- 复制可重建当前值的插入命令（适用类型） -- 一次删除多个键 -- 查看键统计信息，包括内存使用和访问模式 +TTL 会自动倒计时，并可以在详情保持打开时定期刷新完整值。Key 在刷新前过期时，界面会提示并移除失效状态。 -## 命令执行器 +修改值时保留 TTL 可以避免把临时缓存意外变成永久 Key。保存前确认当前过期策略。 -直接从 UI 执行任意 Redis 命令： +## Stream 消费组 -- 以 Redis CLI 语法输入命令 -- 结果以结构化表格显示 -- 适用于 `INFO`、`CONFIG GET`、`CLIENT LIST` 等管理命令 -- **命令历史导航**：使用方向键（↑/↓）浏览之前执行过的命令 -- **文本选择和复制**：直接从终端中选择并复制命令输出 +Stream 详情除了条目，还可以查看： -命令历史按连接保存，帮助你快速重新运行常用命令而无需重新输入。 +- 消费组和最后投递 ID +- 已读取数量和 Lag +- 消费者、空闲时间和非活跃状态 +- Pending 条目、投递次数和归属消费者 -## 清空数据库 +这些数据来自 Redis 消费组命令，适合排查积压和未确认消息。它不是持续监控或告警系统。 -**Flush DB** 按钮会删除当前 Redis 数据库中的所有键。此操作不可撤销。清空前请确认活动连接和数据库编号。 +## 命令行 -## 键统计 +命令行接受 Redis CLI 风格命令并显示结构化结果： -在设置中启用键统计跟踪，以监控： +- 使用 ↑/↓ 浏览按连接保存的历史 +- 清除当前命令历史 +- 选择和复制文本结果 +- 执行 `INFO`、`CLIENT LIST`、`CONFIG GET` 等命令 +- 在支持的响应中查看表格或 JSON -- 每个键的内存使用量 -- 访问频率 -- 空闲时间 +工具栏的命令安全开关会分类 Redis 命令。部分危险命令需要确认，部分命令会默认阻止；关闭开关也不能绕过连接只读、生产保护或 MCP 策略。 -这些数据有助于识别可能需要关注的大键或不常用键。 +## Pub/Sub -## Slowlog 面板 +Pub/Sub 面板可以： -**Slowlog** 面板帮助识别慢速 Redis 命令： +- 连接或断开订阅会话 +- 订阅频道或模式 +- 实时查看收到的消息 +- 发布消息到指定频道 +- 清空当前界面消息记录 -- 查看最近的慢命令及其执行时间 -- 分析可能需要优化的查询模式 -- 用于性能调优和生产问题调试 -- 从 Redis 连接的工具菜单访问 slowlog +Web/Docker 模式通过 WebSocket 维持订阅。反向代理部署时，需要允许对应 WebSocket 升级。 -Slowlog 条目显示命令、执行时间和时间戳，帮助你识别 Redis 工作负载中的性能瓶颈。 +## Dashboard、Key 统计与 Slowlog + +Redis Dashboard 展示服务端和实例信息，并把指标按区域折叠。根据服务端能力可以查看： + +- 版本、运行时间、内存、客户端和连接状态 +- Keyspace、命令、持久化、复制和集群摘要 +- 每个 Key 的内存使用、空闲时间或访问相关统计 +- Slowlog 条目、耗时、时间戳和集群节点 + +Key 统计和 Slowlog 会额外调用 Redis 命令。大型实例或集群中应限制范围和条目数量。 + +## 批量与破坏性操作 + +- 删除选中的 Key +- 删除当前分组中已加载的 Key +- 清空当前 Redis DB +- 对支持的结构执行批量字段/成员操作 + +清空 DB、批量删除和 `FLUSH*` 无法撤销。只读连接会拒绝写入；生产环境保护和危险命令规则会继续生效。 + +## 安全与性能建议 + +- 生产 Redis 使用只读账号或 ACL，并在 DBX 启用只读/生产保护 +- 不要用 `KEYS *` 代替增量浏览；优先使用模式和 `SCAN` +- 值搜索、内存统计和 Slowlog 查询都可能增加服务端负载 +- Stream 消费组详情会读取 Pending 和消费者状态，避免高频无限刷新 +- 二进制值、模块命令和厂商扩展可能只能通过命令行查看 +- MCP 暴露 Redis 时，普通写入和 `FLUSH*` 由不同权限级别控制 + + + + 配置只读连接、生产保护和 MCP Redis 命令权限。 + + + 查看 MongoDB、向量、消息队列、etcd、ZooKeeper 和 Nacos。 + + + 为 Redis 配置 TLS、SSH、SOCKS5 或 HTTP 代理。 + + diff --git a/docs/content/docs/redis.mdx b/docs/content/docs/redis.mdx index d1c1e610ba..1a29883a1b 100644 --- a/docs/content/docs/redis.mdx +++ b/docs/content/docs/redis.mdx @@ -1,88 +1,134 @@ --- -title: Redis Browser -description: Browse Redis keys, view and edit values, search by pattern, and run commands across all Redis data types. +title: Redis Workspace +description: Browse, search, and edit Redis keys and inspect TTLs, Stream consumer groups, Pub/Sub, Slowlog, and instance status. --- -DBX provides a full Redis key browser with support for all core Redis data types. It replaces the need to switch between a Redis CLI and a GUI by combining browsing, editing, searching, and command execution in one view. +The Redis workspace combines key browsing, type-specific editing, command execution, instance inspection, and high-risk command protection in one connection. It uses incremental operations such as `SCAN` instead of loading an entire large keyspace at once. -## Key Browser +## Databases and Aliases -The Redis key browser displays keys in a table format for easier scanning and filtering: +Redis connections list available numeric databases. You can assign local aliases to `db0`, `db1`, and others, such as “Order cache” or “Development.” Aliases affect DBX display and search only; Redis commands still use numeric database IDs. -- Keys are paginated to avoid blocking on large keyspaces -- Click any key to open its value in the detail panel -- Use the search bar to filter keys by pattern (e.g., `user:*`, `cache:*`) -- Key type, TTL, and size are shown inline +The scan page size is stored per connection. Reduce it for very large keyspaces or high-latency networks, and increase it carefully for small instances. -For Redis instances with millions of keys, use specific key patterns in the search bar instead of loading the entire keyspace. Set the scan page size in Settings to control how many keys are fetched per batch. +## Key Browsing and Search -## Value Viewer and Editor +The key list can show name, type, value summary, size, and TTL. It supports: -Each Redis data type has a dedicated viewer and editor: +- Redis patterns such as `user:*` +- Fuzzy search that turns a normal keyword into a contains match +- Hierarchical grouping and flat-list browsing +- Load more, fetch all, and stopping a long scan +- Copying key names, selecting multiple keys, or selecting a loaded group +- Searching by key, value, or both key and value -| Type | Viewer | Editing | -| ---------- | ---------------------------------------- | ----------------------------- | -| String | Plain text or JSON viewer | Inline text edit | -| Hash | Field/value table with resizable columns | Edit individual fields | -| List | Ordered list with index | Add, remove, reorder elements | -| Set | Member list with cardinality | Add and remove members | -| Sorted Set | Member list with scores | Edit members and scores | -| Stream | Entry list with IDs | View stream entries | +Value search reads matching content and applies type-aware matching for String, Hash, and other supported structures. Hash details can also search fields and values directly. -## JSON Value Viewer +Fetch all and value search can touch many keys. In production, narrow the pattern first and monitor Redis latency, CPU, and network traffic. -For String keys that contain valid JSON, DBX automatically renders a structured JSON viewer with collapsible nodes, syntax highlighting, and copy support. +## Data Types -## Value Search +| Type | Main capabilities | +| --- | --- | +| String | Text, JSON, and multiple display formats; binary strings are shown as escaped read-only text | +| Hash | Field/value table, search, sorting, add, edit, and delete | +| List | Paged elements with index, add, edit, and delete | +| Set | Member browsing, add, and delete | +| Sorted Set | Member and score browsing, editing, and deletion | +| Stream | Entries, consumer groups, consumers, pending messages, lag, and delivery details | +| RedisJSON | JSON tree/source editing, formatting, and compact saves; requires the RedisJSON server module | -Search Redis values by content, not just keys: +Large collection types load in pages and display total and loaded counts where available. -- Scan String values for matching text -- Find Hash fields by value -- Results are streamed progressively for large keyspaces +## Create and Edit Keys -Value search scans all keys that match the current pattern. On large databases this can be resource-intensive. Narrow the key pattern before starting a value search. +Choose a data type and initial content when creating a key. Set a positive TTL or choose a persistent key. -## Bulk Operations +When editing an existing value, DBX can: -Perform batch actions on multiple keys at once: +- Preserve the existing TTL +- Make the key persistent +- Set a relative TTL in seconds +- Choose a local absolute expiration time +- Format or compact JSON source before saving +- Copy a reconstruction command for supported value types -- Delete multiple keys in one operation -- View key statistics including memory usage and access patterns +TTL values count down automatically, and the detail view can periodically refresh the complete value. If a key expires before refresh, DBX reports and clears the stale state. -## Command Runner +Preserving TTL while changing a value prevents a temporary cache entry from becoming permanent accidentally. Review expiration behavior before saving. -Execute arbitrary Redis commands directly from the UI: +## Stream Consumer Groups -- Type commands in Redis CLI syntax -- Results are displayed in a structured table -- Useful for `INFO`, `CONFIG GET`, `CLIENT LIST`, and other admin commands -- **Command history navigation**: Use arrow keys (↑/↓) to navigate through previously executed commands -- **Text selection and copy**: Select and copy command output directly from the terminal +Stream details can also show: -The command history is preserved per connection and helps you quickly rerun frequently used commands without retyping them. +- Consumer groups and last-delivered ID +- Entries read and lag +- Consumers, idle time, and inactive state +- Pending entries, delivery count, and owning consumer -## Flush Database +These values come from Redis consumer-group commands and help troubleshoot backlog or unacknowledged messages. They are not a continuous monitoring or alerting system. -The **Flush DB** button removes all keys from the current Redis database. This action cannot be undone. Confirm the active connection and database number before flushing. +## Command Line -## Key Statistics +The command line accepts Redis CLI-style commands and renders structured results: -Enable key statistics tracking in Settings to monitor: +- Use ↑/↓ to navigate history saved per connection +- Clear the current command history +- Select and copy text output +- Run commands such as `INFO`, `CLIENT LIST`, and `CONFIG GET` +- View table or JSON output where the response supports it -- Memory usage per key -- Access frequency -- Idle time +The command-safety control classifies Redis commands. Some risky commands require confirmation and some are blocked by default. Disabling that control cannot bypass connection read-only state, production protection, or MCP policy. -This data helps identify large or infrequently used keys that may need attention. +## Pub/Sub -## Slowlog Panel +The Pub/Sub panel can: -The **Slowlog** panel helps identify slow Redis commands: +- Connect or disconnect a subscription session +- Subscribe to channels or patterns +- Display incoming messages in real time +- Publish a message to a channel +- Clear messages from the current UI session -- View recent slow commands with execution time -- Analyze query patterns that may need optimization -- Useful for performance tuning and debugging production issues -- Access slowlog from the Redis connection's tools menu +Web/Docker uses WebSocket for the subscription. Reverse proxies must allow the related WebSocket upgrade. -Slowlog entries show the command, execution time, and timestamp, helping you identify performance bottlenecks in your Redis workload. +## Dashboard, Key Statistics, and Slowlog + +The Redis dashboard groups server and instance information into collapsible areas. Depending on server support, it can show: + +- Version, uptime, memory, clients, and connection state +- Keyspace, commands, persistence, replication, and cluster summaries +- Per-key memory usage, idle time, or access-related statistics +- Slowlog entries, duration, timestamp, and cluster node + +Key statistics and Slowlog require additional Redis commands. Limit scope and entry counts on large instances or clusters. + +## Bulk and Destructive Operations + +- Delete selected keys +- Delete keys loaded under the current group +- Flush the active Redis database +- Run supported bulk field/member operations + +Flush, bulk delete, and `FLUSH*` operations cannot be undone. Read-only connections reject writes, while production and dangerous-command checks remain active. + +## Safety and Performance Guidance + +- Use a read-only account or ACL for production and enable DBX read-only/production protection +- Do not replace incremental browsing with `KEYS *`; prefer patterns and `SCAN` +- Value search, memory statistics, and Slowlog can increase server load +- Stream consumer-group details read pending and consumer state; avoid unbounded high-frequency refresh +- Binary values, module commands, and vendor extensions may require the command line +- MCP applies different permission levels to ordinary Redis writes and destructive `FLUSH*` commands + + + + Configure read-only connections, production protection, and MCP Redis permissions. + + + Review MongoDB, vector, message queue, etcd, ZooKeeper, and Nacos tools. + + + Configure TLS, SSH, SOCKS5, or HTTP proxying for Redis. + + diff --git a/docs/content/docs/schema-browser.cn.mdx b/docs/content/docs/schema-browser.cn.mdx index 5c126802d3..bd902266ba 100644 --- a/docs/content/docs/schema-browser.cn.mdx +++ b/docs/content/docs/schema-browser.cn.mdx @@ -1,102 +1,153 @@ --- -title: 结构浏览 -description: 使用侧边栏浏览连接、数据库、Schema、表、字段和 Redis 键空间。 +title: 结构浏览与对象树 +description: 使用 DBX 侧边栏组织连接、搜索数据库对象、打开数据与结构，并执行数据库专属操作。 --- -结构浏览器是 DBX 的左侧工作区，用于理解当前连接里有哪些数据库对象，并快速打开表数据、表结构或上下文操作。 +对象树是 DBX 的主要导航入口。它不仅展示数据库、Schema、表和字段，还负责连接分组、可见范围、对象搜索、固定、复制粘贴、结构操作、专项工作台和管理视图。 -## 层级结构 +## 连接与对象层级 -侧边栏按数据库对象层级组织： +典型关系型结构如下： ```text -连接 - └── 数据库 - └── Schema - └── 表 / 视图 - └── 字段（类型、约束、默认值） +连接分组 + └── 连接 + └── Catalog / 数据库 + └── Schema + └── 表 / 视图 / 例程 / 其他对象 + └── 字段 / 索引 / 外键 / 触发器 ``` -点击节点可以展开或折叠；点击表名可以打开数据浏览；字段节点会展示类型、约束和默认值等信息。 +实际层级由数据库模型决定： -## 不同数据库的树结构 +| 类型 | 树结构示例 | +| --- | --- | +| MySQL 兼容 | 连接 → 数据库 → 表/视图 → 字段/索引/外键/触发器 | +| PostgreSQL、Oracle、SQL Server 等 | 连接 → 数据库或服务 → Schema → 对象 | +| Doris / StarRocks | 可在多 Catalog 时显示 Catalog → 数据库 → 表；只有 `internal` 时保持扁平 | +| Redis | 连接 → Redis DB；Key 在专用浏览器中分页展示 | +| MongoDB | 连接 → 数据库 → 集合、索引和 GridFS Bucket | +| Elasticsearch / Easysearch | 连接 → 索引等文档对象 | +| HBase、向量、消息队列、etcd、ZooKeeper、Nacos | 展示系统对应对象，并打开 [专项工作台](/cn/docs/specialized-workspaces) | -| 连接类型 | 浏览模型 | -| ------------ | ------------------------------------------------------------------------------- | -| 关系型数据库 | 连接、数据库、Schema、表/视图、字段、索引、外键、触发器，以及可获取元数据的例程 | -| Redis | Redis 数据库和键，并为 String、Hash、List、Set、Sorted Set、Stream 提供值编辑 | -| MongoDB | 数据库、集合和分页文档浏览 | -| 对象浏览器 | 在数据库支持时查看视图、存储过程和函数源码 | -| 保存的 SQL | 侧边栏中的 SQL 文件夹和可复用 SQL 文件 | +## 连接分组与批量管理 -## 搜索 +- 创建嵌套分组和自定义子组名称 +- 把连接拖入分组，或使用复制/粘贴和批量移动 +- 多选连接后使用工具栏执行分组、复制、断开或其他批量操作 +- 为连接设置颜色、备注、置顶、只读和生产环境范围 +- 复制连接名称或复制整个连接配置作为新连接 +- 在连接提示中查看主机、端口、数据库类型和其他摘要 -侧边栏搜索用于在对象数量较多时快速定位： +导入连接时，支持的来源可以保留分组信息。跨设备迁移侧边栏布局时，DBX 会重新映射连接 ID。 -- 表名 -- 视图名 -- 字段名 -- 部分数据库对象路径 +## 展开、折叠与固定 -当连接中有大量表时，搜索会优先面向可见对象和缓存的元数据工作。刚刷新或首次展开的对象，可能需要等待元数据加载完成后才能完整匹配。 +- 单击节点展开或折叠 +- 使用**展开全部**或**折叠全部**处理当前树范围 +- 固定常用连接、数据库、Schema、表或 Nacos Namespace +- 长列表滚动时，当前数据库或关键行可以保持可见 +- 打开的标签页会反向选中或定位对应对象 -## 置顶 +固定用于提高访问效率，不代表生产保护。生产连接应单独启用 [生产环境与写入安全](/cn/docs/production-safety) 中的只读和生产标记。 -把常用连接、数据库或表置顶后，可以减少在深层树结构中反复展开的操作。置顶适合这些对象： +## 搜索与过滤 -- 高频查询表 -- 当前迭代相关表 -- 生产环境中需要重点区分的连接 -- 排查问题时反复查看的对象 +对象树搜索可以匹配： -## 右键菜单 +- 连接、分组、数据库、Catalog 和 Schema +- 表、视图、字段、索引和部分数据库专属对象 +- 对象路径、字段注释和表注释 +- 已加载元数据和支持服务端过滤的表列表 -不同节点会显示不同的上下文操作： +部分搜索会把关键词传给驱动并延迟请求，避免先加载全部表。也可以按节点类型缩小搜索范围，或在当前数据库中使用本地表搜索。 -| 节点 | 常用操作 | -| ------ | ---------------------------------------------- | -| 连接 | 刷新元数据、复制连接、断开连接、编辑连接 | -| 数据库 | 创建数据库、删除数据库、导出数据库 | -| Schema | 创建 Schema、删除 Schema | -| 表 | 打开数据、查看结构、导入数据、复制表名、删除表 | -| 字段 | 复制字段名、查看字段信息 | +可见范围设置可以隐藏不需要的数据库、Schema、系统 Schema 或带特定前缀的表。新增数据库或 Schema 后，可以按设置自动加入可见列表。 -删除数据库、删除 Schema、删除表等操作可能不可恢复。执行前请确认当前连接环境，必要时先备份。 +搜索结果依赖当前账号可见权限和已加载元数据。刚创建、删除或重命名对象后，刷新对应节点再搜索。 -## 字段注释 +## 元数据显示 -如果数据库支持字段注释，DBX 会在字段旁展示注释内容。对于接手陌生库或阅读历史表结构，这通常比只看字段名更有帮助。 +根据数据库和设置，对象树可以显示： -## 连接颜色 +- 表和字段注释 +- 字段类型、可空、默认值和约束摘要 +- 对象数量或加载状态 +- 表类型、Catalog、Schema 和数据库路径 +- MongoDB Collection 元数据 +- 数据库专属对象类型和状态 -可以给连接设置颜色，用于区分环境。例如： +对象元数据显示方式可以在设置中调整。大型 Schema 建议只展示真正需要的附加信息，减少视觉噪声和元数据请求。 -| 环境 | 建议颜色 | -| ---- | ---------- | -| 本地 | 灰色或绿色 | -| 测试 | 蓝色或紫色 | -| 预发 | 黄色 | -| 生产 | 红色 | +## 打开数据、结构与源码 -颜色会出现在侧边栏连接名称和标签页中，帮助减少误操作。 +| 操作 | 结果 | +| --- | --- | +| 打开表 | 进入 [数据表格](/cn/docs/data-grid) | +| 查看结构 | 打开字段、索引、外键、触发器和 DDL 标签 | +| 编辑表结构 | 进入 [表结构编辑器](/cn/docs/table-structure) | +| 查看 DDL | 读取数据库生成或驱动生成的对象定义 | +| 打开源码 | 在侧边面板或编辑器查看视图、过程、函数、触发器等源码 | +| 定位查询对象 | 从编辑器光标定位当前表，或从对象树拖字段/表引用到 SQL 编辑器 | +| 打开专项对象 | 进入 Redis、MongoDB、向量、HBase、MQ、etcd、ZooKeeper 或 Nacos 工作台 | -## Redis 浏览器 +表、对象和数据标签使用不同身份，避免同名对象与表数据标签错误复用。 -Redis 连接会使用更适合键值数据的浏览方式： +## 右键菜单与批量操作 -- 键以表格方式展示，便于扫描 -- 支持分页浏览，避免一次性加载大量键 -- 可直接查看和编辑键值 -- 支持 String、Hash、List、Set、Sorted Set 和 Stream +上下文菜单按节点类型和数据库 capability 动态生成。常见操作包括： -Redis 键空间较大时，建议配合搜索和分页使用，避免一次性展开过多数据。 +- 创建、重命名、删除数据库或 Schema，并编辑支持的注释、字符集和排序规则 +- 创建、复制、粘贴、重命名、清空或删除表 +- 跨数据库复制/粘贴表数据或表结构（目标驱动支持时） +- 打开数据、结构、DDL、源码、ER 图、字段血缘、Schema 对比和数据库搜索 +- 导入数据、传输数据、执行 SQL 文件、导出数据库或备份支持的文件型数据库 +- 生成 `SELECT`、`INSERT`、`UPDATE`、`DELETE` 或其他模板 SQL +- 管理索引、触发器、例程、扩展、用户、任务和数据库专属对象 +- 打开 Dashboard、进程/会话或专项管理页面 -## 功能边界 +破坏性操作会整理到更明确的菜单层级，并按只读、生产环境和数据库能力决定是否显示或要求确认。 -| 功能 | 支持类型 | -| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Schema 感知树 | PostgreSQL、SQL Server、Oracle、Redshift、DM、GaussDB、KingBase、HighGo、Vastbase、JDBC、H2、Snowflake、Trino、DB2、TDengine | -| ER 图 | MySQL、PostgreSQL、SQLite、SQL Server、Oracle、Redshift、DM、GaussDB、KingBase、HighGo、Vastbase、GoldenDB、Access、H2、DB2 | -| 数据库搜索 | MySQL、PostgreSQL、SQLite、SQL Server、Oracle、Redshift、DuckDB、ClickHouse、DM、GaussDB、KingBase、HighGo、Vastbase、GoldenDB、Access、H2、Snowflake、Trino、Hive、DB2、Informix、Neo4j、Cassandra、BigQuery、Kylin、SunDB、TDengine | +## 复制、粘贴与拖拽 -如果某个节点菜单里没有对应操作，通常说明当前数据库类型没有暴露所需元数据，或 DBX 没有足够把握生成安全 SQL。 +- 复制连接、数据库、Schema、表、字段或所选表名 +- 选择是否带数据库/Schema 限定和标识符引号 +- 把表或字段拖入 SQL 编辑器生成引用 +- 复制表后在兼容目标数据库中粘贴，实现表结构或数据传输入口 +- 本地文件数据库可以从对象树在系统文件管理器中显示文件 + +跨数据库复制涉及类型映射、默认值、约束和自增语义。执行前查看 [数据传输](/cn/docs/data-transfer) 和生成 SQL。 + +## 数据库专属层级 + +DBX 不会把所有系统强制映射成关系型树。例如： + +- SQL Server 可以浏览 Linked Server 和数据库对象 +- Doris / StarRocks 支持外部 Catalog，外部 Catalog 表使用三段式名称 +- MongoDB 展示 Collection、索引和 GridFS +- Elasticsearch / Easysearch 将索引作为一等对象 +- 达梦、Oracle、PostgreSQL 等可以展示更多例程、任务、扩展或管理对象 +- etcd、Nacos、消息队列和向量数据库从树节点进入专用工作台 + +## 安全与性能边界 + +- 对象树只展示当前账号有权限读取的对象；看不到对象时先检查数据库权限 +- 大型 Schema 使用按需加载、缓存和服务端过滤，不建议无目的展开全部节点 +- 系统 Schema、对象数量和额外元数据会增加请求量，可以在设置中关闭 +- 删除、清空、跨库粘贴和管理操作可能不可恢复，生产环境先确认备份和影响范围 +- 只读连接会隐藏或拒绝多个修改入口，但数据库账号权限仍是最终边界 + + + + 使用列表或网格集中查看表、视图、例程和统计信息。 + + + 修改字段和索引，并在执行前检查 DDL。 + + + 在大型数据库中按对象类型、名称和元数据定位对象。 + + + 查看 Redis、MongoDB、向量、MQ、etcd、ZooKeeper 和 Nacos 入口。 + + diff --git a/docs/content/docs/schema-browser.mdx b/docs/content/docs/schema-browser.mdx index 4b85d741ce..062ff47347 100644 --- a/docs/content/docs/schema-browser.mdx +++ b/docs/content/docs/schema-browser.mdx @@ -1,102 +1,153 @@ --- -title: Schema Browser -description: Browse connections, databases, schemas, tables, columns, and Redis keyspaces from the sidebar. +title: Schema Browser and Object Tree +description: Organize connections, search database objects, open data and structure, and run database-specific actions from the DBX sidebar. --- -The schema browser is the left-side workspace in DBX. Use it to understand what exists in a connection and to open data, inspect structure, or run context-specific actions. +The object tree is the main navigation surface in DBX. It displays more than databases, schemas, tables, and columns: it also manages connection groups, visible scope, object search, pins, copy/paste, schema actions, specialized workspaces, and administration views. -## Object Hierarchy +## Connection and Object Hierarchy -The sidebar organizes objects by database hierarchy: +A typical relational hierarchy looks like this: ```text -Connection - └── Database - └── Schema - └── Tables / Views - └── Columns (type, constraints, defaults) +Connection group + └── Connection + └── Catalog / database + └── Schema + └── Table / view / routine / other object + └── Column / index / foreign key / trigger ``` -Expand or collapse nodes to drill down. Click a table to open its data. Column entries show type, constraints, defaults, and related attributes when available. +The actual hierarchy follows the database model: -## Database-Specific Trees +| Type | Example tree | +| --- | --- | +| MySQL-compatible | Connection → database → table/view → column/index/foreign key/trigger | +| PostgreSQL, Oracle, SQL Server, and others | Connection → database or service → schema → object | +| Doris / StarRocks | Catalog → database → table when multiple catalogs exist; flat when only `internal` exists | +| Redis | Connection → Redis DB, with paged keys in the dedicated browser | +| MongoDB | Connection → database → collections, indexes, and GridFS buckets | +| Elasticsearch / Easysearch | Connection → indexes and other document objects | +| HBase, vector, message queue, etcd, ZooKeeper, Nacos | System-specific objects that open [Specialized Workspaces](/en/docs/specialized-workspaces) | -| Connection Type | Browser Model | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -| Relational databases | Connection, database, schema, tables/views, columns, indexes, foreign keys, triggers, and routines where metadata is available | -| Redis | Redis databases and keys, with value editors for String, Hash, List, Set, Sorted Set, and Stream | -| MongoDB | Databases, collections, and paginated document browsing | -| Object browser | Views, procedures, and functions when the database exposes source metadata | -| Saved SQL | Folders and reusable SQL files in the sidebar library | +## Connection Groups and Bulk Management -## Search +- Create nested groups with custom subgroup names +- Drag connections into groups or use copy/paste and bulk movement +- Multi-select connections and use the toolbar for grouping, copying, disconnecting, and other batch actions +- Configure connection colors, notes, pins, read-only state, and production scope +- Copy a connection name or duplicate the full connection as a new entry +- Inspect host, port, database type, and other summaries in connection tooltips -Sidebar search helps locate objects when a connection contains many tables: +Supported connection imports can retain group information. When sidebar layouts move between devices, DBX remaps connection IDs. -- Table names -- View names -- Column names -- Parts of database object paths +## Expand, Collapse, and Pin -For large schemas, search works best with visible objects and cached metadata. Objects that were just refreshed or not yet expanded may need metadata loading before they are fully matched. +- Click a node to expand or collapse it +- Use **Expand all** or **Collapse all** for the current tree scope +- Pin frequent connections, databases, schemas, tables, or Nacos namespaces +- Keep the active database or important row visible while scrolling long lists +- Let open tabs select or reveal the related tree object -## Pinning +Pins improve navigation but do not mark production. Configure read-only and production state separately under [Production and Write Safety](/en/docs/production-safety). -Pin frequently used connections, databases, or tables to reduce repeated navigation through deep trees. Pinning is useful for: +## Search and Filtering -- High-frequency query tables -- Objects related to the current iteration -- Production connections that should stand out -- Tables repeatedly checked during debugging +Object-tree search can match: -## Context Menus +- Connections, groups, databases, catalogs, and schemas +- Tables, views, columns, indexes, and selected database-specific objects +- Object paths, column comments, and table comments +- Loaded metadata and table lists that support server-side filtering -Different node types expose different actions: +Some searches pass the keyword to the driver with debouncing, avoiding a full table load first. You can also restrict search by node type or use local table search inside the active database. -| Node | Common Actions | -| ---------- | ------------------------------------------------------------------- | -| Connection | Refresh metadata, duplicate connection, disconnect, edit connection | -| Database | Create database, drop database, export database | -| Schema | Create schema, drop schema | -| Table | Open data, open structure, import data, copy table name, drop table | -| Column | Copy column name, inspect column details | +Visible-scope settings can hide databases, schemas, system schemas, or tables with configured prefixes. Newly created databases or schemas can be added to the visible list automatically. -Dropping databases, schemas, or tables may be irreversible. Confirm the active connection and back up data when needed. +Search results depend on account visibility and loaded metadata. Refresh the related node after creating, deleting, or renaming an object. -## Column Comments +## Metadata Display -When the database supports column comments, DBX displays them next to columns. This is especially helpful when you are reading an unfamiliar schema or legacy database. +Depending on database and settings, the tree can show: -## Connection Colors +- Table and column comments +- Column type, nullability, default, and constraint summaries +- Object counts and loading state +- Table type plus catalog, schema, and database path +- MongoDB collection metadata +- Database-specific object types and status -Connection colors help separate environments: +Object metadata display is configurable. In large schemas, show only the extra information you need to reduce visual noise and metadata requests. -| Environment | Suggested Color | -| ----------- | --------------- | -| Local | Gray or green | -| Test | Blue or purple | -| Staging | Yellow | -| Production | Red | +## Open Data, Structure, and Source -Colors appear beside connection names in the sidebar and in tabs, reducing the chance of operating on the wrong environment. +| Action | Result | +| --- | --- | +| Open table | Opens the [Data Grid](/en/docs/data-grid) | +| View structure | Opens columns, indexes, foreign keys, triggers, and DDL tabs | +| Edit table structure | Opens the [Table Structure Editor](/en/docs/table-structure) | +| View DDL | Reads database- or driver-generated object definition | +| Open source | Shows view, procedure, function, trigger, or other source in a side panel or editor | +| Locate query object | Finds the table at the editor cursor or drags table/column references into SQL | +| Open specialized object | Opens Redis, MongoDB, vector, HBase, MQ, etcd, ZooKeeper, or Nacos workspaces | -## Redis Browser +Table, object, and data tabs use distinct identities so same-named objects do not incorrectly reuse a data tab. -Redis connections use a browser designed for key-value data: +## Context Menus and Batch Actions -- Keys are displayed in a table for easier scanning -- Pagination avoids loading large keyspaces at once -- Values can be viewed and edited directly -- String, Hash, List, Set, Sorted Set, and Stream are supported +Context menus are generated from node type and database capabilities. Common actions include: -For large Redis keyspaces, use search and pagination together instead of expanding too much data at once. +- Create, rename, or delete databases and schemas and edit supported comments, charsets, or collations +- Create, copy, paste, rename, truncate, or drop tables +- Copy/paste table structure or data across databases when the target driver supports it +- Open data, structure, DDL, source, ER diagram, field lineage, schema diff, and database search +- Import data, transfer data, execute SQL files, export databases, or back up supported file databases +- Generate `SELECT`, `INSERT`, `UPDATE`, `DELETE`, and other SQL templates +- Manage indexes, triggers, routines, extensions, users, jobs, and database-specific objects +- Open dashboards, processes/sessions, or specialized administration pages -## Feature Boundaries +Destructive actions are grouped more explicitly and appear or require confirmation based on read-only state, production scope, and database capability. -| Feature | Supported Types | -| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Schema-aware tree | PostgreSQL, SQL Server, Oracle, Redshift, DM, GaussDB, KingBase, HighGo, Vastbase, JDBC, H2, Snowflake, Trino, DB2, TDengine | -| ER diagram | MySQL, PostgreSQL, SQLite, SQL Server, Oracle, Redshift, DM, GaussDB, KingBase, HighGo, Vastbase, GoldenDB, Access, H2, DB2 | -| Database search | MySQL, PostgreSQL, SQLite, SQL Server, Oracle, Redshift, DuckDB, ClickHouse, DM, GaussDB, KingBase, HighGo, Vastbase, GoldenDB, Access, H2, Snowflake, Trino, Hive, DB2, Informix, Neo4j, Cassandra, BigQuery, Kylin, SunDB, TDengine | +## Copy, Paste, and Drag -If an action is missing from a node menu, the active database type may not expose the required metadata or safe SQL generation path. +- Copy connection, database, schema, table, column, or selected table names +- Choose database/schema qualification and identifier quoting where supported +- Drag tables or columns into the SQL editor to generate references +- Copy a table and paste into a compatible target to start structure or data transfer +- Reveal local file databases in the operating-system file manager + +Cross-database copying involves type mapping, defaults, constraints, and identity semantics. Review [Data Transfer](/en/docs/data-transfer) and generated SQL first. + +## Database-Specific Hierarchies + +DBX does not force every system into a relational tree. For example: + +- SQL Server can expose linked servers and database objects +- Doris / StarRocks support external catalogs and three-part names for external tables +- MongoDB exposes collections, indexes, and GridFS +- Elasticsearch / Easysearch model indexes as first-class objects +- Dameng, Oracle, PostgreSQL, and others can expose routines, jobs, extensions, or administration objects +- etcd, Nacos, message queues, and vector databases open dedicated workspaces from tree nodes + +## Safety and Performance Boundaries + +- The tree shows only objects visible to the current account; missing objects often indicate database permissions +- Large schemas use lazy loading, caching, and server-side filtering; avoid expanding everything without a purpose +- System schemas, object counts, and extra metadata increase request volume and can be disabled +- Drop, truncate, cross-database paste, and administration actions may be irreversible; review backups and scope first +- Read-only connections hide or reject multiple mutation entry points, but database privileges remain the final boundary + + + + Use list or grid views for tables, views, routines, and statistics. + + + Change columns and indexes and review DDL before execution. + + + Locate objects by type, name, and metadata in large databases. + + + Open Redis, MongoDB, vector, MQ, etcd, ZooKeeper, and Nacos workspaces. + + diff --git a/docs/content/docs/schema-diff.cn.mdx b/docs/content/docs/schema-diff.cn.mdx index f7f0d5ea90..b0e306a422 100644 --- a/docs/content/docs/schema-diff.cn.mdx +++ b/docs/content/docs/schema-diff.cn.mdx @@ -1,89 +1,211 @@ --- -title: Schema 对比 -description: 对比两个数据库的结构差异，生成可审查的同步 SQL。 +title: Schema 与数据对比 +description: 对比数据库结构或表数据，审查差异、类型映射、影响范围和同步 SQL，再部署到目标环境。 --- -Schema 对比用于检查两个数据库环境之间的结构差异，例如开发库和生产库、测试库和预发库，或迁移前后的数据库。 +DBX 提供两类对比工作流： -Schema 同步可能包含删除表、删除字段、修改字段类型等破坏性操作。生成 SQL 后请逐条审查，生产环境建议先备份。 +- **Schema 对比**比较对象结构和 DDL，生成从源环境部署到目标环境的脚本 +- **数据对比**按关键字段比较一张或多张表的行，生成可选择的插入、更新和删除同步 SQL -## 适合的场景 +两者都遵循“源端作为期望状态，目标端作为待检查/同步状态”的方向。选择反了会生成相反的操作。 -- 检查开发环境中的结构变更是否已经同步到生产 -- 对齐 staging、QA、production 等多套环境 -- 生成迁移脚本，交给团队审查后执行 -- 对比两个版本数据库之间的表、字段、索引差异 +对比结果和生成 SQL 都需要人工审查。删除对象、删除行、字段类型转换、跨方言映射和批量同步可能不可逆，生产环境先备份并准备回滚方案。 -## 使用流程 +## Schema 对比流程 - ### 选择源库 + ### 选择或创建配置 - 源库通常是你认为“结构较新”或“结构正确”的数据库。 + 选择最近配置，或新建、重命名、复制一个对比配置。配置可以导入/导出 JSON，便于复用源/目标和比较选项。 - ### 选择目标库 + ### 选择源与目标 - 目标库是需要被检查或同步的数据库。它可以和源库位于不同服务器，也可以是不同数据库引擎。 + 分别选择连接、数据库和 Schema。可以交换源/目标，但交换后必须重新检查部署方向。 - ### 执行对比 + ### 配置比较范围 - DBX 会读取两边的表、字段和索引元数据，并计算差异。当前对比只处理表，不包含视图。 + 选择表、主键、外键、唯一键、Check、视图、函数、索引、序列、触发器、Rule、Owner 等对象。实际选项按数据库类型显示。 - ### 审查差异 + ### 比较并筛选对象 - 重点检查缺失表、额外表、字段类型变化、是否允许 NULL、默认值变化、索引增删和可能的数据风险。 + DBX 读取两端元数据和 DDL，构建对象树，标记新增、删除、修改和依赖关系。选择真正需要部署的对象。 - ### 生成同步 SQL + ### 审查 DDL 与影响 - 根据差异生成 `CREATE TABLE`、`ALTER TABLE`、`DROP TABLE` 等语句。确认后再决定是否执行。 + 查看源/目标 DDL、字段映射、部署脚本、依赖、潜在冲突和影响报告。 + + + + ### 导出或部署 + + 复制/导出 `.sql`，或在最终确认后部署到目标数据库。支持时可以在事务中执行，并查看语句级进度与结果。 -## 差异类型 +## Schema 差异类型 -| 类型 | 含义 | -| ------------ | -------------------------------------------- | -| 仅源库存在 | 目标库缺少该对象，通常需要创建 | -| 仅目标库存在 | 目标库多出该对象，删除前需要确认是否仍被使用 | -| 字段差异 | 字段类型、是否允许 NULL 或默认值不同 | -| 索引差异 | 按索引名称检查新增或删除的索引 | +| 状态 | 含义 | 典型脚本 | +| --- | --- | --- | +| 源端新增 | 目标缺少对象 | `CREATE`、添加字段/索引/约束 | +| 目标多余 | 源端没有对象 | `DROP` 或删除字段/索引/约束 | +| 对象修改 | 两端定义不同 | `ALTER`、重建、替换源码 | +| 重命名候选 | 名称不同但结构相似 | 根据阈值建议重命名，需要人工确认 | +| 兼容性冲突 | 源类型或特性不能直接映射到目标 | 字段映射、降级或手写迁移 | -当前 Schema 对比不完整覆盖外键、触发器、视图定义、字段注释，也不会检测同名索引的列或唯一性变化。重要迁移仍建议人工审查生成的 SQL。 +对象树可以按操作类型筛选和选择。删除对象不会因为“目标多余”就自动执行，仍需要用户选择和最终确认。 -## 数据库覆盖范围 +## 比较选项 -Schema 对比依赖表、字段和索引元数据。它更适合 MySQL、PostgreSQL、SQLite、SQL Server、Oracle、Redshift、DM、GaussDB 系等可以稳定读取关系结构的数据库。Redis、MongoDB、Elasticsearch、Easysearch 的数据模型不同，不适合作为关系型 Schema 同步目标。 +### 对象范围 -## 执行前检查 +不同数据库可以比较： -同步前建议确认： +- 表、字段、列顺序和主键 +- 唯一键、外键、Check 和排除约束 +- 索引、视图、函数、序列、触发器和 Rule +- Owner 和序列当前值 -- 当前连接颜色和环境名称是否正确 -- 目标库是否已经备份 -- `DROP`、`TRUNCATE`、字段类型变更是否符合预期 -- 是否需要在业务低峰期执行 -- 是否需要先在测试环境验证生成的 SQL +选项按方言默认值加载。没有可靠元数据或同步 SQL 的对象会隐藏或只显示差异。 -## 相关功能 +### 表过滤 + +- 包含和排除模式 +- 包含/排除冲突时的优先级 +- 批次模式和表名模式 +- 是否显示系统对象 + +过滤用于控制比较范围，不等于数据库权限。当前账号无法读取的对象不会出现在结果中。 + +### 重命名检测 + +可以启用字段或表重命名检测，并设置相似度阈值。重命名建议基于结构相似度，不知道业务语义；确认前检查数据、约束、应用代码和依赖对象。 + +### 跨方言与字段映射 + +源/目标数据库类型不同时，可以指定源方言、目标方言、兼容阈值和字段类型映射： + +- 保留参数，例如 `VARCHAR(255)` 的长度 +- 去掉不兼容参数 +- 使用自定义目标参数 + +跨引擎对比只能生成“尽可能兼容”的脚本。字符集、排序规则、自增、序列、分区、存储引擎、函数和权限往往需要人工迁移设计。 + +## DDL、依赖与部署审核 + +选择对象后可以查看： + +- 源端和目标端 DDL +- 单对象部署 SQL +- 全部所选对象的部署脚本 +- 对象依赖和被依赖关系 +- 字段映射与兼容性提示 +- 创建、修改、删除数量和影响摘要 +- 可选回滚脚本（启用且能够生成时） + +最终部署页面会再次显示目标服务器、数据库、Schema、数据库版本和语句数量。生产环境保护会在执行前要求明确确认。 + +“在事务中执行”只在目标数据库和语句支持事务 DDL 时提供真正的整体回滚。MySQL 等数据库的 DDL 可能隐式提交。 + +## 方言语义 + +DBX 会尽量保留数据库专属语义，而不是把所有 DDL 转成通用格式，例如： + +- PostgreSQL / openGauss 等的 Schema、序列、Owner、Rule 和索引特性 +- MySQL 兼容数据库的字符集、排序规则、自增和索引语法 +- Oracle、达梦、GaussDB、KingBase 等的类型和对象限定方式 +- Doris / StarRocks、ClickHouse、Elasticsearch/Easysearch 等只在可可靠处理的结构范围内参与 + +支持连接不代表所有对象都可对比或部署。查看 [数据库支持](/cn/docs/databases) 和结果中的 capability 提示。 + +## 数据对比 + +数据对比独立于 Schema 对比，用于比较源表和目标表的行。 + + + + ### 选择源表和目标表 + + 选择连接、数据库、Schema 和表。批量模式可以选择多张源表，并按同名表映射到目标。 + + + + ### 选择关键字段 + + 指定能够唯一识别行的主键或业务键。关键字段错误会把更新误判为新增/删除。 + + + + ### 执行比较 + + DBX 读取两端数据并标记源端新增、目标端多余和字段修改。批量模式显示当前表、进度和单表失败原因。 + + + + ### 选择差异 + + 按新增、删除、修改筛选，并选择要同步的行或字段。详情预览限制可以控制一次展示的数据量。 + + + + ### 生成并执行同步 SQL + + DBX 为目标数据库生成 `INSERT`、`UPDATE` 和 `DELETE`。确认语句、数量和目标后再执行。 + + + + +### 数据差异方向 + +| 状态 | 含义 | 同步到目标时 | +| --- | --- | --- | +| 新增 | 行只存在于源端 | 生成 `INSERT` | +| 删除 | 行只存在于目标端 | 生成 `DELETE` | +| 修改 | 相同关键字段的其他列不同 | 生成 `UPDATE` | +| 一致 | 两端行相同 | 不生成语句 | + +删除同步风险最高。若目标端允许存在源端没有的本地数据，不要选择删除差异。 + +## 对比前检查 + +- 源和目标方向是否正确 +- 账号是否能读取完整元数据、DDL 或表数据 +- 表过滤和对象选择是否遗漏关键依赖 +- 关键字段是否唯一、是否包含 `NULL` +- 跨方言字段映射是否保留精度和语义 +- 目标是否启用只读或生产保护 +- 是否已经备份并在测试环境验证脚本 + +## 已知边界 + +- 动态 SQL、存储过程内部行为、应用代码和外部 ETL 不在 Schema 对比范围内 +- 重命名检测是相似度建议，不是确定结论 +- DDL 格式差异可能产生语义相同但文本不同的结果 +- 数据对比需要把选定范围读入比较流程，不适合无过滤地处理超大表 +- 事务回滚能力取决于目标数据库 +- 对比配置包含连接 ID 和范围，但不包含数据库密码 - - 对单张表进行可视化结构修改，并在保存前预览 DDL。 + + 可视化修改字段、索引、外键和触发器。 - - 在执行高风险同步前导出结构和数据。 + + 在执行高风险同步前创建手动或定时逻辑备份。 - - 查看哪些数据库支持结构相关工作流。 + + 当目标是迁移整表数据而不是逐行对比时使用。 + + + 了解部署脚本和数据同步的生产确认。 diff --git a/docs/content/docs/schema-diff.mdx b/docs/content/docs/schema-diff.mdx index 28e1a488ee..fae55ff346 100644 --- a/docs/content/docs/schema-diff.mdx +++ b/docs/content/docs/schema-diff.mdx @@ -1,89 +1,211 @@ --- -title: Schema Diff -description: Compare two database schemas and generate reviewable sync SQL. +title: Schema and Data Comparison +description: Compare schemas or table data, review differences, type mappings, impact, and synchronization SQL, then deploy to a target environment. --- -Schema Diff helps compare structure between database environments, such as development and production, staging and QA, or databases before and after a migration. +DBX provides two comparison workflows: -Schema sync may include destructive operations such as dropping tables, dropping columns, or changing column types. Review generated SQL line by line, and back up production databases first. +- **Schema Diff** compares objects and DDL and generates a deployment script from source to target +- **Data Compare** compares rows in one or more tables by key columns and generates selectable insert, update, and delete SQL -## Use Cases +Both treat the source as the desired state and the target as the environment to inspect or synchronize. Reversing them generates the opposite operations. -- Check whether schema changes from development are already applied to production -- Align staging, QA, and production environments -- Generate migration SQL for team review -- Compare tables, columns, indexes, and constraints between database versions +Comparison results and generated SQL require human review. Object drops, row deletes, type conversions, cross-dialect mappings, and bulk synchronization can be irreversible. Back up production and prepare rollback first. -## Workflow +## Schema Diff Workflow - ### Select the Source + ### Select or create a configuration - The source is usually the database whose structure is newer or considered correct. + Choose a recent configuration or create, rename, or duplicate one. Configurations can be imported/exported as JSON to reuse source, target, and options. - ### Select the Target + ### Choose source and target - The target is the database to inspect or sync. It can be on another server or even another database engine. + Select connection, database, and schema for both sides. You can swap them, but must review deployment direction again afterward. - ### Run the Comparison + ### Configure comparison scope - DBX reads table, column, and index metadata from both sides. The current comparison handles tables, not views. + Select tables, primary keys, foreign keys, unique keys, checks, views, functions, indexes, sequences, triggers, rules, owners, and other supported objects. Options depend on database type. - ### Review Differences + ### Compare and select objects - Check missing tables, extra tables, column type changes, nullable changes, default value changes, added or removed indexes, and data risk. + DBX reads metadata and DDL, builds an object tree, and marks creations, deletions, modifications, and dependencies. Select the objects that should actually deploy. - ### Generate Sync SQL + ### Review DDL and impact - DBX generates statements such as `CREATE TABLE`, `ALTER TABLE`, and `DROP TABLE`. Review them before execution. + Inspect source/target DDL, field mappings, deployment script, dependencies, potential conflicts, and impact report. + + + + ### Export or deploy + + Copy/export `.sql` or deploy to the target after final confirmation. When supported, use a transaction and inspect statement-level progress and results. -## Difference Types +## Schema Difference Types -| Type | Meaning | -| ----------------- | ---------------------------------------------------------------------- | -| Source only | The object is missing from the target and may need to be created | -| Target only | The object exists only in the target; confirm usage before dropping it | -| Column difference | Type, nullable flag, or default value differs | -| Index difference | Added or removed indexes, matched by index name | +| Status | Meaning | Typical script | +| --- | --- | --- | +| Added in source | Target is missing the object | `CREATE` or add column/index/constraint | +| Extra in target | Source does not contain the object | `DROP` or remove column/index/constraint | +| Modified object | Definitions differ | `ALTER`, rebuild, or replace source | +| Rename candidate | Names differ but structures are similar | Similarity-based rename suggestion requiring review | +| Compatibility conflict | Source type or feature cannot map directly to target | Field mapping, downgrade, or manual migration | -Schema Diff currently does not fully compare foreign keys, triggers, view definitions, column comments, or changed columns/uniqueness inside an index with the same name. Important migrations still need manual SQL review. +Filter and select operations in the object tree. An object is not dropped automatically just because it is extra in the target; it still requires selection and final confirmation. -## Database Coverage +## Comparison Options -Schema Diff depends on table, column, and index metadata. It works best on relational engines where DBX can list structures consistently, such as MySQL, PostgreSQL, SQLite, SQL Server, Oracle, Redshift, DM, and GaussDB-family engines. Redis, MongoDB, Elasticsearch, and Easysearch use different data models and are not good targets for relational schema sync. +### Object Scope -## Before Running Sync SQL +Depending on database, comparison can include: -Before applying generated SQL, confirm: +- Tables, columns, column order, and primary keys +- Unique keys, foreign keys, checks, and exclusion constraints +- Indexes, views, functions, sequences, triggers, and rules +- Owners and sequence current values -- The active connection color and environment name are correct -- The target database has been backed up -- `DROP`, `TRUNCATE`, and column type changes are intentional -- The operation should run during a maintenance window -- The SQL has been tested in a non-production environment +Options load dialect-specific defaults. Objects without reliable metadata or synchronization SQL are hidden or shown as differences only. -## Related Features +### Table Filters + +- Include and exclude patterns +- Priority when include and exclude both match +- Batch mode and table-name patterns +- System-object visibility + +Filtering controls comparison scope, not permissions. Objects the current account cannot read do not appear. + +### Rename Detection + +Enable column or table rename detection and configure a similarity threshold. Suggestions use structural similarity and do not understand business meaning; verify data, constraints, application code, and dependencies. + +### Cross-Dialect Field Mapping + +When source and target types differ, configure source dialect, target dialect, compatibility threshold, and field mappings: + +- Preserve parameters such as the length in `VARCHAR(255)` +- Strip incompatible parameters +- Supply custom target parameters + +Cross-engine comparison can only generate a best-effort compatible script. Charset, collation, identity, sequences, partitioning, storage engines, functions, and privileges often need manual migration design. + +## DDL, Dependencies, and Deployment Review + +For selected objects, review: + +- Source and target DDL +- Per-object deployment SQL +- The complete script for all selected objects +- Dependencies and reverse dependencies +- Field mappings and compatibility warnings +- Create, modify, delete counts and impact summary +- Optional rollback SQL when enabled and generatable + +The final deployment page repeats the target server, database, schema, database version, and statement count. Production protection requires explicit confirmation before execution. + +Run in transaction provides full rollback only when the target database and statements support transactional DDL. MySQL and other databases can implicitly commit DDL. + +## Dialect Semantics + +DBX attempts to preserve database-specific semantics rather than normalizing everything to generic DDL, including: + +- PostgreSQL/openGauss schemas, sequences, owners, rules, and index features +- MySQL-compatible charset, collation, identity, and index syntax +- Oracle, Dameng, GaussDB, KingBase, and similar type and qualification behavior +- Doris/StarRocks, ClickHouse, Elasticsearch/Easysearch, and others only within reliably supported structure scope + +A supported connection does not mean every object can compare or deploy. Use [Database Support](/en/docs/databases) and capability messages in the result. + +## Data Compare + +Data Compare is separate from Schema Diff and compares rows between source and target tables. + + + + ### Choose source and target tables + + Select connection, database, schema, and table. Batch mode can select multiple source tables and map them to same-named targets. + + + + ### Choose key columns + + Select a primary or business key that uniquely identifies rows. Incorrect keys can turn updates into apparent inserts and deletes. + + + + ### Run comparison + + DBX reads both sides and marks source-only, target-only, and changed rows. Batch mode shows current table, progress, and per-table failures. + + + + ### Select differences + + Filter additions, removals, and modifications and select the rows or fields to synchronize. A detail-preview limit controls displayed data volume. + + + + ### Generate and execute synchronization SQL + + DBX generates target-dialect `INSERT`, `UPDATE`, and `DELETE` statements. Review statement count and target before execution. + + + + +### Data Difference Direction + +| Status | Meaning | Synchronization to target | +| --- | --- | --- | +| Added | Row exists only in source | Generate `INSERT` | +| Removed | Row exists only in target | Generate `DELETE` | +| Modified | Same key, different non-key columns | Generate `UPDATE` | +| Same | Rows match | No statement | + +Delete synchronization is the highest-risk option. If target-local data is allowed, do not select removals. + +## Pre-Comparison Checklist + +- Source and target direction is correct +- Accounts can read complete metadata, DDL, or table data +- Filters and object selection include required dependencies +- Key columns are unique and handle `NULL` correctly +- Cross-dialect mappings preserve precision and meaning +- Target read-only and production settings are correct +- Backups exist and scripts were validated in a test environment + +## Known Boundaries + +- Dynamic SQL, procedure behavior, application code, and external ETL are outside schema comparison +- Rename detection is a similarity suggestion, not a confirmed conclusion +- Formatting differences can produce text changes with equivalent semantics +- Data compare reads the selected scope and is not suitable for unfiltered huge tables +- Transaction rollback depends on the target database +- Configurations contain connection IDs and scope but not database passwords - - Edit one table visually and preview DDL before applying changes. + + Edit columns, indexes, foreign keys, and triggers visually. - - Export structure and data before high-risk sync operations. + + Create manual or scheduled logical backups before risky synchronization. - - Check which engines support schema and structure workflows. + + Use this when the goal is moving full tables rather than comparing rows. + + + Review production confirmation for deployment and data synchronization. diff --git a/docs/content/docs/specialized-workspaces.cn.mdx b/docs/content/docs/specialized-workspaces.cn.mdx new file mode 100644 index 0000000000..d9fa99ef59 --- /dev/null +++ b/docs/content/docs/specialized-workspaces.cn.mdx @@ -0,0 +1,139 @@ +--- +title: 专项工作台 +description: 使用 DBX 管理 Redis、MongoDB、搜索与向量数据库、HBase、消息队列、etcd、ZooKeeper 和 Nacos。 +--- + +除了 SQL 编辑器和数据表格，DBX 还会根据连接类型打开专项工作台。它们直接使用对应系统的对象模型和管理 API，例如 Redis Key、MongoDB 文档、向量集合、消息队列 Topic、etcd Key、ZooKeeper ZNode 和 Nacos 配置。 + +专项能力按数据库类型、服务端版本、驱动和当前账号权限动态开放。界面没有显示某个入口时，先查看 [数据库支持](/cn/docs/databases)、连接测试结果和账号权限。 + +## 工作台总览 + +| 类别 | 连接类型 | 主要入口 | +| --- | --- | --- | +| 键值与文档 | Redis、MongoDB | Key/文档浏览、筛选、编辑、命令或聚合流程 | +| 搜索与文档索引 | Elasticsearch、Easysearch、Manticore Search | 索引/文档浏览和对应请求入口 | +| 向量数据库 | Qdrant、Milvus、Weaviate、ChromaDB | Collection 浏览、向量检索、Upsert、删除和请求预览 | +| 宽表与列族 | HBase | Namespace、表结构、Column Family 和行数据浏览 | +| 消息队列 | Pulsar、Kafka、RocketMQ、RabbitMQ | Topic、订阅/消费者、消息、监控、权限、策略和管理 API | +| 注册与配置中心 | etcd、ZooKeeper、Nacos | Key/ZNode、集群状态、访问控制、配置、服务和实例 | +| 运行状态 | MySQL、PostgreSQL、Redis、etcd、Nacos 等 | Dashboard、进程/会话、指标和数据库专属管理视图 | + +## Redis 与 MongoDB + +Redis 和 MongoDB 有独立的详细文档： + + + + 浏览和搜索 Key，编辑多种数据类型，执行命令，查看统计与 Slowlog。 + + + 浏览集合和文档，筛选、分页、编辑、管理索引，并处理 GridFS 数据。 + + + +连接只读时，DBX 会禁用或拒绝 Redis、MongoDB 和 GridFS 中的修改操作。危险 Redis 命令还会经过独立的命令安全分类。 + +## 搜索与文档索引 + +Elasticsearch、Easysearch 和 Manticore Search 使用面向索引与文档的浏览方式。DBX 会根据驱动返回的对象结构展示索引或集合，并提供浏览、查询和查看文档的入口。 + +使用时需要注意： + +- Elasticsearch 和 Easysearch 的地址通常是 HTTP/HTTPS 服务端点，不是传统数据库 TCP 端口 +- TLS、代理和认证方式取决于连接类型及服务端配置 +- 文档查询和写入能力会随驱动、服务端版本和账号权限变化 +- 结构对比、SQL 文件执行等 SQL 工作流只在对应引擎确实支持时开放 + +## 向量数据库 + +Qdrant、Milvus、Weaviate 和 ChromaDB 会打开向量集合工作台。根据引擎能力，可以： + +- 浏览 Collection 和记录 +- 查看集合维度或 Schema 信息 +- 输入向量并执行 Top K 相似度检索 +- 预览或编辑原始请求 +- Upsert 向量、Payload/Metadata 或文档 +- 按 ID 或请求条件删除记录 + +不同产品的 API、集合模型和检索参数并不相同。DBX 会生成对应引擎的请求模板，但向量维度、字段名、距离度量和索引设置仍应以目标数据库定义为准。 + +向量 Upsert 和删除属于写入操作。生产连接建议同时使用数据库账号权限、DBX 只读/生产保护和人工请求审查。 + +## HBase + +HBase 工作台围绕 Namespace、表、Column Family 和行键组织。根据 Agent 与服务端能力，可以浏览表结构和行数据，并在非只读连接上使用创建、修改、截断或删除等管理入口。 + +HBase 的扫描范围和过滤条件会直接影响服务端负载。处理大表时应限制行键范围、分页大小和返回列，避免把全表扫描当作普通数据表格浏览。 + +## 消息队列 + +Pulsar、Kafka、RocketMQ 和 RabbitMQ 共用消息队列控制台框架，但每个系统只显示自身支持的面板。常见能力包括： + +- Topic、Namespace、Tenant 或 Virtual Host 浏览与管理 +- Subscription、Consumer Group、Producer 和 Client 查看 +- 消息查询、发送和消息轨迹 +- Broker 或集群监控 +- Permission、Policy 和配额等管理入口 +- Raw API，用于查看或调用驱动公开的底层管理请求 + +例如，Pulsar 更强调 Tenant、Namespace 和 Subscription；Kafka 使用 Topic、Consumer Group 和 Broker 视角；RocketMQ 提供消息与轨迹相关入口；RabbitMQ 使用 Virtual Host、Exchange/Queue、连接、Policy 和 Permission 模型。 + +消息队列面板根据 Agent 返回的 capability 动态显示。服务端版本、管理 API、账号权限或未配置的管理端口都可能让某些标签页不可用。 + +## etcd、ZooKeeper 与 Nacos + +### etcd + +etcd 提供 Key 浏览器、集群 Dashboard 和访问控制工作台。可用能力包括前缀浏览、值查看/编辑、租约相关信息、成员与健康状态、指标，以及用户和角色管理。 + +### ZooKeeper + +ZooKeeper 使用 ZNode 树展示层级数据。可以浏览路径、查看节点内容，并在权限允许且连接非只读时创建、修改或删除节点。 + +### Nacos + +Nacos 工作台覆盖配置和服务两个主要视图，并可管理 Namespace。根据连接和控制台 API 能力，还可以使用： + +- 配置创建、编辑、删除和全文搜索 +- 配置历史、版本对比与回滚 +- 批量导入、导出和跨 Namespace 复制 +- 服务、实例、权重和健康信息 +- Dashboard 与 Raw API + +Nacos 的配置历史可能依赖额外的控制台地址和凭据。连接成功但历史入口不可用时，检查连接表单中的控制台设置。 + +## Dashboard 与管理视图 + +部分连接会在对象树或标签页中提供运行状态页面，例如： + +- MySQL 和 PostgreSQL 的 Dashboard 或会话/进程视图 +- Redis 实例信息、统计和 Slowlog +- etcd 集群成员、数据库大小、Raft/租约相关指标 +- Nacos 命名空间、配置、服务和实例统计 +- 消息队列 Broker、Topic、客户端和消费状态 + +这些页面用于排查和观察，不等同于长期监控系统。需要告警、历史趋势和容量规划时，仍应使用 Prometheus、Grafana 或厂商监控平台。 + +## 安全与兼容边界 + +- 专项工作台会尊重连接只读；MCP 暴露的专项命令还受全局 MCP 策略限制。 +- 生产环境保护对 DBX 识别到的写入继续生效，但数据库账号权限仍是最终边界。 +- 驱动只会公开能够可靠实现的 capability，同一类系统的标签页可能不同。 +- 管理 API 和数据协议可能使用不同端口，例如 RabbitMQ Management API、Nacos 控制台 API。 +- Docker/Web 中的文件路径和网络可达性属于服务器环境，不是浏览器电脑。 + + + + 确认连接类型、默认端口、驱动架构和高级功能覆盖范围。 + + + 安装或更新 Agent/JDBC 驱动，并处理运行时依赖。 + + + 为专项系统配置只读连接、生产保护和 MCP 权限。 + + + 配置 TLS、SSH、SOCKS5、HTTP 代理或 HTTP 隧道。 + + diff --git a/docs/content/docs/specialized-workspaces.mdx b/docs/content/docs/specialized-workspaces.mdx new file mode 100644 index 0000000000..21e4810bcc --- /dev/null +++ b/docs/content/docs/specialized-workspaces.mdx @@ -0,0 +1,139 @@ +--- +title: Specialized Workspaces +description: Manage Redis, MongoDB, search and vector databases, HBase, message queues, etcd, ZooKeeper, and Nacos in DBX. +--- + +In addition to the SQL editor and data grid, DBX opens specialized workspaces for specific connection types. These interfaces use each system's native object model and management APIs, including Redis keys, MongoDB documents, vector collections, message queue topics, etcd keys, ZooKeeper ZNodes, and Nacos configurations. + +Specialized capabilities are enabled dynamically based on database type, server version, driver, and account privileges. If an entry point is missing, check [Database Support](/en/docs/databases), the connection test result, and server permissions. + +## Workspace Overview + +| Category | Connection types | Main entry points | +| --- | --- | --- | +| Key/value and document | Redis, MongoDB | Key or document browsing, filtering, editing, commands, and aggregation workflows | +| Search and document indexes | Elasticsearch, Easysearch, Manticore Search | Index/document browsing and engine-specific requests | +| Vector databases | Qdrant, Milvus, Weaviate, ChromaDB | Collection browsing, vector search, upsert, delete, and request preview | +| Wide-column and column family | HBase | Namespaces, table structure, column families, and row data | +| Message queues | Pulsar, Kafka, RocketMQ, RabbitMQ | Topics, subscriptions or consumers, messages, monitoring, permissions, policies, and admin APIs | +| Registry and configuration | etcd, ZooKeeper, Nacos | Keys/ZNodes, cluster status, access control, configuration, services, and instances | +| Runtime status | MySQL, PostgreSQL, Redis, etcd, Nacos, and others | Dashboards, processes or sessions, metrics, and database-specific administration views | + +## Redis and MongoDB + +Redis and MongoDB have dedicated guides: + + + + Browse and search keys, edit multiple data types, run commands, and inspect statistics and Slowlog. + + + Browse collections and documents, filter, paginate, edit, manage indexes, and work with GridFS data. + + + +When a connection is read-only, DBX disables or rejects mutations in Redis, MongoDB, and GridFS. Dangerous Redis commands also pass through a separate command-safety classifier. + +## Search and Document Indexes + +Elasticsearch, Easysearch, and Manticore Search use index- and document-oriented browsing. DBX displays indexes or collections from driver metadata and provides entry points for browsing, querying, and inspecting documents. + +Keep these boundaries in mind: + +- Elasticsearch and Easysearch usually connect to HTTP/HTTPS endpoints rather than traditional database TCP ports +- TLS, proxying, and authentication depend on the connection type and server configuration +- Document queries and mutations vary by driver, server version, and account privileges +- SQL workflows such as schema diff or SQL file execution only appear when the engine reliably supports them + +## Vector Databases + +Qdrant, Milvus, Weaviate, and ChromaDB open a vector collection workspace. Depending on the engine, it can: + +- Browse collections and records +- Display dimensions or schema details +- Run Top K similarity search with an input vector +- Preview or edit the raw request +- Upsert vectors, payloads/metadata, or documents +- Delete records by ID or request condition + +The products use different APIs, collection models, and search parameters. DBX generates an engine-specific request template, but dimensions, field names, distance metrics, and index settings must match the target database. + +Vector upserts and deletes are write operations. Production connections should combine database privileges, DBX read-only/production protection, and human request review. + +## HBase + +The HBase workspace is organized around namespaces, tables, column families, and row keys. Depending on Agent and server capabilities, it can browse table structure and rows and expose create, alter, truncate, or delete operations on writable connections. + +Scan ranges and filters directly affect server load. For large tables, constrain row-key ranges, page size, and returned columns instead of treating a full scan like a normal relational data grid. + +## Message Queues + +Pulsar, Kafka, RocketMQ, and RabbitMQ share the message queue console framework, but each system only shows panels supported by its own capabilities. Common areas include: + +- Topics plus namespaces, tenants, or virtual hosts +- Subscriptions, consumer groups, producers, and clients +- Message queries, sending, and traces +- Broker or cluster monitoring +- Permissions, policies, quotas, and related administration +- Raw API requests exposed by the driver + +Pulsar emphasizes tenants, namespaces, and subscriptions; Kafka uses topics, consumer groups, and brokers; RocketMQ adds message and trace workflows; RabbitMQ uses virtual hosts, exchanges/queues, connections, policies, and permissions. + +Message queue panels are capability-driven. Server versions, management APIs, account privileges, or a missing management port can make individual tabs unavailable. + +## etcd, ZooKeeper, and Nacos + +### etcd + +etcd provides a key browser, cluster dashboard, and access-control workspace. Available features include prefix browsing, value editing, lease information, member and health status, metrics, and user/role management. + +### ZooKeeper + +ZooKeeper displays hierarchical data as a ZNode tree. You can browse paths and inspect node content, then create, update, or delete nodes when permissions and connection state allow it. + +### Nacos + +The Nacos workspace covers configuration and services and can also manage namespaces. Depending on the connection and console API, it includes: + +- Configuration creation, editing, deletion, and full-text search +- Configuration history, version diff, and rollback +- Batch import/export and cross-namespace copy +- Services, instances, weights, and health data +- Dashboard and Raw API access + +Configuration history can require an additional console URL and credentials. If the connection works but history is unavailable, check the console settings in the connection form. + +## Dashboards and Administration Views + +Some connections expose runtime status pages from the object tree or a tab, including: + +- MySQL and PostgreSQL dashboards or process/session views +- Redis instance information, statistics, and Slowlog +- etcd members, database size, and Raft/lease-related metrics +- Nacos namespace, configuration, service, and instance statistics +- Message queue broker, topic, client, and consumption state + +These pages are for inspection and troubleshooting, not long-term monitoring. Use Prometheus, Grafana, or a vendor monitoring platform when you need alerts, historical trends, and capacity planning. + +## Safety and Compatibility Boundaries + +- Specialized workspaces respect connection read-only state; MCP-exposed specialized commands also follow the global MCP policy. +- Production protection still applies to writes recognized by DBX, while database privileges remain the final boundary. +- Drivers expose only capabilities they can implement reliably, so tabs can differ even within one category. +- Management APIs and data protocols can use different ports, such as RabbitMQ Management API or the Nacos console API. +- File paths and network reachability in Docker/Web belong to the server environment, not the browser computer. + + + + Check connection types, default ports, driver architecture, and advanced feature coverage. + + + Install or update Agent/JDBC drivers and handle runtime dependencies. + + + Configure read-only connections, production protection, and MCP permissions. + + + Configure TLS, SSH, SOCKS5, HTTP proxies, or HTTP tunnels. + + diff --git a/docs/content/docs/sql-file.cn.mdx b/docs/content/docs/sql-file.cn.mdx index e1a99727ab..5d0b616e48 100644 --- a/docs/content/docs/sql-file.cn.mdx +++ b/docs/content/docs/sql-file.cn.mdx @@ -1,76 +1,123 @@ --- title: SQL 文件执行 -description: 选择连接后执行 .sql 文件，查看进度，并在需要时取消后续语句。 +description: 预览并按顺序执行一个或多个 SQL 文件，查看逐文件统计、语句进度和失败结果。 --- -SQL 文件执行用于导入或运行本地 `.sql` 脚本。它适合执行初始化脚本、数据补丁、数据库导出文件和迁移脚本。 +SQL 文件执行用于运行初始化脚本、数据库导出、数据补丁和迁移脚本。DBX 会先展示截断预览，再按文件选择顺序和语句顺序执行。 -执行 SQL 文件可能修改大量数据或结构。运行前请确认目标连接、目标数据库和脚本来源，生产环境建议先备份。 +SQL 文件可以创建、修改或删除大量对象和数据。预览不是完整文件，不能用于证明脚本安全。执行前确认目标连接、数据库、文件顺序和脚本来源。 -## 使用流程 +## Desktop 和 Docker/Web + +| 运行方式 | 文件位置和处理 | +| --- | --- | +| Desktop | 直接选择本机一个或多个 `.sql` 文件，并显示本地文件名或路径信息 | +| Docker/Web | 浏览器选择文件后上传到 DBX 服务器临时目录；界面只展示用户选择的文件名，不暴露服务器临时路径 | + +Docker/Web 中，脚本读取和执行发生在服务器端，文件完成或释放后会清理临时资源。它不能直接访问浏览器所在电脑上的任意路径。 + +## 执行流程 - ### 打开 SQL 文件执行 + ### 选择一个或多个文件 - 在 DBX 中打开 SQL 文件执行面板。 + 文件按照选择顺序排列。多文件模式左侧显示文件列表，点击可以切换右侧预览。 - ### 选择文件 + ### 检查预览和文件信息 - 选择本地 `.sql` 文件。大文件可能需要更长解析和执行时间。 + 每个文件显示名称、大小、预览行数和截断状态。大文件只读取有限字符用于预览，完整内容仍会在执行时流式读取。 - ### 选择目标连接 + ### 选择连接和数据库 - 选择要执行脚本的数据库连接和数据库。 + 一般需要选择目标数据库。如果脚本自身建立数据库上下文，例如前面的文件包含可识别的 `USE`，DBX 可以在支持的路径中允许不预选数据库。 - ### 开始执行 + ### 配置错误策略并确认 - 点击执行后，DBX 会按语句执行并显示进度。 + 默认遇到失败语句即停止；开启“遇错继续”后会记录失败并继续后续语句和文件。生产保护范围内会在执行前要求新的确认。 - ### 检查结果 + ### 执行和查看结果 - 执行结束后查看成功数量、失败语句和错误信息。 + 进度显示当前文件、语句序号、成功数、失败数、受影响行数、耗时、语句摘要和错误。多文件完成后会显示逐文件统计和总计。 -## 语句分割 +## 多文件会话语义 -DBX 会按流式方式读取 SQL 文件，并尽量正确识别语句边界，避免简单按每个分号拆分： +多个文件属于同一个执行任务，按列表顺序运行。MySQL 兼容路径会在整个批次中复用同一条固定连接，因此前一个文件中的以下状态可以影响后续文件： -- 字符串中的分号不会被当作语句结束 -- 行注释和块注释中的分号不会被当作语句结束 -- PostgreSQL 的 dollar-quoted 函数体会保持为同一条语句 -- SQL Server 的 `GO` 行会被识别为批次分隔 -- MySQL executable comments 会在导入前按目标连接处理：MySQL 兼容连接会展开可执行内容，非 MySQL 连接会跳过；`ENABLE/DISABLE KEYS`、`LOCK/UNLOCK TABLES`、session 状态恢复这类导入辅助指令会跳过 +- `USE database` +- 临时表 +- Session 变量和设置 +- 显式事务 + +这使拆分的初始化或恢复脚本可以保持上下文，但也意味着文件顺序非常重要。不要把相互独立的脚本随意放入同一个批次。 + +## 语句分割和导入辅助语句 + +DBX 流式读取文件，并使用数据库感知的分割逻辑，而不是简单按每个分号拆分： + +- 字符串、行注释和块注释中的分号不会结束语句 +- PostgreSQL dollar-quoted 函数体会保持完整 +- SQL Server 的独立 `GO` 行作为批次边界 +- MySQL 例程使用的 `DELIMITER` 流程会被识别 +- MySQL executable comments 会按目标连接处理：MySQL 兼容路径展开可执行内容，其他连接跳过 +- `ENABLE/DISABLE KEYS`、`LOCK/UNLOCK TABLES` 和部分 session 恢复等导入辅助指令会按执行器策略处理或跳过 + +数据库方言和脚本生成工具差异很大。复杂脚本仍应先在测试环境验证，尤其是自定义分隔符、客户端专属命令和数据库管理工具生成的元命令。 + +## 错误策略 + +### 遇错停止 + +默认模式在第一条失败语句后结束整个任务。界面保留已经完成的统计、失败语句摘要和数据库错误。 + +### 遇错继续 + +开启后，DBX 记录失败并继续后续语句。多文件模式也会继续下一个文件，并在结束时给出每个文件的成功数、失败数、受影响行数和耗时。 + +“遇错继续”只改变任务控制流，不会修复事务状态。某些数据库在事务内发生错误后要求显式回滚，后续语句仍可能连续失败。 + +## 取消和事务 + +取消会停止后续语句，但已经发送或提交到数据库的语句不会自动撤销。如果脚本需要整体原子性，应由脚本显式控制事务，并确认目标数据库、DDL 和导入语句都具备所需事务语义。 + +多文件共享会话时，未提交事务可能跨文件延续。确保脚本包含清晰的 `BEGIN`、`COMMIT` 或 `ROLLBACK`，不要依赖关闭对话框自动提交或回滚。 ## 数据库覆盖范围 -SQL 文件执行面向 SQL 类数据库。Redis、MongoDB、Elasticsearch 和 Easysearch 不执行关系型 SQL 脚本，因此 DBX 会隐藏或禁用该功能。 +该入口按驱动的 `sqlFileExecution` 能力显示。大多数 SQL 型驱动启用；Redis、MongoDB、搜索、向量、HBase、配置中心和消息队列等专用工作区不会执行关系型 SQL 文件。 -## 错误处理 - -默认情况下，执行遇到错误会停止。你也可以启用“遇错继续”，让 DBX 继续执行后续语句并记录失败数量。 - -## 取消执行 - -执行过程中可以取消任务。取消只会阻止后续语句继续执行，已经提交到数据库的语句不会自动回滚。 - -如果脚本需要整体原子性，建议脚本本身包含事务控制，并确认目标数据库支持相关事务语义。 +能够运行查询不一定表示所有客户端脚本语法都受支持。`psql`、`mysql`、`sqlcmd` 或其他工具特有的元命令可能需要先转换成数据库服务器可以直接执行的 SQL。 ## 执行前检查 -- 当前连接是否是预期环境 -- 脚本是否来自可信来源 -- 是否包含 `DROP`、`TRUNCATE`、大范围 `UPDATE` 或 `DELETE` -- 是否需要先在测试环境执行 -- 是否需要启用“遇错继续” -- 是否需要先使用 [数据库导出](/cn/docs/database-export) 备份 +- 文件顺序和数据库上下文是否正确 +- 预览是否被截断，是否已用编辑器审阅完整文件 +- 是否包含 `DROP`、`TRUNCATE`、无条件 `UPDATE` / `DELETE`、用户权限或配置变更 +- “遇错继续”是否会掩盖关键失败 +- 目标连接是否开启只读或生产保护 +- 是否需要先做 [数据库导出](/cn/docs/database-export) 或 [数据库备份](/cn/docs/database-backup) + +## 相关功能 + + + + 生成结构、数据和对象 SQL 文件。 + + + 为 MySQL 和 PostgreSQL 配置 Desktop 定时备份。 + + + 了解执行前确认、只读保护和权限边界。 + + diff --git a/docs/content/docs/sql-file.mdx b/docs/content/docs/sql-file.mdx index 695331dbfa..b66a794be7 100644 --- a/docs/content/docs/sql-file.mdx +++ b/docs/content/docs/sql-file.mdx @@ -1,76 +1,123 @@ --- title: SQL File Execution -description: Execute .sql files against a selected connection, monitor progress, and cancel remaining statements when needed. +description: Preview and execute one or more SQL files in order with per-file statistics, statement progress, and failure reporting. --- -SQL File Execution runs local `.sql` scripts in DBX. Use it for initialization scripts, data patches, database dumps, and migration scripts. +SQL File Execution runs initialization scripts, database exports, data patches, and migrations. DBX shows a truncated preview first, then executes files in selection order and statements in script order. -SQL files may modify large amounts of data or schema. Confirm the target connection, target database, and script source before running. Back up production databases first. +SQL files can create, modify, or remove large amounts of data and schema. The preview is not the complete file and cannot prove a script is safe. Verify the target connection, database, file order, and source before execution. + +## Desktop and Docker/Web + +| Runtime | File location and handling | +| --- | --- | +| Desktop | Selects one or more local `.sql` files directly and can display local filename or path information | +| Docker/Web | Uploads browser-selected files into temporary DBX server storage; the UI shows the selected names instead of server UUID paths | + +In Docker/Web, reading and execution happen on the server. Temporary resources are released after the operation. The server cannot directly open arbitrary paths from the computer running the browser. ## Workflow - ### Open SQL File Execution + ### Select One or More Files - Open the SQL file execution panel in DBX. + Files remain in selection order. Multi-file mode shows a side list; select an item to switch the preview pane. - ### Choose a File + ### Review Preview and File Details - Select a local `.sql` file. Large files may take longer to parse and execute. + Each file reports its name, size, preview lines, and truncation state. Large files read only a limited preview, while execution still streams the complete content. - ### Select Target Connection + ### Select Connection and Database - Choose the connection and database where the script should run. + A target database is normally required. When the script establishes database context itself, such as an earlier recognizable `USE`, DBX can allow execution without a preselected database on supported paths. - ### Start Execution + ### Choose Error Policy and Confirm - DBX executes the script statement by statement and shows progress. + Execution stops on the first failure by default. Continue on error records failures and proceeds to later statements and files. Protected production contexts require a fresh confirmation before execution. - ### Check Results + ### Run and Inspect Results - After execution, review successful statements, failed statements, and error messages. + Progress includes the current file, statement index, success and failure counts, affected rows, elapsed time, statement summary, and error. Multi-file runs finish with per-file statistics and totals. -## Statement Splitting +## Multi-File Session Semantics -DBX reads SQL files as a stream and tries to detect statement boundaries correctly instead of splitting on every semicolon: +Selected files form one execution task and run in list order. MySQL-compatible paths reuse one pinned connection across the complete batch, so state established by an earlier file can affect later files, including: -- Semicolons inside strings are not treated as statement endings -- Semicolons inside line and block comments are ignored -- PostgreSQL dollar-quoted function bodies are kept together -- SQL Server `GO` lines split batches -- MySQL executable comments are prepared for the target connection before import: MySQL-compatible connections unwrap executable content, non-MySQL connections skip it, and import-helper directives such as `ENABLE/DISABLE KEYS`, `LOCK/UNLOCK TABLES`, and session state restores are skipped +- `USE database` +- Temporary tables +- Session variables and settings +- Explicit transactions + +This supports split initialization and restore scripts, but makes ordering significant. Do not batch unrelated scripts when session state could leak between them. + +## Statement Splitting and Import Helpers + +DBX reads files as a stream and uses database-aware splitting instead of breaking at every semicolon: + +- Semicolons inside strings, line comments, and block comments do not terminate a statement +- PostgreSQL dollar-quoted function bodies remain intact +- Standalone SQL Server `GO` lines split batches +- MySQL routine `DELIMITER` workflows are recognized +- MySQL executable comments are unwrapped for compatible targets and skipped for other targets +- Import helpers such as `ENABLE/DISABLE KEYS`, `LOCK/UNLOCK TABLES`, and selected session-state restoration directives are handled or skipped by executor policy + +Database dialects and script generators vary widely. Test complex scripts first, especially those containing custom delimiters, client-only commands, or meta-commands generated by administration tools. + +## Error Policy + +### Stop on Error + +The default ends the task after the first failed statement. DBX retains completed statistics, the failed statement summary, and the database error. + +### Continue on Error + +When enabled, DBX records a failure and proceeds. Multi-file tasks also move to the next file and report success count, failure count, affected rows, and elapsed time for each file. + +Continue on error changes task control flow only. It does not repair transaction state. Some databases require an explicit rollback after a transaction error, so later statements may continue failing. + +## Cancellation and Transactions + +Cancellation stops later statements, but statements already submitted or committed are not reverted automatically. If the script must be atomic, control transactions explicitly and verify that the target engine, DDL, and import statements provide the required semantics. + +With a shared multi-file session, an open transaction can continue across file boundaries. Use clear `BEGIN`, `COMMIT`, or `ROLLBACK` statements instead of relying on closing the dialog to commit or roll back. ## Database Coverage -SQL file execution is for SQL-oriented engines. DBX hides or disables it for Redis, MongoDB, Elasticsearch, and Easysearch because those connections do not execute relational SQL scripts. +The action follows the driver's `sqlFileExecution` capability. Most SQL-oriented drivers enable it. Specialized Redis, MongoDB, search, vector, HBase, configuration-center, and message-queue workspaces do not execute relational SQL files. -## Error Handling - -By default, execution stops when a statement fails. You can enable continue-on-error to keep running later statements while recording failures. - -## Cancelling Execution - -You can cancel while execution is running. Cancelling stops later statements from running, but statements already submitted to the database are not rolled back automatically. - -If a script must be atomic, include transaction control in the script itself and confirm the target database supports the required transaction behavior. +Query execution support does not guarantee compatibility with every client script language. Meta-commands specific to `psql`, `mysql`, `sqlcmd`, or another client may need conversion into SQL the database server accepts directly. ## Before Running -- Confirm the active connection is the intended environment -- Verify the script comes from a trusted source -- Look for `DROP`, `TRUNCATE`, broad `UPDATE`, or broad `DELETE` -- Run the script in a test environment first when possible -- Decide whether continue-on-error is appropriate -- Back up with [Database Export](/en/docs/database-export) when needed +- Verify file order and database context +- Check whether previews are truncated and review the complete files in an editor +- Look for `DROP`, `TRUNCATE`, unqualified `UPDATE` / `DELETE`, privilege changes, or configuration changes +- Decide whether continue-on-error could hide a critical failure +- Check read-only and production protection on the target +- Create a [Database Export](/en/docs/database-export) or [Database Backup](/en/docs/database-backup) first when appropriate + +## Related Features + + + + Generate structure, data, and object SQL files. + + + Schedule MySQL and PostgreSQL backups in Desktop. + + + Understand pre-execution confirmation, read-only protection, and privilege boundaries. + + diff --git a/docs/content/docs/sql-formatter.cn.mdx b/docs/content/docs/sql-formatter.cn.mdx index fabd928062..875be4fe41 100644 --- a/docs/content/docs/sql-formatter.cn.mdx +++ b/docs/content/docs/sql-formatter.cn.mdx @@ -1,33 +1,58 @@ --- title: SQL 格式化 -description: 配置 SQL 格式化选项、导入导出 JSON 配置，并定制 JSON 配置编辑器快捷键。 +description: 使用数据库方言格式化所选 SQL 或整个编辑器，并管理当前版本的格式化选项和 JSON 配置。 --- -DBX 的 SQL 格式化配置位于**设置 → SQL 格式化**。配置分为两部分： +DBX 会根据当前连接选择接近的 SQL 方言，并把格式化结果写回查询编辑器。选中一段 SQL 时只格式化选区；没有选区时格式化整个编辑器。 -- `options`：控制 SQL 格式化结果，例如关键字大小写、缩进、操作符换行和参数类型。 -- `editor`：控制 SQL 格式化 JSON 配置编辑器中的快捷键。 +你可以使用编辑器工具栏的 **格式化 SQL** 按钮，或使用[快捷键](/cn/docs/keyboard-shortcuts)中配置的格式化命令。 -## 表单与 JSON + + SQL 格式化只重排文本，不会执行 SQL。无法解析的语法会返回错误并保留原内容；单次格式化最多处理 `1,000,000` 个字符。 + -表单模式适合修改常用选项。JSON 模式适合复制、粘贴、导入或批量修改完整配置。 +## 方言选择 -JSON 配置合法时，DBX 会把配置同步回表单；配置无效时，会显示具体错误并阻止应用。 +DBX 当前对以下方言使用专用格式化语法： -## 快捷键平台 +| 连接类型 | 格式化方言 | +| --- | --- | +| MySQL | MySQL | +| PostgreSQL、openGauss、GaussDB、KingBase、Redshift 等兼容连接 | PostgreSQL | +| SQLite、Turso、rqlite、Cloudflare D1 | SQLite | +| SQL Server | Transact-SQL | +| ClickHouse | ClickHouse | +| 其他 SQL 数据库 | 通用 SQL；必要时再尝试 PostgreSQL 语法 | -快捷键配置文件可以同时保存 Windows、Linux 和 macOS 三个平台的按键。 +MongoDB 查询编辑器使用单独的 Mongo Shell 格式化器，不使用本页的 SQL 方言映射。 -表单中只显示当前系统的平台列。例如在 macOS 上只显示 macOS 快捷键，避免三端配置同时挤在一个表格里。导入和导出仍会保留完整三端配置，便于在不同系统间迁移。 +## 配置格式化选项 -## 完整模板 JSON +前往 **设置 → SQL 格式化**。表单模式提供以下选项： + +| 选项 | 可用值或作用 | +| --- | --- | +| 关键字、数据类型、函数、标识符大小写 | `upper`、`lower`、`preserve` | +| 缩进样式 | `standard`、`tabularLeft`、`tabularRight` | +| 缩进字符 | 空格或 Tab | +| Tab 宽度 | `2` 或 `4` | +| 逻辑操作符换行 | 操作符之前或之后 | +| 表达式宽度 | `50`、`80` 或 `120` | +| 查询间空行 | `0`、`1` 或 `2` | +| 紧凑操作符 | 减少操作符周围的空格 | +| 分号前换行 | 把语句结尾分号放到新行 | +| 参数类型 | 识别位置参数、编号参数、命名参数、引号参数或自定义正则参数 | + +**恢复默认值**会恢复当前代码定义的默认格式化设置。设置窗口中的改动需要点击 **应用** 才会持久化。 + +## JSON 模式与导入导出 + +JSON 模式适合精确编辑、复制或迁移格式化器配置。当前配置文件只包含 `version`、`formatter` 和 `options`： ```json { "version": 1, "formatter": "sql-formatter", - "name": "DBX SQL 格式化配置", - "description": "SQL 格式化选项，以及 SQL 格式化 JSON 配置编辑器快捷键模板。", "options": { "keywordCase": "upper", "dataTypeCase": "preserve", @@ -37,189 +62,52 @@ JSON 配置合法时，DBX 会把配置同步回表单；配置无效时，会 "useTabs": false, "tabWidth": 2, "logicalOperatorNewline": "before", - "expressionWidth": 80, + "expressionWidth": 50, "linesBetweenQueries": 1, "denseOperators": false, "newlineBeforeSemicolon": false, "paramTypes": null - }, - "editor": { - "scope": "sqlFormatterConfigJsonEditor", - "platforms": ["windows", "linux", "macos"], - "shortcuts": [ - { - "id": "find", - "action": "openSearchPanel", - "label": "查找", - "keys": { - "windows": "Ctrl+F", - "linux": "Ctrl+F", - "macos": "Cmd+F" - }, - "enabled": true - }, - { - "id": "replace", - "action": "openSearchPanel", - "label": "替换", - "keys": { - "windows": "Ctrl+H", - "linux": "Ctrl+H", - "macos": "Cmd+Option+F" - }, - "enabled": true - }, - { - "id": "indentMore", - "action": "indentMore", - "label": "增加缩进", - "keys": { - "windows": "Tab", - "linux": "Tab", - "macos": "Tab" - }, - "enabled": true - }, - { - "id": "indentLess", - "action": "indentLess", - "label": "减少缩进", - "keys": { - "windows": "Shift+Tab", - "linux": "Shift+Tab", - "macos": "Shift+Tab" - }, - "enabled": true - }, - { - "id": "duplicateLine", - "action": "copyLineDown", - "label": "复制当前行", - "keys": { - "windows": "Ctrl+D", - "linux": "Ctrl+D", - "macos": "Cmd+D" - }, - "enabled": true - }, - { - "id": "deleteLine", - "action": "deleteLine", - "label": "删除当前行", - "keys": { - "windows": "Ctrl+Shift+K", - "linux": "Ctrl+Shift+K", - "macos": "Cmd+Shift+K" - }, - "enabled": true - }, - { - "id": "moveLineUp", - "action": "moveLineUp", - "label": "当前行上移", - "keys": { - "windows": "Alt+Up", - "linux": "Alt+Up", - "macos": "Option+Up" - }, - "enabled": true - }, - { - "id": "moveLineDown", - "action": "moveLineDown", - "label": "当前行下移", - "keys": { - "windows": "Alt+Down", - "linux": "Alt+Down", - "macos": "Option+Down" - }, - "enabled": true - }, - { - "id": "copyLineUp", - "action": "copyLineUp", - "label": "向上复制当前行", - "keys": { - "windows": "Shift+Alt+Up", - "linux": "Shift+Alt+Up", - "macos": "Shift+Option+Up" - }, - "enabled": true - }, - { - "id": "copyLineDown", - "action": "copyLineDown", - "label": "向下复制当前行", - "keys": { - "windows": "Shift+Alt+Down", - "linux": "Shift+Alt+Down", - "macos": "Shift+Option+Down" - }, - "enabled": true - }, - { - "id": "undo", - "action": "undo", - "label": "撤销", - "keys": { - "windows": "Ctrl+Z", - "linux": "Ctrl+Z", - "macos": "Cmd+Z" - }, - "enabled": true - }, - { - "id": "redo", - "action": "redo", - "label": "重做", - "keys": { - "windows": "Ctrl+Y", - "linux": "Ctrl+Shift+Z", - "macos": "Cmd+Shift+Z" - }, - "enabled": true - }, - { - "id": "selectAll", - "action": "selectAll", - "label": "全选", - "keys": { - "windows": "Ctrl+A", - "linux": "Ctrl+A", - "macos": "Cmd+A" - }, - "enabled": true - }, - { - "id": "formatJson", - "action": "formatJson", - "label": "格式化 JSON 配置", - "keys": { - "windows": "Shift+Alt+F", - "linux": "Shift+Alt+F", - "macos": "Shift+Cmd+F" - }, - "enabled": true - }, - { - "id": "applyConfig", - "action": "applyJsonDraft", - "label": "应用 JSON 配置", - "keys": { - "windows": "Ctrl+S", - "linux": "Ctrl+S", - "macos": "Cmd+S" - }, - "enabled": true - } - ] } } ``` -## 兼容说明 +JSON 编辑器会实时校验配置。以下情况会阻止应用或导入： -- `version` 当前固定为 `1`。 -- `formatter` 当前固定为 `sql-formatter`。 -- `params` 参数替换不会被 SQL 格式化执行；需要参数识别时使用 `paramTypes`。 -- 旧模板中的 `replace` 动作如果写成 `openReplacePanel`，导入时会自动兼容并归一化。 +- JSON 语法错误； +- `version` 不是 `1`； +- `formatter` 不是 `sql-formatter`； +- `options` 中包含未知字段； +- 字段值不在当前代码允许的范围内。 + +点击 **导出配置** 会下载 `dbx-sql-formatter.json`。导入只替换 SQL 格式化选项，不会修改连接、编辑器快捷键或其他 DBX 设置。完整设置迁移请参阅[配置云同步](/cn/docs/cloud-sync)。 + +## 参数识别 + +`paramTypes` 为 `null` 时使用格式化器默认识别规则。需要额外语法时，可以配置： + +```json +{ + "positional": true, + "numbered": ["?", "$"], + "named": [":", "@", "$"], + "quoted": [":", "@", "$"], + "custom": [ + { "regex": "@\\{[^}]+\\}" } + ] +} +``` + +- `numbered` 只接受 `?`、`:`、`$`； +- `named` 和 `quoted` 只接受 `:`、`@`、`$`； +- `custom` 中每项只能包含非空且合法的 `regex`。 + +DBX 始终额外识别 `${name}` 和 `#{name}` 形式的变量，避免这类模板变量导致格式化解析失败。旧配置中的非空 `params` 字段不再用于文本替换，应改用 `paramTypes`。 + + + + 了解格式化、压缩、执行范围和自动补全。 + + + 使用可跳转占位符创建可复用 SQL 模板。 + + diff --git a/docs/content/docs/sql-formatter.mdx b/docs/content/docs/sql-formatter.mdx index a682bbd3d7..5e7d0d9204 100644 --- a/docs/content/docs/sql-formatter.mdx +++ b/docs/content/docs/sql-formatter.mdx @@ -1,33 +1,58 @@ --- -title: SQL Formatter -description: Configure SQL formatting options, import and export JSON config, and customize JSON config editor shortcuts. +title: SQL Formatting +description: Format a selection or the full editor with database-aware syntax, then manage the current formatter options and JSON config. --- -DBX SQL formatter settings live in **Settings → SQL Formatter**. +DBX chooses a formatter dialect from the active connection and writes the result back to the query editor. When text is selected, only that range is formatted; otherwise DBX formats the entire editor. -- `options` controls formatting output such as keyword case, indentation, line breaks, and parameter types. -- `editor` controls shortcuts used inside the SQL formatter JSON config editor. +Use the **Format SQL** toolbar button or the configurable formatting command documented under [Keyboard Shortcuts](/en/docs/keyboard-shortcuts). -## Form And JSON + + Formatting only rewrites text and never executes SQL. Unsupported syntax returns an error and leaves the original text unchanged. One formatting operation accepts at most `1,000,000` characters. + -Use the form for common options. Use JSON mode to copy, paste, import, export, or edit the full config. +## Dialect Selection -When the JSON config is valid, DBX syncs it back to the form. Invalid JSON shows an error and cannot be applied. +DBX currently uses dedicated formatter grammars for: -## Shortcut Platform +| Connection type | Formatter dialect | +| --- | --- | +| MySQL | MySQL | +| PostgreSQL, openGauss, GaussDB, KingBase, Redshift, and related profiles | PostgreSQL | +| SQLite, Turso, rqlite, and Cloudflare D1 | SQLite | +| SQL Server | Transact-SQL | +| ClickHouse | ClickHouse | +| Other SQL databases | Generic SQL, with one PostgreSQL-grammar retry when needed | -The config file can store Windows, Linux, and macOS shortcuts at the same time. +The MongoDB query editor uses a separate Mongo Shell formatter rather than this SQL dialect mapping. -The form only shows the current system column. For example, macOS shows only macOS shortcuts. Import and export still preserve all platform keys. +## Configure Formatting Options -## Full Template JSON +Open **Settings → SQL Formatter**. Form mode exposes: + +| Option | Values or behavior | +| --- | --- | +| Keyword, data type, function, and identifier case | `upper`, `lower`, or `preserve` | +| Indent style | `standard`, `tabularLeft`, or `tabularRight` | +| Indentation | Spaces or tabs | +| Tab width | `2` or `4` | +| Logical operator newline | Before or after the operator | +| Expression width | `50`, `80`, or `120` | +| Lines between queries | `0`, `1`, or `2` | +| Dense operators | Reduces spaces around operators | +| Newline before semicolon | Places a statement-ending semicolon on a new line | +| Parameter types | Recognizes positional, numbered, named, quoted, or custom-regex parameters | + +**Restore Defaults** restores the formatter settings defined by the current DBX build. Click **Apply** in the settings dialog to persist changes. + +## JSON Mode and Import / Export + +JSON mode is useful for exact editing, copying, or moving formatter settings. The current file contains only `version`, `formatter`, and `options`: ```json { "version": 1, "formatter": "sql-formatter", - "name": "DBX SQL Formatter Config", - "description": "SQL formatter options and SQL formatter JSON config editor shortcut template.", "options": { "keywordCase": "upper", "dataTypeCase": "preserve", @@ -37,189 +62,52 @@ The form only shows the current system column. For example, macOS shows only mac "useTabs": false, "tabWidth": 2, "logicalOperatorNewline": "before", - "expressionWidth": 80, + "expressionWidth": 50, "linesBetweenQueries": 1, "denseOperators": false, "newlineBeforeSemicolon": false, "paramTypes": null - }, - "editor": { - "scope": "sqlFormatterConfigJsonEditor", - "platforms": ["windows", "linux", "macos"], - "shortcuts": [ - { - "id": "find", - "action": "openSearchPanel", - "label": "Find", - "keys": { - "windows": "Ctrl+F", - "linux": "Ctrl+F", - "macos": "Cmd+F" - }, - "enabled": true - }, - { - "id": "replace", - "action": "openSearchPanel", - "label": "Replace", - "keys": { - "windows": "Ctrl+H", - "linux": "Ctrl+H", - "macos": "Cmd+Option+F" - }, - "enabled": true - }, - { - "id": "indentMore", - "action": "indentMore", - "label": "Indent more", - "keys": { - "windows": "Tab", - "linux": "Tab", - "macos": "Tab" - }, - "enabled": true - }, - { - "id": "indentLess", - "action": "indentLess", - "label": "Indent less", - "keys": { - "windows": "Shift+Tab", - "linux": "Shift+Tab", - "macos": "Shift+Tab" - }, - "enabled": true - }, - { - "id": "duplicateLine", - "action": "copyLineDown", - "label": "Duplicate current line", - "keys": { - "windows": "Ctrl+D", - "linux": "Ctrl+D", - "macos": "Cmd+D" - }, - "enabled": true - }, - { - "id": "deleteLine", - "action": "deleteLine", - "label": "Delete current line", - "keys": { - "windows": "Ctrl+Shift+K", - "linux": "Ctrl+Shift+K", - "macos": "Cmd+Shift+K" - }, - "enabled": true - }, - { - "id": "moveLineUp", - "action": "moveLineUp", - "label": "Move line up", - "keys": { - "windows": "Alt+Up", - "linux": "Alt+Up", - "macos": "Option+Up" - }, - "enabled": true - }, - { - "id": "moveLineDown", - "action": "moveLineDown", - "label": "Move line down", - "keys": { - "windows": "Alt+Down", - "linux": "Alt+Down", - "macos": "Option+Down" - }, - "enabled": true - }, - { - "id": "copyLineUp", - "action": "copyLineUp", - "label": "Copy line up", - "keys": { - "windows": "Shift+Alt+Up", - "linux": "Shift+Alt+Up", - "macos": "Shift+Option+Up" - }, - "enabled": true - }, - { - "id": "copyLineDown", - "action": "copyLineDown", - "label": "Copy line down", - "keys": { - "windows": "Shift+Alt+Down", - "linux": "Shift+Alt+Down", - "macos": "Shift+Option+Down" - }, - "enabled": true - }, - { - "id": "undo", - "action": "undo", - "label": "Undo", - "keys": { - "windows": "Ctrl+Z", - "linux": "Ctrl+Z", - "macos": "Cmd+Z" - }, - "enabled": true - }, - { - "id": "redo", - "action": "redo", - "label": "Redo", - "keys": { - "windows": "Ctrl+Y", - "linux": "Ctrl+Shift+Z", - "macos": "Cmd+Shift+Z" - }, - "enabled": true - }, - { - "id": "selectAll", - "action": "selectAll", - "label": "Select all", - "keys": { - "windows": "Ctrl+A", - "linux": "Ctrl+A", - "macos": "Cmd+A" - }, - "enabled": true - }, - { - "id": "formatJson", - "action": "formatJson", - "label": "Format JSON config", - "keys": { - "windows": "Shift+Alt+F", - "linux": "Shift+Alt+F", - "macos": "Shift+Cmd+F" - }, - "enabled": true - }, - { - "id": "applyConfig", - "action": "applyJsonDraft", - "label": "Apply JSON config", - "keys": { - "windows": "Ctrl+S", - "linux": "Ctrl+S", - "macos": "Cmd+S" - }, - "enabled": true - } - ] } } ``` -## Compatibility +The JSON editor validates the draft continuously. DBX blocks apply or import when: -- `version` is currently `1`. -- `formatter` is currently `sql-formatter`. -- `params` replacement is not executed by SQL formatting. Use `paramTypes` when parameter recognition is needed. -- Legacy templates that use `openReplacePanel` for the `replace` action are accepted and normalized on import. +- the text is not valid JSON; +- `version` is not `1`; +- `formatter` is not `sql-formatter`; +- `options` contains an unknown field; or +- a value is outside the range accepted by the current build. + +**Export Config** downloads `dbx-sql-formatter.json`. Import replaces only SQL formatter options; it does not change connections, editor shortcuts, or other DBX settings. Use [Configuration Cloud Sync](/en/docs/cloud-sync) when you need a broader settings migration. + +## Parameter Recognition + +Set `paramTypes` to `null` to use the formatter defaults. Configure additional parameter syntax with an object such as: + +```json +{ + "positional": true, + "numbered": ["?", "$"], + "named": [":", "@", "$"], + "quoted": [":", "@", "$"], + "custom": [ + { "regex": "@\\{[^}]+\\}" } + ] +} +``` + +- `numbered` accepts only `?`, `:`, and `$`. +- `named` and `quoted` accept only `:`, `@`, and `$`. +- Each `custom` item may contain only a non-empty, valid `regex`. + +DBX always adds recognition for `${name}` and `#{name}` variables so those templates do not cause formatter parse failures. A non-null legacy `params` option is no longer used for text substitution; configure `paramTypes` instead. + + + + Learn how formatting, compression, execution scope, and completion work. + + + Build reusable SQL templates with tab-stop placeholders. + + diff --git a/docs/content/docs/sql-snippets.cn.mdx b/docs/content/docs/sql-snippets.cn.mdx index 4aa33b1be6..05c88e0c00 100644 --- a/docs/content/docs/sql-snippets.cn.mdx +++ b/docs/content/docs/sql-snippets.cn.mdx @@ -1,70 +1,78 @@ --- title: SQL 代码片段 -description: 创建带有自定义触发键的可复用 SQL 模板，加速查询编写。 +description: 管理可复用 SQL 模板、触发键和可跳转占位符，并在编辑器补全中快速展开。 --- -SQL 代码片段允许你定义可复用的 SQL 模板，输入触发键时自动展开。这对于经常编写的查询模式、标准子句或团队特定的 SQL 约定非常有用。 +SQL 代码片段会作为编辑器补全候选出现。输入触发键后接受候选，DBX 会在光标处插入模板；模板中的占位符可以继续用 `Tab` 和 `Shift+Tab` 逐个填写。 -## 代码片段工作原理 +## 管理代码片段 -1. 使用**触发键**和**模板**定义一个代码片段 -2. 在 SQL 编辑器中输入触发键 -3. DBX 将触发键自动完成为完整模板 -4. 模板中的占位符让你可以按 Tab 键在可编辑位置之间跳转 +前往 **设置 → 代码片段**。每个片段包含： -## 创建代码片段 +| 字段 | 作用 | +| --- | --- | +| 标签 | 补全列表中显示的名称；留空时使用触发键。 | +| 触发键 | 用于匹配补全候选的前缀，必填，并且在当前片段列表中必须唯一。 | +| 状态 | 临时启用或停用片段，不需要删除模板。 | +| SQL 内容 | 接受补全后插入编辑器的模板正文。 | - - ### 打开代码片段设置 前往**设置 → SQL 代码片段**。 - ### 添加新片段 点击**添加片段**并填写： - **触发键**：在编辑器中输入的简短关键字（如 `selall`、`joinex`） - **模板**：替换触发键的 SQL 文本 - ### 使用代码片段 在 SQL 编辑器中输入触发键，然后按 `Tab` 或从自动补全列表中选择。模板会在光标处展开。 - +你可以新增、编辑、启用、停用或删除片段。**恢复默认值**会把当前草稿替换为 DBX 内置片段；完成修改后点击设置窗口中的 **应用** 保存。 -## 示例片段 + + DBX 自带 `sel`、`ins`、`upd`、`cte`、`join` 等常用片段。部分内置片段会根据当前数据库调整语法，例如选择合适的行数限制或 `ALTER TABLE` 写法；自定义片段则按原文插入。 + -以下是一些实用的片段模板： +## 在编辑器中展开 -**带常用子句的 SELECT：** +1. 在 SQL 编辑器中输入触发键，例如 `sel`。 +2. 在补全列表中确认标签和正文预览。 +3. 按 `Tab`、`Enter` 或点击候选接受补全。 +4. 如果模板包含占位符，继续按 `Tab` 前进，按 `Shift+Tab` 返回。 + +如果补全列表没有出现，请确认片段已启用、触发键与当前输入匹配，并检查编辑器自动补全是否被关闭。 + +## 占位符语法 + +DBX 使用 CodeMirror 代码片段语法： + +| 写法 | 作用 | +| --- | --- | +| `${}` | 创建一个空的可编辑位置。 | +| `${name}` | 创建默认文本为 `name` 的可编辑位置；同名位置会同步编辑。 | +| `${1}` | 使用数字显式指定跳转顺序。 | +| `${1:defaultText}` | 指定跳转顺序并提供默认文本。 | +| `#{name}` | `${name}` 的等价写法。 | + +数字占位符按照编号跳转；没有数字时按照模板中的出现顺序跳转。要插入不会被识别为占位符的字面量花括号，请在花括号前加反斜杠。 + +例如： ```sql SELECT ${1:columns} FROM ${2:table} WHERE ${3:condition} -ORDER BY ${4:column} +ORDER BY ${4:column}; ``` -**LEFT JOIN 模式：** - -```sql -LEFT JOIN ${1:table} ON ${2:left_alias}.${3:column} = ${4:right_alias}.${5:column} -``` - -**带 GROUP BY 的 COUNT：** +重复使用同一个占位符可以同时修改多个位置： ```sql SELECT ${1:column}, COUNT(*) AS cnt FROM ${2:table} -GROUP BY ${1:column} -HAVING COUNT(*) > ${3:threshold} -ORDER BY cnt DESC +GROUP BY ${1:column}; ``` -**CREATE TABLE 模板：** +## 保存、同步与安全 -```sql -CREATE TABLE ${1:table_name} ( - ${2:id} INTEGER PRIMARY KEY, - ${3:column} ${4:type} -); -``` +代码片段属于编辑器设置，会保存在当前 DBX 运行环境中。桌面版的[配置云同步](/cn/docs/cloud-sync)可以连同其他编辑器设置一起同步片段；[连接配置迁移](/cn/docs/config-export)只处理数据库连接，不包含代码片段。 -## 占位符 +片段只是生成 SQL，不会绕过数据库权限或 DBX 的生产保护。执行包含写入或 DDL 的模板前，仍应检查展开后的完整 SQL，并遵循[生产安全](/cn/docs/production-safety)建议。 -在模板中使用 `${1}`、`${2}` 等标记可编辑位置。展开后，按 `Tab` 在占位符之间跳转。相同编号的占位符会同时编辑。 - -## 使用建议 - -- 触发键保持简短但易记（3-6 个字符效果较好） -- 使用一致的前缀来区分个人片段（如 `my_selall`） -- 执行前检查展开的片段，尤其是在生产数据库上 -- 与团队分享实用的片段，以保持查询模式一致 + + + 了解补全、执行范围、历史记录和 SQL 文件等编辑器能力。 + + + 查看接受补全、格式化和执行 SQL 的当前快捷键。 + + diff --git a/docs/content/docs/sql-snippets.mdx b/docs/content/docs/sql-snippets.mdx index 23ca7fdd6a..0aaac029f1 100644 --- a/docs/content/docs/sql-snippets.mdx +++ b/docs/content/docs/sql-snippets.mdx @@ -1,70 +1,78 @@ --- title: SQL Snippets -description: Create customizable SQL snippet templates with custom trigger keys for faster query writing. +description: Manage reusable SQL templates, trigger prefixes, and tab-stop placeholders for editor completion. --- -SQL Snippets let you define reusable SQL templates that expand automatically when you type a trigger key. This is useful for frequently written query patterns, standard clauses, or team-specific SQL conventions. +SQL snippets appear as editor completion candidates. Accept a matching trigger to insert the template at the cursor, then use `Tab` and `Shift+Tab` to move through any editable placeholders. -## How Snippets Work +## Manage Snippets -1. You define a snippet with a **trigger key** and a **template** -2. In the SQL editor, type the trigger key -3. DBX auto-completes the trigger to the full template -4. Placeholders in the template let you tab through editable positions +Open **Settings → Snippets**. Each snippet contains: -## Creating A Snippet +| Field | Purpose | +| --- | --- | +| Label | Name shown in the completion list. DBX uses the prefix when the label is empty. | +| Prefix | Text that matches the completion candidate. It is required and must be unique in the current snippet list. | +| Status | Enables or disables the snippet without deleting it. | +| SQL Body | Template inserted into the editor when you accept the completion. | - - ### Open Snippet Settings Go to **Settings → SQL Snippets**. - ### Add a New Snippet Click **Add Snippet** and fill in: - **Trigger**: a short key you type in the editor (e.g., `selall`, `joinex`) - **Template**: the SQL text that replaces the trigger - ### Use the Snippet In the SQL editor, type the trigger key and press `Tab` or select it from the autocomplete list. The template expands in place. - +You can add, edit, enable, disable, or delete snippets. **Restore Defaults** replaces the current draft with DBX's built-in snippets; click **Apply** in the settings dialog to persist your changes. -## Example Snippets + + DBX includes common snippets such as `sel`, `ins`, `upd`, `cte`, and `join`. Some built-in templates adapt to the active database, for example by choosing the appropriate row-limit or `ALTER TABLE` syntax. Custom snippets are inserted exactly as written. + -Here are some useful snippet templates to get started: +## Expand a Snippet -**SELECT with common clauses:** +1. Type a prefix such as `sel` in the SQL editor. +2. Confirm the label and body preview in the completion list. +3. Press `Tab`, `Enter`, or click the candidate to accept it. +4. When the template has placeholders, press `Tab` to move forward and `Shift+Tab` to move back. + +If no candidate appears, confirm that the snippet is enabled, the prefix matches the current text, and editor autocomplete is enabled. + +## Placeholder Syntax + +DBX uses CodeMirror snippet syntax: + +| Syntax | Purpose | +| --- | --- | +| `${}` | Creates an empty editable field. | +| `${name}` | Creates a field whose default text is `name`; repeated names are edited together. | +| `${1}` | Sets an explicit field order. | +| `${1:defaultText}` | Sets the order and provides default text. | +| `#{name}` | Alternative form of `${name}`. | + +Numbered fields follow numeric order. Unnumbered fields follow their textual order in the template. Escape a literal opening or closing brace with a backslash when it must not be parsed as a placeholder. + +For example: ```sql SELECT ${1:columns} FROM ${2:table} WHERE ${3:condition} -ORDER BY ${4:column} +ORDER BY ${4:column}; ``` -**LEFT JOIN pattern:** - -```sql -LEFT JOIN ${1:table} ON ${2:left_alias}.${3:column} = ${4:right_alias}.${5:column} -``` - -**COUNT with GROUP BY:** +Reuse a field to edit multiple locations together: ```sql SELECT ${1:column}, COUNT(*) AS cnt FROM ${2:table} -GROUP BY ${1:column} -HAVING COUNT(*) > ${3:threshold} -ORDER BY cnt DESC +GROUP BY ${1:column}; ``` -**CREATE TABLE template:** +## Storage, Sync, and Safety -```sql -CREATE TABLE ${1:table_name} ( - ${2:id} INTEGER PRIMARY KEY, - ${3:column} ${4:type} -); -``` +Snippets are editor settings stored in the current DBX runtime. On Desktop, [Configuration Cloud Sync](/en/docs/cloud-sync) can synchronize snippets with the other editor settings. [Connection Config Migration](/en/docs/config-export) only moves database connections and does not include snippets. -## Placeholders +A snippet only generates SQL; it does not bypass database permissions or DBX production protection. Review the fully expanded statement before running templates that contain writes or DDL, and follow the [Production Safety](/en/docs/production-safety) guidance. -Use `${1}`, `${2}`, etc. in templates to mark editable positions. After expansion, press `Tab` to jump between placeholders. Placeholders with the same number are edited simultaneously. - -## Tips - -- Keep triggers short but memorable (3-6 characters works well) -- Use a consistent prefix for personal snippets (e.g., `my_selall`) -- Review expanded snippets before execution, especially on production databases -- Share useful snippets with your team for consistent query patterns + + + Learn how completion, execution scope, history, and SQL files work together. + + + Check the current shortcuts for accepting completion, formatting, and execution. + + diff --git a/docs/content/docs/ssh-tunnel.cn.mdx b/docs/content/docs/ssh-tunnel.cn.mdx index c4c384b66c..cfc2b05eb8 100644 --- a/docs/content/docs/ssh-tunnel.cn.mdx +++ b/docs/content/docs/ssh-tunnel.cn.mdx @@ -5,6 +5,10 @@ description: 通过 SSH 隧道、HTTP 隧道、SOCKS5 代理或 HTTP 代理连 当数据库不能直接访问时，DBX 可以在连接窗口的 **隧道/代理** 页签里配置连接层。 + + 隧道实际运行在 DBX 后端所在的位置。桌面版中的“本地路径”和临时监听端口属于当前电脑；Docker/Web 版中的路径、网络出口和临时监听端口属于服务器或容器，不属于浏览器所在电脑。 + + DBX 支持三类隧道/代理： | 类型 | 适用场景 | @@ -13,7 +17,19 @@ DBX 支持三类隧道/代理： | 代理 | 网络环境要求通过 SOCKS5 或 HTTP CONNECT 代理。 | | HTTP 隧道 | 只有内网 Web 服务器能访问数据库，不能使用 SSH/VPN。 | -对网络数据库来说，DBX 会先在本机打开一个本地端口，让数据库驱动连接这个端口，再由隧道/代理层把数据库协议字节转发到真实目标。 +对网络数据库来说，DBX 会先在当前运行环境中打开一个临时端口，让数据库驱动连接这个端口，再由隧道/代理层把数据库协议字节转发到真实目标。一个连接可以组合多层传输配置，DBX 会按照连接窗口中的顺序建立链路。 + +## 连接内配置与共享配置 + +你可以直接在单个连接的 **隧道/代理** 页签中填写配置，也可以前往 **设置 → 隧道** 创建共享配置： + +- 共享配置支持 SSH、SOCKS5 / HTTP CONNECT 代理和 HTTP 隧道； +- 一个共享配置可以被多个数据库连接引用； +- 修改共享配置后，所有引用它的连接会在下次连接时使用新配置； +- SSH 测试会验证主机可达性和认证，代理测试会验证代理握手，并可填写目标 `host:port`； +- HTTP 隧道只有在转发真实目标流量时才会建立会话，因此共享配置页不提供独立测试。 + +如果某个连接需要不同凭据或特殊顺序，可以把共享配置从该连接中分离，再保存为连接专属配置。 ## SSH 隧道 @@ -26,11 +42,11 @@ SSH 隧道是内置能力，不需要在终端里手动执行端口转发命令 | SSH 用户 | 登录 SSH 服务器的用户名 | | 连接超时 | DBX 等待 SSH 连接建立的最长时间，默认 5 秒 | - + - 选择本地的 SSH 私钥文件，例如 `~/.ssh/id_rsa`、`~/.ssh/id_ed25519`： + 填写 DBX 后端可以读取的 SSH 私钥文件，例如 `~/.ssh/id_rsa`、`~/.ssh/id_ed25519`： - - **密钥路径**：浏览并选择私钥文件。 + - **密钥路径**：桌面版可以浏览本机文件；Web 版需要手动填写服务器或容器内的路径。 - **密钥密码**：如果私钥设置了密码保护，在这里输入。 密钥认证比密码认证更安全，推荐优先使用。 @@ -48,13 +64,25 @@ SSH 隧道是内置能力，不需要在终端里手动执行端口转发命令 直接输入 SSH 用户的登录密码。适用于允许密码登录的服务器。 + + 只执行 SSH `none` 认证，不发送密码或私钥。仅适用于明确允许无凭据登录的 SSH 代理或特殊网关；服务器拒绝后不会回退到其他认证方式。 + +### 主机密钥验证 + +DBX 会在发送凭据前验证 SSH 主机密钥。已知密钥从系统 `known_hosts` 和 DBX 数据目录中的 `known_hosts` 读取： + +- 第一次连接到未知主机时，DBX 会显示指纹并要求明确接受； +- 可以只信任本次连接，也可以记住到 DBX 的 `known_hosts`； +- 已记录主机的密钥发生变化时，DBX 会拒绝连接； +- 如果确认窗口不可用、超时或被拒绝，连接会失败，并且不会发送密码或私钥。 + ### 允许局域网访问 -启用“允许局域网访问”后，同一网络里的其他设备也可以通过你的机器访问转发后的数据库端口。只应在可信网络中启用。 +启用“允许局域网访问”会把 SSH 临时监听端口从 `127.0.0.1` 改为 `0.0.0.0`。这会扩大当前 DBX 运行环境的攻击面，只应在可信网络并配合防火墙使用。 -默认情况下，SSH 隧道只监听 `localhost`。启用局域网访问后会绑定到 `0.0.0.0`，适合临时团队协作或多设备共享访问。 +桌面版中，这意味着当前电脑可能被局域网设备访问。Docker/Web 版中，监听发生在服务器或容器内，是否能从容器外访问还取决于端口发布、容器网络和主机防火墙。 ## 代理 @@ -66,6 +94,8 @@ DBX 支持： - HTTP CONNECT 代理 - 可选代理用户名和密码 +共享代理配置可以填写可选的测试目标，例如 `mysql.internal:3306`。不填写时，测试只验证代理端点和认证；最终数据库可达性仍以连接测试为准。 + ## HTTP 隧道 功能类型叫 HTTP 隧道。DBX 当前随代码提供的部署脚本是 `dbx_tunnel.php`，所以部署文件是 PHP 实现，但连接类型本身不是“PHP 隧道”。 @@ -110,7 +140,7 @@ DBX 数据库驱动 具体协议是短 HTTP 轮询： -1. DBX 在本机启动一个 TCP 监听端口。 +1. DBX 在当前运行环境中启动一个 TCP 监听端口。 2. 数据库驱动连接这个本地端口。 3. DBX 向 `dbx_tunnel.php` 发送 `open`，带上 session id、目标主机、目标端口和连接超时。 4. PHP 脚本校验 token 和 allow-list，然后启动 worker，worker 打开到数据库的 TCP socket。 @@ -128,11 +158,14 @@ DBX 数据库驱动 - 如果条件允许，限制脚本路径的公网访问范围。 - HTTP 隧道部署方便，但通常比直连、VPN、SSH 慢，因为它通过 HTTP 轮询和服务器端队列搬运数据库字节流。 - 如果和其他连接层一起使用，HTTP 隧道必须放在隧道/代理第一层，因为它是最外层网络边界。 +- HTTP 隧道脚本拥有访问目标主机的能力，部署和日常使用应遵循[生产安全](/cn/docs/production-safety)中的最小暴露与凭据要求。 ## 文件型数据库 SQLite 和 Access 是文件型连接，不使用隧道/代理。DuckDB 通常也使用本地文件，所以只有当当前驱动类型确实需要网络端点时才需要配置隧道/代理。 +Oracle TNS 描述符可能包含多个故障转移地址，DBX 不会把它重写到单个临时端口，因此 TNS 模式不能和 SSH、代理或 HTTP 隧道组合。需要隧道时请改用 Service Name 或 SID 模式。 + 在同一个连接窗口里配置数据库类型、隧道/代理、SSL 和连接颜色。 @@ -140,4 +173,7 @@ SQLite 和 Access 是文件型连接，不使用隧道/代理。DuckDB 通常也 查看哪些数据库是文件型、原生驱动、兼容协议或插件驱动。 + + 规划最小权限、网络暴露、只读保护和生产写入流程。 + diff --git a/docs/content/docs/ssh-tunnel.mdx b/docs/content/docs/ssh-tunnel.mdx index f282053c77..ede8474f88 100644 --- a/docs/content/docs/ssh-tunnel.mdx +++ b/docs/content/docs/ssh-tunnel.mdx @@ -5,6 +5,10 @@ description: Connect to private databases through SSH tunnels, HTTP tunnels, SOC DBX can open connection layers for databases that are not directly reachable. Configure them from the connection dialog's **Tunnel / Proxy** tab. + + Tunnels run where the DBX backend runs. On Desktop, local paths and temporary listeners belong to your computer. In Docker/Web, paths, network egress, and temporary listeners belong to the server or container, not the computer running the browser. + + DBX supports three tunnel / proxy types: | Type | Use When | @@ -13,7 +17,19 @@ DBX supports three tunnel / proxy types: | Proxy | Your network requires SOCKS5 or HTTP CONNECT proxy access. | | HTTP tunnel | Only a web server can reach the database, and SSH/VPN is not available. | -For network databases, DBX opens a local port and points the database driver at that port. The tunnel / proxy layer then forwards the database protocol bytes to the real target. +For network databases, DBX opens a temporary port in its current runtime and points the database driver at that port. The tunnel / proxy layer forwards protocol bytes to the real target. A connection may combine multiple transport layers, which DBX establishes in the order shown in the connection dialog. + +## Per-Connection and Shared Profiles + +Configure a layer directly under a connection's **Tunnel / Proxy** tab, or create reusable profiles under **Settings → Tunnels**: + +- Shared profiles support SSH, SOCKS5 / HTTP CONNECT proxies, and HTTP tunnels. +- Multiple database connections can reference the same profile. +- Editing a profile changes every referencing connection the next time it connects. +- The SSH test verifies reachability and authentication. The proxy test performs a proxy handshake and may use an optional target `host:port`. +- HTTP tunnels open lazily only when real target traffic starts, so there is no standalone HTTP-tunnel profile test. + +Detach a profile from an individual connection when that connection needs different credentials or a custom layer order. ## SSH Tunnel @@ -26,11 +42,11 @@ SSH tunnels are built in. You do not need to create a manual terminal port forwa | SSH User | Username for SSH authentication | | Connect Timeout | Maximum time DBX waits while opening the SSH connection; default is 5 seconds | - + - Select a private key file (for example `~/.ssh/id_rsa` or `~/.ssh/id_ed25519`): + Enter a private key file that the DBX backend can read, for example `~/.ssh/id_rsa` or `~/.ssh/id_ed25519`: - - **Key Path** — Browse and select your key file. + - **Key Path** — Desktop can browse local files. Web requires a server- or container-side path entered manually. - **Key Passphrase** — Enter the passphrase if your key is encrypted. Key authentication is more secure than password authentication. @@ -48,13 +64,25 @@ SSH tunnels are built in. You do not need to create a manual terminal port forwa Enter your SSH password directly. This works on servers that allow password authentication. + + Uses only SSH `none` authentication and sends no password or private key. This is intended for SSH proxies or special gateways that explicitly allow credential-free login. A rejection does not fall back to another method. + +### Host-Key Verification + +DBX verifies the SSH host key before it sends a credential. Trusted keys come from the system `known_hosts` files and DBX's own `known_hosts` under the data directory: + +- An unknown host prompts you to review and explicitly accept its fingerprint. +- You can trust it for the current connection only or remember it in DBX's `known_hosts`. +- DBX rejects a changed key for a previously known host. +- If the confirmation UI is unavailable, times out, or rejects the key, the connection fails without sending a password or private key. + ### Expose Tunnel to LAN -Enabling LAN exposure means other devices on the same network can access the forwarded database port through your machine. Only enable this on trusted networks. +LAN exposure changes the SSH listener from `127.0.0.1` to `0.0.0.0`. This expands the attack surface of the DBX runtime and should only be used on trusted networks with appropriate firewall rules. -By default, the SSH tunnel listens on `localhost` only. Enable LAN exposure to bind to `0.0.0.0`, which is useful for temporary team sharing or multi-device access. +On Desktop, this may make the temporary port reachable through your computer. In Docker/Web, the listener is inside the server or container; external reachability still depends on published ports, container networking, and the host firewall. ## Proxy @@ -66,6 +94,8 @@ DBX supports: - HTTP CONNECT proxy - Optional proxy username and password +A shared proxy profile may include an optional test target such as `mysql.internal:3306`. Without one, the test verifies only the proxy endpoint and credentials. Use the database connection test to verify the complete route. + ## HTTP Tunnel The feature is an HTTP tunnel. The script currently provided by DBX is `dbx_tunnel.php`, so the deployment artifact is PHP-specific, but the connection type in DBX is HTTP tunnel. @@ -110,7 +140,7 @@ DBX database driver The request protocol is short HTTP polling: -1. DBX starts a local TCP listener. +1. DBX starts a TCP listener in its current runtime. 2. The database driver connects to that local port. 3. DBX sends `open` to `dbx_tunnel.php` with a session id, target host, target port, and connect timeout. 4. The PHP script validates the token and allow-list, then starts a worker that opens a TCP socket to the database. @@ -128,11 +158,14 @@ This does not require DBX Web and does not use WebSocket. - Restrict public access to the script path where possible. - HTTP tunnel is convenient, but it is usually slower than direct TCP, VPN, or SSH because it forwards bytes through HTTP polling and a server-side queue. - If combined with other layers, HTTP tunnel must be the first tunnel / proxy layer because it is the outermost network boundary. +- The script can reach target hosts from the private network. Deploy and operate it with the least-exposure and credential guidance under [Production Safety](/en/docs/production-safety). ## File Databases SQLite and Access connections are file-based and do not use tunnel / proxy layers. DuckDB usually uses a local file as well, so only configure tunnel / proxy layers when the selected driver profile uses a network endpoint. +An Oracle TNS descriptor may contain multiple failover addresses. DBX does not rewrite that descriptor through one temporary endpoint, so TNS mode cannot be combined with SSH, proxy, or HTTP tunnel layers. Use Service Name or SID mode when a tunnel is required. + Configure the database profile, tunnel / proxy layers, SSL, and connection color together. @@ -140,4 +173,7 @@ SQLite and Access connections are file-based and do not use tunnel / proxy layer Check which database profiles are file-based, native, compatibility-based, or plugin-backed. + + Plan least privilege, network exposure, read-only protection, and production writes. + diff --git a/docs/content/docs/table-import.cn.mdx b/docs/content/docs/table-import.cn.mdx index bf98f71f86..22a081e6c8 100644 --- a/docs/content/docs/table-import.cn.mdx +++ b/docs/content/docs/table-import.cn.mdx @@ -1,93 +1,132 @@ --- title: 表数据导入 -description: 将 CSV、TSV、JSON 或 Excel 文件导入数据库表，并检查列映射和导入模式。 +description: 通过向导将 CSV、TSV、文本、JSON 或 Excel 数据导入现有表，或按文件批量创建新表。 --- -表数据导入用于把本地文件写入指定表。它适合一次性导入测试数据、业务数据补录、从表格工具迁移数据等场景。 +表数据导入用于把文件数据写入数据库表。DBX 会先解析和预览文件，再让你确认解析选项、目标表、字段映射和执行方式，而不是选中文件后立即写入。 + +导入会真实写入数据库。连接的只读保护会阻止导入，但数据库权限仍是最终边界。生产环境使用前请确认目标连接、目标表和备份方案。 + +## 两种目标方式 + +| 目标方式 | 行为 | 适合场景 | +| --- | --- | --- | +| 导入现有表 | 读取目标字段并建立源字段映射，可选择追加或清空后导入 | 数据补录、测试数据恢复、批量更新样例数据 | +| 创建新表 | 根据预览数据推断字段类型，你可以修改表名、字段名和类型后创建表并导入 | 从文件快速建表、迁移表格数据、一次导入多个文件 | + +创建新表时可以一次选择多个文件。Excel 文件会按工作表拆成独立任务；DBX 为每个文件或工作表生成一个建议表名，并要求最终表名唯一。批量任务按顺序执行，每个任务保留自己的预览、映射和类型设置。 ## 支持的文件 -| 格式 | 说明 | -| ----- | ----------------------------------------------------- | -| CSV | 逗号分隔文本，适合通用数据交换 | -| TSV | 制表符分隔文本，适合字段中包含逗号的场景 | -| JSON | JSON 数组，适合从接口或脚本导出的数据 | -| Excel | `.xlsx`、`.xlsm` 或 `.xls` 文件；DBX 读取第一个工作表 | +| 格式 | 说明 | +| --- | --- | +| CSV | 默认逗号分隔，也可以调整标题行、数据范围和编码 | +| TSV | 使用制表符分隔 | +| 分隔文本 | `.txt` 等文本文件，可自定义分隔符 | +| JSON | 支持单个对象、对象数组或数组行；可以指定对象或数组结构 | +| Excel | 支持 `.xlsx`、`.xlsm` 和 `.xls`，可选择工作表 | -DBX 会在导入前预览前 50 行。CSV/TSV 中的空单元格会按 `NULL` 处理。JSON 可以是单个对象、对象数组或数组行；对象行和数组行混用会被拒绝。 +Desktop 直接读取所选本地文件；Docker/Web 会先把浏览器选择的文件上传到服务器临时目录，预览和导入结束后释放临时源文件。 -## 导入流程 +## 导入向导 - ### 选择目标表 + ### 选择文件和目标方式 - 在侧边栏中右键目标表，选择 **导入数据**。 + 从表的右键菜单打开导入时，目标表会自动带入；也可以切换到创建新表并选择一个或多个文件。 - ### 选择文件 + ### 调整解析选项 - 选择要导入的 CSV、TSV、JSON 或 Excel 文件。 + 检查编码、标题行、数据起始行、最后一行、工作表、JSON 结构、空字符串和前后空白处理。 - ### 检查列映射 + ### 检查字段映射 - DBX 会按列名尝试匹配文件字段和数据库字段。请检查主键、必填字段、日期字段和数值字段。 + 导入现有表时把源字段映射到目标字段；创建新表时确认字段名和推断类型。右侧预览用于核对实际值。 - ### 选择导入模式 + ### 复核执行计划 - 选择追加或清空后导入。清空模式会先删除目标表已有数据。 + 确认目标连接、数据库、Schema、表名、导入模式、映射数量、预计行数和批大小。 ### 执行并检查结果 - 导入完成后检查成功行数、失败原因和目标表数据。 + 进度页显示读取、写入、完成状态、已导入行数、字节进度、耗时、错误和取消结果。 -## 导入模式 +## 解析选项 -| 模式 | 行为 | 适合场景 | -| ---------- | ---------------------------- | ------------------------ | -| 追加 | 保留原有数据，继续插入新行 | 补充数据、追加样例数据 | -| 清空后导入 | 先清空目标表，再导入文件内容 | 重建测试表、替换临时数据 | +### 文本编码 -清空后导入会删除目标表中的现有数据。生产环境使用前请确认备份和影响范围。 +CSV、TSV 和分隔文本支持自动检测、UTF-8、GBK、UTF-16 LE 和 UTF-16 BE。自动检测不正确时，请手动选择编码后重新检查预览。 -导入会分批执行。默认批大小为 500 行，进度视图会显示已导入行数、总行数、错误和取消状态。 +### 行范围 -## 字段映射规则 +- **标题行**：指定哪一行作为字段名 +- **数据起始行**：跳过文件前部的说明或空行 +- **最后一行**：只导入指定范围；`0` 表示读取到文件末尾 +- **预览行数**：控制映射页显示多少行，不等于最终导入行数 + +### 值处理 + +- **去除前后空白**：对文本值执行 trim +- **空字符串按 NULL**：默认开启；关闭后会保留空字符串 +- **JSON 结构**：自动识别，也可以强制按对象行或数组行解析 +- **工作表**：Excel 可以切换工作表；批量建表会为各工作表建立独立任务 + +## 字段映射和建表 + +导入现有表时，DBX 先按字段名精确匹配，再按规范化名称匹配，规范化会忽略大小写、空格、下划线和连字符差异。 -- 先按字段名精确匹配 -- 也会按规范化名称匹配，忽略大小写、空格、下划线和连字符差异 - 源字段可以跳过 - 同一个目标字段不能被重复映射 -- 至少需要映射一个字段才能开始导入 +- 至少需要映射一个字段 +- 未映射的必填字段必须有默认值、自增/生成规则或允许为空 + +创建新表时，源字段默认映射为同名目标字段，并根据预览值推荐数据库类型。类型建议只是起点；日期、精度、长文本、JSON、二进制和数据库特有类型应在执行前人工确认。 + +## 导入模式和批次 + +| 选项 | 行为 | +| --- | --- | +| 追加 | 保留目标表现有数据并插入新行 | +| 清空后导入 | 在支持的路径中先清空目标表，再写入文件数据 | +| 批大小 | 控制每次写入的行数，默认 500 | + +创建新表和多文件批量导入固定使用追加模式，因为目标表由当前任务创建。清空后导入具有破坏性；不同数据库的事务和 `TRUNCATE` 语义不同，失败时不能假设所有已执行操作都会自动回滚。 ## 数据库覆盖范围 -表数据导入支持 MySQL、PostgreSQL、SQLite、DuckDB、ClickHouse、SQL Server、Oracle、Doris、StarRocks、Redshift、DM、GaussDB、KingBase、HighGo、Vastbase、GoldenDB 和 Access。 +DBX 根据驱动能力清单决定是否显示表导入。原生 SQL 驱动中只有实现了字段读取、建表/写入和类型转换的连接才会启用；Redis、MongoDB、搜索、向量、消息队列和配置中心等专用工作区不使用这个关系型表导入入口。 -## 导入前检查 +不要把“能够连接”理解为“支持表导入”。如果菜单未出现，应先检查当前数据库类型、驱动模式和版本，而不是直接假设权限问题。 -- 文件首行是否是列名 -- 字符编码是否正确 -- 日期、数字、布尔值格式是否符合目标数据库要求 -- 非空字段是否都有值 -- 唯一索引和主键是否会冲突 -- 是否需要先导入父表，再导入带外键的子表 +## 失败和取消 -## 常见问题 +- 解析失败通常发生在编码、分隔符、标题行、JSON 结构或 Excel 工作表设置不正确时 +- 写入失败通常来自类型不匹配、非空约束、主键/唯一键冲突、权限或目标表结构 +- 取消会阻止后续批次继续写入，但已经提交的批次不保证回滚 +- 批量创建新表时，任务按顺序执行；某个任务失败后会保留失败表和错误信息，不应假设前面已完成的表会被撤销 -| 现象 | 可能原因 | -| -------------- | ------------------------------------------------ | -| 部分列没有导入 | 文件列名和表字段名不匹配，或列被取消映射 | -| 导入失败 | 非空字段为空、类型不匹配、主键冲突或唯一约束冲突 | -| 中文乱码 | 文件编码和解析方式不一致 | -| 日期错误 | 文件中的日期格式无法被目标数据库识别 | +## 相关功能 + + + + 在两个连接、数据库或引擎之间复制表数据。 + + + 把结构、数据和对象导出为 SQL 文件。 + + + 了解只读保护、生产保护和数据库权限的边界。 + + diff --git a/docs/content/docs/table-import.mdx b/docs/content/docs/table-import.mdx index da770bcc80..0a1e5eb2c7 100644 --- a/docs/content/docs/table-import.mdx +++ b/docs/content/docs/table-import.mdx @@ -1,93 +1,132 @@ --- title: Table Import -description: Import CSV, TSV, JSON, or Excel files into a table with reviewed column mapping and import mode. +description: Use a guided workflow to import CSV, TSV, text, JSON, or Excel data into an existing table or create new tables in batches. --- -Table Import writes a local file into a selected database table. Use it for one-off test data, operational data backfills, or moving data out of spreadsheet tools. +Table Import writes file data into database tables. DBX parses and previews the source first, then asks you to review parsing options, the target, column mappings, and execution settings before any rows are written. + +Import performs real database writes. Connection read-only protection blocks the operation, but database privileges remain the final boundary. Verify the target connection, target table, and backup plan before importing into production. + +## Target Modes + +| Target mode | Behavior | Typical use | +| --- | --- | --- | +| Existing table | Loads target columns and maps source fields; supports append or truncate-then-import | Backfills, test data restoration, and sample data replacement | +| Create new table | Infers column types from preview data and lets you edit the table name, column names, and types | Fast file-to-table workflows, spreadsheet migration, and multi-file imports | + +Create-table mode accepts multiple files at once. Excel workbooks are expanded into separate tasks per worksheet. DBX suggests a table name for each file or sheet and requires the final names to be unique. Tasks run sequentially and keep independent previews, mappings, and type settings. ## Supported Files -| Format | Details | -| ------ | ------------------------------------------------------------ | -| CSV | Comma-separated text for general data exchange | -| TSV | Tab-separated text, useful when values contain commas | -| JSON | JSON arrays exported from APIs or scripts | -| Excel | `.xlsx`, `.xlsm`, or `.xls` files; DBX reads the first sheet | +| Format | Details | +| --- | --- | +| CSV | Comma-delimited by default, with configurable header row, row range, and encoding | +| TSV | Tab-delimited text | +| Delimited text | Files such as `.txt` with a custom delimiter | +| JSON | A single object, object rows, or array rows; the shape can be selected explicitly | +| Excel | `.xlsx`, `.xlsm`, and `.xls`, with worksheet selection | -DBX previews the first 50 rows before import. Empty CSV/TSV cells are treated as `NULL`. JSON imports can be a single object, an array of objects, or an array of arrays; mixed object and array rows are rejected. +Desktop reads selected local files directly. Docker/Web uploads browser-selected files to temporary server storage, then releases the prepared source after preview and import finish. -## Import Workflow +## Import Wizard - ### Select the Target Table + ### Choose Files and Target Mode - Right-click the target table in the sidebar and choose **Import Data**. + Opening the action from a table preselects that table. You can instead create a new table and select one or more files. - ### Choose a File + ### Configure Parsing - Select a CSV, TSV, JSON, or Excel file. + Review encoding, title row, data range, worksheet, JSON shape, empty-string behavior, and whitespace trimming. ### Review Column Mapping - DBX tries to match file columns to table columns by name. Check primary keys, required fields, dates, and numeric values. + Map source fields to an existing table, or review inferred names and data types for a new table. Use the data preview to verify real values. - ### Choose Import Mode + ### Review the Plan - Select append or truncate-then-import. Truncate mode removes existing target data first. + Confirm the connection, database, schema, table name, import mode, mapping count, estimated row count, and batch size. - ### Run and Inspect + ### Run and Inspect Results - After import, check inserted rows, failures, and the resulting table data. + The execution view reports reading and writing phases, imported rows, byte progress, elapsed time, errors, and cancellation state. -## Import Modes +## Parsing Options -| Mode | Behavior | Best For | -| -------------------- | ------------------------------------------------- | -------------------------------------------------- | -| Append | Keep existing data and insert new rows | Backfills and sample data | -| Truncate then import | Remove existing rows first, then insert file data | Rebuilding test tables or replacing temporary data | +### Text Encoding -Truncate-then-import deletes existing rows from the target table. Confirm backups and impact before using it on production data. +CSV, TSV, and delimited text support auto detection, UTF-8, GBK, UTF-16 LE, and UTF-16 BE. If detection is wrong, select an encoding manually and recheck the preview. -Imports run in batches. The default batch size is 500 rows, and the progress view reports imported rows, total rows, errors, and cancellation state. +### Row Range -## Column Mapping Rules +- **Title row** chooses the row used for field names +- **Data start row** skips leading notes or blank rows +- **Last data row** limits the import; `0` reads to end of file +- **Preview rows** controls the mapping preview only, not the final import size -- Exact column names are matched first -- Normalized names also match when spacing, underscores, hyphens, or case differ -- A source column can be skipped +### Value Handling + +- **Trim values** removes surrounding whitespace from text values +- **Empty string as NULL** is enabled by default; disable it to preserve empty strings +- **JSON shape** can be detected automatically or forced to object rows or array rows +- **Worksheet** selects an Excel sheet; batch create mode creates an independent task for each sheet + +## Mapping and Table Creation + +For existing tables, DBX first matches exact names, then normalized names. Normalization ignores case and differences in spaces, underscores, and hyphens. + +- Source columns can be skipped - A target column cannot be mapped more than once -- At least one column must be mapped before import can start +- At least one column must be mapped +- Required unmapped columns need a default, auto-generated behavior, or nullable definition + +For new tables, source columns initially map to same-name targets and DBX suggests database-specific types from preview values. Suggestions are only a starting point; review dates, precision, long text, JSON, binary values, and engine-specific types before execution. + +## Modes and Batches + +| Option | Behavior | +| --- | --- | +| Append | Keeps existing rows and inserts new ones | +| Truncate then import | Clears the target table on supported paths before writing file data | +| Batch size | Controls rows written per batch; the default is 500 | + +New-table and multi-file imports always use append because each target is created by the current task. Truncate-then-import is destructive, and transaction or `TRUNCATE` semantics differ by database. Do not assume every completed operation will be rolled back after a later failure. ## Database Coverage -Table import is available for MySQL, PostgreSQL, SQLite, DuckDB, ClickHouse, SQL Server, Oracle, Doris, StarRocks, Redshift, DM, GaussDB, KingBase, HighGo, Vastbase, GoldenDB, and Access. +DBX exposes Table Import through the driver capability manifest. Only connections that implement column discovery, table creation or writing, and required type conversion enable the action. Specialized Redis, MongoDB, search, vector, message queue, and configuration-center workspaces use their own workflows instead of this relational table importer. -## Before Importing +Being able to connect does not imply Table Import support. If the action is absent, check the database type, driver mode, and DBX version before treating it as a privilege problem. -- Confirm whether the first row contains column names -- Check file encoding -- Verify date, number, and boolean formats -- Ensure required fields have values -- Check for primary key and unique index conflicts -- Import parent tables before child tables when foreign keys are involved +## Failure and Cancellation -## Troubleshooting +- Parsing failures usually indicate an incorrect encoding, delimiter, title row, JSON shape, or worksheet setting +- Write failures usually come from type mismatches, required columns, key conflicts, privileges, or target schema differences +- Cancellation stops later batches, but already committed batches are not guaranteed to roll back +- Batch create tasks run sequentially; a failed task keeps its error state, while previously completed tables are not automatically removed -| Symptom | Possible Cause | -| ------------------------ | ------------------------------------------------------------------------------------------ | -| Some columns are skipped | File column names do not match table columns, or the mapping was disabled | -| Import fails | Required value missing, type mismatch, primary key conflict, or unique constraint conflict | -| Text is garbled | File encoding does not match parser settings | -| Dates are wrong | Date format is not recognized by the target database | +## Related Features + + + + Copy table data between connections, databases, or engines. + + + Export structure, data, and supported objects as SQL. + + + Understand read-only protection, production protection, and database privilege boundaries. + + diff --git a/docs/content/docs/table-structure.cn.mdx b/docs/content/docs/table-structure.cn.mdx index 3e0a1782cb..2436bd4938 100644 --- a/docs/content/docs/table-structure.cn.mdx +++ b/docs/content/docs/table-structure.cn.mdx @@ -1,77 +1,144 @@ --- title: 表结构编辑器 -description: 可视化编辑表字段和索引，并在保存前预览 DDL。 +description: 可视化查看和修改字段、索引、外键与触发器，并在执行前审查数据库方言对应的 DDL。 --- -表结构编辑器用于修改单张表的字段、索引和约束。它适合小范围结构调整，也适合在不手写 DDL 的情况下生成可审查的变更 SQL。 +表结构编辑器把单表元数据和变更草稿放在持久化标签页中。DBX 会根据数据库 capability 只开放能够可靠生成的操作，并在保存前展示最终 DDL。 -表结构编辑器目前面向 MySQL、PostgreSQL、SQLite、SQL Server 和 ClickHouse 开启。其他数据库仍可能在结构浏览器中展示 DDL，但当 DBX 无法可靠生成安全变更时，不会显示可视化编辑器。 +## 打开方式 -## 可以编辑什么 +- 右键表选择**查看结构**或**编辑结构** +- 从字段节点直接打开并定位对应字段 +- 从索引节点直接打开并定位对应索引 +- 从数据表格的表信息区域打开结构标签 +- 从对象浏览器或 DDL 入口打开同一张表 -| 对象 | 支持操作 | -| ------ | ------------------------------------------------------------------ | -| 字段 | 新增、删除、重命名和修改字段；修改类型、长度、默认值、可空性和注释 | -| 主键 | 添加、修改或移除主键字段 | -| 索引 | 新增、删除和重建索引；配置索引类型、包含列、WHERE 过滤和注释 | -| 注释 | MySQL/PostgreSQL 支持字段和索引注释写入 | -| 列顺序 | 可视化调整列顺序；DBX 会生成对应的 ALTER 语句 | +编辑器会保留当前标签、滚动位置、列宽和本地字段顺序，便于在结构与数据之间切换。 -## 编辑器界面 +## 结构标签 -表结构编辑器以持久化标签页形式打开，而非模态对话框： +| 标签 | 主要内容 | +| --- | --- | +| 字段 | 名称、类型、长度/精度、可空、默认值、主键、自增、字符集、排序规则、注释 | +| 索引 | 名称、字段、类型、唯一、包含列、过滤条件、注释和重建入口 | +| 外键 | 本地字段、目标表/字段、`ON DELETE`、`ON UPDATE` | +| 触发器 | 触发器元数据、源码和数据库支持的创建/修改/删除 | +| DDL | 当前表定义或驱动生成的结构 SQL | -- **类型 + 长度分列**：数据类型和长度/精度分离为独立列，配有可搜索的下拉选择器 -- **可调整列宽**：拖拽列边框调整编辑器布局 -- **语法高亮**：SQL 预览使用 Shiki 语法高亮 -- **DDL 能力矩阵**：编辑器了解每种数据库支持的 DDL 操作，仅启用相关控件 +数据库未提供某类元数据时，对应标签会隐藏、只读或显示能力说明。 -不同数据库的 DDL 能力不完全一致，DBX 会按当前连接类型生成对应语法。 +## 字段编辑 -## 工作流 +根据数据库能力，可以： + +- 新增字段，或插入到当前选中字段之后 +- 删除、重命名和修改字段 +- 修改类型、长度、精度、Scale 和数据库专属长度单位 +- 修改 `NULL`、默认值、主键、自增、字符集、排序规则和注释 +- 使用常见默认值快捷选项 +- 拖拽字段调整顺序 + +列重排有两种语义： + +- MySQL 等支持物理列顺序的数据库会生成真正的顺序变更 DDL +- 部分数据库只在 DBX 中保存本地显示顺序，不修改数据库物理结构 + +创建新表时，可以使用设置中的预设字段快速加入常见主键、时间戳或审计字段。 + +## 索引、外键与触发器 + +索引能力按数据库方言开放，例如： + +- 创建、删除或重建索引 +- 普通、唯一和数据库专属索引类型 +- PostgreSQL / SQL Server 等支持的包含列或过滤条件 +- 索引注释（数据库支持时） +- 自动生成新索引名称，并允许修改 + +外键编辑包括字段映射和更新/删除动作。触发器编辑依赖数据库源码读取和安全 DDL 生成能力；不支持直接修改时仍可以查看源码或复制 DDL。 + +## DDL 预览 + +编辑不会立即写入数据库。保存前，DBX 会根据当前方言生成并高亮： + +- `ALTER TABLE ... ADD/DROP/RENAME/MODIFY COLUMN` +- 默认值、`NULL`、主键和注释变更 +- `CREATE INDEX`、`DROP INDEX`、重建索引 +- 外键和触发器相关 DDL +- SQLite 等需要重建表时的迁移步骤 + +可以复制完整 DDL，在代码仓库中审查或交给迁移工具执行。 + +字段删除、类型转换、收紧 `NULL`、修改主键、重排物理字段和重建表都可能锁表或丢失数据。生产环境先检查执行计划、锁影响、备份和回滚方案。 + +## 保存流程 - ### 打开表结构 + ### 读取最新结构 - 在侧边栏右键表，选择查看或编辑结构。 + 打开编辑器后确认字段、索引、外键和触发器已经加载完成。其他客户端刚修改过表时先刷新。 - ### 修改字段或索引 + ### 创建本地草稿 - 在可视化界面中添加、修改或删除字段和索引。修改会先暂存在本地。 + 新增、修改、删除或重排对象。删除操作会以待删除状态显示，尚未执行。 - ### 查看 SQL 预览 + ### 审查 DDL - 保存前检查 DBX 生成的 `ALTER TABLE`、`CREATE INDEX`、`DROP INDEX` 等语句。 + 检查对象限定名、字段类型、默认值、约束、索引和每条语句顺序。 - ### 确认执行 + ### 执行并刷新 - 确认 SQL 没有问题后再应用到数据库。 + 确认后执行。生产范围会再次进入生产写入确认；成功后重新读取表结构。 -删除字段、修改字段类型、修改 NULL 约束都可能影响现有数据。生产环境执行前建议先备份，并确认应用代码是否依赖旧结构。 +## 方言与能力差异 -## 数据库差异 +| 方言/数据库 | 典型行为 | +| --- | --- | +| MySQL / MariaDB 兼容 | 字段属性、物理重排、主键、索引、外键和注释覆盖较完整 | +| PostgreSQL / Gauss 系兼容 | 字段类型/默认值/可空/注释、索引包含列/过滤、外键等按方言生成 | +| SQLite | 部分复杂字段变更通过安全的表重建策略实现 | +| DuckDB | 支持常见字段与索引操作，但能力不同于 SQLite | +| SQL Server | 支持字段和索引变更，部分默认约束、包含列和过滤索引使用专属语法 | +| Oracle / 达梦等 | 使用 Oracle 风格字段、注释和索引 DDL；整数长度等无意义选项会禁用 | +| ClickHouse / Manticore / InfluxDB 等 | 只开放对应实现已验证的子集 | +| JDBC/Agent | 根据识别出的方言映射；无法可靠识别时保持只读 | -| 数据库 | 说明 | -| --------------- | ---------------------------------------------------------------------- | -| MySQL / MariaDB | 支持新增、删除、修改字段，以及新增/删除索引 | -| PostgreSQL | 支持字段重命名、类型、默认值、NULL 约束和注释变更，以及新增/删除索引 | -| SQLite | 支持新增字段、删除字段和重命名字段；更复杂的字段修改会提示无法安全处理 | -| SQL Server | 支持常见单表结构操作 | -| 其他引擎 | 当 DBX 不显示可视化编辑器时，使用生成 DDL、Schema 对比或手写 SQL | +不要根据“能连接”推断“所有 DDL 都能编辑”。当前范围以 [数据库支持](/cn/docs/databases) 和编辑器实际控件为准。 + +## 并发与恢复 + +- 编辑草稿基于打开时读取的元数据，不会自动合并其他客户端的结构变更 +- 执行失败后，数据库可能已经成功执行前面的部分语句 +- SQLite 重建和多语句 DDL 的原子性取决于数据库和驱动 +- 刷新会重新读取结构，未保存草稿可能需要先确认放弃 +- 只读连接会阻止保存；生产连接每次写入都需要明确确认 ## 使用建议 -- 小改动可以直接使用表结构编辑器 -- 大规模结构迁移建议生成 SQL 后进入代码仓库审查 -- 多环境同步建议配合 [Schema 对比](/cn/docs/schema-diff) -- 不确定影响范围时，先通过 [数据库导出](/cn/docs/database-export) 备份 +- 小范围单表修改可以直接使用编辑器 +- 大规模迁移把复制的 DDL 纳入版本控制和 Review +- 多环境对齐使用 [Schema 对比](/cn/docs/schema-diff) +- 高风险操作前使用 [数据库导出](/cn/docs/database-export) 或 [定时数据库备份](/cn/docs/database-backup) +- 修改字段前结合 [字段血缘](/cn/docs/field-lineage) 和应用代码搜索评估影响 + + + + 对比多个环境并生成部署脚本。 + + + 查看外键、视图和历史 SQL 中的字段关系。 + + + 配置只读连接和生产 DDL 确认。 + + diff --git a/docs/content/docs/table-structure.mdx b/docs/content/docs/table-structure.mdx index 304f886f4f..2c28be5117 100644 --- a/docs/content/docs/table-structure.mdx +++ b/docs/content/docs/table-structure.mdx @@ -1,77 +1,144 @@ --- title: Table Structure Editor -description: Edit table columns and indexes visually, then preview DDL before applying changes. +description: Inspect and edit columns, indexes, foreign keys, and triggers and review dialect-specific DDL before execution. --- -The table structure editor modifies columns, indexes, and constraints for a single table. Use it for focused structure changes or to generate reviewable DDL without writing it by hand. +The table structure editor keeps single-table metadata and a change draft in a persistent tab. DBX enables only operations that the active database capability can generate reliably and shows the final DDL before save. -The structure editor is enabled for MySQL, PostgreSQL, SQLite, SQL Server, and ClickHouse. Other databases may still expose DDL through the schema browser, but DBX does not show the visual editor when it cannot generate safe changes. +## Open the Editor -## What You Can Edit +- Right-click a table and choose **View structure** or **Edit structure** +- Open from a column node and focus that column +- Open from an index node and focus that index +- Open from table information in the data grid +- Open the same table from Object Browser or a DDL action -| Object | Supported Actions | -| ------------ | ---------------------------------------------------------------------------------------------------- | -| Columns | Add, delete, rename, and modify columns; change type, length, default, nullable, and comments | -| Primary Key | Add, modify, or remove primary key columns | -| Indexes | Add, delete, and rebuild indexes; configure index type, included columns, WHERE filter, and comments | -| Comments | MySQL/PostgreSQL can write column and index comments | -| Column Order | Reorder columns visually; DBX generates the appropriate ALTER statements | +The editor retains the active tab, scroll position, column widths, and local column order while you move between structure and data. -## Editor Interface +## Structure Tabs -The table structure editor opens as a persistent tab, not a modal dialog: +| Tab | Main contents | +| --- | --- | +| Columns | Name, type, length/precision, nullability, default, primary key, identity, charset, collation, comment | +| Indexes | Name, columns, type, unique state, included columns, filter, comment, and rebuild action | +| Foreign keys | Local columns, target table/columns, `ON DELETE`, and `ON UPDATE` | +| Triggers | Trigger metadata, source, and supported create/edit/drop actions | +| DDL | Current table definition or driver-generated structure SQL | -- **Type + Length columns**: Data type and length/precision are split into separate columns with searchable select dropdowns -- **Resizable columns**: Drag column borders to adjust the editor layout -- **Syntax highlighting**: SQL preview uses Shiki syntax highlighting -- **DDL capability matrix**: The editor knows which DDL operations each database supports and only enables relevant controls +When the database does not provide a metadata class, the related tab is hidden, read-only, or displays a capability explanation. -Database engines differ in DDL capabilities. DBX generates SQL for the active connection type. +## Column Editing -## Workflow +Depending on database capability, you can: + +- Add a column or insert after the current selection +- Drop, rename, and alter columns +- Change type, length, precision, scale, and database-specific length units +- Change `NULL`, default, primary key, identity, charset, collation, and comment +- Use quick picks for common default values +- Drag columns to change order + +Column reorder has two meanings: + +- MySQL and other databases with physical column-order DDL generate a real reorder +- Some databases save only the local display order in DBX without changing physical structure + +New-table creation can use preset fields from settings for common primary keys, timestamps, or audit columns. + +## Indexes, Foreign Keys, and Triggers + +Index capabilities vary by dialect and can include: + +- Create, drop, or rebuild an index +- Standard, unique, and database-specific index types +- Included columns or filters on PostgreSQL, SQL Server, and similar databases +- Index comments where supported +- Automatic names for new indexes with editable values + +Foreign-key editing covers column mappings and update/delete actions. Trigger editing depends on source retrieval and safe DDL generation; unsupported databases can still expose source or copyable DDL. + +## DDL Preview + +Edits do not immediately change the database. Before save, DBX generates highlighted dialect-specific SQL such as: + +- `ALTER TABLE ... ADD/DROP/RENAME/MODIFY COLUMN` +- Default, `NULL`, primary-key, and comment changes +- `CREATE INDEX`, `DROP INDEX`, and rebuild operations +- Foreign-key and trigger DDL +- Table-rebuild steps when SQLite requires them + +Copy the complete DDL for code review or execution through a migration tool. + +Dropping columns, converting types, tightening `NULL`, changing primary keys, physical reorder, and table rebuilds can lock tables or lose data. Review execution impact, backups, and rollback plans in production. + +## Save Workflow - ### Open Table Structure + ### Read the latest structure - Right-click a table in the sidebar and open its structure view. + Confirm that columns, indexes, foreign keys, and triggers are loaded. Refresh first if another client recently changed the table. - ### Edit Columns or Indexes + ### Build a local draft - Add, modify, or remove columns and indexes in the visual editor. Changes are staged locally first. + Add, edit, remove, or reorder objects. Deletions remain pending and are not executed yet. - ### Review SQL Preview + ### Review DDL - Before saving, review generated statements such as `ALTER TABLE`, `CREATE INDEX`, and `DROP INDEX`. + Verify qualification, types, defaults, constraints, indexes, and statement order. - ### Apply Changes + ### Execute and refresh - Execute the SQL only after confirming it matches your intent. + Execute after review. Production scope enters production-write confirmation again, and DBX reloads structure after success. -Dropping columns, changing column types, and changing nullable constraints can affect existing data. Back up production databases first and confirm application code does not depend on the old structure. +## Dialect and Capability Differences -## Engine Differences +| Dialect/database | Typical behavior | +| --- | --- | +| MySQL / MariaDB compatible | Broad column properties, physical reorder, primary key, index, foreign key, and comment coverage | +| PostgreSQL / Gauss-compatible | Dialect-aware type/default/null/comment, included/filtered indexes, foreign keys, and related DDL | +| SQLite | Some complex column changes use a safe table-rebuild strategy | +| DuckDB | Supports common column and index operations with behavior distinct from SQLite | +| SQL Server | Column and index changes with dedicated syntax for defaults, included columns, and filtered indexes | +| Oracle / Dameng and similar | Oracle-style column, comment, and index DDL; irrelevant integer-length controls are disabled | +| ClickHouse / Manticore / InfluxDB and others | Only the verified implemented subset is enabled | +| JDBC/Agent | Maps through a recognized dialect and stays read-only when the dialect cannot be identified reliably | -| Engine | Notes | -| --------------- | ---------------------------------------------------------------------------------------------- | -| MySQL / MariaDB | Add, delete, and modify columns; add and delete indexes | -| PostgreSQL | Rename columns, change type/default/nullability/comments, and add/delete indexes | -| SQLite | Add, delete, and rename columns; more complex existing-column edits are blocked with a warning | -| SQL Server | Focused editor support for common table structure operations | -| Other engines | Use generated DDL, Schema Diff, or manual SQL when DBX does not expose the visual editor | +Do not assume that every DDL feature is editable because a database can connect. Use [Database Support](/en/docs/databases) and the actual editor controls as the current source of truth. + +## Concurrency and Recovery + +- Drafts are based on metadata read when the editor opened and do not merge external schema changes automatically +- If execution fails, earlier statements may already have succeeded +- Atomicity of SQLite rebuilds and multi-statement DDL depends on database and driver behavior +- Refresh reloads structure and may require discarding an unsaved draft +- Read-only connections block save, and production writes require explicit confirmation every time ## Recommendations -- Use the editor for small, focused changes -- For large migrations, generate SQL and review it in your code repository -- For environment sync, use [Schema Diff](/en/docs/schema-diff) -- When impact is uncertain, back up first with [Database Export](/en/docs/database-export) +- Use the editor for focused, single-table changes +- Put copied DDL into version control and review for larger migrations +- Use [Schema Diff](/en/docs/schema-diff) to align environments +- Use [Database Export](/en/docs/database-export) or [Scheduled Database Backups](/en/docs/database-backup) before risky changes +- Combine [Field Lineage](/en/docs/field-lineage) with application-code search before changing important columns + + + + Compare environments and generate deployment scripts. + + + Inspect relationships from foreign keys, views, and query history. + + + Configure read-only connections and production DDL confirmation. + + diff --git a/docs/content/docs/web-api.cn.mdx b/docs/content/docs/web-api.cn.mdx index ce49ad304a..ba38a915d5 100644 --- a/docs/content/docs/web-api.cn.mdx +++ b/docs/content/docs/web-api.cn.mdx @@ -1,6 +1,6 @@ --- title: Web API 参考 -description: DBX Web 与 Docker 部署使用的 HTTP API，适用于自动化与集成场景。 +description: DBX Web 与 Docker UI 使用的内部 HTTP API，包括认证、查询、后台任务、上传和下载边界。 --- 这套 API 主要服务于 DBX Web 界面，以及 MCP Web 模式等内部工具。它不是单独对外承诺的集成契约，路由和字段可能随版本调整。做脚本或 Agent 集成时，优先使用 [@dbx-app/cli](/cn/docs/cli) 或 [@dbx-app/mcp-server](/cn/docs/mcp)。 @@ -71,6 +71,8 @@ Content-Type: application/json 登录成功后，响应会返回 `Set-Cookie: dbx_session=...`。后续请求带上这个 Cookie 即可。 +连续 5 次登录失败会触发约 60 秒锁定。会话保存在当前 Web 进程内，进程重启后需要重新登录；Cookie 使用 `HttpOnly` 和 `SameSite=Lax`，路径会跟随 `DBX_PUBLIC_BASE_PATH`。 + ### 退出登录 ```http @@ -87,12 +89,18 @@ Cookie: dbx_session=... | `DBX_PORT` | 修改监听端口，默认 `4224` | | `DBX_DATA_DIR` | 存放 `dbx.db` 的数据目录 | | `DBX_PUBLIC_BASE_PATH` | 在子路径下提供服务，例如 `/dbx` | +| `DBX_MAX_UPLOAD_MB` | 调整通用请求/上传大小上限，默认 1024 MB | +| `DBX_AGENT_DIR` | 覆盖 Web 端 Agent/驱动目录，默认位于数据目录下的 `agents` | +| `DBX_STATIC_DIR` | 覆盖 Web 静态文件目录 | ## 请求约定 -- JSON 请求体字段名默认使用 `camelCase`。 -- `GET` 请求的查询参数使用 `snake_case`，例如 `connection_id`。 +- 字段命名由具体 Rust 请求结构决定，既有 `camelCase`，也有连接配置使用的 `snake_case`；不要对整个 API 套用单一命名规则。 +- `GET` 查询参数通常使用 `snake_case`，例如 `connection_id`，但仍应以当前路由实现为准。 - 出错时通常返回带 `error` 字段的 JSON 和对应 HTTP 状态码。 +- 导出、导入、数据传输、SQL 文件和 AI 等长任务通常使用“启动请求 + SSE 进度 + 取消/下载”组合，不是一个同步响应。 + +只有数据网格提取器当前提供受测试的局部 OpenAPI 文档：`/api/query/data-grid-extractor-openapi.json`。它不覆盖完整 DBX Web API，也不代表其它路由已经版本化。 ## 连接相关 API @@ -309,6 +317,16 @@ Content-Type: application/json MCP Server 会自动处理登录和会话 Cookie。 +CLI 同样支持 `DBX_WEB_URL` 和 `DBX_WEB_PASSWORD`。两者都复用 Web 后端的连接、驱动、只读保护、生产保护和数据库权限，比复制内部路由字段更容易随 DBX 升级。 + +## 写入、安全和文件边界 + +- API 认证只证明请求来自已登录会话，不会替代数据库权限 +- 查询、导入和传输路径会继续检查连接只读保护；生产保护和 SQL 风险策略在对应核心路径中执行 +- 浏览器上传的表导入和 SQL 文件会写入服务器临时目录，不是浏览器电脑的原始路径 +- Web 导出先生成服务器临时文件，再通过下载路由返回并清理 +- 反向代理应保留 Cookie、SSE 流和较长请求超时，并限制公网暴露范围 + ## 示例脚本 仓库内示例： diff --git a/docs/content/docs/web-api.mdx b/docs/content/docs/web-api.mdx index 82da55dccc..73f6882da2 100644 --- a/docs/content/docs/web-api.mdx +++ b/docs/content/docs/web-api.mdx @@ -1,6 +1,6 @@ --- title: Web API Reference -description: HTTP API used by DBX Web and Docker deployments for automation and integrations. +description: Internal HTTP APIs used by the DBX Web and Docker UI, including authentication, queries, background jobs, uploads, and downloads. --- This API powers the DBX Web UI and internal tooling such as the MCP Web backend. It is not a separate public integration contract. Endpoints and payloads may change between releases. For scripting and agent workflows, prefer [@dbx-app/cli](/en/docs/cli) or [@dbx-app/mcp-server](/en/docs/mcp) when possible. @@ -71,6 +71,8 @@ Content-Type: application/json On success, the response sets `Set-Cookie: dbx_session=...`. Reuse that cookie on later requests. +Five consecutive login failures trigger an approximately 60-second lockout. Sessions live in the current Web process and require login again after restart. The cookie is `HttpOnly`, uses `SameSite=Lax`, and follows `DBX_PUBLIC_BASE_PATH` for its path. + ### Logout ```http @@ -87,12 +89,18 @@ Cookie: dbx_session=... | `DBX_PORT` | Change the listen port (default `4224`) | | `DBX_DATA_DIR` | Data directory containing `dbx.db` | | `DBX_PUBLIC_BASE_PATH` | Serve DBX under a subpath such as `/dbx` | +| `DBX_MAX_UPLOAD_MB` | Override the general request/upload limit; default 1024 MB | +| `DBX_AGENT_DIR` | Override the Web Agent/driver directory; defaults to `agents` under the data directory | +| `DBX_STATIC_DIR` | Override the Web static asset directory | ## Request Format -- JSON request bodies use `camelCase` field names unless noted otherwise. -- Query parameters for `GET` routes use `snake_case`, for example `connection_id`. +- Field naming follows each Rust request type. Some bodies use `camelCase`, while connection configuration still contains `snake_case`; do not apply one naming convention to the whole API. +- `GET` query parameters commonly use `snake_case`, such as `connection_id`, but the current route implementation remains authoritative. - Errors usually return JSON with an `error` field and an HTTP status code. +- Long-running export, import, transfer, SQL-file, and AI operations commonly use a start request plus SSE progress and cancel/download routes rather than one synchronous response. + +Only the data-grid extractor currently exposes a tested, scoped OpenAPI document at `/api/query/data-grid-extractor-openapi.json`. It does not cover the complete DBX Web API or version the other routes. ## Connection APIs @@ -309,6 +317,16 @@ When MCP runs against a deployed Web instance, set: The MCP server handles login and session cookies for you. +CLI supports the same `DBX_WEB_URL` and `DBX_WEB_PASSWORD` variables. Both integrations reuse server-side connections, drivers, read-only protection, production protection, and database privileges, making them easier to maintain across DBX upgrades than copied internal route payloads. + +## Writes, Safety, and File Boundaries + +- API authentication proves only that the request belongs to a logged-in session; it does not replace database privileges +- Query, import, and transfer paths continue to enforce connection read-only protection, while production and SQL-risk policy apply in their corresponding core paths +- Browser-selected table-import and SQL files are uploaded into server temporary storage, not read from arbitrary client paths +- Web exports create a temporary server file, return it through a download route, and then clean it up +- Reverse proxies should preserve cookies and SSE streaming, allow appropriate long-running timeouts, and limit public exposure + ## Example Scripts See the repository examples: diff --git a/docs/content/docs/what-is-dbx.cn.mdx b/docs/content/docs/what-is-dbx.cn.mdx index ed45754ba0..7928953aa6 100644 --- a/docs/content/docs/what-is-dbx.cn.mdx +++ b/docs/content/docs/what-is-dbx.cn.mdx @@ -1,70 +1,153 @@ --- title: 什么是 DBX？ -description: DBX 是一个开源数据库工作台，覆盖连接管理、SQL 编辑、数据浏览、结构工具、AI 助手和自托管访问。 +description: DBX 是一个开源、轻量的数据库与数据基础设施工作台，覆盖 70+ 种连接、桌面与自托管访问、AI、CLI 和 MCP。 --- -DBX 是一个开源数据库工作台。它把日常数据库工作里的高频动作放在同一个界面里：连接数据库、写 SQL、查看和编辑数据、浏览结构、对比 Schema、导入导出数据，以及在需要时让 AI 辅助分析。 +DBX 是一个开源、轻量的数据库与数据基础设施工作台。它把连接管理、对象浏览、SQL 编辑、数据修改、结构工具、专项控制台和自动化入口放在同一个工作区中，支持 70+ 种数据库及数据系统。 -它同时提供桌面应用和 Docker 版本。桌面应用适合本机开发和日常连接管理；Docker 版本适合在服务器上自托管，通过浏览器访问同一套能力。 +DBX 不会强行把所有系统都抽象成 SQL 数据库：关系型数据库使用查询编辑器、数据表格和 Schema 工具；Redis、MongoDB、向量数据库、消息队列、etcd、ZooKeeper、Nacos 等系统则使用更符合其数据模型的专项界面。 -![DBX 截图](/screenshot-dark.png) +如果你已经决定开始使用，可以直接阅读 [快速开始](/cn/docs/getting-started)。如果你正在确认某个引擎或功能是否支持，请查看 [数据库支持与功能矩阵](/cn/docs/databases)。 -## 适合的场景 +![DBX 深色界面截图](/screenshot-dark.png) + +## DBX 解决什么问题 - - 使用 SQL 编辑器编写、格式化和执行查询，并通过查询历史快速找回之前的排查过程。 + + 集中管理本地、测试、预发和生产连接，并使用分组、颜色、置顶、搜索、只读和生产保护减少选错目标。 - - 在数据表格中筛选、排序、编辑、预览 SQL，再决定是否写入数据库。 + + 使用元数据补全、格式化、选中执行、查询历史、多结果和执行计划完成日常 SQL 工作。 - - 通过侧边栏浏览数据库、Schema、表、字段、索引、外键和触发器，适合接手陌生库时快速定位对象。 + + 在虚拟滚动表格中筛选、排序和编辑数据，并在写入前检查生成的 SQL。 - - 对比开发、测试、生产等环境之间的结构差异，生成可审查的同步 SQL。 + + 浏览数据库对象，编辑表结构，对比 Schema，查看 ER 图和字段血缘，并生成可审查的 DDL。 + + + 导入表格文件、跨连接传输数据、执行 SQL 文件，并按数据库能力导出结构和数据。 + + + 通过 CLI、MCP 或自托管后端，把已经配置的连接安全地接入终端、脚本和 AI 编程助手。 -## 主要能力 +## 支持的不只是 SQL 数据库 -| 能力 | 说明 | -| ------------ | ----------------------------------------------------------------------------------------------- | -| 多数据库连接 | 支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、DuckDB、ClickHouse、SQL Server、Oracle 等数据库 | -| SQL 编辑器 | 基于 CodeMirror 6，支持语法高亮、元数据补全、格式化、选中执行和查询历史 | -| 数据表格 | 虚拟滚动、行内编辑、WHERE/ORDER BY 控制、SQL 预览和多格式导出 | -| 结构工具 | 结构浏览、表结构编辑、Schema 对比、ER 图、字段血缘、数据库导出和 SQL 文件执行 | -| 数据流转 | 表数据导入、数据传输、SQL 文件执行，以及支持进度和取消的 SQL 导出 | -| 专项浏览器 | Redis 键值浏览和 MongoDB 文档浏览 | -| AI 与自动化 | 根据连接元数据生成 SQL、解释查询、优化语句、辅助修复错误，并通过 MCP 暴露连接给编程助手 | -| 自托管访问 | Docker 版本可部署在服务器上，通过浏览器访问 DBX | +DBX 的连接选择器按实际工作方式组织数据库和数据系统。不同类别会进入不同的工作区，而不是只显示一个通用查询框。 -## 设计取向 +| 类别 | 代表系统 | DBX 中的主要体验 | +| --- | --- | --- | +| 关系型与兼容协议 | MySQL、PostgreSQL、SQLite、Oracle、SQL Server、达梦、openGauss、GaussDB | SQL 编辑器、数据表格、对象树、表结构、Schema 工具 | +| 分析型与数据仓库 | ClickHouse、Doris、StarRocks、Databricks、Snowflake、Trino、BigQuery | 查询、结果分析、元数据浏览，以及驱动支持的结构和导出能力 | +| 文档、键值与搜索 | MongoDB、Redis、Elasticsearch、Easysearch、HBase、Cassandra | 文档、键、索引或表族等专项浏览器 | +| 图、向量与 AI 数据 | Neo4j、Qdrant、Milvus、Weaviate、ChromaDB | 图数据库连接，以及向量集合浏览、检索和写入入口 | +| 时序系统 | QuestDB、TDengine、IoTDB、InfluxDB | 时序查询与系统对应的连接、对象和数据视图 | +| 消息队列 | Pulsar、Kafka、RocketMQ、RabbitMQ | Topic、订阅/消费者、消息、监控、权限或策略等能力 | +| 注册与配置中心 | etcd、ZooKeeper、Nacos | Key/ZNode 浏览、集群状态、访问控制、配置与服务管理 | +| 驱动扩展 | JDBCX、自定义 MySQL/PostgreSQL、可选 JDBC 插件 | 使用兼容协议或厂商 JDBC 驱动扩展连接范围 | -DBX 优先覆盖数据库客户端里的核心工作流，而不是把所有数据库管理场景都塞进一个复杂入口。它更关注这些细节： +具体数据库能使用哪些高级能力，取决于驱动、协议和数据库本身。以 [数据库支持](/cn/docs/databases) 中的功能矩阵为准；专项系统的入口与边界见 [专项工作台](/cn/docs/specialized-workspaces)。 -- **少切换上下文**：结构浏览、SQL 编辑、数据表格和结果查看尽量在同一工作区内完成。 -- **操作可审查**：涉及数据或结构变更时，尽量先展示将要执行的 SQL。 -- **多环境可区分**：连接颜色、置顶、搜索和上下文菜单帮助区分开发、测试和生产环境。 -- **轻量部署**：桌面版适合个人日常工作，Docker 版适合团队或服务器环境。 +## 一套工作流，多个使用入口 -## 数据与安全 +| 入口 | 适合场景 | 能力与边界 | +| --- | --- | --- | +| 桌面版 | 个人日常开发、本地数据库文件、完整工作台 | 提供本地文件、SQL 文件树/SQL 库、桌面 Deep Link 等操作系统集成 | +| Docker / Web | 服务器自托管、远程浏览器访问 | 共享大部分数据库工作流；文件路径指向服务器，部分本地文件和桌面集成功能不可用 | +| CLI | 终端、脚本、CI、Codex 工作流 | 列出连接和 Schema、描述表、执行查询、生成紧凑上下文，并可唤起桌面端打开表 | +| MCP Server | Claude Code、Cursor、Windsurf 等 AI 客户端 | 列出连接、读取结构、执行受策略约束的查询或命令，并可连接本地数据目录或 DBX Web | -- 连接配置保存在本机应用数据目录的 SQLite 数据库中，密码、SSH 密码、SSH 密钥密码等敏感字段会从普通连接配置中拆出，单独存放在 `connection_secrets` 表。 -- 配置导出支持 AES-GCM 加密，适合在多台设备之间迁移连接。 -- SSH 隧道可以连接私有网络或防火墙后的数据库。 -- AI Ask 模式不会执行生成的 SQL。Agent 和 MCP 流程会使用保守执行策略，并默认阻止危险 SQL。 +桌面版和 Web 版复用同一套 Rust 核心能力，但它们不是所有系统集成上的完全等价替代。选择部署方式时，应同时考虑数据库所在网络、文件位于本机还是服务器，以及是否需要桌面 Deep Link 或本地 SQL 文件管理。 + +## 从连接到自动化 + + + + ### 建立连接边界 + + 选择数据库类型，填写认证信息，并按需要配置 TLS、SSH、SOCKS5、HTTP 代理或 HTTP 隧道。为高风险连接启用只读或生产环境保护。 + + + + ### 先理解对象和上下文 + + 从侧边栏查看数据库、Schema、表、字段、索引、外键和数据库专属对象。陌生数据库可以先使用搜索、对象源码、ER 图或字段血缘建立上下文。 + + + + ### 查询、检查并修改 + + 在查询编辑器中执行 SQL，或在数据表格、文档/键值浏览器和专项控制台中完成对应操作。DBX 会在可行时展示 SQL 或请求内容，便于执行前审查。 + + + + ### 比较、迁移和复用 + + 使用 Schema 对比、表导入、数据传输、数据库导出、SQL 文件执行、查询历史和 SQL 库，把一次性操作变成可检查、可复用的流程。 + + + + ### 接入 AI 与自动化 + + 在应用内使用 AI Ask/Agent，或通过 CLI 和 MCP 把连接、Schema 上下文和查询能力提供给终端脚本与 AI 编程助手。 + + + + +## 核心能力地图 + +| 任务 | 代码中对应的产品能力 | 详细文档 | +| --- | --- | --- | +| 创建连接 | 连接分类、URL 解析、TLS、隧道/代理、只读、生产保护、驱动选择 | [快速开始](/cn/docs/getting-started)、[隧道/代理](/cn/docs/ssh-tunnel) | +| 编写和执行查询 | CodeMirror 6、元数据补全、格式化、执行目标、多结果、取消、历史 | [查询编辑器](/cn/docs/query-editor) | +| 查看和编辑结果 | 虚拟滚动、数据库侧过滤/排序、行内编辑、SQL 预览、多格式导出 | [数据表格](/cn/docs/data-grid) | +| 理解数据库结构 | 对象树、对象搜索、源码查看、表结构、Schema 对比、ER 图、字段血缘 | [结构浏览](/cn/docs/schema-browser)、[Schema 对比](/cn/docs/schema-diff) | +| 导入、传输和导出 | CSV/TSV/JSON/Excel 导入、跨连接传输、SQL 文件执行、数据库导出 | [表数据导入](/cn/docs/table-import)、[数据传输](/cn/docs/data-transfer) | +| 管理非关系型系统 | Redis、MongoDB、搜索、向量、HBase、消息队列、注册与配置中心工作台 | [专项工作台](/cn/docs/specialized-workspaces) | +| AI 与外部工具 | Ask/Agent、CLI、MCP、Web/Docker 后端 API | [AI 助手](/cn/docs/ai-assistant)、[CLI](/cn/docs/cli)、[MCP](/cn/docs/mcp) | +| 迁移个人配置 | 连接导入、加密配置导出、WebDAV/Gist/Gitee 同步、SQL 库同步 | [配置导出/导入](/cn/docs/config-export)、[云同步与备份](/cn/docs/cloud-sync) | + +## 安全模型 + +DBX 使用多层限制，而不是只依赖一个“危险操作确认”开关： + +- **数据库账号权限**始终是最终边界，建议生产环境使用最小权限账号。 +- **只读连接**会在核心查询执行路径阻止可识别的写入，并隐藏或禁用多个修改入口。 +- **生产环境保护**可以作用于整个连接或指定数据库；检测到写入时，每次都要求新的明确确认。 +- **可审查的变更**会在数据编辑、表结构、Schema 对比等流程中尽量先展示 SQL。 +- **AI Ask 模式**只生成回答，不执行 SQL；Agent 在生产环境中不会获得自动写入授权，而是把 SQL 放回编辑器供人工检查。 +- **MCP 策略**统一管理连接 allowlist 和“只读 / 数据读写 / 完全访问”三档权限，且不能绕过连接只读、生产保护和数据库账号权限。 +- **敏感配置**与普通连接 JSON 分开存储；配置导出可使用 AES-GCM 加密。 + +完整配置和各入口的行为见 [生产环境与写入安全](/cn/docs/production-safety)。 + +## 需要了解的边界 + + + DBX 是数据库工作台，不是托管数据库服务，也不能替代数据库账号权限、审计、备份和变更审批。数据库导出适合轻量备份或迁移，但大型生产库仍应使用数据库原生备份工具。AI 输出、自动生成的 SQL 和跨引擎数据迁移都需要人工审查。 + + +- 高级功能不会对所有数据库强行开放；不可靠的兼容路径会被隐藏或降级。 +- Docker/Web 中的本地路径属于服务器文件系统，不是浏览器所在电脑。 +- JDBC/Agent 数据库需要相应驱动或运行时，功能范围可能少于原生驱动。 +- [Web API](/cn/docs/web-api) 主要服务 DBX Web 和内部集成，不是稳定的公共契约；脚本和 AI 集成优先使用 CLI 或 MCP。 ## 下一步 - 从桌面应用或 Docker 版本开始，创建第一个数据库连接。 + 选择桌面版或 Docker，创建第一个连接并完成网络与安全配置。 - - 了解不同数据库引擎、兼容协议和 ODBC 场景的支持情况。 + + 查看连接类型、默认端口、驱动方式和高级功能矩阵。 - - 设置 API Key 后，在 SQL 编辑器中使用自然语言生成和解释查询。 + + 设置只读连接、生产保护、AI 与 MCP 权限边界。 + + + 根据终端脚本、Codex 或 AI 客户端场景选择 CLI 或 MCP。 diff --git a/docs/content/docs/what-is-dbx.mdx b/docs/content/docs/what-is-dbx.mdx index 5fc6d1df28..e7e785fd82 100644 --- a/docs/content/docs/what-is-dbx.mdx +++ b/docs/content/docs/what-is-dbx.mdx @@ -1,70 +1,153 @@ --- title: What is DBX? -description: DBX is an open-source database workspace for connections, SQL editing, data grids, schema tools, AI assistance, and self-hosted access. +description: DBX is an open-source, lightweight workspace for 70+ databases and data systems, with desktop and self-hosted access, AI, CLI, and MCP. --- -DBX is an open-source database workspace. It brings the daily database workflow into one place: connecting to databases, writing SQL, browsing and editing data, exploring schemas, comparing structures, importing and exporting data, and using AI assistance when it helps. +DBX is an open-source, lightweight workspace for databases and data infrastructure. It brings connection management, object browsing, SQL editing, data changes, schema tools, specialized consoles, and automation into one interface across more than 70 databases and data systems. -DBX is available as both a desktop app and a Docker deployment. Use the desktop app for local daily work, or self-host the Docker version when you want browser-based access from a server. +DBX does not force every system into a SQL-shaped interface. Relational databases use the query editor, data grid, and schema tools, while Redis, MongoDB, vector databases, message queues, etcd, ZooKeeper, Nacos, and similar systems use workspaces designed around their own data models. -![DBX Screenshot](/screenshot-dark.png) +If you are ready to use DBX, start with [Getting Started](/en/docs/getting-started). To check a specific engine or feature, use [Database Support and the feature matrix](/en/docs/databases). -## Where DBX Fits +![DBX dark interface screenshot](/screenshot-dark.png) + +## What DBX Helps You Do - - Write, format, and execute SQL, then use query history to return to previous investigation steps. + + Manage local, test, staging, and production connections with groups, colors, pins, search, read-only mode, and production protection. - - Filter, sort, edit, preview SQL, and decide when changes should be committed to the database. + + Use metadata completion, formatting, selected execution, query history, multiple results, and execution plans for daily SQL work. - - Browse databases, schemas, tables, columns, indexes, foreign keys, and triggers from the sidebar. + + Filter, sort, and edit data in a virtualized grid, then review generated SQL before writing changes. - - Compare dev, staging, and production schemas, then generate SQL you can review before syncing. + + Browse database objects, edit table structures, compare schemas, inspect ER diagrams and lineage, and generate reviewable DDL. + + + Import tabular files, transfer data across connections, execute SQL files, and export schemas and data where supported. + + + Use the CLI, MCP, or a self-hosted backend to connect configured databases to terminals, scripts, and coding agents. -## Core Capabilities +## More Than SQL Databases -| Capability | Details | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -| Database connections | MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, ClickHouse, SQL Server, Oracle, and more | -| SQL editor | CodeMirror 6, syntax highlighting, metadata completion, formatting, selected execution, and query history | -| Data grid | Virtual scrolling, inline editing, WHERE/ORDER BY controls, SQL preview, and export tools | -| Schema tools | Schema browser, table structure editing, schema diff, ER diagrams, field lineage, database export, and SQL file execution | -| Data movement | Table import, data transfer, SQL file execution, and SQL export with progress and cancellation where supported | -| Specialized browsers | Redis key/value browsing and MongoDB document browsing | -| AI and automation | Generate SQL, explain queries, suggest optimizations, help fix errors, and expose DBX connections to coding agents through MCP | -| Self-hosted access | Run DBX with Docker and access it from a browser | +The connection picker groups databases and data systems by how they are actually used. Each category can open a different workspace instead of falling back to one generic query box. -## Product Principles +| Category | Representative systems | Main DBX experience | +| --- | --- | --- | +| Relational and compatible protocols | MySQL, PostgreSQL, SQLite, Oracle, SQL Server, Dameng, openGauss, GaussDB | SQL editor, data grid, object tree, table structure, and schema tools | +| Analytics and warehouses | ClickHouse, Doris, StarRocks, Databricks, Snowflake, Trino, BigQuery | Queries, result analysis, metadata, and driver-supported schema and export tools | +| Document, key/value, and search | MongoDB, Redis, Elasticsearch, Easysearch, HBase, Cassandra | Specialized document, key, index, or column-family browsers | +| Graph, vector, and AI data | Neo4j, Qdrant, Milvus, Weaviate, ChromaDB | Graph connections plus vector collection browsing, search, and mutation flows | +| Time series | QuestDB, TDengine, IoTDB, InfluxDB | Time-series queries and system-specific connection, object, and data views | +| Message queues | Pulsar, Kafka, RocketMQ, RabbitMQ | Topics, subscriptions or consumers, messages, monitoring, permissions, and policies | +| Registry and configuration | etcd, ZooKeeper, Nacos | Key/ZNode browsing, cluster status, access control, configuration, and service management | +| Driver extensions | JDBCX, custom MySQL/PostgreSQL, optional JDBC plugins | Extend coverage through compatible protocols or vendor JDBC drivers | -DBX focuses on the core work of a database client instead of turning every operation into a separate tool. A few details shape the product: +Advanced features depend on the driver, protocol, and database itself. Use the [Database Support](/en/docs/databases) matrix as the source of truth, and see [Specialized Workspaces](/en/docs/specialized-workspaces) for non-relational and infrastructure interfaces. -- **Less context switching**: schema browsing, SQL editing, data grids, and results stay close together. -- **Reviewable operations**: data and schema changes show the SQL before they are applied where possible. -- **Clear environment separation**: connection colors, pins, search, and context menus help separate dev, test, and production. -- **Flexible deployment**: the desktop app fits personal workflows; the Docker version fits shared or server-hosted access. +## One Workflow, Multiple Entry Points -## Data and Security +| Entry point | Best for | Capabilities and boundaries | +| --- | --- | --- | +| Desktop | Daily personal work, local database files, the complete workbench | Adds local files, the SQL file tree and SQL library, desktop deep links, and other OS integrations | +| Docker / Web | Self-hosting on a server and remote browser access | Shares most database workflows; paths belong to the server, and some local-file and desktop integrations are unavailable | +| CLI | Terminals, scripts, CI, and Codex workflows | Lists connections and schemas, describes tables, runs queries, builds compact context, and can open a table in Desktop | +| MCP Server | Claude Code, Cursor, Windsurf, and other AI clients | Lists connections, reads schema, and runs policy-controlled queries or commands against local storage or DBX Web | -- Connection configuration is stored in a local SQLite database under the app data directory. Sensitive fields such as passwords, SSH passwords, SSH key passphrases, and connection strings are removed from the normal connection JSON and stored separately in the `connection_secrets` table. -- Config export can be encrypted with AES-GCM for migration between machines. -- SSH tunnels can connect to databases behind firewalls or private networks. -- AI Ask mode does not execute generated SQL. Agent and MCP flows use conservative execution policies and block dangerous SQL by default. +Desktop and Web reuse the same Rust core, but they are not identical substitutes for every system integration. Choose a deployment mode based on database network placement, whether files live on the local machine or server, and whether you need desktop deep links or local SQL file management. + +## From Connection to Automation + + + + ### Establish the connection boundary + + Choose a database type, enter credentials, and configure TLS, SSH, SOCKS5, HTTP proxying, or HTTP tunneling when needed. Enable read-only mode or production protection for high-risk targets. + + + + ### Understand objects and context first + + Use the sidebar to inspect databases, schemas, tables, columns, indexes, foreign keys, and database-specific objects. Search, source views, ER diagrams, and field lineage help with unfamiliar systems. + + + + ### Query, inspect, and change + + Run SQL in the query editor or use the data grid, document/key-value browsers, and specialized consoles. DBX shows SQL or request content before execution where the workflow supports it. + + + + ### Compare, move, and reuse + + Use schema diff, table import, data transfer, database export, SQL file execution, query history, and the SQL library to turn one-off operations into reviewable workflows. + + + + ### Add AI and automation + + Use AI Ask or Agent inside the app, or expose connections, schema context, and query execution to scripts and coding agents through the CLI and MCP. + + + + +## Capability Map + +| Task | Product capabilities implemented in DBX | Documentation | +| --- | --- | --- | +| Create connections | Connection categories, URL parsing, TLS, tunnels/proxies, read-only mode, production protection, and driver selection | [Getting Started](/en/docs/getting-started), [Tunnels and Proxies](/en/docs/ssh-tunnel) | +| Write and run queries | CodeMirror 6, metadata completion, formatting, execution targets, multiple results, cancellation, and history | [Query Editor](/en/docs/query-editor) | +| Browse and edit results | Virtual scrolling, database-side filters and sorting, inline edits, SQL preview, and multiple export formats | [Data Grid](/en/docs/data-grid) | +| Understand schemas | Object tree and search, source views, table structure, schema diff, ER diagrams, and field lineage | [Schema Browser](/en/docs/schema-browser), [Schema Diff](/en/docs/schema-diff) | +| Import, transfer, and export | CSV/TSV/JSON/Excel import, cross-connection transfer, SQL file execution, and database export | [Table Import](/en/docs/table-import), [Data Transfer](/en/docs/data-transfer) | +| Manage non-relational systems | Redis, MongoDB, search, vector, HBase, message queue, registry, and configuration workspaces | [Specialized Workspaces](/en/docs/specialized-workspaces) | +| Use AI and external tools | Ask/Agent, CLI, MCP, and the Web/Docker backend API | [AI Assistant](/en/docs/ai-assistant), [CLI](/en/docs/cli), [MCP](/en/docs/mcp) | +| Move personal configuration | Connection import, encrypted config export, WebDAV/Gist/Gitee sync, and SQL library sync | [Config Export and Import](/en/docs/config-export), [Cloud Sync and Backup](/en/docs/cloud-sync) | + +## Safety Model + +DBX uses layered controls rather than relying on a single dangerous-operation confirmation switch: + +- **Database account privileges** remain the final boundary. Use least-privilege accounts for production. +- **Read-only connections** block recognizable writes in the core query execution path and hide or disable multiple mutation entry points. +- **Production protection** can cover an entire connection or selected databases and requires a fresh explicit confirmation for every detected write. +- **Reviewable changes** show SQL first where possible in data editing, table structure, schema diff, and similar workflows. +- **AI Ask mode** returns an answer without executing SQL. Agent does not receive autonomous write permission in production and returns SQL to the editor for review. +- **MCP policy** centrally controls the connection allowlist and Read only, Data read/write, or Full access modes. It cannot bypass connection read-only state, production protection, or database privileges. +- **Sensitive configuration** is stored separately from normal connection JSON, and config exports can be protected with AES-GCM encryption. + +See [Production and Write Safety](/en/docs/production-safety) for configuration and behavior across entry points. + +## Boundaries to Understand + + + DBX is a database workbench, not a managed database service, and it does not replace database privileges, auditing, backups, or change approval. Database export is useful for lightweight backup or migration, but large production systems should use native backup tools. AI output, generated SQL, and cross-engine transfers still require human review. + + +- Advanced features are not force-enabled for every database; unreliable compatibility paths are hidden or degraded. +- Local paths in Docker/Web refer to the server filesystem, not the computer running the browser. +- JDBC and Agent databases require the corresponding driver or runtime and may expose fewer features than native drivers. +- The [Web API](/en/docs/web-api) primarily serves DBX Web and internal integrations and is not a stable public contract. Prefer the CLI or MCP for scripts and AI integrations. ## Next Steps - - Start with the desktop app or Docker version, then create your first database connection. + + Choose Desktop or Docker, then configure the first connection, network path, and safety settings. - - Check supported engines, compatible protocols, and ODBC-specific setup. + + Review connection types, default ports, driver architecture, and the advanced feature matrix. - - Add an API key and use natural language in the SQL editor. + + Set read-only connections, production protection, and AI and MCP permission boundaries. + + + Select the CLI or MCP based on terminal, Codex, scripting, or AI-client workflows. diff --git a/docs/package.json b/docs/package.json index 588eb4c531..c3d0cc4f6e 100644 --- a/docs/package.json +++ b/docs/package.json @@ -4,6 +4,8 @@ "license": "Apache-2.0", "scripts": { "dev": "next dev", + "content:check": "node scripts/verify-doc-content.mjs", + "prebuild": "node scripts/verify-doc-content.mjs", "build": "next build", "postbuild": "node scripts/generate-sitemap.mjs && node scripts/verify-static-export.mjs", "contributors:update": "node scripts/update-contributors.mjs", diff --git a/docs/scripts/verify-doc-content.mjs b/docs/scripts/verify-doc-content.mjs new file mode 100644 index 0000000000..b995499a44 --- /dev/null +++ b/docs/scripts/verify-doc-content.mjs @@ -0,0 +1,98 @@ +import fs from "node:fs"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; + +const scriptDir = path.dirname(fileURLToPath(import.meta.url)); +const docsDir = path.resolve(scriptDir, "../content/docs"); +const errors = []; + +const files = fs + .readdirSync(docsDir) + .filter((file) => file.endsWith(".mdx")) + .sort(); + +const pages = new Map(); + +for (const file of files) { + const chinese = file.endsWith(".cn.mdx"); + const slug = file.replace(/\.cn\.mdx$|\.mdx$/, ""); + const page = pages.get(slug) ?? {}; + page[chinese ? "cn" : "en"] = file; + pages.set(slug, page); +} + +for (const [slug, page] of pages) { + if (!page.cn || !page.en) { + errors.push(`${slug}: missing ${page.cn ? "English" : "Chinese"} page`); + } +} + +function navigationPages(file) { + const navigation = JSON.parse(fs.readFileSync(path.join(docsDir, file), "utf8")); + return navigation.pages.filter((entry) => !entry.startsWith("---")); +} + +const chineseNavigation = navigationPages("meta.cn.json"); +const englishNavigation = navigationPages("meta.json"); + +for (const [name, entries] of [ + ["meta.cn.json", chineseNavigation], + ["meta.json", englishNavigation], +]) { + const duplicates = entries.filter((entry, index) => entries.indexOf(entry) !== index); + for (const slug of new Set(duplicates)) errors.push(`${name}: duplicate page ${slug}`); + + for (const slug of entries) { + if (!pages.has(slug)) errors.push(`${name}: unknown page ${slug}`); + } + + for (const slug of pages.keys()) { + if (!entries.includes(slug)) errors.push(`${name}: page ${slug} is not in navigation`); + } +} + +if (JSON.stringify(chineseNavigation) !== JSON.stringify(englishNavigation)) { + errors.push("Chinese and English navigation page order differs"); +} + +const knownSlugs = new Set(pages.keys()); + +for (const file of files) { + const fullPath = path.join(docsDir, file); + const content = fs.readFileSync(fullPath, "utf8"); + const expectedLanguage = file.endsWith(".cn.mdx") ? "cn" : "en"; + const frontmatter = content.match(/^---\n([\s\S]*?)\n---/); + + if (!frontmatter) { + errors.push(`${file}: missing frontmatter`); + } else { + if (!/^title:\s*.+$/m.test(frontmatter[1])) errors.push(`${file}: missing title`); + if (!/^description:\s*.+$/m.test(frontmatter[1])) errors.push(`${file}: missing description`); + } + + const headings = [...content.matchAll(/^#{2,4}\s+(.+)$/gm)].map((match) => match[1].trim()); + const headingCounts = new Map(); + for (const heading of headings) headingCounts.set(heading, (headingCounts.get(heading) ?? 0) + 1); + for (const [heading, count] of headingCounts) { + if (count > 1) errors.push(`${file}: duplicate heading "${heading}"`); + } + + const links = [ + ...content.matchAll(/\]\(\/(cn|en)\/docs\/([^)#?]+)(?:#[^)]*)?\)/g), + ...content.matchAll(/href="\/(cn|en)\/docs\/([^"#?]+)(?:#[^"]*)?"/g), + ]; + + for (const link of links) { + const [, language, slug] = link; + if (!knownSlugs.has(slug)) errors.push(`${file}: broken documentation link /${language}/docs/${slug}`); + if (language !== expectedLanguage) errors.push(`${file}: cross-language documentation link /${language}/docs/${slug}`); + } +} + +if (errors.length > 0) { + console.error("Documentation content verification failed:\n"); + for (const error of errors) console.error(`- ${error}`); + process.exit(1); +} + +console.log(`Verified ${pages.size} bilingual documentation pages.`);