dbboard

dbboard

⬇️ 下载 dbboard — Windows .exe / macOS .dmg

一个窗口管理你维护的所有数据库——并以安全的方式让 AI Agent 读取这些数据库。

dbboard 是一款适用于 Windows 和 macOS 的桌面数据库客户端。它支持 Postgres （以及 Neon、Supabase、CockroachDB、Aurora DSQL）、MySQL / MariaDB、Turso / libSQL、Cloudflare D1、Cloud Firestore、MongoDB 和兼容 Redis 的存储（Redis、Valkey、Amazon MemoryDB、Amazon ElastiCache、Upstash），会将所有密码保存在操作系统的钥匙串中，并附带一个独立的 MCP 服务，让 Claude 和 其他 Agent 能读取相同的数据库，但无法修改数据。

适用场景

你的数据库分布在四个不同的服务上。 生产环境在 Neon， 个人项目在 Supabase，旧系统在堡垒机后面的 MySQL 服务上，实验项目在 Turso 文件中。无需在四个 Web 控制台和终端之间来回切换，它们都显示在同一个侧边栏中。SSH 隧道可连接堡垒机后的数据库，每个连接的颜色和标签也会清楚标明你即将对哪个数据库执行语句。

你想让 AI Agent 读取生产环境数据，而且绝不能让它写入。 dbboard-mcp 会将你现有的连接提供给 Claude Code 或 Claude Desktop。读取操作会在数据库自身的只读模式下运行（通过 READ ONLY 事务、PRAGMA query_only），而不是依赖关键字过滤，因此 UPDATE 会在服务端失败。写入功能默认关闭，只有你为某个连接启用后才会开放；即便如此，DROP、TRUNCATE 和权限变更仍会被拒绝。密码绝不会传给 Agent。 → MCP 服务

一个登录账号可以访问十几个数据库。 添加 Postgres 或 MySQL 连接时，将数据库名称留空，侧边栏就会列出该账号可以打开的所有数据库，以及它们的架构和表格。点击某个表格，编辑器就会在对应数据库中运行查询；Run 旁边的标签会显示当前数据库。

有人需要修改一个值，但不想编写 UPDATE。 打开表格，双击单元格，输入内容，然后点击 Save changes。编辑操作以主键为依据，因此没有主键的表会保持只读，而不会猜测如何更新。

试用

1. 从**下载页面** 下载适用于你设备的安装程序（Windows x64 / ARM64 .exe、macOS .dmg）。
2. 打开安装程序。构建版本未经过代码签名，因此 Windows SmartScreen 和 macOS Gatekeeper 首次运行时会要求确认；如果想确认文件安全无误，可以先将文件与发布版本中的 SHA256SUMS.txt 进行比对。
3. 点击 Manage → Add connection，选择数据库类型并填写服务信息。除非你为该连接关闭 TLS，否则 dbboard 会要求使用 TLS。

目前还没有 Linux 构建版本；在 Linux 上，请从源代码构建（参见 运行）。

功能概览

添加连接。 输入主机、端口、用户名和密码，或直接粘贴连接 URL。密码会存入操作系统密钥链，不会写入文件。将 Database 留空即可浏览所有数据库。

查找表。 依次浏览数据库、架构和表。选择一张表即可查看其结构：列、类型、默认值、主键以及两个方向的外键。你添加的备注会保存在本机。

查询数据。 编写 SQL，然后按 ⌘/Ctrl + Enter。查询结果会显示在网格中，你可以复制为 TSV 或 CSV，也可以保存到文件；最近的查询会保存在该连接的历史记录中。

修改行。 在表格菜单中选择 Select top 100，即可打开可编辑网格。编辑会保持待处理状态并高亮显示，直到你保存或放弃更改。

浅色或深色，随心选择语言。 主题可跟随系统，也可保持你选择的设置；界面支持 11 种语言。

此处的所有截图均在单独的配置文件中，使用虚构数据截取（scripts/demo-profile），绝不会连接真实数据库（ADR-0098）。

状态

尚未发布 1.0。阶段 1、3、6 以及阶段 4 的 AI 助手均已完成；dbboard 现在还可作为 MCP 服务（dbboard-mcp）供外部 AI Agent 使用（ADR-0046）——除非你主动为某个连接启用写入权限，否则仅支持只读；且绝不允许更改权限、执行 TRUNCATE 或 DROP（ADR-0087）。Turso、Cloudflare D1、CockroachDB、Neon、Supabase、AWS Aurora DSQL、MySQL / MariaDB、 Cloud Firestore、MongoDB 和 Redis 兼容适配器均通过本地 HTTP 后端提供。请参阅 CHANGELOG.md 了解已发布的内容，并查看 docs/roadmap.md 了解下一阶段计划。

客户端基于 Tauri 2 + SvelteKit，使用共享的 Rust 核心 crate。被其取代的 egui 客户端曾发布至 v0.4.0，并根据 ADR-0089 停止维护；截至 v0.4.0 的版本仍包含其二进制文件。

这是 桌面版。网页版本位于 meta-taro/dbboard-web（Nuxt + NestJS）。两者共享概念和功能对等目标，但代码库彼此独立。

下载

最新版本的预构建 Windows 安装程序（.exe）和 macOS 磁盘映像（.dmg）可在 下载页面 （GitHub Pages）获取，也可直接从 Releases 页面下载。每个版本都附带 SHA256SUMS.txt；运行前请验证下载文件。二进制文件未经代码签名，今后也不会签名——证书需要持续付费购买，本项目不承担这项费用（ADR-0106）。因此，每次发布的版本首次启动时，Windows SmartScreen / macOS Gatekeeper 都会发出警告。请通过校验和进行验证。

