dsh-local-dba

Readme

# dsh-local-dba

English | [中文](README.zh.md)

A local database-administration (DBA) plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness). It ships as a Cordis plugin bundle that registers a set of `db_*` model-facing tools, letting the agent query, inspect schema, run DDL/DML, back up/restore and analyze slow queries against **MySQL / MariaDB** and **PostgreSQL**.

Repository: <https://github.com/kichare/dsh-local-dba>

## Features

- **8 `db_*` tools** — query, schema, health, backup, restore and slow-query analysis in one bundle.
- **Configured inside the Harness UI** — the plugin ships a settings card, so connections are added/removed and the default connection is picked right in the page. Saving applies immediately; no files to edit.
- **Mainstream SQL databases** — MySQL / MariaDB and PostgreSQL.
- **Safe and read-only by default** — the write and backup/restore switches are **off by default**; passwords can come from an environment variable (`passwordEnv`); `db_query` is read-only enforced.
- **No build step** — plain JavaScript (ESM); install and go.

## Tools

`*` marks a required argument.

| Tool | Purpose | Arguments |
|---|---|---|
| `db_connections` | List configured connections (no passwords) | — |
| `db_query` | Read-only SQL (`SELECT` / `SHOW` / `DESCRIBE` / `EXPLAIN` / `WITH`) | `sql`\*, `connection`, `limit` |
| `db_execute` | Write SQL (DDL / DML) | `sql`\*, `connection` |
| `db_schema` | Structure: tables / columns / indexes / foreign keys | `connection`, `action`, `table`, `schema` |
| `db_health` | Version, current database, per-database sizes | `connection` |
| `db_backup` | Logical backup via `mysqldump` / `pg_dump` | `connection`, `database`, `output` |
| `db_restore` | Restore a `.sql` dump via `mysql` / `psql` | `connection`, `file`\*, `database` |
| `db_slow_queries` | Active connections / process list / slow queries | `connection`, `limit` |

`db_schema`'s `action` is one of `tables` (default), `columns`, `indexes`, `foreign_keys`; the last three require `table`.

## Requirements

- **DeepSeek Harness** (`dsh`) with the Web UI.
- **Node.js 24** and **pnpm** (used by `dsh plugin` to install plugins).
- **Runtime drivers** `mysql2` and `pg` — installed automatically with this plugin.
- **Backup / restore** additionally needs the native clients `mysqldump` / `mysql` and `pg_dump` / `psql`. When missing, `db_backup` / `db_restore` report a clear error; **query-only tools do not depend on them**.

## Install

### Install with `dsh plugin`

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

**Restart the profile** to load the new bundle:

```sh
# example: the web profile
lsof -ti tcp:3080 | xargs kill   # stop the old process (adjust the port)
dsh web
```

> This command forwards to pnpm through `dsh plugin`. If it reports `pnpm not found`, install pnpm first (`corepack enable pnpm` or `npm i -g pnpm`) and make sure it is on `PATH`.

## Configuration

**Everything is configured in the Harness UI**:

> **Settings → Plugins → Plugin configuration → "本地 DBA 连接"** (the card)

Add or remove database connections and pick the default connection in the card; saving applies immediately (hot reload) — **no file editing and no restart**.

Currently supported SQL types: **MySQL / MariaDB** and **PostgreSQL**.

## Usage examples

No need to memorize tool names — just say what you want:

```text
# health check
check the database health
list the databases and their sizes

# schema
list all tables in mydb
what columns and indexes does the users table have?

# queries
show the latest 20 rows of mydb.orders
count orders per user, top 10 descending

# changes (these really mutate the database)
add a unique index on users.email
update orders set status='pending' where status='tmp'

# backup / restore
back up mydb into the backups directory
restore mydb from backups/mydb-2026-xx-xx.sql

# diagnostics
show the current slow queries
```

With several connections configured, name one: "query `local-pg` for ...".

## Security notes

- **Prefer `passwordEnv`** so the password lives in an environment variable rather than in the configuration. `db_backup` / `db_restore` pass credentials to the client processes via `MYSQL_PWD` / `PGPASSWORD`, so they never appear in the process argument list.
- **Write-permission switches (important; off by default)**: the card's "全局选项" section has **allowWrite** and **allowBackupRestore**, and **both default to off** — read-only first, safe right after install.
  - Once `allowWrite` is on, the agent can run `CREATE` / `ALTER` / `DROP` / `INSERT` / `UPDATE` / `DELETE` — these **really and irreversibly modify data**; any damage from a mistaken change is the operator's responsibility.
  - Once `allowBackupRestore` is on, `db_restore` writes into the target database and **overwrites same-named objects** (it can wipe production data), while `db_backup` dumps a whole database to disk — mind disk usage and data leakage.
  - **Turn them on only when genuinely needed, and preferably only in an isolated local or test profile**; leave them off for production / important databases.
- **`db_query` is read-only enforced**: only statements starting with `SELECT` / `SHOW` / `DESCRIBE` / `EXPLAIN` / `WITH` are accepted; writes are rejected with a pointer to `db_execute`.
- **Add an explicit `LIMIT`** for large tables; `maxRows` only caps the returned rows, it does not limit how much the SQL scans.

## Troubleshooting

| Symptom | Cause / fix |
|---|---|
| `pnpm not found` | Install pnpm (`corepack enable pnpm` or `npm i -g pnpm`) and put it on `PATH` |
| `ECONNREFUSED` / cannot connect | Wrong host or port; verify the server is listening and the port is right (non-default ports especially) |
| `no database selected` | Set the connection's default database in the card, or write `db.table` in the SQL |
| `db_schema` lists no tables | Same: the connection has no default database |
| `connection "x" not found` | The `connection` argument does not match a connection alias in the card |
| `db_execute` says writes are disabled | Write permission is **off by default**; tick "允许写操作" in the card's "全局选项" and save |
| `db_backup` / `db_restore` say they are disabled | Same: tick "允许备份 / 恢复" and save |
| No `dba` card in the UI | The plugin is not loaded / not restarted; check **Plugin list** for `dsh-local-dba` running |
| Backup reports `command not found` | `mysqldump` / `pg_dump` is missing on this machine |
| `only_full_group_by`-style errors | Raw database errors surfaced as-is; fix the SQL |

## Layout

```
dsh-local-dba/
├── package.json        # dual-face: dsh.bundle.patch → cordis.patch.yml; dsh.client → lib/client.js
├── cordis.patch.yml    # the row that registers this plugin
├── lib/
│   ├── index.js        # Host half: the 8 db_* tools + the settings namespace
│   ├── db.js           # database and native-CLI helpers
│   ├── client.js       # browser half: the settings card
│   └── index.d.ts      # type declarations
├── README.md
├── README.zh.md
└── LICENSE
```

## Development notes

- **No build step**: `lib/*.js` is the runtime code (ESM).
- `@deepseek-ai/cordis` and `@deepseek-ai/dsh-tools` are **peerDependencies** (so the plugin reuses the host's single tool registry); `@deepseek-ai/schemastery`, `mysql2` and `pg` are regular dependencies.
- Changing the Host half (`lib/index.js` / `lib/db.js`) or the browser half (`lib/client.js`) requires a **profile restart**. Configuration changes made in the card hot-reload.

## Contact

- **Email**: 5235278@qq.com
- **Issues**: <https://github.com/kichare/dsh-local-dba/issues>

Questions, bug reports and feature requests are all welcome.

## License

[MIT](LICENSE)