dsh-db-tool

dsh-db-tool

DSH 社区插件：在聊天中安全操作数据库，配套侧边栏管理台与 db-admin skill。架构与交互模式对齐 dsh-ssh-tunnel。

功能

• 8 种数据库：MySQL、PostgreSQL、GaussDB（openGauss 官方驱动）、SQLite、Redis、MongoDB、Oracle、达梦（DM）
• DatabaseManager 单工具多 action：list_connections / query / execute / schema / preview / run_script
• 分级权限：连接级只读（ro）/读写（rw）+ 项目级授权（grants.json：projectPathKey → 连接 → 模式）；未授权项目一律拒绝
• 危险操作确认：DDL / FLUSHALL / dropDatabase 等先返回 NEEDS_CONFIRMATION，对话内（模型经 ask）或 SQL 控制台（弹窗）确认后携一次性 challengeId（绑定语句 SHA256、5 分钟过期）重试
• 审计：全部执行落 audit.jsonl（语句、危险级、是否确认、结果）
• 侧边栏 4 面板（dsh-better-sidebar，zh/en）：连接管理、项目授权、数据浏览、SQL 控制台
• db-admin skill：随插件分发，覆盖 8 库方言速查、安全规范、确认流程

数据布局

$DSH_HOME/db-tool/（0700）：

文件	内容
connections.json	连接定义（urlSafe 中密码脱敏为 ***）
secrets.json	0600，密码/URL 凭据，永不返回给模型
grants.json	项目授权（归一化路径 → connId → ro/rw）
audit.jsonl	追加式审计日志

安装

# npm（推荐）
dsh plugin --profile web add dsh-db-tool

# GitHub 源码
dsh plugin --profile web add "dsh-db-tool@github:mengqi1436/dsh-db-tool"

# 本地开发
dsh plugin --profile web add "link:E:\path\to\dsh-db-tool"

GaussDB 官方驱动未发布 npm，需先构建 vendor：npm run build:gaussdb（PowerShell）或 bash scripts/build-gaussdb.sh；运行要求 Node ≥ 22.12（产物依赖 p-limit@7 纯 ESM）。oracledb 安装脚本需 npm approve-scripts oracledb。mongodb 驱动已 bundle 进发布包（vendor/mongodb-driver.cjs，esbuild 构建，npm run build:mongodb 可重建），依赖树中不含 mongodb/punycode，详见 docs/install.md。

安全模型

• HTTP API 仅同源（ctx.webServer prefix /dsh-db-tool/api）+ loopback/Origin trust 校验（等价 ssh-tunnel http-trust），body 限 2MB
• ro 双保险：服务层拦截 + 驱动会话级 SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY（pg/gaussdb）、readonly 打开（SQLite）
• SQL 参数绑定 + 标识符白名单（[A-Za-z0-9_$]+ + 引用包裹）；MySQL multipleStatements:false；Redis 元数据走 SCAN（禁 KEYS）；Mongo 递归拒 $where
• run_script：node:vm 独立 context、60s 超时、无 require/process/网络/文件系统，仅注入受限 db.{query,execute} 句柄
• 已知边界：对话内确认为提示级强制 + 审计兜底；DSH 无硬中断通道前，恶意对话仍可能诱导用户确认，请配合最小权限数据库账号使用

Troubleshooting

npm 安装插件导入失败（punycode / resolve.paths）

症状：DSH 启动后插件加载报 failed to import，伴随 TypeError: Cannot read properties of null (reading 'Symbol(Symbol.iterator)')，栈指向 dsh-app-boot 的 routeScoped。

根因：上游 @deepseek-ai/dsh-app-boot 对 createRequire(parent).resolve.paths(name) 直接做 for..of，而 Node 对 core-module 同名包（punycode 等）返回 null，hoisted profile 下凡依赖树含此类 npm 包的插件都会炸。0.1.7-rc.2 中共两处同型缺陷：routeScoped() 与 nativePackageDir()，本补丁一并修复（两处分别独立判定，已打过旧版单处补丁的机器只会补上缺的那处）。

一键修复（幂等，应用前自动备份为 index.js.bak-hotfix；--revert 可还原）：

npm run patch:dsh        # Windows（PowerShell）
npm run patch:dsh:sh     # macOS / Linux

脚本自动探测 DSH 安装根（--dsh-root 可显式指定）；补丁文件见 patches/dsh-app-boot-route-scoped-hotfix.patch，仅对 0.1.7-rc.2 声明兼容，其他版本会警告（--force 覆盖）。上游 issue：https://github.com/mengqi1436/dsh-db-tool/issues（占位，待上游仓库开放后替换）。

本插件的免补丁路径（0.1.9+）：该 bug 的触发条件是依赖树中出现 core-module 同名包，mongodb 链（mongodb-connection-string-url → whatwg-url → tr46 → punycode）正是元凶。0.1.9 起 mongodb 驱动经 esbuild bundle 为 vendor/mongodb-driver.cjs 随包发布，生产依赖树不再含 mongodb 与 punycode——在未修复宿主（含桌面版 app.asar，无法打补丁）上也能正常安装加载。守卫测试 tests/guard/deps-core-collision.spec.ts 断言依赖树永不回退（dependencies 白名单 + lockfile 生产树 core 同名包零交集）。patch:dsh 仍保留，用于修复其他含同类依赖的插件或宿主自身报错。

测试

npm test        # 离线 mock 全量（含 e2e-mock 全链路与对抗用例）
npx tsc --noEmit
npx stryker run # 变异测试（范围 lib/guard + lib/manager + lib/store，报告 reports/mutation/）

真机冒烟（设了才跑）：DBT_TEST_MYSQL_URL / DBT_TEST_PG_URL / DBT_TEST_REDIS_URL / DBT_TEST_DM_CONNECT / DBT_TEST_MONGO_URL / DBT_TEST_ORACLE_CONNECT。GaussDB 与 Oracle/Mongo 官方要求均按官方文档实现，未真机验证处以代码内标注为准。

目录

lib/        host 插件（store / adapters×8 / guard / manager / http / index）
client/     侧边栏单文件产物（client.js，即源码）
skills/     db-admin skill
scripts/    GaussDB vendor 构建、mongodb 驱动 bundle（build:mongodb）、DSH dsh-app-boot 热修复（patch:dsh）
docs/       安装、HTTP 契约（api-contract.md）、skill 说明
tests/      vitest（离线 mock + DBT_TEST_* 门控真机）
vendor/     gaussdb 构建源/产物与 mongodb-driver.cjs bundle（gitignore，发布经 files 白名单收录 bundle）