目标

• 性能优先 — 核心使用 Rust；UI 是运行在其上的 WebView 外壳，而非捆绑的浏览器运行时。
• 本地优先 — 运行时无需依赖外部服务。
• 模块化 — 数据库层与 AI 层相互解耦。
• 可扩展 — 可通过 trait 接入新的数据库和 AI 提供商。

支持的数据库（初始范围）

• Turso / libSQL（基于 SQLite 的分布式数据库）
• Cloudflare D1（基于 SQLite，REST API）
• CockroachDB（分布式 SQL，PostgreSQL 协议）
• Neon（托管 PostgreSQL）
• Supabase（托管 PostgreSQL）
• AWS Aurora DSQL（托管 PostgreSQL 协议）
• MySQL / MariaDB（mysql://…，使用独立的 SQL 方言）
• Cloud Firestore（文档存储，REST API——只读）
• MongoDB（文档存储，官方驱动——只读）
• 兼容 Redis 的存储：Redis、Valkey、Amazon MemoryDB、Amazon ElastiCache、Upstash（键值存储，RESP——只读）

目前已提供全部 10 个适配器。4 种 pg-wire 类型共用通用的 dbboard-postgres 适配器（sqlx + tls-rustls-ring），仅 DatabaseAdapter::id() 暴露的运行时标签不同（"postgres"、"neon"、"supabase"、"aurora-dsql"），因此连接选择器和历史记录能准确标记每个连接。参见 ADR-0018（Neon）、ADR-0019（Supabase）和 ADR-0021（Aurora DSQL）。

MySQL / MariaDB 是首个采用真正不同 SQL 方言的引擎（反引号标识符、反斜杠字符串转义、X'…' 二进制数据，DOUBLE 不支持 NaN / ±Inf）：它使用基于 sqlx MySQL 驱动的独立 dbboard-mysql 适配器，以及独立的 SqlDialect::MySql。参见 ADR-0068。

Cloud Firestore 是首个完全不使用 SQL 的适配器。查询是以 JSON 编写的 Firestore StructuredQuery——与 Google 文档中展示的对象相同，没有转换层，也没有自创的查询语言——嵌套文档则以 Value::Json 单元格返回。它从设计上就是只读的：REST API 在端点层面将读取和写入分开，而且 crate 中没有构造写入 URL 的代码。它通过服务账号密钥连接（密钥存储在 OS 钥匙串中，绝不会写入 connections.toml），也可以不提供任何凭据，直接连接本地模拟器。参见 ADR-0091、ADR-0093 和 ADR-0094。

MongoDB 是第二个完全不使用 SQL 的适配器，它需要不同的保障机制。查询是以 JSON 编写的命令文档——{"find": "orders", "limit": 100}，与 mongosh 文档中展示的对象相同。每条 MongoDB 命令都通过一个 runCommand 路径传递，因此只读无法像 Firestore 那样通过结构设计来保证：它采用的是命令及每条命令选项的允许列表。因此，{"find": …, "insert": …} 会因包含 find 不支持的选项而被拒绝，而不是因为系统记住了某个动词。系统会递归检查任意深度的 $out 和 $merge，并直接拒绝服务器端 JavaScript。整个连接 URI 都是机密信息，存储在 OS 钥匙串中。

MongoDB 连接无法通过 SSH 建立隧道——一个 URI 可能包含多个主机，而 mongodb+srv:// 会通过 DNS 发现副本集，因此只转发单个主机会导致驱动故障转移到隧道未覆盖的成员。参见 ADR-0095 和 ADR-0096。 Redis 兼容存储是第三类，也是首个完全没有表的存储。 Redis、Valkey、Amazon MemoryDB、Amazon ElastiCache 和 Upstash 都使用 RESP，因此它们共用一个适配器，仅标签和表单默认值有所不同。查询就是一行命令，和 redis-cli 接受的格式一样—— HGETALL user:1——而只读限制同样是对命令及其参数的允许列表。写入、脚本、阻塞和发布/订阅命令在发送前都会被拒绝，KEYS 也一样，因为它会阻塞服务器： SCAN 每次分页给出相同的结果，而 dbboard 会沿着游标继续扫描，直到获取所需的键；集群中的每个节点都会扫描。返回整个哈希、集合、列表或有序集合的命令会先检查其大小。侧边栏会列出键前缀（user:*）。MemoryDB 始终以集群模式运行，并使用 TLS。私有网络中的存储通过 SSH 堡垒机访问：集群列出的每个节点都会单独转发，URL 则保留其 TLS 证书所列的主机名。参见 ADR-0166 和 ADR-0167。

Aurora DSQL 还支持第二种连接类型 aurora-dsql-iam (ADR-0036)：对于需要保持 24/7 连接的场景，dbboard 不再使用手动提供且令牌约 15 分钟后过期的 URL，而是根据已存储的 AWS 凭证自行生成 SigV4 IAM 令牌。后台任务会重新生成令牌，并在其过期前换入经过全新身份验证的连接池 (ADR-0037，阶段 B)，因此无人值守的连接可以在 Aurora DSQL 空闲回收后继续使用，无需手动重新连接。

Supabase REST/auth 层有意留待未来的 ADR 处理——在当前阶段，所有 pg-wire 类型都使用相同的 postgres://… URL 约定（aurora-dsql-iam 类型除外，它存储的是 AWS 凭证而不是 URL）。

权威的逐版本支持矩阵（Tier 1 / Tier 2 / 尽力支持）位于 docs/compatibility.md； 版本管理和数据库支持政策定义于 ADR-0011。

