dsh-tool-sql

dsh-tool-sql

English | 中文

A Cordis tool plugin that gives DeepSeek Harness (dsh) read-only SQL capabilities. Agents can query data, list tables, and inspect table schemas on PostgreSQL and MySQL in natural language — with a safety-first model that rejects write statements by default.

Built on the official "everything is a plugin" architecture via ctx.tools.register(defineTool(...)), following the official adding-a-tool contract.

Install

Install directly from GitHub (no npm publish needed):

npm install github:LJH-snow/dsh-tool-sql
# or a specific branch/tag
npm install github:LJH-snow/dsh-tool-sql#main

Or from a local checkout:

git clone https://github.com/LJH-snow/dsh-tool-sql
cd dsh-tool-sql
npm install && npm run build   # builds to lib/
npm install /path/to/dsh-tool-sql

Once published to npm, it will also be installable as npm install @libai168/dsh-tool-sql.

Requires @deepseek-ai/cordis (^4.0.1) and @deepseek-ai/dsh-tools (^0.1.0-rc.6) as peer dependencies, provided by the host dsh runtime.

Configuration

Load the plugin in a dsh composition config (cordis.yml):

- name: 'dsh-tool-sql'
  config:
    type: 'postgres'        # or 'mysql'
    host: 'localhost'
    port: 5432              # optional (postgres 5432, mysql 3306)
    user: 'dbuser'
    password: 'dbpass'
    database: 'appdb'
    maxRows: 100            # optional, max rows per query (default 100)
    maxColumns: 100         # optional, max columns per query (default 100)
    maxBytes: 1048576       # optional, max serialized result bytes (default 1 MiB)
    timeoutMs: 15000        # optional, query timeout in ms (default 15000)
    ssl: false              # optional, enable TLS
    # sslRejectUnauthorized: true # optional; defaults to true when TLS is enabled

Full example: examples/cordis.yml.

Security: the plugin enforces read-only at two layers. Only SELECT/EXPLAIN/SHOW/DESCRIBE/WITH/PRAGMA/VALUES statements are allowed; multiple statements, DML/DDL, transaction/session control, locking clauses, file I/O, external execution, sequence mutation, and dangerous PostgreSQL/MySQL functions are rejected before the driver runs. PostgreSQL sessions set default_transaction_read_only and statement_timeout; MySQL sessions set TRANSACTION READ ONLY and MAX_EXECUTION_TIME. Results are bounded in the client by rows, columns, and serialized bytes before tools render them. Credentials are read from plugin config only and are never printed or logged.

When ssl: true, certificate verification is enabled by default (sslRejectUnauthorized: true). Set sslRejectUnauthorized: false only for an explicitly trusted self-signed deployment.

Tools

Development

npm install
npm run typecheck   # type check
npm test            # unit tests (vitest)
npm run build       # build to lib/

Development plan and decision records: DEVELOPMENT.md.

Publishing & Ecosystem

1. Publishing uses your npm scope: @libai168/dsh-tool-sql (npm publishing requires a granular access token with 2FA bypass, or trusted publishing).
2. After npm run build, run npm publish --access public.
3. Add the dsh-plugin topic to your GitHub repository for ecosystem discovery.

License

MIT