dsh-sql

dsh-sql is a database plugin for DSH (DeepSeek Harness) that lets agents connect to and operate databases. It provides six tools covering connection management, read-only queries, write operations, schema exploration, statistics overview, and health self-checks. Tool overview: - sql_list: lists configured connections and performs connectivity tests. - sql_query: read-only queries, supports SELECT/PRAGMA/EXPLAIN/SHOW/DESCRIBE/WITH, uses a keyword whitelist and rejects multiple statements. - sql_exec: write operations and DDL, can execute multi-statement scripts, constrained by the readOnly switch and approval gate. - sql_schema: lists tables or shows the structure of a specified table; table names are validated against an identifier whitelist. - sql_stats: provides an overview of table count, row counts, and database size; query failures are isolated from one another. - sql_health: probes each connection for liveness and checks security configuration without echoing passwords. Engines and connections: SQLite uses node:sqlite built into Node 22.13+, with zero dependencies; MySQL uses the mysql2 connection pool; PostgreSQL uses the pg connection pool. Multiple named connections can be declared in the configuration, each specifying an engine and connection parameters. If no configuration is provided, a default :memory: SQLite connection is given; however, if a configuration exists but is invalid, loading stops with an error rather than silently falling back to an in-memory database. Security design: - Lexical read-only protection: sql_query strips strings and comments before validation, rejecting data-modifying CTEs (WITH...DELETE/UPDATE), SELECT INTO, FOR UPDATE/FOR SHARE, PRAGMA assignments, and multiple statements. - Write approval gate: sql_exec prompts for approval by default; in headless environments without an approval channel, execution is refused. - readOnly mode: write operations can be disabled entirely, suitable for production databases. - Streaming row clamping: SQLite iterators, MySQL Readable streams, and PostgreSQL Query row events collect at most maxRows+1 rows and mark results as truncated when exceeded; MySQL and PostgreSQL close the dedicated connection for that query once the limit is reached, and return it to the pool otherwise, preventing full result sets from residing in memory. - Cancellable execution: queries and write operations honor the Harness exec.signal; on cancellation, waiting is aborted and in-flight dedicated MySQL/PostgreSQL connections are destroyed. - Lossless big integers: bigint values within JavaScript's safe integer range are output as numbers, while those beyond the range are output as decimal strings, avoiding silent precision loss. - Identifier validation: table names only allow letters, digits, and underscores, preventing schema injection. - Secrets kept out of configuration: passwords can be supplied via the DSH_SQL_PASSWORD_ environment variable with the connection name appended. Configuration options include maxRows (maximum rows returned per query, 1-10000), queryTimeoutMs (per-query timeout, default 60 seconds), execTimeoutMs (per-write-operation timeout, default 120 seconds), readOnly, and writeApproval. Installation is done via dsh plugin --profile web add dsh-sql; after uninstalling, the Web service must be restarted. The project uses the MIT license; for development, use pnpm install and pnpm test (build plus the full test suite, including real SQLite integration). The README states it has been verified on official @deepseek-ai/dsh@0.1.5-rc.1 and Node 24.16.0, using the cordis.patch.yml and dsh.bundle.patch combined package model.