架构

主要分为三层，组织为 Cargo 工作区：

• UI 层 — 使用 SvelteKit 前端的 Tauri 2 外壳（apps/desktop），通过 Tauri IPC 调用核心 crate。
• 数据库适配器层 — 将数据库专属逻辑封装在统一的 trait 后，让多个提供方都能接入。
• AI 集成层（可选） — 可插拔的提供方（Claude、 OpenAI、本地大模型）。与核心数据库操作隔离。

完整的 crate 映射和依赖规则请参见 docs/architecture.md。

要求

• Rust 1.98.0。版本固定在 rust-toolchain.toml 中，因此 rustup 会在此代码库中为你安装该版本；手动配置的计算机也需要使用相同版本。之所以刻意升级版本而不跟踪 stable，是因为 clippy -D warnings 让 lint 集成为构建的一部分（ADR-0139）。
• cargo（随 Rust 一同提供）
• 用于 libsql 原生依赖的 C/C++ 工具链：
  • Windows：MSVC Build Tools
  • macOS：Xcode Command Line Tools
  • Linux：build-essential

设置

git clone https://github.com/meta-taro/dbboard.git
cd dbboard
sh scripts/cargo-test-serialised.sh

然后安装 Git 钩子（pre-commit、commit-msg、pre-push）：

sh scripts/install-hooks.sh

这些钩子只是本地便利工具——无论是否安装，CI 都会在每次推送和拉取请求时运行相同的检查。编辑钩子后请重新运行安装程序。

运行

cd apps/desktop
pnpm install        # first time only
pnpm tauri dev

前端不会直接访问数据库：它调用封装了与 MCP 服务公开的同一个 McpService 的 Tauri 命令，因此由引擎强制执行的只读路径只有一个实现。没有任何服务监听网络接口。（crates/dbboard-server 中的环回 HTTP 后端是其 Web 同类产品所实现契约的可执行描述——参见 docs/api-contract.md——客户端已不再启动该后端。）

默认情况下，应用会打开一个内存中的 Turso/libSQL 数据库，因此无需配置即可运行。后端按以下优先级选择：

1. 下面记录的环境变量 （DBBOARD_AURORA_DSQL_URL > DBBOARD_NEON_URL > DBBOARD_SUPABASE_URL > DBBOARD_PG_URL > DBBOARD_MYSQL_URL > DBBOARD_D1_* > DBBOARD_FIRESTORE_PROJECT_ID > DBBOARD_MONGODB_URI > DBBOARD_TURSO_PATH）。四种 pg-wire 类型之间 按字母顺序排列——同时设置两个类型专属变量并不常见，但优先级已明确规定。
2. 将 DBBOARD_CONNECTION=<id> 与 connections.toml 匹配—— 这是由操作系统密钥链支持的本地连接存储（ADR-0013）。
3. 如果 connections.toml 中恰好有一项，则会自动选中该项。
4. 否则使用内存中的 Turso/libSQL 数据库。

有关连接存储的架构以及各操作系统中的文件位置，请参阅 docs/connections.md。

注册后，可通过顶栏中的 Connections 窗口添加、编辑和删除条目，并在进程运行期间切换活动连接——每行的 Connect 按钮可就地切换后端，无需重启应用（正在处理的请求会继续使用旧后端；新请求则会使用新后端）。有关切换语义，请参阅 ADR-0020。

同一窗口还可以将所有连接 Export 到由口令加密的 .dbbx 捆绑包（age scrypt + ChaCha20-Poly1305），其中包含连接元数据和密钥；也可以在另一台机器上 Import，无需手动在密钥链中逐一录入，即可通过单个文件迁移整套配置。遇到 ID／引用冲突时，导入会跳过并报告。请参阅 ADR-0038 和 docs/connections.md。

如果数据库只监听堡垒机的 localhost，则可以通过 SSH 隧道连接：桌面连接表单中设有 SSH tunnel 区域（适用于 Postgres 系列、MySQL 和兼容 Redis 的存储），可用于设置堡垒机主机／端口／用户、基于密钥或密码的身份验证，以及必填的服务端主机密钥固定项（指纹或 known_hosts）。dbboard 会打开纯 Rust 本地端口转发（russh），并在连接前将连接 URL 改写为隧道地址；密钥口令／SSH 密码仅保存在密钥链中。请参阅 ADR-0069 和 docs/connections.md。

顶栏中的 Language / 言語 菜单会以各语言的本地名称列出随附的 11 种语言。选择一种语言即可就地切换 UI 语言；DBBOARD_LANG 环境变量仍决定启动时的默认语言，不受运行时切换器影响。请参阅 ADR-0022。

Help 菜单会显示当前运行版本；有较新版本发布时，还会显示包含发行说明的 Update available 通知。这是 dbboard 代表自身发起的唯一网络请求：启动时会尽力检查一次每次发布时附带的已签名 latest.json，并与当前运行版本进行比较。是否安装由你决定；替换任何内容之前，下载文件都会先通过发行版签名密钥验证（ADR-0067）。离线或发生任何错误时，检查不会显示提示；将 DBBOARD_NO_UPDATE_CHECK 设为任意非空值即可完全关闭检查。请参阅 ADR-0040。 查询工具栏上的 备份… 按钮会将当前连接导出为一个独立的 .sql 文件，其中包含架构和数据，并使用源引擎自己的方言（Turso/D1 SQLite 系列会原样导出 DDL；Postgres 系列，包括 Neon、Supabase 和 Aurora DSQL，则会重建 DDL）。导出过程使用键集分页，直接将 INSERT 批次流式写入磁盘，因此大型数据库不会占用大量内存。开始前会预先统计行数；如果数据库超过阈值（默认 500k 行，可在 备份 菜单中调整并跨重启保留设置），系统会发出警告，避免在未确认的情况下启动超大型导出。运行期间会显示表和行的进度及百分比进度条，并可随时取消（文件会保留已生成的部分）。参见 ADR-0049 和 ADR-0050（可配置阈值）。

