dsh-db-tool 1.6.0 → 1.7.0

package/dist/adapters/dmdb/index.js

@@ -12,7 +12,9 @@
  *  - db.createPool({ connectString: 'dm://user:pass@host:5236', poolMin: 1, poolMax: 10,
  *    poolTimeout: 60, queueTimeout: 60000 })；不启用压缩（默认 compress=0，规避
  *    @napi-rs/snappy 跨平台坑）。
- *  - execute 必须显式 maxRows（默认 0=无限制）与 autoCommit: true（驱动默认非自动提交）。
+ *  - execute 必须显式 maxRows（默认 0=无限制）；autoCommit 显式传 true 使语义
+ *    不依赖驱动默认（驱动连接属性默认已是自动提交：dmdb connection.js
+ *    conn_prop_autoCommit = !0；d.ts 三级优先链 执行选项 > dmdb.autoCommit > 连接属性）。
  *  - 返回 { metaData, rows, rowsAffected } 与 oracledb 兼容。
  */
 import db from 'dmdb';
@@ -103,7 +105,8 @@ export async function createDmAdapter(conn, opts) {
             throw humanizeDmError(e);
         }
     }
-    /** 默认 execute 选项：显式 maxRows + 显式 autoCommit:true（dmdb 默认分别为 0/false，必须覆盖；SELECT 立即结束隐式事务，避免 ro 事务悬挂） */
+    /** 默认 execute 选项：显式 maxRows（dmdb 默认 0=无限制，必须覆盖）+ 显式 autoCommit:true
+     *  （驱动连接属性默认已是 true，显式传递仅让语义不依赖驱动默认；SELECT 立即结束隐式事务，避免 ro 事务悬挂） */
     const execOpts = { outFormat: db.OUT_FORMAT_OBJECT, maxRows: ROWS_MAX + 1, autoCommit: true };
     /** 事务内 execute：显式关闭自动提交，由 tx 的 commit/rollback 收口 */
     const execOptsTx = { ...execOpts, autoCommit: false };
@@ -312,8 +315,10 @@ export async function createDmAdapter(conn, opts) {
             const n = Math.max(1, Math.min(Math.floor(limit) || 20, ROWS_MAX));
             const off = Math.max(0, Math.floor(offset ?? 0) || 0);
             try {
-                // 统一 ANSI 分页（不依赖 compatibleMode=oracle），OFFSET/FETCH 均走 bind ⚠️ 推断（未真机验证）
-                const r = await withConn((c) => c.execute(`SELECT * FROM "${escIdent(owner)}"."${escIdent(tab)}" OFFSET :o ROWS FETCH FIRST :n ROWS ONLY`, [off, n], execOpts));
+                // 统一 ANSI 分页（不依赖 compatibleMode=oracle）。ROW_LIMIT 子句语法图的
+                // <offset>/<大小> 均为字面 <整数>（DM8 SQL 手册），绑定占位符能否用于该
+                // 位置无官方佐证 → 内联经 clamp 的整数（off/n 源自内部 offset/limit，无注入面）
+                const r = await withConn((c) => c.execute(`SELECT * FROM "${escIdent(owner)}"."${escIdent(tab)}" OFFSET ${off} ROWS FETCH FIRST ${n} ROWS ONLY`, [], execOpts));
                 return await rowsToQueryResult(r);
             }
             catch (e) {
@@ -330,3 +335,19 @@ export async function createDmAdapter(conn, opts) {
     return adapter;
 }
 export const factory = async (conn) => createDmAdapter(conn);
+/** 数据传输读写端用的独立连接池 */
+export async function openDmPool(conn) {
+    const { connectString } = resolveDmConn(conn);
+    try {
+        return (await db.createPool({
+            connectString,
+            poolMin: 1,
+            poolMax: 10,
+            poolTimeout: 60,
+            queueTimeout: 60000,
+        }));
+    }
+    catch (e) {
+        throw humanizeDmError(e);
+    }
+}

package/dist/adapters/gaussdb/index.js

@@ -40,6 +40,8 @@ function loadGaussDriver() {
             `原始错误: ${msg}`);
     }
 }
