dsh-db-tool 1.6.0 → 1.7.1

package/dist/adapters/dmdb/index.js

@@ -9,10 +9,13 @@
  *  - DM 事务隐式开始，无需 SET TRANSACTION。
  *
  * 驱动要点：
- *  - 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（驱动默认非自动提交）。
+ *  - db.createPool({ connectString: 'dm://user:pass@host:5236', poolAlias: <逐池唯一>,
+ *    poolMin: 1, poolMax: 10, poolTimeout: 60, queueTimeout: 60000 })；不启用压缩
+ *    （默认 compress=0，规避 @napi-rs/snappy 跨平台坑）。
+ *  - poolAlias 必须逐池唯一（不传即撞驱动缺省 'default' 并抛 [20006]；见 nextPoolAlias 注释）。
+ *  - execute 必须显式 maxRows（默认 0=无限制）；autoCommit 显式传 true 使语义
+ *    不依赖驱动默认（驱动连接属性默认已是自动提交：dmdb connection.js
+ *    conn_prop_autoCommit = !0；d.ts 三级优先链 执行选项 > dmdb.autoCommit > 连接属性）。
  *  - 返回 { metaData, rows, rowsAffected } 与 oracledb 兼容。
  */
 import db from 'dmdb';
@@ -82,6 +85,39 @@ export function resolveDmConn(conn) {
     const password = typeof f.password === 'string' ? f.password : '';
     return { connectString: `dm://${encodeURIComponent(user)}:${encodeURIComponent(password)}@${host}:${port}`, user, password };
 }
+/**
+ * 连接池别名：dmdb 把池登记在模块级全局 Map（dmdb.pools），key 即 poolAlias。
+ * 驱动缺省别名恒为 'default'（driver/pool.js `_poolAlias = "default"`，仅显式传参才覆盖），
+ * 且判重无条件执行 → 不传别名时第二个池必抛 [20006] 连接池别名已存在（src/dm.js:236）。
+ * 本插件同进程内可并存多个池（连接的 ro/rw 各一份缓存、testConnection/testDraft 的
+ * 一次性池、控制台事务会话、数据传输独立池），故必须逐池唯一。
+ * 别名同时是 close 的回收键：正常路径 driver/pool.js 会 `pools.delete(alias)`，
+ * 但 close 抛错的异常分支会跳过该删除（登记项残留，插件侧无可观测点）。
+ */
+let poolSeq = 0;
+function nextPoolAlias(conn) {
+    return `dsh-dm-${conn.meta.id}-${++poolSeq}`;
+}
+/** 建池（连接串解析、池参数与别名单点维护，供适配器与数据传输入口共用） */
+async function createDmPool(conn) {
+    const { connectString } = resolveDmConn(conn);
+    try {
+        // 注意：实参对象不要直接包进 `as unknown as` 断言——变异工具不为该形态生成
+        // ObjectLiteral 变异体，「删掉 poolAlias」这类关键退化会在变异报告中不可见（已验证）。
+        const pool = await db.createPool({
+            connectString,
+            poolAlias: nextPoolAlias(conn),
+            poolMin: 1,
+            poolMax: 10,
+            poolTimeout: 60,
+            queueTimeout: 60000,
+        });
+        return pool;
+    }
+    catch (e) {
+        throw humanizeDmError(e);
+    }
+}
 export async function createDmAdapter(conn, opts) {
     const mode = opts?.mode ?? 'rw';
     let pool;
@@ -89,21 +125,10 @@ export async function createDmAdapter(conn, opts) {
         pool = opts.pool;
     }
     else {
-        const { connectString } = resolveDmConn(conn);
-        try {
-            pool = (await db.createPool({
-                connectString,
-                poolMin: 1,
-                poolMax: 10,
-                poolTimeout: 60,
-                queueTimeout: 60000,
-            }));
-        }
-        catch (e) {
-            throw humanizeDmError(e);
-        }
+        pool = await createDmPool(conn);
     }
-    /** 默认 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 +337,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 +357,7 @@ export async function createDmAdapter(conn, opts) {
     return adapter;
 }
 export const factory = async (conn) => createDmAdapter(conn);
+/** 数据传输读写端用的独立连接池（别名逐池唯一，可与主连接池并存） */
+export async function openDmPool(conn) {
+    return await createDmPool(conn);
+}

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

@@ -2,9 +2,13 @@
  * Oracle 适配器（oracledb v7 thin 模式，DB 12.1+）。
  *
  * 设计要点（依据官方文档调研）：
- *  - oracledb.createPool({ user, password, connectString, poolMin: 1, poolMax: 10, poolTimeout: 60 })。
+ *  - oracledb.createPool({ user, password, connectString, poolAlias: <逐池唯一>,
+ *    poolMin: 1, poolMax: 10, poolTimeout: 60 })。
  *    禁止 SYSDBA 等特权连接（不透传 privilege）。
- *  - CLOB 经全局 fetchAsString 转字符串；BLOB 经 execute 的 fetchInfo 转 string。
+ *  - poolAlias 显式传唯一值：不传则落到匿名池（不可经 getPool() 检索），见 createOraPool 注释。
+ *  - 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 +18,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 +82,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));
@@ -116,6 +131,37 @@ export function resolveOracleConn(conn) {
         connectString: `${host}:${port}/${service}`,
     };
 }
