kichare/dsh-local-dba

dsh-local-dba

面向 DeepSeek Harness 的本地数据库管理（DBA）插件。以 Cordis 插件 bundle 形式提供一组 db_ 模型工具，让 agent 在会话里直接查询、检查结构、执行 DDL/DML、备份/恢复并分析慢查询，支持 MySQL / MariaDB 与 PostgreSQL。

仓库地址：

特性

- 8 个 db_ 工具 —— 查询、结构、健康、备份、恢复、慢查询一站覆盖。
- 在 Harness 页面里配置 —— 插件自带设置卡片，增删连接、切换默认连接都在页面完成，保存即生效，无需改文件。
- 支持主流 SQL 数据库 —— MySQL / MariaDB 与 PostgreSQL。
- 安全可控、默认只读 —— 写操作与备份/恢复开关默认关闭；密码可走环境变量（passwordEnv）；db_query 强制只读。
- 零构建 —— 纯 JavaScript（ESM），安装即用。

工具

表示必填参数。

| 工具 | 作用 | 参数 |
|---|---|---|
| db_connections | 列出已配置的连接（不含密码） | — |
| db_query | 只读 SQL（SELECT / SHOW / DESCRIBE / EXPLAIN / WITH） | sql\、connection、limit |
| db_execute | 写 SQL（DDL / DML） | sql\、connection |
| db_schema | 结构检查：表 / 列 / 索引 / 外键 | connection、action、table、schema |
| db_health | 版本、当前库、各库大小 | connection |
| db_backup | 用 mysqldump / pg_dump 做逻辑备份 | connection、database、output |
| db_restore | 用 mysql / psql 从 .sql 恢复 | connection、file\、database |
| db_slow_queries | 活动连接 / 进程列表 / 慢查询 | connection、limit |

db_schema 的 action 取 tables（默认）、columns、indexes、foreign_keys；后三者需要 table。

环境要求

- DeepSeek Harness（dsh），含 Web 界面。
- Node.js 24 与 pnpm（dsh plugin 安装插件时使用）。
- 运行时驱动 mysql2、pg —— 由本插件自动安装。
- 备份 / 恢复额外需要本机客户端：mysqldump / mysql、pg_dump / psql。缺失时 db_backup / db_restore 会给出明确报错；查询类工具不依赖这些 CLI。

安装

用 dsh plugin 安装

git clone https://github.com/kichare/dsh-local-dba.git
dsh plugin --profile web add ./dsh-local-dba

装完重启该 profile 才会加载：

以 web profile 为例
lsof -ti tcp:3080 | xargs kill   # 停掉旧进程（端口按实际改）
dsh web

该命令由 dsh plugin 转发给 pnpm。若提示 pnpm not found，先 corepack enable pnpm 或 npm i -g pnpm，并确保 pnpm 在 PATH 中。

配置

只需在 Harness 页面里配置：

设置 → 插件 → 插件配置 → 「本地 DBA 连接」（卡片）

在卡片里增删数据库连接、选择默认连接，保存后立即生效（热加载），不需要改任何文件、也不需要重启。

目前支持的 SQL 类型：MySQL / MariaDB 与 PostgreSQL。

使用示例

不用记工具名，直接用大白话说需求即可：

巡检
看看数据库健康状态
查一下有哪些库、各占多大

结构
列出 mydb 的所有表
users 表有哪些字段和索引

查询
查 mydb.orders 里最近 20 条
统计每个用户的订单数，倒序取前 10

变更（会真的改库）
给 users 的 email 字段加唯一索引
把 orders 里 status='tmp' 的改成 'pending'

备份 / 恢复
备份 mydb 到 backups 目录
从 backups/mydb-2026-xx-xx.sql 恢复 mydb

排查
看看现在有哪些慢查询

配了多个连接时，点名即可：“用 local-pg 查一下…”。

安全说明

- 优先用 passwordEnv：把密码放在环境变量里，而不是写进配置。db_backup / db_restore 通过 MYSQL_PWD / PGPASSWORD 把密码交给客户端进程，不出现在命令行参数里。
- 写权限开关（重要，默认关闭）：卡片里的「全局选项」有两个开关 —— 允许写操作 allowWrite、允许备份 / 恢复 allowBackupRestore，默认都是关闭的（只读优先，装完即可安全查询）。
- 一旦开启 allowWrite，agent 就能执行 CREATE / ALTER / DROP / INSERT / UPDATE / DELETE 等语句，会真实且不可逆地修改数据；误操作造成的损失由使用者自行承担。
- 一旦开启 allowBackupRestore，db_restore 会向目标库写入并覆盖同名对象（可能清空生产数据）；db_backup 会把整库导出落盘到备份目录，注意磁盘占用与数据外泄。
- 只有在确有必要时才开启，且建议只在隔离的本地 / 测试 profile 中开启；生产 / 重要数据库保持默认关闭。
- db_query 强制只读：只放行 SELECT / SHOW / DESCRIBE / EXPLAIN / WITH 开头的语句，写语句会被拒绝并提示改用 db_execute。
- 大表查询请显式 LIMIT：maxRows 只是返回后的截断兜底，不会限制 SQL 实际扫描量。

常见问题

| 现象 | 原因 / 处理 |
|---|---|
| pnpm not found | 装 pnpm（corepack enable pnpm 或 npm i -g pnpm）并放进 PATH |
| ECONNREFUSED / 连不上 | 主机或端口不对；确认数据库在监听、端口正确（非默认端口尤其注意） |
| no database selected | 在卡片的该连接里设置「默认库」，或在 SQL 里写 库名.表名 |
| db_schema 列不出表 | 同上：该连接没设默认库 |
| 报「未找到名为 "x" 的连接」 | 调用的 connection 与卡片里的连接别名不一致 |
| db_execute 报「写操作已被禁用」 | 写权限默认关闭；在卡片「全局选项」里勾选「允许写操作」并保存 |
| db_backup / db_restore 报「备份/恢复已被禁用」 | 同上，勾选「允许备份 / 恢复」并保存 |
| 页面里没有 dba 卡片 | 插件未加载或未重启；先在 插件列表 确认 dsh-local-dba 已启用 / 运行中 |
| 备份报 command not found | 本机缺 mysqldump / pg_dump，装上再试 |
| only_full_group_by 之类的 SQL 报错 | 数据库返回的原始报错，按提示修正 SQL |

目录结构

dsh-local-dba/
├── package.json        # 双端声明：dsh.bundle.patch → cordis.patch.yml；dsh.client → lib/client.js
├── cordis.patch.yml    # 注册本插件的那一行
├── lib/
│   ├── index.js        # Host 端入口：8 个 db_* 工具 + 设置命名空间
│   ├── db.js           # 数据库与本地 CLI 的辅助实现
│   ├── client.js       # 浏览器端：设置卡片
│   └── index.d.ts      # 类型声明
├── README.md
├── README.zh.md
└── LICENSE

开发说明

- 不需要构建：lib/*.js 就是运行时代码（ESM）。
- @deepseek-ai/cordis 与 @deepseek-ai/dsh-tools 是 peerDependencies（复用宿主单一工具注册表）；@deepseek-ai/schemastery、mysql2、pg 是普通依赖。
- 改动 Host 端（lib/index.js / lib/db.js）或浏览器端（lib/client.js）后需要重启 profile；页面里的配置改动是热加载的。

交流反馈

- 邮箱 / Email：5235278@qq.com
- Issues：

使用问题、Bug、功能建议都欢迎联系。

License

MIT