dsh-mysql

MySQL connections and guarded database tools for DeepSeek Harness
Configure connections once, choose one per conversation, and let your agent inspect or query the selected database.

English | 中文

dsh-mysql is a profile bundle for DeepSeek Harness (DSH). It adds a settings page for multiple MySQL connections, a per-session connection picker beside the composer, and three guarded tools that every agent preset can use. No preset edits are required.

Data boundary: connection settings and passwords stay in your local DSH storage. Database schema and query results are sent to the LLM provider as ordinary tool output when the agent uses a database tool.

At a glance

Features

• Multiple connections: keep separate development, staging, or production data sources in one DSH installation.
• Per-session selection: changing the connection in one conversation does not silently switch another conversation.
• Schema-first workflow: mysql_tables exposes readable columns, types, nullability, keys, and comments before a query is written.
• Read-only by default: write access is an explicit per-connection setting and is disabled by default.
• Local-first configuration: the browser receives a safe connection view with hasPassword, never the stored password.
• No preset changes: the tools are registered globally by the profile bundle and are available under every agent preset.

Agent tools

A typical read-only request is:

Use mysql_tables to inspect the available schema first, then use mysql_query to answer my question. Do not modify data.

Requirements and compatibility

• A DSH installation with the Web profile and Node.js 20 or newer.
• A MySQL-compatible server reachable through the configured TCP host and port.
• The connection form currently supports host, port, username, password, default database, table allowlist, and write permission. It does not expose SSL/TLS, Unix socket/named-pipe, or charset options.
• The MAX_EXECUTION_TIME optimizer hint is intended for MySQL versions that support it (MySQL 5.7.8+). MariaDB may handle this hint differently; SHOW, DESCRIBE, and EXPLAIN do not receive the hint.
• mysql_tables discovers tables in DATABASE(). Configure a default database if you want schema discovery; a connection without one can return an empty table list.

Install, update, or remove

Install from GitHub

dsh plugin --profile web add github:1321928757/dsh-mysql#v0.1.11

Install from npm

Use this after dsh-mysql is available in the npm registry:

dsh plugin --profile web add dsh-mysql

PowerShell installer

The repository also provides a Windows installer that checks for dsh, prepares a pinned pnpm helper under %USERPROFILE%\.dsh-tmp, and installs the selected GitHub tag into the web profile:

irm https://raw.githubusercontent.com/1321928757/dsh-mysql/v0.1.11/scripts/install.ps1 | iex

After installation, restart dsh web. Then open Settings → MySQL 数据库, add and test a connection, and select it from the database button beside the composer.

Verify that the bundle is in the profile:

dsh --profile web --dump-config | findstr dsh-mysql

Remove it with:

dsh plugin --profile web remove dsh-mysql

dsh plugin --profile web update dsh-mysql@latest

dsh plugin --profile demo add E:\path\to\dsh-mysql
dsh --profile demo --dump-config

Quick start

1. Open Settings → MySQL 数据库 and click 添加连接. Fill in the host, port, username, password, and default database. Optionally add readable table names and enable write permission only when needed. Test the connection, then save it.
2. Open a conversation and click the database button on the left of the composer. Select a connection for that session. If exactly one connection exists, it is selected automatically.
3. Ask a database question. The agent can inspect the schema with mysql_tables, read with mysql_query, and use mysql_execute only for an explicitly writable connection.

Screenshots

The screenshots below were captured from the real DSH Web shell with the plugin loaded. Connection names and account names in the settings example are illustrative; passwords are not shown.

Configure a connection

The settings page groups connection details, database scope, and permissions. Read-only is the default. The add-connection form keeps 保存连接 as the primary action, while 测试连接 remains a quieter secondary action.

The form can be opened below the saved connection cards without leaving the settings page:

Select a connection for a session

The composer shows the database control even before a connection is selected. Its arrow points down while the picker is closed:

Click it to search and choose from the configured connections. The arrow points up while the list is expanded:

After a connection is selected, its name, green status dot, and down arrow appear in the composer. The selected connection is also included in the conversation context shown to the agent:

After the agent runs a read-only query, the tool result is displayed in the conversation:

Security and permissions

The plugin uses multiple guardrails, but it does not replace database permissions. Use a dedicated MySQL account with the least privileges possible; for read-only work, a SELECT-only account is recommended.

Passwords are stored as plain text in $DSH_HOME/storages/dsh-mysql/connections.json. Protect this file with operating-system permissions and do not commit or share it.

Known limitations

• There is one active database selection per conversation session; selecting a connection does not change other sessions.
• mysql_tables uses the connection's DATABASE() value, so schema discovery may be empty when no default database is configured. It does not browse arbitrary databases.
• The table allowlist is intentionally lightweight and checks common table-reference positions rather than parsing every MySQL grammar form.
• The 2,000-row limit applies to the returned JSON payload after the database response has been fetched.
• mysql_execute does not provide transaction management, DDL, or a confirmation workflow. Enable write permission only for a narrowly scoped database account.
• Connection configuration is TCP-oriented and has no UI for SSL/TLS, Unix sockets/named pipes, or character-set selection.

How it works

Composer / Settings UI
        │  browser slot + Typert RPC (remote.mysql.*)
        ▼
Host mysql service
        │  per-session selection + lazy mysql2 pool
        ├── local JSON: $DSH_HOME/storages/dsh-mysql/connections.json
        └── systemPrompt.context: selected connection + readable tables

• Host bundle (lib/index.js) registers the three model tools, manages lazy mysql2 pools, persists connections, tracks the session selection, and provides the mysql service.
• Typert manifest (lib/typert.host.js) exposes connection CRUD, testing, selection, and table-list methods to the browser through remote.mysql.*.
• Browser bundle (lib/client.js) registers the conversation.input.left database control and the settings.section connection-management page. UI styles consume DSH --dsw-* theme tokens.
• The selected connection is added through systemPrompt.context as a dynamic tail section, so switching connections does not rewrite the stable cached system-prompt prefix.

Migrating from a preset-embedded MySQL tool

If a preset previously embedded mysql_query or mysql_execute through a local tool row:

1. Install this plugin into the profile.
2. Remove the old MySQL tool row and connection configuration from the preset's agent.cordis.yml; keep the business persona text.
3. Restart dsh web, then recreate the connection in Settings → MySQL 数据库. The tool names are unchanged, so prompts that mention them continue to work.

FAQ and troubleshooting

Development

Syntax-check each JavaScript file individually, run the shared-function tests, then pack a local artifact:

Get-ChildItem lib\*.js | ForEach-Object { node --check $_.FullName }
node test\shared.test.mjs
pnpm pack

Install the packed artifact into a scratch profile and verify the real bundle:

dsh plugin --profile demo add .\dsh-mysql-0.1.10.tgz
dsh --profile demo --dump-config

When releasing a new version, update the version in package.json, the $Rev value in scripts/install.ps1, the tagged install URLs in both README files, and screenshots.json if the screenshot set changes.

License

MIT. This project is not affiliated with DeepSeek. Installing the plugin runs third-party code on your machine; review the source before use.