dsh-sql 0.4.5 → 0.4.6

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 [返回简介](README.md) · [使用说明](docs/USAGE.md) · [验证记录](docs/VALIDATION.md)
 
+## 0.4.6 (2026-10-20)
+
+- 修复 sql_query 只读校验与 PostgreSQL 反斜杠语义不一致的问题：词法去噪改为按引擎处理反斜杠（MySQL 默认转义 / PostgreSQL 只有 `E'…'`、`U&'…'` 转义 / SQLite 与引号标识符里都不转义）。`SELECT '\'; DELETE FROM users; --'` 这类双语句载荷会被拒绝，不再能在 readOnly=true 下删表
+- 修复 PRAGMA 函数式写法绕过只读校验的问题：`PRAGMA foreign_keys(0)`、`writable_schema(1)`、`user_version(4242)` 等与 `name=value` 等价，现在改为只读 PRAGMA 白名单，只放行 table_info / index_list / page_count 等内省语句
+- readOnly=true 时把只读约束下沉到数据库自身：SQLite 以只读方式打开文件、PostgreSQL 加 `-c default_transaction_read_only=on`、MySQL 每个新连接执行 `SET SESSION TRANSACTION READ ONLY`。词法校验被绕过时服务器仍会拒绝写入
+- sql_exec 审批文本不再截断到 200 字符：逐条列出每条语句并附语句类型统计；超过 800 字符时把完整 SQL 指回工具参数，200 字符之后的 DROP TABLE 不会再从审批卡里消失
+- 新增 `test/readonly-hardening.test.mjs`（10 项回归），`tools.test.mjs` 的 PRAGMA 断言同步更新
+
 ## 0.4.5 (2026-10-05)
 
 - 保留 SQLite 64 位整数与三种数据库的同名列；零行结果保留列名。同名列 JSON 导出使用 columns / rows，避免后列覆盖前列。

package/README.en.md

