前言¶
DSH 的插件体系可以把外部能力挂到 agent 侧。数据库这类能力很常见，但直接让模型执行任意 SQL 风险较高：读库需要稳定，写库需要审批，连接配置也需要集中管理。
dsh-sql 提供一套 SQL 工具，定位是工程师级数据库插件，覆盖连接管理、只读查询、写操作与结构探查，支持 SQLite / MySQL / PostgreSQL 三引擎。
这是什么¶
dsh-sql 是 DSH 插件，围绕数据库访问提供四个工具：
sql_list：列出连接并做连通性测试。sql_query：执行只读查询。sql_exec：执行写操作或 DDL。sql_schema：查看表清单和表结构。
它强调只读白名单、写审批门、流式行数钳制和多连接配置。许可证为 MIT，运行要求 Node >=22.13。
核心功能¶
工具边界¶
sql_list：用于确认当前配置了哪些连接，以及连接是否可用。sql_query：用于只读查询，支持SELECT、PRAGMA、EXPLAIN、SHOW、DESCRIBE、WITH；按关键字白名单校验，并拒绝多语句。sql_exec：用于写操作/DDL，可执行多语句脚本；受readOnly禁用与审批门控制。sql_schema：用于查看表清单和表结构，并做标识符白名单校验。
连接与限制¶
- 支持 SQLite / MySQL / PostgreSQL 三引擎。
- 支持多连接配置。
- 查询返回行数上限
maxRows范围为1-10000。 queryTimeoutMs默认60秒，范围5秒到10分钟。execTimeoutMs默认120秒，范围5秒到10分钟。- 密码支持环境变量
DSH_SQL_PASSWORD_<连接名>，例如连接名为prod时使用DSH_SQL_PASSWORD_PROD。
安装与启用¶
在 Web profile 下安装：
dsh plugin --profile web add dsh-sql
安装后，sql_list、sql_query、sql_exec、sql_schema 可在 DSH 插件侧使用。该插件已在 @deepseek-ai/dsh@0.1.2-alpha.4 源码模式下验证，验证日期为 2026-09-02。
典型用法¶
下面示例来自已核实用法：
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 用于先看有哪些连接是否可用；sql_schema 用于看表结构；sql_query 用于只读查询；sql_exec 用于写操作，默认会触发审批。headless 环境无审批通道时，sql_exec 会拒绝执行。readOnly 为 true 时，sql_exec 被禁用。
适用场景与注意¶
适合需要在 DSH 中接入数据库、同时限制模型只读或审批写库的场景。若连接生产库，建议把写操作放在受审批的环境中，并考虑使用 readOnly: true。密码优先使用 DSH_SQL_PASSWORD_<连接名> 环境变量，不要写入可公开配置。
使用前应将 dsh-sql 视为以当前 dsh 进程权限运行：它能访问的数据库取决于该进程的连接与权限。安装前建议先检查源码与许可证。卸载后需重启 Web 服务；如需彻底清理，可手动删除自己 profile cordis.patch.yml 中覆盖的插件行。
结尾¶
dsh-sql 的价值在于把数据库访问拆成四个边界更清晰的工具：列连接、读查询、受控写、结构探查。这样既能让 agent 查库，也能把写操作限制在审批和只读策略内。
