# dsh-local-dba

[English](README.md) | 中文

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

仓库地址：<https://github.com/kichare/dsh-local-dba>

## 特性

- **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` 安装

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

装完**重启该 profile** 才会加载：

```sh
# 以 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**。

## 使用示例

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

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

# 结构
列出 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**：<https://github.com/kichare/dsh-local-dba/issues>

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

## License

[MIT](LICENSE)