同一工具栏上的 恢复… 按钮会将 .sql 文件导入当前连接，也就是上述备份功能的读取端，同时也支持其他来源的脚本（pg_dump、sqlite3 .dump）。它会将整个脚本导入匹配的引擎系列（Turso/D1 使用 SQLite，Neon、Supabase 和 Aurora DSQL 使用 Postgres），并在引擎支持事务时在事务中执行语句（Aurora DSQL 则退回到逐条执行）。为确保安全，恢复目标必须是空数据库：如果连接中已有表，系统会要求确认，而不会合并或比较差异。窗口会显示每条语句的进度，运行期间可取消；摘要会报告已执行的架构和数据语句数量，以及执行失败的语句。参见 ADR-0051。

以下示例会设置一个环境变量，供单次运行使用；示例假设当前工作目录为 apps/desktop（pnpm tauri dev 在此目录中运行）。需要长期保留的配置最好写入 connections.toml——参见 docs/connections.md。

本地 Turso/libSQL（默认）

变量	用途	默认值
DBBOARD_TURSO_PATH	libSQL 文件路径，或 :memory:	:memory:

Cloudflare D1

要连接 D1 而不是 Turso，请设置以下三个变量：

变量	用途
DBBOARD_D1_ACCOUNT_ID	Cloudflare 账户 ID
DBBOARD_D1_DATABASE_ID	D1 数据库 ID（wrangler d1 info <name>）
DBBOARD_D1_TOKEN	具有 D1 Edit 权限的 API 令牌
DBBOARD_D1_BASE_URL	(可选) API 根地址覆盖值；默认为 https://api.cloudflare.com/client/v4

账户 ID 和数据库 ID 可在 Cloudflare 控制面板中查看（Workers & Pages → D1），也可通过 wrangler d1 info <database-name> 查看。请在 My Profile → API Tokens 下创建具有 D1 读写权限的 API 令牌。如果缺少任何一个必需变量，应用会回退到本地 Turso 默认配置。

DBBOARD_D1_ACCOUNT_ID=... DBBOARD_D1_DATABASE_ID=... DBBOARD_D1_TOKEN=... \
  pnpm tauri dev

Cloud Firestore

只需项目 ID 即可选择 Firestore。其他配置均为可选，因此模拟器无需任何配置即可使用：

变量	用途
DBBOARD_FIRESTORE_PROJECT_ID	Google Cloud 项目 ID。用于选择 Firestore 后端。
DBBOARD_FIRESTORE_SERVICE_ACCOUNT	(可选) 服务账户密钥，即 JSON 文件的完整内容。省略此项即可连接本地模拟器，模拟器会以 owner 身份验证每个请求。
DBBOARD_FIRESTORE_DATABASE_ID	(可选) 命名数据库；默认为项目的 (default)。
DBBOARD_FIRESTORE_BASE_URL	(可选) API 根地址覆盖值；默认为 https://firestore.googleapis.com。模拟器地址应填写在此处。

配置服务账户密钥时，绝不会通过纯 HTTP 发送该密钥：如果基础 URL 为 http://，系统会直接拒绝；客户端也会设置为 https_only，防止通过重定向绕过此限制。模拟器不受此限制，因为它不会发出可能泄露的凭据。

# The local emulator — no credential at all.
DBBOARD_FIRESTORE_PROJECT_ID=demo-project \
DBBOARD_FIRESTORE_BASE_URL=http://127.0.0.1:8080 \
  pnpm tauri dev

# A real project. The key is a secret: keep it out of version control.
DBBOARD_FIRESTORE_PROJECT_ID=my-project \
DBBOARD_FIRESTORE_SERVICE_ACCOUNT="$(cat key.json)" \
  pnpm tauri dev

查询使用 JSON 格式的 Firestore StructuredQuery 对象，而不是 SQL——侧边栏中的 Select top 100 会为你生成一个：

{
  "from": [{ "collectionId": "users" }],
  "limit": 100
}

MongoDB

变量	用途
DBBOARD_MONGODB_URI	完整连接 URI，mongodb://… 或 mongodb+srv://…。选择 MongoDB 后端。密码位于 URI 的 authority 中，因此该变量本身应视为机密。
DBBOARD_MONGODB_DATABASE	(可选) 数据库名称。如果 URI 的路径中已指定数据库，则可省略。

# A local server started with:
#   docker run -d --rm -p 27017:27017 mongo:8
DBBOARD_MONGODB_URI=mongodb://127.0.0.1:27017 DBBOARD_MONGODB_DATABASE=test   pnpm tauri dev

在 MongoDB 后端中，DBBOARD_SSH_* 会被拒绝，而非忽略：URI 可能列出多个主机，且 mongodb+srv:// 会通过 DNS 发现副本集，因此，单主机转发看似可用，却可能在故障转移到隧道未覆盖的成员时失败。

查询使用 JSON 命令文档，而非 SQL——侧边栏中的 Select top 100 会为你生成一个：

{ "find": "users", "limit": 100 }

