dsh-local-dba
English | 中文
A local database-administration (DBA) plugin for 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
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:
# 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:
# 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
Questions, bug reports and feature requests are all welcome.
License
MIT