+/**
+ * 连接池别名：oracledb 的规则与 dmdb 不同——只有「显式传入的别名」或
+ * 「'default' 尚空闲时取到的缺省值」会登记进模块级 poolCache；两者都被占用时
+ * 驱动创建的是 poolAlias === undefined 的匿名池（不报错，也无法经 getPool() 检索），
+ * 只有显式重复别名才抛 NJS-046（lib/oracledb.js:640-649、lib/errors.js:352）。
+ * 本插件同进程内可并存多个池（连接的 ro/rw 各一份缓存、testConnection/testDraft 的
+ * 一次性池、控制台事务会话、数据传输独立池），故显式传唯一别名：每池身份可检索，
+ * 且不抢占 getPool() 的缺省键 'default'。回收靠 '_afterPoolClose' 事件（close 抛错则不触发）。
+ */
+let poolSeq = 0;
+function nextPoolAlias(conn) {
+    return `dsh-ora-${conn.meta.id}-${++poolSeq}`;
+}
+/** 建池（连接串解析、池参数与别名单点维护，供适配器与数据传输入口共用） */
+async function createOraPool(conn) {
+    const { user, password, connectString } = resolveOracleConn(conn);
+    try {
+        return await oracledb.createPool({
+            user,
+            password,
+            connectString,
+            poolAlias: nextPoolAlias(conn),
+            poolMin: 1,
+            poolMax: 10,
+            poolTimeout: 60,
+        });
+    }
+    catch (e) {
+        throw humanizeOraError(e);
+    }
+}
 export async function createOracleAdapter(conn, opts) {
     const mode = opts?.mode ?? 'rw';
     let pool;
@@ -123,20 +169,7 @@ export async function createOracleAdapter(conn, opts) {
         pool = opts.pool;
     }
     else {
-        const { user, password, connectString } = resolveOracleConn(conn);
-        try {
-            pool = await oracledb.createPool({
-                user,
-                password,
-                connectString,
-                poolMin: 1,
-                poolMax: 10,
-                poolTimeout: 60,
-            });
-        }
-        catch (e) {
-            throw humanizeOraError(e);
-        }
+        pool = await createOraPool(conn);
     }
     function requireRw(action) {
         if (mode === 'ro') {
@@ -166,7 +199,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 +407,7 @@ export async function createOracleAdapter(conn, opts) {
     return adapter;
 }
 export const factory = async (conn) => createOracleAdapter(conn);
+/** 数据传输读写端用的独立连接池（别名逐池唯一，可与主连接池并存） */
+export async function openOraclePool(conn) {
+    return await createOraPool(conn);
+}

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';
     // 所有池（主池 + 跨库池）统一走此初始化。
@@ -166,6 +202,10 @@ export async function createPgLikeAdapter(kind, Driver, conn, opts) {
     setupPool(pool);
     // 事务激活期间所有 query/execute 路由到同一 client
     let txClient = null;
+    /** close 幂等标志：pg-pool 的 end() 二次调用会抛 "Called end on pool more than once"，
+     *  而 manager 的 console 会话在授权复核失败路径会重复关闭同一适配器（见 manager 的
+     *  finish('rollback') 与外层 catch）——重复 close 须为 no-op。 */
+    let closed = false;
     const run = (sql, params) => txClient ? txClient.query(sql, params) : pool.query(sql, params);
     // 跨库浏览（Navicat 行为）：树列出服务器上所有库，展开非连接库时用同一凭据开指向该库的池。
     // 池按库缓存复用；ro 模式下新池同样套会话只读。连接自身的库（fields.database 或 url 库名）直接复用主池。
@@ -189,8 +229,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;
@@ -349,6 +391,9 @@ export async function createPgLikeAdapter(kind, Driver, conn, opts) {
             return toQueryResult(res);
         }),
         close: () => humanize(`${kind} 关闭连接`, async () => {
+            if (closed)
+                return; // 幂等：重复 close 为 no-op（见 closed 声明处注释）
+            closed = true;
             await Promise.all([pool.end(), ...[...dbPools.values()].map((p) => p.end())]);
         }),
     };