读取操作仅允许 aggregate、count、distinct、find、 listCollections 和 listIndexes；其他任何操作都会被拒绝，不会发送到服务器，包括包含 $out、$merge、$where、$function 或 $accumulator 的读取操作。

CockroachDB / PostgreSQL

设置一个连接字符串，即可通过 dbboard-postgres 适配器连接到 CockroachDB 或任何通用 PostgreSQL-wire 数据库（原生 Postgres、可自托管）：

变量	用途
DBBOARD_PG_URL	完整连接字符串，例如 postgresql://user:pass@host:26257/db?sslmode=verify-full

对于 CockroachDB Cloud，请从 CockroachDB Cloud Console 中集群的 Connect 对话框复制连接字符串（Basic 免费层即可使用）。对于使用 cockroach start-single-node 启动的 可自托管 节点，请使用其 postgresql://… 字符串；默认 SQL 端口为 26257。CockroachDB 要求使用 TLS，因此请保留 sslmode=verify-full（或使用部署环境所要求的模式）。

DBBOARD_PG_URL='postgresql://user:pass@host:26257/db?sslmode=verify-full' \
  pnpm tauri dev

对于 Neon、Supabase 和 AWS Aurora DSQL，使用的是同一适配器，但运行时会为连接标记不同名称（"neon"、"supabase"、"aurora-dsql"，而非 "postgres"），以便连接选择器和历史记录区分它们。每种类型都有自己的环境变量，且其优先级均高于 DBBOARD_PG_URL：

变量	用途
DBBOARD_NEON_URL	Neon 连接字符串。必须使用 TLS——sslmode=require（或更严格的模式）。请参阅 ADR-0018。
DBBOARD_SUPABASE_URL	Supabase 连接字符串。必须使用 TLS。直连 :5432 端点和事务池化器 :6543 端点均可用——由 URL 本身决定。请参阅 ADR-0019。
DBBOARD_AURORA_DSQL_URL	Aurora DSQL 连接字符串。密码部分必须是新生成的短时效 IAM 身份验证令牌（约 15 分钟 TTL）；令牌过期会在启动时显示为连接错误。请参阅 ADR-0021。

所有四个 pg-wire 变量都包含凭据——请勿将其提交到版本控制中（请使用已被 gitignore 排除的 .env）。应用不会记录这些变量。

DBBOARD_NEON_URL='postgres://user:pass@ep-…neon.tech/db?sslmode=require' \
  pnpm tauri dev

DBBOARD_SUPABASE_URL='postgres://user:pass@db.<ref>.supabase.co:5432/postgres?sslmode=require' \
  pnpm tauri dev

# Aurora DSQL: the password segment is a short-lived IAM token.
DBBOARD_AURORA_DSQL_URL='postgres://admin:<IAM-token>@<cluster>.dsql.<region>.on.aws:5432/postgres?sslmode=require' \
  pnpm tauri dev

由于 Aurora DSQL IAM 令牌会在约 15 分钟后过期，上述环境变量形式适用于短时会话。对于长期运行或 24/7 连接，请改用 aurora-dsql-iam 连接类型；它会将 AWS 凭据存储在 connections.toml 和操作系统钥匙串中，并由 dbboard 自行生成令牌。此类型在连接存储中配置，而非通过环境变量配置——请参阅 docs/connections.md 和 ADR-0036。

AI 集成（可选）

dbboard 提供一个可选的 AI 面板，可用于解释 SQL，并根据当前连接的架构建议查询。未配置提供商时，面板和用于切换面板的菜单项都会隐藏——优雅降级即是不显示（参见 ADR-0023 决策 11）。

完成接入后，AI 助手菜单项（位于顶部栏，在“连接”和“语言”之间）会打开一个双模式窗口：解释 SQL （粘贴 SQL，获取自然语言讲解）和 建议 SQL （描述问题，获取一份 SQL 草稿，并以当前连接的表列表作为上下文）。响应会内联显示；错误会带有经过翻译的前缀，以免 429 或网络故障看起来与成功但内容为空的响应完全相同。AI 调用不会经过 dbboard-web HTTP 协议，而是从桌面二进制文件的工作线程直接通过 reqwest 发送给提供商。

对于声明支持流式传输的提供商，响应会逐步流式显示（当前接入的两个提供商都支持此能力——Anthropic 提供商依据 ADR-0026，OpenAI 提供商依据 ADR-0052）。模型生成内容时，文本会逐块显示，Tokens：N 输入 / M 输出计数器会根据累计用量数据块更新。请求进行期间，“发送”按钮会替换为取消：点击后会丢弃正在传输的数据流（关闭 HTTP 连接，让服务端停止生成），同时保留已显示的部分文本，并以一行简短的 已取消。 标记结果。对于不支持流式传输的提供商，原子路径上也可使用同一个取消按钮。

在“建议”模式下，如果当前数据库适配器支持描述表结构（内置的三个适配器都支持——ADR-0028），就会显示一个包含列详情复选框。选中后，点击“发送”会先从实时连接获取每张表的列和主键，再将该架构嵌入提示词，这样可以大幅减少草稿中臆造列名的情况。代价是提示词会变长：完整架构会占用提供商的上下文窗口，并计入你的 Token 费用——请留意 Token 计数器；对于大型架构或按量计费的密钥，请不要勾选此框（默认状态，每个会话重置）。如果部分表无法描述，系统会显示数量警告，并使用其余表继续生成建议。

目前已接入两个提供商——Anthropic Messages API 和 OpenAI Chat Completions API（ADR-0052，默认模型为 gpt-4o）。两者都可通过以下两种途径之一配置，并按下列顺序依次检查；最先解析成功的途径生效。

