AI DB Client
文档 · v0.0.5/持续更新

开发者文档

从安装运行到二次开发：连接管理、SQL 工作台、AI 能力、数据库迁移、权限安全与架构概览。所有内容均对应当前已实现的真实功能。

快速开始

AI DB Client 是一个基于 Electron 的开源桌面数据库客户端，本地优先、MIT 协议。下面从源码跑起来。

环境要求

  • Node.js ≥ 20
  • pnpm ≥ 9
  • macOS / Windows / Linux

安装与运行

# 克隆仓库
git clone https://github.com/tomseanmy/dbclient.git
cd dbclient

# 安装依赖（会按需编译 better-sqlite3 / keytar 原生模块）
pnpm install

# 启动开发模式（含 HMR）
pnpm dev
i
首次安装若原生模块报错，运行 pnpm rebuild 重建 better-sqlite3 / keytar；切换 Node/Electron 版本后也需要重建。

命令与打包

命令 说明
pnpm dev 启动 Electron + Vite 开发模式（HMR）
pnpm build 构建主进程 + preload + 渲染进程
pnpm dist:mac 打包 macOS 安装包（.dmg）
pnpm dist:win 打包 Windows 安装包（.exe NSIS，per-user）
pnpm dist:win:portable 打包 Windows 便携版（.exe portable，免安装）
pnpm dist:linux 打包 Linux 安装包（.AppImage / .deb）
pnpm typecheck TypeScript 类型检查（main + renderer）
pnpm lint / pnpm test ESLint / Vitest 单元测试

连接管理

在「连接管理」页新建连接，支持 MySQL / PostgreSQL / SQLite / Redis 四种类型。

  • 连通性测试：保存前可测试连接是否可达。
  • 凭据安全：密码经 OS 钥匙串存储（macOS Keychain / Win Credential Vault），不以明文落盘，连接时按需读取。
  • 环境分级：每个连接标注 dev / staging / prod，驱动安全策略矩阵（详见权限章节）。
  • Redis：支持 single 与 cluster 模式（sentinel 为规划项）。

SQL 工作台

基于 Monaco Editor 的全功能 SQL 工作台，原生 SQL、无 ORM。

  • 自动补全：根据 FROM/JOIN/INTO 上下文补全表名，按别名与 SELECT/WHERE 上下文补全列名，含关键字与代码片段。
  • 格式化：sql-formatter，按方言差异化输出。
  • 历史记录：每条执行的 SQL 自动入历史，可回溯复用。
  • 保存查询：常用查询可命名保存。
  • 导出：结果集一键导出 CSV / JSON。
# 快捷键
Cmd / Ctrl + Enter          执行全部
Cmd / Ctrl + Shift + Enter  执行选中
Cmd / Ctrl + S              保存查询

AI 能力

AI 以三种形态工作，且永远不会擅自动手：生成的写操作 SQL 落入编辑器供你审阅，执行前必须由你确认。

配置 Provider

在「设置 → 模型」中添加 Provider，采用 OpenAI 兼容协议，已验证支持：

  • DeepSeek / Qwen / Moonshot
  • Ollama（本地自托管）
  • 任何 OpenAI 兼容端点

可分别为 agent 与 chat 类别指定默认模型，连通性可一键测试。所有调用记录 token 用量。

三种 AI 形态

形态 说明
NL2SQL 自然语言 → SQL，落入编辑器供审阅
流式对话 SSE 流式响应，逐字输出
Agent loop tool-calling 多步执行：listTables / describeTable / 只读查询 / 生成 SQL；出错自动回灌上下文自愈（上限 50 轮）
!
Agent 的 runReadQuery 只放行只读白名单（SELECT / WITH / EXPLAIN / SHOW / DESCRIBE / PRAGMA），并同样经过安全层 checkSql 校验。generateSql 生成的写操作 SQL 不会自动执行。

数据库迁移

结构 diff + 数据 diff + 跨库迁移，方言感知 DDL/DML 生成。4 步向导：选库 → 选表与设置 → 生成脚本 → 执行迁移。

结构 diff

逐表比对建表 / 改列 / 删列、索引、外键，识别变更项：createTable / dropTable、addColumn / modifyColumn / dropColumn、addIndex / dropIndex、外键增删。

