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

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

Questions, bug reports and feature requests are all welcome.

License

MIT