1. ai-providers.toml + OS 密钥链（推荐）

在每用户的 ai-providers.toml 中添加一个或多个条目，该文件与 connections.toml 位于同一目录（路径：与连接存储相同的 OS 配置目录）。API 密钥会存储在 OS 密钥链中——Windows 凭据管理器、macOS Keychain 或 Linux Secret Service——条目为 dbboard.ai.<id>.api_key。TOML 文件本身只记录密钥链引用，不会记录密钥明文。

运行时存储与“设置”界面修改的是同一个存储（从 AI 提供商菜单打开，ADR-0025 切片 b）：添加条目会将密钥写入密钥链，“使用”会重建进程内的提供商并以原子方式更新 active_id，“删除”会一并移除条目及其密钥。手动编辑 TOML 也可以——适合在不打开窗口的情况下为新机器预先配置——前提是其中指定的 keyring_api_key_ref 在密钥链中有对应条目：

kind 判别字段直接写在每个 [[providers]] 条目中（"anthropic" 或 "openai"）；model 为可选项，省略时使用提供商的默认模型：

# ai-providers.toml
version = 1
active_id = "primary"

[[providers]]
id = "primary"
name = "Anthropic"
kind = "anthropic"
model = "claude-sonnet-5"             # optional; omitted = default
keyring_api_key_ref = "dbboard.ai.primary.api_key"

[[providers]]
id = "gpt"
name = "ChatGPT"
kind = "openai"
model = "gpt-4o"                      # optional; omitted = gpt-4o
keyring_api_key_ref = "dbboard.ai.gpt.api_key"

以下环境变量途径仅支持 Anthropic；如需配置 OpenAI，请使用 ai-providers.toml（或“设置”窗口中的 AI 提供商）。

2. 环境变量（向后兼容／CI）

变量	用途	默认值
DBBOARD_ANTHROPIC_API_KEY	来自 Anthropic 控制台的 API 密钥。无需修改 ai-providers.toml 即可配置面板。	(未设置 = 回退到 TOML)
DBBOARD_ANTHROPIC_MODEL	覆盖模型标识符。	claude-sonnet-5

设置 DBBOARD_ANTHROPIC_API_KEY 后，它始终优先于 ai-providers.toml。这保留了原有的 Stage 1 接线方式，适用于无头／CI 使用，也避免让已经导出该环境变量的用户感到意外。取消设置即可让 TOML 路径接管：

DBBOARD_ANTHROPIC_API_KEY='sk-ant-…' pnpm tauri dev

如果两种路径都无法解析出提供方（或者任何分支失败——例如密钥环中缺少 条目、构造错误），二进制文件会将错误记录到 stderr 并继续运行，不启用 AI； 面板和菜单项也会隐藏。密钥不会出现在 Debug 输出或 history.jsonl 中； 它只会在进程的生命周期内保存在内存中。

每次完成的 AI 调用（流式或原子式，ok／error／ cancelled）都会作为 kind: "ai" 记录写入 history.jsonl，与 SQL 历史记录并列保存（根据 ADR-0027，架构版本为 v:2）。提示词和 响应会原样写入——与 v:1 查询记录中的 SQL 文本采用相同的处理方式。 静态数据保护也相同：根据 ADR-0024，在 Unix 上使用 0o600 权限／在 Windows 上使用仅限用户的 DACL。在共享机器上，请注意， 输入 AI 面板的任何内容——包括后续消息中的架构上下文，以及粘贴到 Explain 请求中的任何机密——都会未经脱敏地写入你用户账户下的磁盘。

剩余暂缓的 Stage 2 功能（完整 DDL 架构快照 + 函数调用——Group D）记录在 ADR-0023 §9 中。Group A／B／ C 已关闭（ADR-0025／ADR-0026／ADR-0027）。

MCP 服务

除了作为 AI 客户端，dbboard 还提供无头的 MCP 服务——dbboard-mcp—— 通过 stdio 将 dbboard 已配置的数据库提供给外部 AI Agent（Claude Desktop、Claude Code），作为一组小型工具。 它复用与 GUI 完全相同的 connections.toml 和操作系统密钥链机制， 因此无需增加新的凭据存放位置。完整规范请参阅 ADR-0046 和 crate README： crates/dbboard-mcp/README.md。

共 22 个固定工具。其中 7 个用于读取数据库——list_connections、 list_tables、describe_table、search_schema（ADR-0053）、 list_relationships（ADR-0054）、run_read_query 和 get_annotations（dbboard 的本地笔记，ADR-0045）——另有 run_write 和 dump_database（ADR-0087）。有 7 个工具完全不访问数据库，而是操作窗口： get_ui_locale／set_ui_locale 用于更改应用的显示语言 （ADR-0107），capture_window 返回正在运行的窗口的 PNG （ADR-0108），set_editor_sql／run_query／open_ai_panel／ open_ai_settings 用于驱动窗口（ADR-0109）——这样便可以设置、执行并检查界面实际呈现的内容，而不是仅仅声称它呈现了什么。这 7 个工具操作的是有人正在使用的屏幕；除两个读取器外，dbboard 未运行时它们都会直接报错。另有两个工具完全不访问任何内容。get_server_info 会标明正在响应的构建版本（ADR-0116），因为该二进制文件是手动安装的，否则旧版本和故障版本无法区分；about 会介绍产品本身——其用途、支持的引擎，以及每个已发布版本的更改内容。变更日志会编译进构建中，因此返回的信息描述的正是正在响应的二进制文件（ADR-0154）。 最后四个工具操作的是连接列表本身，不会打开任何数据库。add_connection 会在 connections.toml 中注册连接，这样 Agent 刚设置好的数据库无需再让人手动重新输入路径即可使用——而且仅适用于不会在钥匙串中存储任何内容的类型：本地 SQLite/libSQL 文件和 Firestore 模拟器（ADR-0134）。凡是需要密码、令牌或密钥的类型，都会在工具自身的说明中被拒绝，在凭据发送之前而非之后就予以拦截。 set_connection_mark 和 move_connection 用于给列表添加颜色和调整顺序（ADR-0136）：这类工作不适合由人重复操作二十次，却很适合由 Agent 一次完成。export_connections 会将连接封装到加密包中，以供另一台机器使用；它会自行生成密码短语并将其存入这台机器的钥匙串，而不会返回密码短语。除非有人已在 connections.toml 中指定文件目录，否则该工具会被完全禁用（ADR-0140）。 以下安全措施正是可以放心让 Agent 使用该工具的原因：