@@ -8,6 +8,8 @@ Connect SQLite, MySQL or PostgreSQL to query data and inspect schemas.
 
 [![npm](https://img.shields.io/npm/v/dsh-sql)](https://www.npmjs.com/package/dsh-sql) [![downloads](https://raw.githubusercontent.com/STARDUSTLC666/dsh-suite/npm-downloads/assets/dsh-sql-downloads.svg)](https://www.npmjs.com/package/dsh-sql)
 
+Feedback and contributions are welcome: report [issues](https://github.com/STARDUSTLC666/dsh-sql/issues) or submit [pull requests](https://github.com/STARDUSTLC666/dsh-sql/pulls).
+
 ## What it does
 
 - Manage connections and inspect schemas or database summaries.

package/README.md

@@ -8,6 +8,8 @@
 
 [![npm](https://img.shields.io/npm/v/dsh-sql)](https://www.npmjs.com/package/dsh-sql) [![downloads](https://raw.githubusercontent.com/STARDUSTLC666/dsh-suite/npm-downloads/assets/dsh-sql-downloads.svg)](https://www.npmjs.com/package/dsh-sql)
 
+欢迎使用，遇到问题或有改进建议，请提交 [issues](https://github.com/STARDUSTLC666/dsh-sql/issues) 和 [PR](https://github.com/STARDUSTLC666/dsh-sql/pulls)。
+
 ## 功能
 
 - 管理连接，查询结构和数据概览。

package/docs/USAGE.md

@@ -44,7 +44,7 @@ dsh plugin --profile web remove dsh-sql
     maxRows: 1000                     # 查询返回行数上限（1-10000）
     queryTimeoutMs: 60000             # 单次查询超时（默认 60 秒，5 秒 - 10 分钟）
     execTimeoutMs: 120000             # 单次写操作超时（默认 120 秒，5 秒 - 10 分钟）
-    readOnly: false                   # true 时禁用 sql_exec
+    readOnly: false                   # true 时禁用 sql_exec，并让数据库自身以只读方式连接
     writeApproval: true               # 写操作先弹审批（默认 true）
 ```
 
@@ -55,7 +55,7 @@ dsh plugin --profile web remove dsh-sql
 | 工具 | 作用 | 安全 |
 | :-- | :-- | :-- |
 | `sql_list` | 列出连接 + 连通性测试 | — |
-| `sql_query` | 只读查询（SELECT/PRAGMA/EXPLAIN/SHOW/DESCRIBE/WITH）| 关键字白名单 + 拒绝多语句 |
+| `sql_query` | 只读查询（SELECT/PRAGMA/EXPLAIN/SHOW/DESCRIBE/WITH）| 按引擎去噪的关键字白名单 + 拒绝多语句 + PRAGMA 白名单 |
 | `sql_exec` | 写操作/DDL（可多语句脚本）| readOnly 禁用 + 审批门 |
 | `sql_schema` | 表清单 / 表结构 | 标识符白名单校验 |
 | `sql_stats` | 表数量、行数与库体积概览 | 表名引用 + 查询失败隔离 |
@@ -75,9 +75,10 @@ sql_exec { sql: UPDATE orders SET status = 'paid' WHERE id = 42 }
 
 ## 安全设计
 
-- **词法级只读保护**：sql_query 先剥离字符串/注释再校验，拒绝 data-modifying CTE（WITH…DELETE/UPDATE）、SELECT INTO、FOR UPDATE/FOR SHARE、PRAGMA 赋值与多语句
+- **词法级只读保护**：sql_query 先剥离字符串/注释再校验，拒绝 data-modifying CTE（WITH…DELETE/UPDATE）、SELECT INTO、FOR UPDATE/FOR SHARE、多语句，以及不在只读白名单里的 PRAGMA。去噪按引擎处理反斜杠（MySQL 默认转义、PostgreSQL 只有 `E'…'`/`U&'…'` 转义、SQLite 与引号标识符里都不转义），避免「校验看到一条、服务器执行两条」
 - **写审批门**：sql_exec 默认弹审批（对齐 dsh-email 的发信审批），headless 环境无审批通道时拒绝执行
-- **readOnly 模式**：生产库可整体禁用写
+- **readOnly 模式**：生产库可整体禁用写。除了禁用 sql_exec，还会把只读约束下沉到数据库自身：SQLite 以只读方式打开文件，PostgreSQL 用 `-c default_transaction_read_only=on` 启动参数，MySQL 在每个新连接上执行 `SET SESSION TRANSACTION READ ONLY`（需要 MySQL 5.6.5+ / MariaDB 10.0+）。即使词法校验被绕过，服务器也会拒绝写入
+- **审批卡不藏语句**：sql_exec 的审批文本逐条列出每条语句，并给出一行语句类型统计；超过 800 字符时把完整 SQL 指回工具参数，第二条 DROP / DELETE 不会因为截断而从审批卡里消失
 - **流式行数钳制**：SQLite 迭代器 / MySQL Readable / PostgreSQL Query 行事件最多收集 maxRows+1 行，超量标记 truncated；MySQL 和 PostgreSQL 在达到上限时关闭该查询的专用连接，未达上限则正常归还连接池，避免全量结果驻留内存
 - **可取消执行**：查询与写操作遵守 Harness 的 `exec.signal`；取消时会中止等待并销毁正在工作的 MySQL/PostgreSQL 专用连接
 - **大整数无损**：数据库返回的 bigint 在 JavaScript 安全整数范围内输出 number，超出范围则输出十进制字符串，避免静默丢精度

package/lib/adapters.d.ts

@@ -1,3 +1,5 @@
+import mysql from 'mysql2/promise';
+import pg from 'pg';
 import { type SqlConnectionConfig } from './config.js';
 /** 查询结果：列名 + 行（值数组，无损 JSON 友好）。 */
 export interface QueryResult {
@@ -21,5 +23,17 @@ export interface DatabaseAdapter {
     ping(signal?: AbortSignal): Promise<void>;
     close(): Promise<void>;
 }
-/** 按连接配置创建适配器。 */
-export declare function createAdapter(connection: SqlConnectionConfig): DatabaseAdapter;
+/** 适配器额外选项：readOnly 时把只读约束下沉到数据库自身。 */
+export interface AdapterOptions {
+    readOnly?: boolean;
+}
+/** MySQL 连接池配置（导出以便测试断言，不含连接）。 */
+export declare function mysqlPoolConfig(connection: SqlConnectionConfig): mysql.PoolOptions;
+/**
+ * PostgreSQL 连接池配置。readOnly 时用启动参数把会话默认事务设为只读：
+ * 即使词法校验被绕过（多语句、反斜杠、注释技巧），服务器也会以
+ * "cannot execute ... in a read-only transaction" 拒绝写操作。
+ */
+export declare function postgresPoolConfig(connection: SqlConnectionConfig, readOnly?: boolean): pg.PoolConfig;
+/** 按连接配置创建适配器；readOnly 会下沉到引擎自身的只读约束。 */
+export declare function createAdapter(connection: SqlConnectionConfig, options?: AdapterOptions): DatabaseAdapter;

package/lib/adapters.js

@@ -117,12 +117,56 @@ function streamPostgresQuery(client, sql, limit, discard) {
         client.query(query);
     });
 }
+/** MySQL 连接池配置（导出以便测试断言，不含连接）。 */
+export function mysqlPoolConfig(connection) {
+    return {
+        host: connection.host ?? 'localhost',
+        port: connection.port ?? 3306,
+        user: connection.user ?? '',
+        password: connection.password ?? '',
+        database: connection.database ?? '',
+        connectionLimit: 5,
+        enableKeepAlive: true,
+        supportBigNumbers: true,
+        bigNumberStrings: true,
+        // 显式关掉多语句：即使词法校验被绕过，服务器也不会把第二句当命令执行。
+        multipleStatements: false,
+    };
+}
+/**
+ * PostgreSQL 连接池配置。readOnly 时用启动参数把会话默认事务设为只读：
+ * 即使词法校验被绕过（多语句、反斜杠、注释技巧），服务器也会以
+ * "cannot execute ... in a read-only transaction" 拒绝写操作。
+ */
+export function postgresPoolConfig(connection, readOnly = false) {
+    const config = {
+        host: connection.host ?? 'localhost',
+        port: connection.port ?? 5432,
+        user: connection.user ?? '',
+        password: connection.password ?? '',
+        database: connection.database ?? '',
+        max: 5,
+    };
+    if (readOnly)
+        config.options = '-c default_transaction_read_only=on';
+    return config;
+}
 /** SQLite 适配器（node:sqlite，零依赖）。 */
 class SqliteAdapter {
     engine = 'sqlite';
     db;
-    constructor(file) {
-        this.db = new DatabaseSync(file === ':memory:' ? ':memory:' : file);
+    constructor(file, readOnly = false) {
+        const memory = file === ':memory:';
+        // 内存库没有落盘风险，也不支持只读打开；文件库在 readOnly 下由 SQLite
+        // 自己拒绝任何写入（PRAGMA 写、DDL、DML 都会报 attempt to write a readonly database）。
+        const options = readOnly && !memory ? { readOnly: true } : {};
+        try {
+            this.db = new DatabaseSync(memory ? ':memory:' : file, options);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new Error('无法打开 SQLite 文件 ' + file + '（readOnly=' + readOnly + '）：' + detail);
+        }
         this.db.exec('PRAGMA busy_timeout = 5000');
     }
     async listTables(signal) {
@@ -188,18 +232,15 @@ class SqliteAdapter {
 class MysqlAdapter {
     engine = 'mysql';
     pool;
-    constructor(connection) {
-        this.pool = mysql.createPool({
-            host: connection.host ?? 'localhost',
-            port: connection.port ?? 3306,
-            user: connection.user ?? '',
-            password: connection.password ?? '',
-            database: connection.database ?? '',
-            connectionLimit: 5,
-            enableKeepAlive: true,
-            supportBigNumbers: true,
-            bigNumberStrings: true,
-        });
+    constructor(connection, readOnly = false) {
+        this.pool = mysql.createPool(mysqlPoolConfig(connection));
+        if (readOnly) {
+            // 会话级只读：MySQL 5.6.5+ 的 SET SESSION TRANSACTION READ ONLY 会让
+            // 该连接上后续任何 DML/DDL 被服务器拒绝，不依赖词法校验。
+            this.pool.on('connection', (session) => {
+                void session.query('SET SESSION TRANSACTION READ ONLY').catch(() => { });
+            });
+        }
     }
     async withSignalConnection(signal, work) {
         signal?.throwIfAborted();
@@ -274,15 +315,8 @@ class MysqlAdapter {
 class PostgresAdapter {
     engine = 'postgres';
     pool;
-    constructor(connection) {
-        this.pool = new pg.Pool({
-            host: connection.host ?? 'localhost',
-            port: connection.port ?? 5432,
-            user: connection.user ?? '',
-            password: connection.password ?? '',
-            database: connection.database ?? '',
-            max: 5,
-        });
+    constructor(connection, readOnly = false) {
+        this.pool = new pg.Pool(postgresPoolConfig(connection, readOnly));
     }
     async withSignalClient(signal, work) {
         signal?.throwIfAborted();
@@ -371,11 +405,12 @@ class PostgresAdapter {
         await this.pool.end();
     }
 }
-/** 按连接配置创建适配器。 */
-export function createAdapter(connection) {
+/** 按连接配置创建适配器；readOnly 会下沉到引擎自身的只读约束。 */
+export function createAdapter(connection, options = {}) {
+    const readOnly = options.readOnly === true;
     if (connection.engine === 'sqlite')
-        return new SqliteAdapter(connection.file ?? ':memory:');
+        return new SqliteAdapter(connection.file ?? ':memory:', readOnly);
     if (connection.engine === 'mysql')
-        return new MysqlAdapter(connection);
-    return new PostgresAdapter(connection);
+        return new MysqlAdapter(connection, readOnly);
+    return new PostgresAdapter(connection, readOnly);
 }

package/lib/index.js

@@ -9,7 +9,7 @@
  * @module dsh-sql
  */
 import { resolveConfig } from './config.js';
-import { buildSqlTools } from './tools.js';
+import { buildSqlTools, summarizeWriteScript } from './tools.js';
 /** cordis 服务注入：apply 里要用 ctx.tools，必须显式声明。 */
 export const name = 'sql';
 export const inject = ['tools'];
@@ -27,7 +27,9 @@ export function apply(ctx, config) {
             const sql = typeof args.sql === 'string' ? args.sql : '';
             return {
                 kind: 'ask',
-                reason: 'sql_exec 写操作需要确认：' + sql.slice(0, 200) + (sql.length > 200 ? '…' : ''),
+                // 不截断整段 SQL：先逐条列出每条语句与语句类型统计，再附完整 SQL。
+                // 只截 200 字符会把第二条 DROP / DELETE 挡在审批卡之外。
+                reason: 'sql_exec 写操作需要确认：\n' + summarizeWriteScript(sql),
             };
         });
     }

package/lib/tools.d.ts

@@ -26,8 +26,22 @@ export interface SqlToolDefinition {
     execute(args: unknown, exec: unknown): Promise<unknown>;
     timeoutMs?: number;
 }
-/** 校验只读查询：词法去噪后白名单开头 + 写关键字扫描 + 单语句。 */
-export declare function assertReadQuery(sql: string): string;
+/** 词法校验需要区分的三种引擎。 */
+type SqlEngine = 'sqlite' | 'mysql' | 'postgres';
+/**
+ * 校验只读查询：词法去噪后白名单开头 + 写关键字扫描 + 单语句 + PRAGMA 白名单。
+ *
+ * `engine` 决定反斜杠转义规则（见 stripSqlNoise）；不传时按最保守的方式把
+ * 反斜杠当字面量，宁可误拒也不放过第二条语句。
+ */
+export declare function assertReadQuery(sql: string, engine?: SqlEngine): string;
+/**
+ * 把一段写操作脚本压成审批卡可读的摘要。
+ *
+ * 关键点：逐条列出每条语句，并额外给一行语句类型统计。即使脚本体被省略，
+ * 第二条、第 N 条语句的 DROP / DELETE 也不会从审批文本里消失。
+ */
+export declare function summarizeWriteScript(sql: string): string;
 /** 查询结果转 CSV 文本（RFC 4180 风格转义）。 */
 export declare function toCsv(columns: string[], rows: unknown[][]): string;
 /** 审批执行上下文的最小面。 */
@@ -42,3 +56,4 @@ export declare function buildSqlTools(config: ResolvedSqlConfig): {
     tools: SqlToolDefinition[];
     adapters: Map<string, DatabaseAdapter>;
 };
+export {};

package/lib/tools.js

@@ -40,8 +40,30 @@ function executionSignal(exec) {
 }
 /** 只读语句关键字白名单。 */
 const READ_KEYWORDS = /^(select|pragma|explain|show|describe|desc|with)\b/i;
-/** 去掉字符串、引号标识符与注释，保留真实 SQL 关键字与分号。 */
-function stripSqlNoise(sql) {
+/**
+ * PostgreSQL 的 E'…' / U&'…' 会把反斜杠当转义；普通 '…' 在
+ * standard_conforming_strings=on（9.1 起的默认值）下反斜杠是普通字符。
+ */
+function isPostgresEscapeString(sql, quoteIndex) {
+    const prev = sql[quoteIndex - 1];
+    const isWordChar = (ch) => ch !== undefined && /[A-Za-z0-9_$]/.test(ch);
+    if (prev === 'E' || prev === 'e')
+        return !isWordChar(sql[quoteIndex - 2]);
+    if (prev === '&') {
+        const u = sql[quoteIndex - 2];
+        return (u === 'U' || u === 'u') && !isWordChar(sql[quoteIndex - 3]);
+    }
+    return false;
+}
+/**
+ * 去掉字符串、引号标识符与注释，保留真实 SQL 关键字与分号。
+ *
+ * 反斜杠规则按引擎对齐，否则去噪结果会和服务器看到的分割方式不一致：
+ * MySQL 默认把 \ 当转义；PostgreSQL 只有 E'…' / U&'…' 才转义；
+ * SQLite 字符串里根本没有反斜杠转义。引号标识符（"…" 与 `…`）在三种
+ * 引擎里都不把反斜杠当转义，永远按字面量处理。
+ */
+function stripSqlNoise(sql, engine) {
     let out = '';
     let i = 0;
     while (i < sql.length) {
@@ -74,6 +96,7 @@ function stripSqlNoise(sql) {
         if (ch === "'") {
             out += ' ';
             i += 1;
+            const backslashEscapes = engine === 'mysql' || (engine === 'postgres' && isPostgresEscapeString(sql, i - 1));
             while (i < sql.length) {
                 if (sql[i] === "'" && sql[i + 1] === "'") {
                     i += 2;
@@ -83,7 +106,7 @@ function stripSqlNoise(sql) {
                     i += 1;
                     break;
                 }
-                if (sql[i] === '\\') {
+                if (backslashEscapes && sql[i] === '\\') {
                     i += 2;
                     continue;
                 }
@@ -99,10 +122,6 @@ function stripSqlNoise(sql) {
                     i += 1;
                     break;
                 }
-                if (sql[i] === '\\') {
-                    i += 2;
-                    continue;
-                }
                 i += 1;
             }
             continue;
@@ -132,10 +151,74 @@ function stripSqlNoise(sql) {
 }
 /** 写操作关键字：出在 SELECT/EXPLAIN/WITH 语句里即拒绝。 */
 const WRITE_KEYWORDS = /\b(insert|update|delete|replace|merge|drop|alter|create|truncate|call|execute|copy|grant|revoke|attach|detach|vacuum|reindex|refresh|set|reset|begin|commit|rollback|savepoint|release|analyze|load_extension)\b/i;
-/** 校验只读查询：词法去噪后白名单开头 + 写关键字扫描 + 单语句。 */
-export function assertReadQuery(sql) {
+/** 允许不带参数的只读 PRAGMA（含查询型与会话状态查询）。 */
+const READONLY_PRAGMAS = new Set([
+    'application_id',
+    'auto_vacuum',
+    'cell_size_check',
+    'collation_list',
+    'compile_options',
+    'data_version',
+    'database_list',
+    'encoding',
+    'freelist_count',
+    'function_list',
+    'journal_mode',
+    'legacy_file_format',
+    'mmap_size',
+    'module_list',
+    'page_count',
+    'page_size',
+    'pragma_list',
+    'schema_version',
+    'sqlite_version',
+    'user_version',
+]);
+/** 允许带一个标识符参数的只读内省 PRAGMA。 */
+const READONLY_PRAGMAS_WITH_ARG = new Set([
+    'foreign_key_check',
+    'foreign_key_list',
+    'index_info',
+    'index_list',
+    'index_xinfo',
+    'integrity_check',
+    'quick_check',
+    'table_info',
+    'table_list',
+    'table_xinfo',
+]);
+/**
+ * PRAGMA 白名单：只放行只读内省。
+ *
+ * SQLite 里 `PRAGMA name(value)` 与 `PRAGMA name = value` 完全等价，
+ * 只拦改号会让 `PRAGMA foreign_keys(0)` / `PRAGMA writable_schema(1)`
+ * 这类会改连接或库文件状态的调用漏过去，所以按名字白名单放行。
+ */
+function assertReadOnlyPragma(statement) {
+    const match = /^pragma\s+(?:[a-z_][a-z0-9_]*\.)?([a-z_][a-z0-9_]*)\s*(.*)$/i.exec(statement);
+    if (match === null)
+        throw new Error('无法解析这条 PRAGMA，sql_query 只接受只读的 PRAGMA 内省语句。');
+    const pragmaName = match[1].toLowerCase();
+    const rest = match[2].trim();
+    if (rest !== '' && /^[=(]/.test(rest)) {
+        if (!READONLY_PRAGMAS_WITH_ARG.has(pragmaName)) {
+            throw new Error('sql_query 不接受带参数的 PRAGMA ' + pragmaName.toUpperCase() + '（PRAGMA name(value) 与 name=value 等价，会改连接或数据库状态）。请用 sql_exec。');
+        }
+        return;
+    }
+    if (!READONLY_PRAGMAS.has(pragmaName) && !READONLY_PRAGMAS_WITH_ARG.has(pragmaName)) {
+        throw new Error('sql_query 只放行只读 PRAGMA 白名单（table_info / index_list / page_count / user_version 等），' + pragmaName.toUpperCase() + ' 不在白名单内。需要修改请用 sql_exec。');
+    }
+}
+/**
+ * 校验只读查询：词法去噪后白名单开头 + 写关键字扫描 + 单语句 + PRAGMA 白名单。
+ *
+ * `engine` 决定反斜杠转义规则（见 stripSqlNoise）；不传时按最保守的方式把
+ * 反斜杠当字面量，宁可误拒也不放过第二条语句。
+ */
+export function assertReadQuery(sql, engine) {
     const trimmed = sql.trim();
-    const clean = stripSqlNoise(trimmed);
+    const clean = stripSqlNoise(trimmed, engine);
     const first = /^[a-z]+/i.exec(clean.trim())?.[0]?.toLowerCase() ?? '';
     if (!READ_KEYWORDS.test(clean.trim())) {
         throw new Error('sql_query 只接受只读语句（SELECT / PRAGMA / EXPLAIN / SHOW / DESCRIBE / WITH）。写操作请用 sql_exec。');
@@ -145,8 +228,7 @@ export function assertReadQuery(sql) {
         throw new Error('sql_query 一次只允许一条语句。');
     const single = statements[0]?.trim() ?? '';
     if (first === 'pragma') {
-        if (/=/.test(single))
-            throw new Error('sql_query 不接受带赋值参数的 PRAGMA 写操作（如 PRAGMA journal_mode=WAL），请用 sql_exec。');
+        assertReadOnlyPragma(single);
     }
     else if (first === 'show' || first === 'describe' || first === 'desc') {
         // SHOW / DESCRIBE 本身只读，不再扫写关键字（避免误伤 SHOW CREATE TABLE）。
@@ -163,6 +245,40 @@ export function assertReadQuery(sql) {
     }
     return trimmed.replace(/;+\s*$/, '').trim();
 }
+/**
+ * 把一段写操作脚本压成审批卡可读的摘要。
+ *
+ * 关键点：逐条列出每条语句，并额外给一行语句类型统计。即使脚本体被省略，
+ * 第二条、第 N 条语句的 DROP / DELETE 也不会从审批文本里消失。
+ */
+export function summarizeWriteScript(sql) {
+    const trimmed = sql.trim();
+    const clean = stripSqlNoise(trimmed);
+    const statements = clean
+        .split(';')
+        .map((part) => part.replace(/\s+/g, ' ').trim())
+        .filter((part) => part !== '');
+    const effective = statements.length === 0 ? ['(空语句)'] : statements;
+    const tally = new Map();
+    for (const statement of effective) {
+        const keyword = /^[a-z]+/i.exec(statement)?.[0]?.toUpperCase() ?? '?';
+        tally.set(keyword, (tally.get(keyword) ?? 0) + 1);
+    }
+    const lines = ['共 ' + effective.length + ' 条语句：'];
+    effective.slice(0, 100).forEach((statement, index) => {
+        lines.push('  ' + (index + 1) + '. ' + (statement.length > 120 ? statement.slice(0, 120) + '…' : statement));
+    });
+    if (effective.length > 100)
+        lines.push('  …另有 ' + (effective.length - 100) + ' 条语句');
+    lines.push('语句类型：' + [...tally.entries()].map(([keyword, count]) => keyword + '×' + count).join('，'));
+    if (trimmed.length <= 800) {
+        lines.push('', '完整 SQL：' + trimmed);
+    }
+    else {
+        lines.push('', '完整 SQL 共 ' + trimmed.length + ' 个字符，见本次工具调用参数。');
+    }
+    return lines.join('\n');
+}
 const querySchema = {
     type: 'object',
     properties: {
@@ -289,15 +405,20 @@ const healthSchema = {
 export function buildSqlTools(config) {
     const cfg = config;
     const adapters = new Map();
-    const getAdapter = (name) => {
+    /** 只解析连接配置（不建连接），用于在打开数据库前挑选词法规则。 */
+    const findConnection = (name) => {
         const target = name ?? cfg.connections[0].name;
         const connection = cfg.connections.find((item) => item.name.toLowerCase() === target.toLowerCase());
         if (connection === undefined) {
             throw new Error('未找到名为 ' + target + ' 的数据库连接。可用 sql_list 查看连接清单。');
         }
+        return connection;
+    };
+    const getAdapter = (name) => {
+        const connection = findConnection(name);
         let adapter = adapters.get(connection.name);
         if (adapter === undefined) {
-            adapter = createAdapter(connection);
+            adapter = createAdapter(connection, { readOnly: cfg.readOnly });
             adapters.set(connection.name, adapter);
         }
         return { adapter, name: connection.name };
@@ -352,7 +473,7 @@ export function buildSqlTools(config) {
     };
     const sqlQuery = {
         name: 'sql_query',
-        description: '执行只读 SQL 查询（SELECT / PRAGMA / EXPLAIN / SHOW / DESCRIBE / WITH）。词法级校验会拒绝 data-modifying CTE、SELECT INTO、FOR UPDATE/FOR SHARE、PRAGMA 赋值与多语句。connection 为连接名（缺省第一个连接）。返回列名与行数据，最多 maxRows 行（超出 truncated=true）。写操作请用 sql_exec。',
+        description: '执行只读 SQL 查询（SELECT / PRAGMA / EXPLAIN / SHOW / DESCRIBE / WITH）。词法级校验按引擎处理反斜杠转义，拒绝 data-modifying CTE、SELECT INTO、FOR UPDATE/FOR SHARE、非白名单 PRAGMA 与多语句；readOnly=true 时还会让数据库自身以只读方式连接。connection 为连接名（缺省第一个连接）。返回列名与行数据，最多 maxRows 行（超出 truncated=true）。写操作请用 sql_exec。',
         parameters: compileParameters({
             sql: { type: 'string', required: true, description: '只读 SQL 语句（必填，单条）。' },
             connection: { type: 'string', description: '连接名（可选，缺省第一个连接）。' },
@@ -378,8 +499,11 @@ export function buildSqlTools(config) {
         },
         async execute(rawArgs, exec) {
             const args = asRecord(rawArgs);
-            const sql = assertReadQuery(requiredString(args, 'sql', 'SQL 语句'));
-            const { adapter, name } = getAdapter(optionalString(args, 'connection'));
+            const rawSql = requiredString(args, 'sql', 'SQL 语句');
+            const connectionName = optionalString(args, 'connection');
+            // 先按目标连接的引擎做词法校验，再打开数据库：被拒绝的 SQL 不该去建连接或建库文件。
+            const sql = assertReadQuery(rawSql, findConnection(connectionName).engine);
+            const { adapter, name } = getAdapter(connectionName);
             const result = await adapter.query(sql, cfg.maxRows + 1, executionSignal(exec));
             const total = result.rows.length;
             const rows = result.rows.slice(0, cfg.maxRows);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-sql",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "连接 SQLite、MySQL 或 PostgreSQL，查询数据并检查数据库结构。",
   "type": "module",
   "main": "lib/index.js",