+/** 数据传输模块用的驱动加载入口 */
+export { loadGaussDriver };
 export async function createGaussdbAdapter(conn, opts) {
     return createPgLikeAdapter('gaussdb', loadGaussDriver(), conn, opts);
 }

package/dist/adapters/mongodb/index.js

@@ -170,6 +170,11 @@ export async function createMongoAdapter(conn, opts) {
             ? urlDbName(conn.url)
             : defaultDbName(conn.fields);
     const db = client.db(dbName);
+    /** 库定位：database 指定且非连接默认库时切库（client.db() 是轻量句柄，不建新连接）；
+     *  表清单/预览按所选库真实返回，避免「清单来自固定库、定位发所选库」的错位 */
+    function dbOf(database) {
+        return database && database !== dbName ? client.db(database) : db;
+    }
     function wrap(e) {
         const M = vendorOrNull();
         if (M && e instanceof M.MongoServerError) {
@@ -194,8 +199,17 @@ export async function createMongoAdapter(conn, opts) {
         connId: conn.meta.id,
         async testConnect() {
             try {
-                const hello = await client.db('admin').command({ hello: 1 });
-                return { ok: true, serverInfo: `MongoDB ${String(hello.version ?? '')}` };
+                // hello 响应没有 version 字段（官方手册字段表仅 isWritablePrimary/topologyVersion/
+                // maxBsonObjectSize/maxWireVersion 等），软件版本属 buildInfo 命令 → 取
+                // buildInfo.version；权限不足等失败回退 hello 仅判连通（版本信息尽力而为）
+                try {
+                    const info = (await client.db('admin').command({ buildInfo: 1 }));
+                    return { ok: true, serverInfo: `MongoDB ${String(info.version ?? '')}` };
+                }
+                catch {
+                    await client.db('admin').command({ hello: 1 });
+                    return { ok: true, serverInfo: 'MongoDB（版本信息不可读）' };
+                }
             }
             catch (e) {
                 return { ok: false, error: wrap(e).message };
@@ -338,8 +352,11 @@ export async function createMongoAdapter(conn, opts) {
                             : isPlainObject(cmd.indexes) ? [cmd.indexes] : Array.isArray(cmd.indexes) ? cmd.indexes : null;
                     if (!specs)
                         throw new Error('MongoDB createIndex 需要 index 规格对象或数组：{"createIndex":"coll","index":{"key":{"a":1},"name":"a_1"}}');
-                    const created = (await db.collection(name).createIndexes(specs));
-                    return { affectedRows: created.createdNewIndexes ?? undefined, message: `已在集合 ${name} 创建索引（${created.createdNewIndexes ?? '?'} 个新增）` };
+                    // 官方返回索引名数组（mongodb.d.ts: createIndexes(...): Promise<string[]>），
+                    // 无 createdNewIndexes 字段（曾按记忆臆造，恒 undefined）；驱动不区分
+                    // 新建/已存在，affectedRows = 规格数
+                    const created = await db.collection(name).createIndexes(specs);
+                    return { affectedRows: created.length, message: `已在集合 ${name} 创建索引（${created.length} 个）` };
                 }
                 if (op === 'dropIndex' || op === 'dropIndexes') {
                     const name = collOf(cmd, op);
@@ -417,9 +434,9 @@ export async function createMongoAdapter(conn, opts) {
                 throw wrap(e);
             }
         },
-        async listTables() {
+        async listTables(database) {
             try {
-                const infos = await db.listCollections().toArray();
+                const infos = await dbOf(database).listCollections().toArray();
                 return infos.map((c) => ({ name: c.name, type: c.type === 'view' ? 'view' : 'collection' }));
             }
             catch (e) {
@@ -468,11 +485,11 @@ export async function createMongoAdapter(conn, opts) {
                 throw wrap(e);
             }
         },
-        async previewRows(name, limit, _database, offset) {
+        async previewRows(name, limit, database, offset) {
             try {
                 const n = Math.max(1, Math.min(Math.floor(limit) || 20, FIND_MAX_LIMIT));
                 const skip = Math.max(0, Math.floor(offset ?? 0) || 0);
-                const docs = await db.collection(name).find({}).sort({ _id: 1 }).skip(skip).limit(n).toArray();
+                const docs = await dbOf(database).collection(name).find({}).sort({ _id: 1 }).skip(skip).limit(n).toArray();
                 return docsToResult(docs, false);
             }
             catch (e) {
@@ -587,3 +604,25 @@ function sanitizeUri(uri) {
     return uri.replace(/:\/\/[^@/]*@/, '://***:***@');
 }
 export const factory = async (conn) => createMongoAdapter(conn);
+export async function openMongoRaw(conn) {
+    const M = vendor();
+    const uri = conn.url ?? buildUri(conn.fields, conn.ssl);
+    const client = new M.MongoClient(uri, {
+        maxPoolSize: 10,
+        readPreference: 'primary',
+        w: 'majority',
+        family: 4,
+    });
+    try {
+        await client.connect();
+    }
+    catch (e) {
+        throw new Error(`MongoDB 连接失败（${sanitizeUri(uri)}）：${e instanceof Error ? e.message : String(e)}`);
+    }
+    const dbName = typeof conn.meta.database === 'string' && conn.meta.database !== ''
+        ? conn.meta.database
+        : conn.url
+            ? urlDbName(conn.url)
+            : defaultDbName(conn.fields);
+    return { client, db: client.db(dbName), M };
+}

package/dist/adapters/mysql/index.js

@@ -9,6 +9,23 @@ import mysql from 'mysql2/promise';
 import { assertIdent, clampLimit, clampOffset, humanize, normalizeCell, quoteIdent } from '../sql-shared/common.js';
 /** ro 模式下 query 允许的读语句首词白名单 */
 const RO_READ_PREFIX = /^(select|show|desc|describe|explain|use|help|table)\b/i;
+/**
+ * 吞掉 'connection' 回调里会话级 SET 的失败（ro / time_zone 仅是增强，失败不应拖垮连接与进程）。
+ * mysql2 promise 池的 'connection' 事件由核心池 emit、经 lib/promise/inherit_events.js
+ * 原样转发参数，回调收到的是 callback 版 PoolConnection：其 query() 返回 Query 命令
+ * 对象（EventEmitter，无 onResult 时错误走 emit('error')，lib/commands/command.js），
+ * 无监听会抛 uncaughtException 崩溃进程——.catch 防御对它恒不生效，必须挂 error 监听。
+ * 若驱动版本改为返回 Promise，则走 .catch 吞 rejection（双分支防御）。
+ */
+function swallowSetError(r) {
+    if (r && typeof r.catch === 'function') {
+        void r.catch(() => { });
+        return;
+    }
+    if (r && typeof r.on === 'function') {
+        r.on('error', () => { });
+    }
+}
 function connOptions(conn) {
     const base = {
         waitForConnections: true,
@@ -65,12 +82,10 @@ export async function createMysqlAdapter(conn, opts) {
     const readOnly = opts?.mode === 'ro';
     if (readOnly) {
         // 服务器级 ro 强制：每个新底层连接自动设为只读会话（应用层另有 query 白名单双保险）。
-        // 运行时连接可能是 promise 包装或 callback 版：query() 返回 promise 才需要吞掉 SET 失败。
+        // 回调收到的是 callback 版 PoolConnection，query() 返回 Query 命令对象（EventEmitter）：
+        // 吞掉 SET 失败防 uncaughtException（见 swallowSetError）。
         pool.on('connection', (c) => {
-            const r = c.query('SET SESSION TRANSACTION READ ONLY');
-            if (r && typeof r.catch === 'function') {
-                void r.catch(() => { });
-            }
+            swallowSetError(c.query('SET SESSION TRANSACTION READ ONLY'));
         });
     }
     /** 事务激活期间路由到同一连接，保证 BEGIN/COMMIT 生效 */
@@ -220,3 +235,14 @@ export async function createMysqlAdapter(conn, opts) {
     };
 }
 export const factory = (conn) => createMysqlAdapter(conn);
+export async function openMysqlRaw(conn) {
+    const opts = connOptions(conn);
+    const pool = mysql.createPool({ ...opts, dateStrings: true });
+    // 回调式 query（带 err 回调吞错）。必须用回调式：非回调式返回的 Query 命令对象与
+    // promise 池连接状态机冲突 → 该连接所有后续 query 永挂（真机实证 mysql2 3.24.4）
+    pool.on('connection', (c) => {
+        // 运行时 c 是 callback 版连接（promise 池类型标注不反映），按回调式调用
+        c.query("SET time_zone = '+00:00'", () => { });
+    });
+    return { pool, database: typeof opts.database === 'string' ? opts.database : '' };
+}

package/dist/adapters/oracle/index.js

@@ -4,7 +4,9 @@
  * 设计要点（依据官方文档调研）：
  *  - oracledb.createPool({ user, password, connectString, poolMin: 1, poolMax: 10, poolTimeout: 60 })。
  *    禁止 SYSDBA 等特权连接（不透传 privilege）。
- *  - CLOB 经全局 fetchAsString 转字符串；BLOB 经 execute 的 fetchInfo 转 string。
+ *  - CLOB 经全局 fetchAsString 转字符串；BLOB 经全局 fetchAsBuffer 转 Buffer。
+ *    （fetchInfo 的键是【列名】而非类型名，按类型统一转换只能用全局 fetchXXX 属性——
+ *    官方 connection.rst「fetchInfo」节：「Each column is specified by name」）
  *    NUMBER 保持 number（超精度损失由用户承担，见文档标注）。
  *  - query() 仅允许 SELECT/WITH；execute() DML/DDL，autoCommit: true 单语句语义。
  *  - Oracle 无 BEGIN，事务用 SET TRANSACTION READ WRITE + commit/rollback（tx 成员）。
@@ -14,14 +16,17 @@
  */
 import oracledb from 'oracledb';
 import { sqlHead, SQL_READ_HEADS } from '../../guard/index.js';
-// CLOB 统一按字符串返回（BLOB 不能走 fetchAsString，须用 execute 的 fetchInfo）
+// CLOB 统一按字符串返回；BLOB 统一按 Buffer 返回。均为官方全局按类型转换
+// （fetchInfo 的键是列名而非类型名，`{ BLOB: … }` 只会匹配恰好名为 "BLOB" 的列，
+// 按类型统一转换须用全局 fetchAsString/fetchAsBuffer——官方 connection.rst
+// 「fetchInfo」节原文「Each column is specified by name, using Oracle's standard
+// naming convention.」；fetchInfo 自 6.0 标记 deprecated，官方建议全局属性/fetchTypeHandler）
 if (!oracledb.fetchAsString.includes(oracledb.CLOB)) {
     oracledb.fetchAsString = [...oracledb.fetchAsString, oracledb.CLOB];
 }
-/** BLOB → string（execute 级选项） */
-const BLOB_FETCH = {
-    fetchInfo: { BLOB: { type: oracledb.STRING } },
-};
+if (!oracledb.fetchAsBuffer.includes(oracledb.BLOB)) {
+    oracledb.fetchAsBuffer = [...oracledb.fetchAsBuffer, oracledb.BLOB];
+}
 const ROWS_MAX = 500;
 const CELL_TRUNC = 1000;
 const DDL_KEYWORDS = new Set([
@@ -75,8 +80,16 @@ async function normalizeCell(v) {
         return trunc(v);
     if (v instanceof Date)
         return v.toISOString();
-    if (typeof v === 'object' && v.constructor?.name === 'Lob') {
-        const s = await v.toString();
+    if (Buffer.isBuffer(v))
+        return trunc(`0x${v.toString('hex')}`); // fetchAsBuffer 产出的 BLOB
+    if (v instanceof oracledb.Lob) {
+        // 官方 Lob 类成员仅 getData()/read()/close()/destroy() 等，无 toString()（官方 lob.rst；
+        // 实测 Lob.prototype.toString 即 Object.prototype.toString）——曾误用 toString()
+        // 致 LOB 列恒显示 '[object Object]'。getData() 按 CLOB/BFILE 返回 string、按
+        // 未转换 BLOB 返回 Buffer。判别用官方导出类 instanceof（constructor.name 非
+        // 官方承诺，esbuild 压缩改名场景会失效）。
+        const data = await v.getData();
+        const s = typeof data === 'string' ? data : `0x${Buffer.from(data).toString('hex')}`;
         return trunc(s);
     }
     return trunc(String(v));
@@ -166,7 +179,7 @@ export async function createOracleAdapter(conn, opts) {
         return { columns, rows, rowCount: rows.length, truncated: truncated || undefined };
     }
     // autoCommit 默认 true：query/元数据 SELECT 结束隐式事务避免 ro 事务悬挂；tx 专用连接显式 autoCommit:false 覆盖
-    const execOpts = { outFormat: oracledb.OBJECT, maxRows: ROWS_MAX + 1, autoCommit: true, ...BLOB_FETCH };
+    const execOpts = { outFormat: oracledb.OBJECT, maxRows: ROWS_MAX + 1, autoCommit: true };
     /**
      * 从池借一条连接执行后归还。⚠️ oracledb 的 Pool 没有 execute，
      * 一切语句必须在 Connection 上执行；close() 即归还连接。
@@ -374,3 +387,20 @@ export async function createOracleAdapter(conn, opts) {
     return adapter;
 }
 export const factory = async (conn) => createOracleAdapter(conn);
+/** 数据传输读写端用的独立连接池（复用 resolveOracleConn 与错误包装） */
+export async function openOraclePool(conn) {
+    const { user, password, connectString } = resolveOracleConn(conn);
+    try {
+        return await oracledb.createPool({
+            user,
+            password,
+            connectString,
+            poolMin: 1,
+            poolMax: 10,
+            poolTimeout: 60,
+        });
+    }
+    catch (e) {
+        throw humanizeOraError(e);
+    }
+}

package/dist/adapters/postgresql/index.js

@@ -8,6 +8,10 @@
 import { createRequire } from 'node:module';
 import { createPgLikeAdapter } from '../sql-shared/pg-like.js';
 const require = createRequire(import.meta.url);
+/** 数据传输模块用的驱动加载入口（与适配器同一份 require 缓存） */
+export function getPgDriver() {
+    return require('pg');
+}
 export async function createPostgresqlAdapter(conn, opts) {
     const driver = require('pg');
     return createPgLikeAdapter('postgresql', driver, conn, opts);

package/dist/adapters/sql-shared/pg-like.js

@@ -1,7 +1,11 @@
 import { assertIdent, clampLimit, clampOffset, humanize, normalizeCell, quoteIdent } from './common.js';
-function poolConfig(conn, overrideUrl) {
+/** 多主机 authority 逐台重组段（host[:port]） */
+function joinHostSeg(h) {
+    return `${h.host}${h.port != null ? ':' + h.port : ''}`;
+}
+function poolConfig(conn, overrideUrl, max = 10) {
     const base = {
-        max: 10,
+        max,
         idleTimeoutMillis: 30000,
         connectionTimeoutMillis: 5000,
     };
@@ -104,18 +108,22 @@ export async function pickHost(driver, base, hosts, masterOnly) {
     }
     return undefined;
 }
-export async function createPgLikeAdapter(kind, Driver, conn, opts) {
-    // GaussDB JDBC 风格 URL 驱动自带的 WHATWG 解析处理不了（jdbc: 非特殊 scheme 使
-    // hostname/port 为空 → 兜底连本机；多主机 authority 端口段含逗号 → 抛 Invalid URL），
-    // 故建池前先规范化，多主机时逐台探测选可用节点；postgresql 多主机列表剥 jdbc: 后
-    // 原样透传（pg 驱动原生支持 libpq 多主机 failover），不 probe。
+/**
+ * 建池前置解析（浏览适配器与传输读写端共用，保证两条路径连接语义一致）：
+ * URL 规范化（剥 jdbc:、多主机 authority 重组）后，多主机一律逐台探测选可用节点——
+ * 纯 JS 驱动（pg 8.x 与 gaussdb-node）均无 libpq 式多主机 failover：带端口多台
+ * connectionString 在 pg-connection-string / gaussdb-connection-string parse 时直接抛
+ * Invalid URL（实测），不带端口则整串 host 'h1,h2' 直传 net.connect → DNS ENOTFOUND，
+ * 故不能透传，须拆台探测（targetservertype=master 两 kind 同义：只接受主节点）。
+ * 返回最终驱动池配置与最终连接 URL。
+ */
+export async function pgLikePoolCfg(kind, driver, conn, max) {
     const norm = conn.url ? normalizeUrl(conn.url) : null;
-    const joinSeg = (h) => `${h.host}${h.port != null ? ':' + h.port : ''}`;
-    const cleanUrl = norm ? norm.prefix + (norm.hosts ?? []).map(joinSeg).join(',') + norm.suffix : undefined;
+    const cleanUrl = norm ? norm.prefix + (norm.hosts ?? []).map(joinHostSeg).join(',') + norm.suffix : undefined;
     let finalUrl = cleanUrl;
-    if (kind === 'gaussdb' && norm?.hosts && norm.hosts.length > 1) {
+    if (norm?.hosts && norm.hosts.length > 1) {
         const { prefix, suffix } = norm;
-        const joinHost = (h) => prefix + joinSeg(h) + suffix;
+        const joinHost = (h) => prefix + joinHostSeg(h) + suffix;
         const firstUrl = joinHost(norm.hosts[0]);
         // targetServerType=master（键值大小写不敏感）→ 只接受主节点
         const qi = suffix.indexOf('?');
@@ -124,7 +132,7 @@ export async function createPgLikeAdapter(kind, Driver, conn, opts) {
             if (k.toLowerCase() === 'targetservertype' && v.toLowerCase() === 'master')
                 masterOnly = true;
         }
-        const base = poolConfig(conn, firstUrl);
+        const base = poolConfig(conn, firstUrl, max);
         // 探测凭据自 prefix userinfo 解出（按最后一个 @ / 最后一个 : 分界，decode 与
         // percent-encode 注入互逆）；仅密码无用户名时 user 不设
         if (prefix.endsWith('@')) {
@@ -140,11 +148,39 @@ export async function createPgLikeAdapter(kind, Driver, conn, opts) {
                 base.urlUser = decodeURIComponent(body);
             }
         }
-        const picked = await pickHost(Driver, base, norm.hosts, masterOnly);
+        const picked = await pickHost(driver, base, norm.hosts, masterOnly);
         // 全败回退首台重组值：让 testConnect 报真实连接错误
         finalUrl = picked ? joinHost(picked) : firstUrl;
     }
-    const cfg = poolConfig(conn, finalUrl);
+    return { cfg: poolConfig(conn, finalUrl, max), url: finalUrl };
+}
+/**
+ * 生成「同一份池配置仅覆盖库名」的 cfg：pg / gaussdb ConnectionParameters 按
+ * Object.assign({}, config, parse(config.connectionString)) 合并——connectionString
+ * 解析值覆盖全部显式字段（实测：{connectionString:'postgres://u:p@h1:5432/appdb',
+ * database:'otherdb',host:'x',user:'y'} → database 'appdb'/host 'h1'/user 'u'；
+ * node-postgres packages/pg/lib/connection-parameters.js:53-57，gaussdb-node
+ * lib/connection-parameters.js:55-57 同款）。故 URL 形态叠加 database 字段会被 URL
+ * 里的原库名覆盖（跨库池静默连回原库），必须改写 URL path 段；字段形态直接叠加。
+ * 写回库名 encodeURIComponent 与驱动 parse 的 decodeURI 对空格/非 ASCII 往返无损
+ * （两驱动实测 parse('.../a%20b') → database 'a b'；两驱动源码 pg-connection-string
+ * index.js:67 / gaussdb-connection-string index.js:62 均为 decodeURI(pathname)）——
+ * 含 # / 等保留字符的库名 decodeURI 不还原（驱动能力边界，libpq 才有完整
+ * percent-decoding），此类库名无法经 URL 形态无损表达。
+ */
+export function pgCfgWithDatabase(cfg, db) {
+    const cs = cfg.connectionString;
+    // 无 authority 的非 URL 形态不产生垃圾改写，退回字段叠加
+    if (typeof cs !== 'string' || !cs.includes('://'))
+        return { ...cfg, database: db };
+    const norm = normalizeUrl(cs);
+    const qi = /[?#]/.exec(norm.suffix)?.index ?? -1;
+    const tail = qi >= 0 ? norm.suffix.slice(qi) : '';
+    const hosts = (norm.hosts ?? []).map(joinHostSeg).join(',');
+    return { ...cfg, connectionString: `${norm.prefix}${hosts}/${encodeURIComponent(db)}${tail}` };
+}
+export async function createPgLikeAdapter(kind, Driver, conn, opts) {
+    const { cfg, url: finalUrl } = await pgLikePoolCfg(kind, Driver, conn, 10);
     const pool = new Driver.Pool(cfg);
     const readOnly = opts?.mode === 'ro';
     // 所有池（主池 + 跨库池）统一走此初始化。
@@ -189,8 +225,10 @@ export async function createPgLikeAdapter(kind, Driver, conn, opts) {
         const cached = dbPools.get(db);
         if (cached)
             return cached;
-        // 与主池同一份最终 cfg（多主机探测选定台后的 connectionString），仅覆盖库名
-        const created = new Driver.Pool({ ...cfg, database: db });
+        // 与主池同一份最终 cfg（多主机探测选定台后的 connectionString），仅覆盖库名——
+        // URL 形态经 pgCfgWithDatabase 改写 path（叠加 database 字段会被驱动里 URL
+        // 库名覆盖，静默连回原库）
+        const created = new Driver.Pool(pgCfgWithDatabase(cfg, db));
         setupPool(created); // 与主池一致：error 兜底 + ro 会话只读
         dbPools.set(db, created);
         return created;

package/dist/adapters/sqlite/index.js

@@ -1,3 +1,13 @@
+/**
+ * SQLite 适配器（同步 API 包装 Promise）。
+ * fields.database / fields.path 为文件路径；ro 模式 readonly 打开。
+ *
+ * 驱动双路径（离线环境友好）：
+ *  1. node:sqlite（Node ≥ 22.5 内置，零原生依赖，离线/无编译工具链环境直接可用）
+ *  2. better-sqlite3（optionalDependency；预构建缺失或本地编译失败时 pnpm 会
+ *     自动排除该包，不影响插件整体安装，动态加载失败时回退到明确报错）
+ */
+import { basename } from 'node:path';
 import { assertIdent, clampLimit, clampOffset, humanize, normalizeCell, quoteIdent } from '../sql-shared/common.js';
 let cached = null;
 let cachedFor = '';
@@ -57,30 +67,53 @@ function resolveFile(conn) {
     }
     throw new Error('sqlite 连接缺少文件路径（fields.database / fields.path 或 url）');
 }
-function toQueryResult(raw, columns) {
-    return {
-        columns,
-        rows: raw.map((r) => columns.map((c) => normalizeCell(r[c]))),
-        rowCount: raw.length,
-    };
-}
-export async function createSqliteAdapter(conn, opts) {
+/**
+ * 打开原始数据库句柄（不包适配器规范化）。数据传输读写端用：
+ * 必须绕过 normalizeCell（BLOB 截断 / bigint 降位）保真搬运原始值。
+ */
+export async function openRaw(conn, readOnly) {
     const file = resolveFile(conn);
-    const readOnly = opts?.mode === 'ro';
     const { ctor, driver } = await loadDriver();
-    let db;
     try {
-        // 选项名按驱动区分：node:sqlite 用 readOnly（打开不存在文件即报错）；
-        // better-sqlite3 用 readonly + fileMustExist。node:sqlite 不接受显式
-        // undefined 作 options，rw 模式统一传空对象。
-        db = driver === 'node:sqlite'
+        // 选项名按驱动区分：node:sqlite 用 readOnly（打开不存在文件即报错；官方签名
+        // new DatabaseSync(location[, options])，options 为可选参数，空对象与不传/undefined
+        // 等价，open 默认 true —— https://nodejs.org/docs/latest-v24.x/api/sqlite.html）；
+        // better-sqlite3 用 readonly + fileMustExist。rw 模式两驱动均传空对象。
+        const db = driver === 'node:sqlite'
             ? new ctor(file, readOnly ? { readOnly: true } : {})
             : new ctor(file, readOnly ? { readonly: true, fileMustExist: true } : {});
+        return { db, driver };
     }
     catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
-        throw new Error(`sqlite 打开失败 (${file}, 驱动 ${driver}): ${msg}`);
+        // 只带文件名不带完整路径：错误会经驱动错误通道外发（传输失败快照等），避免内网路径泄露
+        throw new Error(`sqlite 打开失败 (${basename(file)}, 驱动 ${driver}): ${msg}`);
     }
+}
+function toQueryResult(raw, columns) {
+    return {
+        columns,
+        rows: raw.map((r) => columns.map((c) => normalizeCell(r[c]))),
+        rowCount: raw.length,
+    };
+}
+/**
+ * 取 SELECT 列名。stmt.columns() 在 node:sqlite 需 Node ≥ 22.16.0（官方文档
+ * "Added in: v22.16.0"，https://nodejs.org/docs/latest-v22.x/api/sqlite.html），
+ * 而本适配器放行的最低版本是 22.5——22.13.0–22.15.x 上 columns 为 undefined，
+ * 无条件调用即 TypeError（浏览主路径 query/previewRows 每次必崩）。旧版本回退
+ * 到结果首行的 keys（对象字符串键保序 = SELECT 列序；纯数字列名会被当作整数
+ * 索引键排前，属降级路径已知盲区）。空结果集无行可推，返回空列头。
+ */
+export function stmtColumns(stmt, raw) {
+    if (typeof stmt.columns === 'function')
+        return stmt.columns().map((c) => c.name);
+    const first = raw[0];
+    return first ? Object.keys(first) : [];
+}
+export async function createSqliteAdapter(conn, opts) {
+    const readOnly = opts?.mode === 'ro';
+    const { db, driver } = await openRaw(conn, readOnly);
     return {
         kind: 'sqlite',
         connId: conn.meta.id,
@@ -90,9 +123,8 @@ export async function createSqliteAdapter(conn, opts) {
         }),
         query: (sql, params) => humanize('sqlite 查询失败', async () => {
             const stmt = db.prepare(sql);
-            const columns = stmt.columns().map((c) => c.name);
             const raw = stmt.all(...(params ?? []));
-            return toQueryResult(raw, columns);
+            return toQueryResult(raw, stmtColumns(stmt, raw));
         }),
         execute: (statement, params) => humanize('sqlite 执行失败', async () => {
             const stmt = db.prepare(statement);
@@ -139,9 +171,8 @@ export async function createSqliteAdapter(conn, opts) {
             const lim = clampLimit(limit);
             const off = clampOffset(offset);
             const stmt = db.prepare(`SELECT * FROM ${tbl} LIMIT ? OFFSET ?`);
-            const columns = stmt.columns().map((c) => c.name);
             const raw = stmt.all(lim, off);
-            return toQueryResult(raw, columns);
+            return toQueryResult(raw, stmtColumns(stmt, raw));
         }),
         close: () => humanize('sqlite 关闭连接', async () => {
             db.close();