• 密钥绝不会通过网络传输。 序列化的连接元数据仅包含 { id, name, kind }，不含 URL、令牌或密钥环引用，错误消息中也不会包含这些内容。
• 只读由引擎强制执行，而非通过字符串匹配。 Postgres-wire 会在 BEGIN TRANSACTION READ ONLY 中执行每条语句，libSQL/Turso 会使用 PRAGMA query_only，D1 则会对 AST 进行分类——因此，UPDATE、DDL、多语句批处理和 SELECT … FOR UPDATE 都会在源头被拒绝。
• 写入功能默认关闭，需由人针对每个连接单独启用（在 connections.toml 中设置 mcp_write，或通过 连接 → 编辑 → AI Agent 访问权限 启用）。即使启用，run_write 也只接受允许列表中的语句（INSERT / UPDATE / DELETE / MERGE、CREATE TABLE / VIEW / INDEX / SCHEMA、ALTER TABLE）——通过 AST 进行分类，遇到问题时默认拒绝。GRANT / REVOKE / DENY、用户和角色 DDL、SET PASSWORD、TRUNCATE 以及对任何对象执行的 DROP，无论该标志如何设置，都会被拒绝（ADR-0087）。
• 导出功能默认关闭，需由人指定导出目录（在 connections.toml 中设置 [mcp_export]）。dbboard 会为封装内容生成密码短语并存入这台机器的钥匙串，绝不会返回该密码短语——工具结果是 Agent 对话记录中的明文，因此加密包及其密钥绝不能一起传输（ADR-0140）。
• 结果集有数量限制。 run_read_query 会将 max_rows 限制在 1000 行的硬上限内（默认 200 行），并带有 truncated 标志。
• stdout 不容有失。 stdout 仅用于 JSON-RPC 帧；所有日志均写入 stderr（RUST_LOG，默认值为 info）。

从最新版本下载——dbboard-mcp-windows-x86_64.exe、dbboard-mcp-windows-aarch64.exe（ARM 版 Windows）或 dbboard-mcp-macos-universal。它是无需运行时依赖的单个可执行文件，与桌面应用的下载分开提供：下载页面上的安装程序不包含它。请将其放在固定位置，因为 Agent 配置中需要填写该路径：

# Windows (PowerShell)
mkdir -Force "$env:LOCALAPPDATA\dbboard"
Move-Item -Force ~\Downloads\dbboard-mcp-windows-x86_64.exe "$env:LOCALAPPDATA\dbboard\dbboard-mcp.exe"

# macOS
mkdir -p ~/.local/bin
mv ~/Downloads/dbboard-mcp-macos-universal ~/.local/bin/dbboard-mcp
chmod +x ~/.local/bin/dbboard-mcp
xattr -d com.apple.quarantine ~/.local/bin/dbboard-mcp   # Gatekeeper, unsigned build

使用一条命令将其注册到 Claude Code——--scope user 会使其在这台机器上的所有项目中均可用：

# macOS / Linux
claude mcp add dbboard --scope user -- "$HOME/.local/bin/dbboard-mcp"

# Windows (PowerShell)
claude mcp add dbboard --scope user -- "$env:LOCALAPPDATA/dbboard/dbboard-mcp.exe"

如需自行构建：

cargo build --release -p dbboard-mcp
# binary at target/release/dbboard-mcp(.exe)

或者，在 Claude Desktop 中，将已构建二进制文件的绝对路径添加到 claude_desktop_config.json（Windows 上为 %APPDATA%\Claude\claude_desktop_config.json，macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "dbboard": {
      "command": "C:\\path\\to\\dbboard-mcp.exe"
    }
  }
}

无论采用哪种方式，之后都要重启 Agent。每个客户端都会启动自己的 dbboard-mcp 进程，并在整个会话期间保持该进程运行，因此，已经运行的 Agent 会继续与旧进程通信；而重启 dbboard 桌面应用 对此毫无作用，因为它们是相互独立的进程。 不带任何参数时，它会读取 GUI 使用的同一份用户级 connections.toml；传入 --config（或设置 DBBOARD_CONFIG）即可指定一个经过筛选、遵循最小权限原则的子集。环境变量只决定这一点：工具调用会指定一个 connection_id，服务端会根据存储文件和密钥链解析该 ID，因此无法访问存储文件中未描述的连接。完整配置——包括各操作系统上的配置路径、同时运行多个 Agent、在企业代理后使用 TLS，以及连接失败时产生的具体错误字符串——请参阅 crates/dbboard-mcp/README.md。

