Introduction

DSH’s plugin system allows external capabilities to be attached to the agent side. Database capabilities are common, but allowing the model to execute arbitrary SQL carries high risk: database reads require stability, writes require approval, and connection configuration also requires centralized management.

dsh-sql provides a suite of SQL tools designed for engineers, covering connection management, read-only queries, write operations, and schema exploration, supporting SQLite / MySQL / PostgreSQL.

What is it

dsh-sql is a DSH plugin that provides four tools centered around database access:

  • sql_list: Lists connections and performs connectivity tests.
  • sql_query: Executes read-only queries.
  • sql_exec: Executes write operations or DDL.
  • sql_schema: Views table lists and table structures.

It emphasizes a read-only whitelist, write approval gates, streaming row limits, and multi-connection configuration. The license is MIT, and it requires Node >=22.13.

Core Features

Tool Boundaries

  • sql_list: Used to confirm which connections are currently configured and whether the connections are available.
  • sql_query: Used for read-only queries, supporting SELECT, PRAGMA, EXPLAIN, SHOW, DESCRIBE, and WITH; it validates against a keyword whitelist and rejects multi-statement execution.
  • sql_exec: Used for write operations/DDL, capable of executing multi-statement scripts; it is controlled by readOnly disabling and approval gates.
  • sql_schema: Used for viewing table lists and table structures, and performs identifier whitelist validation.

Connections and Limits

  • Supports SQLite / MySQL / PostgreSQL engines.
  • Supports multi-connection configuration.
  • Query return row limit maxRows ranges from 1-10000.
  • queryTimeoutMs defaults to 60 seconds, with a range from 5 seconds to 10 minutes.
  • execTimeoutMs defaults to 120 seconds, with a range from 5 seconds to 10 minutes.
  • Passwords support environment variables DSH_SQL_PASSWORD_<connection_name>, for example, when the connection name is prod, use DSH_SQL_PASSWORD_PROD.

Installation and Activation

Install under the Web profile:

dsh plugin --profile web add dsh-sql

After installation, sql_list, sql_query, sql_exec, and sql_schema can be used within the DSH plugin side. This plugin has been verified in @deepseek-ai/dsh@0.1.2-alpha.4 source mode, verified on 2026-09-02.

Typical Usage

The following examples come from verified use cases:

sql_list {}
sql_schema {}
sql_schema { table: users }
sql_query { sql: SELECT * FROM orders WHERE status = 'pending' LIMIT 50 }
sql_exec { sql: UPDATE orders SET status = 'paid' WHERE id = 42 }

sql_list is used to first check which connections are available; sql_schema is used to view table structures; sql_query is used for read-only queries; sql_exec is used for write operations, which triggers approval by default. In a headless environment without an approval channel, sql_exec will refuse execution. When readOnly is true, sql_exec is disabled.

Applicable Scenarios and Notes

Suitable for scenarios where database integration is needed in DSH while limiting model access to read-only or requiring approval for write operations. If connecting to a production database, it is recommended to place write operations in an approval-controlled environment and consider using readOnly: true. For passwords, prioritize using the DSH_SQL_PASSWORD_<connection_name> environment variable rather than writing them into publicly accessible configurations.

Before use, treat dsh-sql as running with the current DSH process permissions: the databases it can access depend on the connection and permissions of that process. It is recommended to check the source code and license before installation. After uninstallation, the Web service needs to be restarted; for a thorough cleanup, manually delete the plugin lines overridden in your profile cordis.patch.yml.

Conclusion

The value of dsh-sql lies in splitting database access into four tools with clearer boundaries: connection listing, read queries, controlled writes, and schema exploration. This allows the agent to query databases while keeping write operations within the bounds of approval and read-only policies.

Repository: STARDUSTLC666/dsh-sql