数据 diff

行级差异识别，支持三种策略：incremental（增量）/ fullReplace（全量替换）/ insertOnly（仅插入）。

!
明确的边界：数据 diff 仅支持 insert / delete，不做 update。事务策略可选 none / perStatement / single。

方言脚本与计划

  • 按目标方言生成 DDL/DML，类型自动映射（MySQL 的 MODIFY、PostgreSQL 的 ALTER COLUMN）；不支持项（如 SQLite 改类型）明确标注。
  • 每步带风险徽章 safe / caution / danger。
  • 迁移计划可命名保存、加载复用；脚本一键导出并在文件管理器中定位。

表结构编辑

在表详情中行内编辑列 / 索引 / 外键，改动以脏行高亮，并实时预览即将生成的 ALTER 语句（只读 Monaco）。

  • 类型变更、可空、默认值、注释变更按方言差异化输出。
  • SQLite 对部分类型/可空/默认/注释变更不支持，编辑器内会明确标注。

权限与安全

统一的安全闸门：GUI 与 AI 两条执行路径都流经它。

危险级别判定

node-sql-parser 解析 AST → 判定 safe / write / dangerous。DANGEROUS_KEYWORDS 包含 DROP / TRUNCATE / SHUTDOWN / GRANT / REVOKE，并检测缺 WHERE 的 DELETE / UPDATE。

环境分级策略

环境 读 写 DDL / 危险
dev ✓ 放行 ✓ 放行 弹窗确认（dangerous）
staging ✓ 放行 ✓ 放行 DDL 弹窗确认
prod ✓ 放行 ✗ 拦截（除非提权） ✗ 拦截（即使提权仍确认）
  • 临时提权：生产可 30 分钟临时提权（默认有效期，会话级，自动过期）。
  • 审计：所有写操作（含 AI 路径）全过程审计留痕。

架构概览

核心设计：核心领域层 src/main/domain/ 不依赖 Electron，可独立测试，被 GUI 和 AI 链路共用，保证两条执行路径权限一致。 

src/
├── shared/          # 共享类型契约（IPC、领域 DTO、迁移类型）
│   ├── types/       #   connection / database / llm / security / agent / migration
│   └── db/          #   列类型 + ALTER 语句生成（纯函数，跨进程复用）
├── main/            # Electron 主进程
│   ├── ipc/         #   IPC handler（应用服务层）
│   ├── domain/      #   核心领域层（纯逻辑，零 Electron 依赖）
│   │   ├── db/      #     驱动抽象 + mysql/pg/sqlite/redis
│   │   ├── agent/   #     Agent tool-calling loop + 工具集
│   │   ├── llm/     #     LLM 网关 / prompt / SQL 抽取
│   │   ├── migration/ #   结构 diff / 数据 diff / 方言脚本 / 执行器
│   │   ├── privacy/ #     Schema-only 上下文构造
│   │   └── security/#     SQL 分析 + 环境分级权限
│   ├── executor.ts  #   SQL 执行（走安全层）
│   └── infra/       #   本地库 / 凭据 / 日志
├── preload/         # contextBridge 安全桥
└── renderer/        # React UI

自动更新

集成 electron-updater，对接 GitHub Releases。打包应用启动后自动检查（24h 节流 + 10s 延迟；开发模式跳过），新版本下载完成后提示重启。

  • 状态机：idle / checking / available / downloading / downloaded / up-to-date / error。
  • 产物中由 electron-builder 生成 app-update.yml，autoUpdater 启动时自动读取，无需 setFeedURL。

扩展指南

新增数据库类型

实现 DbDriver 接口并在 createDriver() 工厂注册，补充 DbType 类型与连接表单选项即可被对象浏览、SQL 工作台、迁移复用。

新增 Agent 工具

在 src/main/domain/agent/tools.ts 增加工具定义与 handler；只读查询统一走 isReadOnlySql 白名单 + checkSql 安全闸门。

新增迁移方言

在 src/main/domain/migration/dialect/ 下新增方言实现（DDL/DML 输出 + 类型映射），并在 MigrationDialect 与 target-loader 注册。