若要让另一个仓库中的 Agent 使用 dbboard，请将 docs/agent-onboarding.md 中的代码块复制到该仓库的 CLAUDE.md / AGENTS.md。Agent 不会主动寻找未被告知的工具——曾有一个在网上搜索 dbboard 的 Agent 得出结论，称它“不是公开可用的工具”。

Zenn 上有一篇日文教程，从下载二进制文件讲到首次拒绝执行 DROP： 让 Claude Code 操作自己的数据库.

开发

提交前，pre-commit 钩子会运行：

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo check --all-targets --all-features
cargo test --all-features

推送前，pre-push 钩子也会运行：

cargo build --release
cargo test --all-features --release

纯删除推送（git push --delete <branch>）会跳过构建/测试周期——因为没有可供验证的工作树。

你可以随时手动运行这些检查。

安全检查

dbboard 会在用户级配置目录下创建 connections.toml 和 history.jsonl（DBBOARD_CONFIG_DIR=<path> 可替换该目录——dbboard 管理的所有文件都会一起移动，因此可以用空配置启动以进行演示或截图；参见 docs/connections.md）。在 Unix 上，这些文件的权限均为 0o600；在 Windows 上，它们会继承 %APPDATA%\Roaming\<user>\ 仅限用户访问的 DACL。如果解析后的配置目录位于云同步服务商的文件夹下（OneDrive Known Folder Move、iCloud Drive、Dropbox、Google Drive），二进制文件会在启动时向 stderr 输出一条警告，并指出服务商名称。笔记本电脑丢失后，最有效的加固措施是全盘加密——启用 BitLocker / FileVault / dm-crypt。完整的安全态势说明请参阅 docs/connections.md § 文件权限 和 ADR-0024。

cargo-deny 会针对安全公告、许可证、重复版本和未知来源检查依赖关系图。配置位于 deny.toml。

cargo install --locked cargo-deny    # one-time, ~5 min build
cargo deny check                     # advisories + licenses + bans + sources

CI 目前尚未运行此检查；添加或升级依赖项时，请在本地运行。检查发现的新许可证表达式应加入 deny.toml 的 licenses.allow 列表，并附上一行说明理由。

打包与分发

Windows 和 macOS 安装包由 Tauri CLI 在 apps/desktop 中生成。目前不构建 Linux 版本。

信任说明。 这些构件未进行代码签名，这是经过决定的做法，并非待填补的缺口（ADR-0106）：每次发布时，Windows SmartScreen 和 macOS Gatekeeper 都会针对未知发布者发出警告。请使用已发布的 SHA256SUMS.txt 验证下载内容（参见发布构建与校验和）——判断文件是否由此仓库构建的依据是校验和，而不是操作系统警告。 这与更新程序签名密钥是两回事；该密钥已在使用，用于证明自动更新来自此项目（ADR-0067）。

在本地构建安装包

cd apps/desktop
pnpm install          # first time only
pnpm tauri build

安装包会生成在 target/release/bundle/ 下——整个工作区共用一个 target 目录，因此安装包位于仓库根目录，而不在生成它的 crate 旁边。安装包以 productName 命名，其值为 dbboard；cargo 软件包仍名为 dbboard-desktop， v0.5.0 至 v0.14.0 版本的文件名中都使用了这个名称：

平台	构建产物	构建环境
Windows x64	nsis/dbboard_<version>_x64-setup.exe	Windows x64
Windows ARM64	nsis/dbboard_<version>_arm64-setup.exe	Windows ARM64（原生构建，未交叉编译；ADR-0164）
macOS	dmg/dbboard_<version>_universal.dmg	macOS（无法在 Windows 上生成 .dmg）

应用标识——捆绑包标识符、图标、窗口默认设置、更新器端点—— 位于 apps/desktop/src-tauri/tauri.conf.json； 图标由 assets/ 生成（参见 DESIGN.md）。

由于前端是静态 SPA，pnpm tauri build 会先运行 Vite 构建； 过时的 apps/desktop/build/ 目录不会被打包发布。

发布构建与校验和

推送 v*.*.* 标签会运行 .github/workflows/release.yml， 在原生运行器上构建 Windows 和 macOS 安装包，并将其连同合并后的 SHA256SUMS.txt 以及应用内更新器读取的已签名 latest.json 一起附加到 对应的 GitHub Release。手动运行 workflow_dispatch 会构建相同的构建产物作为冒烟测试，但不会发布。 下载页面 随后会提供最新版本中的文件——它会在加载时读取 Releases API， 因此无需单独部署。验证下载文件：

sha256sum -c SHA256SUMS.txt        # Linux/macOS
# or on Windows PowerShell:
#   (Get-FileHash .\dbboard_<version>_x64-setup.exe -Algorithm SHA256).Hash

将构建交付给他人

以下三份针对不同角色的指南介绍了实际交付流程：

• 生成构建版本（维护者）：构建安装程序，可选择导出 加密的连接包，完成交付，并确保构建产物不进入公开仓库—— docs/maintainer/internal-distribution.md。
• 作为测试人员试用：安装、运行并反馈意见—— docs/internal-testing.md。
• 配置三个固定的数据采集连接（操作员）： docs/collector-setup/README.md。

连接及其密钥会通过一个由口令加密的 .dbbx 包在设备间传递（在连接窗口中选择 Export / Import，ADR-0038）；口令始终通过 单独的渠道传递。

贡献

本项目遵循 CLAUDE.md 中的规则。简而言之：

1. 修改行为前，先编写一个会失败的测试。
2. 保持改动小而聚焦。
3. 使用英文编写符合 Conventional Commits 规范的提交消息。
4. 在 docs/decisions.md 中记录重要决策。

许可证

请参阅 LICENSE。