dsh-db-tool 0.1.7 → 0.1.8

package/README.md

@@ -36,7 +36,7 @@ dsh plugin --profile web add "dsh-db-tool@github:mengqi1436/dsh-db-tool"
 dsh plugin --profile web add "link:E:\path\to\dsh-db-tool"
 ```
 
-GaussDB 官方驱动未发布 npm，需先构建 vendor：`npm run build:gaussdb`（PowerShell）或 `bash scripts/build-gaussdb.sh`；oracledb 安装脚本需 `npm approve-scripts oracledb`。详见 [docs/install.md](docs/install.md)。
+GaussDB 官方驱动未发布 npm，需先构建 vendor：`npm run build:gaussdb`（PowerShell）或 `bash scripts/build-gaussdb.sh`；运行要求 Node ≥ 22.12（产物依赖 p-limit@7 纯 ESM）。oracledb 安装脚本需 `npm approve-scripts oracledb`。详见 [docs/install.md](docs/install.md)。
 
 ## 安全模型
 

package/dist/adapters/gaussdb/index.js

@@ -1,8 +1,20 @@
 /**
  * GaussDB（openGauss）适配器。
  *
- * ⚠️ 官方驱动 openGauss-connector-nodejs 未发布 npm，按 openGauss 官方 README/文档实现，
- * 使用 vendor/gaussdb-pg 构建产物（fork 自 pg 8.7 时代，API 与 pg 完全兼容），未真机验证。
+ * ⚠️ 官方驱动 openGauss-connector-nodejs 未发布 npm（华为云 HCS 26.861.0 官方文档
+ * 应用程序接口清单仅 JDBC/ODBC/libpq/Psycopg/Go/ECPG，无 Node 驱动），Node 接入基于
+ * PostgreSQL 协议兼容自行验证。使用 vendor/gaussdb-pg 构建产物（fork 自 pg 8.6.0，
+ * API 与 pg 完全兼容），未真机验证。
+ *
+ * 已按官方文档对齐（证据见 skills/db-admin/SKILL.md GaussDB 节）：
+ * - 认证：驱动实现 openGauss SHA256 / MD5-SHA256 / SM3 握手（vendor pg-protocol parser.ts:335-357、
+ *   rfc5802.js:44），对应服务端 password_encryption_type 默认 2 (sha256)；
+ * - 默认端口 8000（集中式 DN / 分布式 CN）、ro 会话 `SET SESSION CHARACTERISTICS AS
+ *   TRANSACTION READ ONLY` 两形态官方支持（rf-dist/gaussdb-08-0400、rf-cent/gaussdb-38-0416）；
+ * - 已知限制：SERIALIZABLE 功能不支持（等价 REPEATABLE READ，与 PG 的 SSI 行为不同）；
+ *   SSL 仅布尔开关（不支持 sslmode require/verify-ca/verify-full 细分）；
+ *   information_schema.tables/columns 集中式有官方视图文档、分布式参考无原生视图文档
+ *   （仅 M-Compatibility 模式），跨库浏览在分布式实例上以真机行为为准。
  *
  * 构建方式：bash scripts/build-gaussdb.sh（或 npm run build:gaussdb）
  * 核心逻辑与 postgresql 适配器共享（sql-shared/pg-like.ts）。

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

@@ -10,9 +10,13 @@ function poolConfig(conn) {
     }
     else if (conn.fields) {
         const f = conn.fields;
+        // 兜底默认值按 kind 区分（仅表单字段被清空时触发）：GaussDB 官方默认端口 8000
+        // （华为云 HCS 26.861.0：集中式 DN 与分布式 CN 均为 8000，devg-cent/gaussdb-42-0020、
+        // devg-dist/gaussdb-12-0319）、默认管理用户 gaussdb；postgresql 维持社区默认 5432/postgres 不变。
+        const gb = conn.meta.kind === 'gaussdb';
         base.host = String(f.host ?? '127.0.0.1');
-        base.port = Number(f.port ?? 5432);
-        base.user = String(f.user ?? f.username ?? 'postgres');
+        base.port = Number(f.port ?? (gb ? 8000 : 5432));
+        base.user = String(f.user ?? f.username ?? (gb ? 'gaussdb' : 'postgres'));
         if (f.password != null)
             base.password = String(f.password);
         if (f.database != null)
@@ -28,20 +32,23 @@ function poolConfig(conn) {
 export async function createPgLikeAdapter(kind, Driver, conn, opts) {
     const pool = new Driver.Pool(poolConfig(conn));
     const readOnly = opts?.mode === 'ro';
-    // 服务器级 ro 强制（官方手段）：每个新连接会话设为只读事务。
+    // 所有池（主池 + 跨库池）统一走此初始化。
+    // pg 约定：release(err) 若无等待者会 emit pool 'error'，无监听器会崩进程——
+    // 官方 Pool 文档要求必须注册 error 监听（空闲连接因后端故障销毁时经此冒泡），无条件兜底。
+    // 服务器级 ro 强制（官方手段）：每个新连接会话设为只读事务，仅 ro 模式注册。
     // fail-closed：SET 失败时 release(err) 让驱动销毁该连接、等待的 acquire 收到错误——
     // 会话级只读是 ro 的最后防线，不允许静默降级成可写连接。
-    const setupReadOnly = (p) => {
-        p.on('connect', (c) => {
-            void c.query('SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY').catch((err) => {
-                c.release(err instanceof Error ? err : new Error(String(err)));
-            });
-        });
-        // pg 约定：release(err) 若无等待者会 emit pool 'error'，不监听会崩进程
+    const setupPool = (p) => {
         p.on('error', () => { });
+        if (readOnly) {
+            p.on('connect', (c) => {
+                void c.query('SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY').catch((err) => {
+                    c.release(err instanceof Error ? err : new Error(String(err)));
+                });
+            });
+        }
     };
-    if (readOnly)
-        setupReadOnly(pool);
+    setupPool(pool);
     // 事务激活期间所有 query/execute 路由到同一 client
     let txClient = null;
     const run = (sql, params) => txClient ? txClient.query(sql, params) : pool.query(sql, params);
@@ -67,8 +74,7 @@ export async function createPgLikeAdapter(kind, Driver, conn, opts) {
         if (cached)
             return cached;
         const created = new Driver.Pool({ ...poolConfig(conn), database: db });
-        if (readOnly)
-            setupReadOnly(created);
+        setupPool(created); // 与主池一致：error 兜底 + ro 会话只读
         dbPools.set(db, created);
         return created;
     };

package/dist/index.js

@@ -30,7 +30,9 @@ action 说明：
 - preview：预览行，limit≤50（conn_id, table, database?, limit?）。
 - run_script：子进程沙箱脚本（conn_id, code），60s 超时强杀，permission model 禁文件
   访问 + 新 vm realm 双层隔离，仅注入受限 db.query/db.execute 句柄（经完整
-  guard/审计链路），rw 连接才有写能力。`;
+  guard/审计链路），rw 连接才有写能力。句柄签名 db.query(sql, params?, database?)：
+  第三参为跨库路由目标（pg/gaussdb 等按库路由，同 Navicat 式），多库统计在脚本内
+  循环逐库调用即可一次完成。`;
 export function apply(ctx) {
     const log = ctx.logger ?? { info: () => { }, error: () => { } };
     const store = new DbToolStore();

package/dist/manager.js

@@ -249,8 +249,8 @@ export class DbToolService {
         try {
             const result = await runScriptInChild({
                 code: src,
-                dbQuery: async (sql, params) => this.unwrapForScript(await this.query(key, connId, sql, params, challengeId)),
-                dbExecute: async (statement, params) => this.unwrapForScript(await this.execute(key, connId, statement, params, challengeId)),
+                dbQuery: async (sql, params, database) => this.unwrapForScript(await this.query(key, connId, sql, params, challengeId, database)),
+                dbExecute: async (statement, params, database) => this.unwrapForScript(await this.execute(key, connId, statement, params, challengeId, database)),
                 onLog: (level, text) => level === 'error' ? console.error('[db-script]', text) : console.log('[db-script]', text),
                 onTimeout: () => {
                     void sessionAdapter.close().catch(() => { });

package/dist/script/runner.js

@@ -118,11 +118,13 @@ export async function runScriptInChild(opts) {
         });
     });
     async function handleDbCall(method, args) {
-        const [statement, params] = args;
+        const [statement, params, rawDatabase] = args;
+        // IPC JSON 序列化会把 undefined 变 null，归一回 undefined 保持与直连调用语义一致
+        const database = rawDatabase ?? undefined;
         if (method === 'query')
-            return opts.dbQuery(statement, params);
+            return opts.dbQuery(statement, params, database);
         if (method === 'execute')
-            return opts.dbExecute(statement, params);
+            return opts.dbExecute(statement, params, database);
         throw new DbToolError('INVALID_ARGUMENT', `未知 db 方法: ${method}`);
     }
     function errorOf(e) {

package/dist/script/worker.cjs

@@ -10,7 +10,7 @@
  *
  * IPC 协议：
  *  父→worker {type:'run', code}
- *  worker→父 {type:'db', reqId, method, args}
+ *  worker→父 {type:'db', reqId, method, args}   // args=[statement, params, database?]，database 即跨库路由目标
  *  父→worker {type:'dbResult', reqId, ok, result, error}
  *  worker→父 {type:'done', ok, result, error}
  */
@@ -28,11 +28,11 @@ async function runScript(code) {
   const pending = new Map();
   let reqSeq = 0;
 
-  const dbCall = (method) => (statement, params) =>
+  const dbCall = (method) => (statement, params, database) =>
     new Promise((resolve, reject) => {
       const reqId = ++reqSeq;
       pending.set(reqId, { resolve, reject });
-      process.send({ type: 'db', reqId, method, args: [statement, params] });
+      process.send({ type: 'db', reqId, method, args: [statement, params, database] });
     });
 
   const db = {

package/docs/architecture.md

@@ -0,0 +1,154 @@
+# dsh-db-tool 项目架构图
+
+> 由 cbm（codebase-memory）索引数据绘制：843 节点 / 2702 边，模块分层见各图。
+> 索引项目名：`E-Code-dsh-dsh-db-tool`。
+
+## 1. 总体分层架构
+
+```mermaid
+flowchart TB
+    subgraph UI["客户端层（DSH 侧边栏）"]
+        CLIENT["client/client.js<br/>连接管理 · 对象树浏览 · SQL 控制台 · 授权面板"]
+    end
+
+    subgraph API["接入层"]
+        HTTP["lib/http<br/>HTTP API（13 条路由）"]
+        TOOL["lib/index.ts<br/>DatabaseManager 工具定义<br/>list_connections / query / execute /<br/>schema / preview / run_script"]
+    end
+
+    subgraph SVC["服务编排层"]
+        MGR["lib/manager.ts<br/>ro/rw 项目授权校验 · 适配器生命周期 · 事务编排"]
+    end
+
+    subgraph SEC["安全层"]
+        GUARD["lib/guard<br/>SQL/命令分类 · 危险操作识别 ·<br/>一次性 challenge 确认（5 分钟有效）"]
+        STORE["lib/store<br/>connections · grants · secrets（脱敏）·<br/>audit 审计 · normalize · io"]
+        SCRIPT["lib/script<br/>runner.ts + worker.cjs<br/>子进程沙箱（vm realm · 禁文件 · 60s 超时）"]
+    end
+
+    subgraph ADPT["适配器层 lib/adapters（8 库）"]
+        REG["index.ts<br/>kind → 工厂注册表 + driverMissingError"]
+        SQLSHARED["sql-shared/<br/>common.ts（标识符/分页/规范化）<br/>pg-like.ts（PostgreSQL + GaussDB 共享）"]
+        A1["mysql"]
+        A2["postgresql"]
+        A3["gaussdb<br/>vendor/gaussdb-pg 驱动加载"]
+        A4["sqlite"]
+        A5["redis"]
+        A6["mongodb"]
+        A7["oracle"]
+        A8["dmdb"]
+        TYPES["types.ts<br/>DatabaseAdapter 契约"]
+    end
+
+    subgraph DRV["驱动层"]
+        D1["pg / mysql2 / sqlite3 / redis<br/>mongodb / oracledb / dmdb"]
+        D2["vendor/gaussdb-pg<br/>openGauss-connector-nodejs 构建产物"]
+    end
+
+    CLIENT -->|HTTP| HTTP
+    CLIENT -.->|注入| TOOL
+    TOOL --> MGR
+    MGR --> GUARD
+    MGR --> STORE
+    MGR --> SCRIPT
+    MGR --> REG
+    REG --> SQLSHARED
+    REG --> A1 & A4 & A5 & A6 & A7 & A8
+    A2 --> SQLSHARED
+    A3 --> SQLSHARED
+    SQLSHARED --> TYPES
+    A1 & A2 & A3 & A4 & A5 & A6 & A7 & A8 -.-> DRV
+    SCRIPT -.->|db.query / db.execute 经完整 guard 链路| MGR
+```
+
+## 2. 请求时序（query 与危险操作确认流）
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant U as 用户（聊天）
+    participant T as DatabaseManager 工具
+    participant M as lib/manager.ts
+    participant G as lib/guard
+    participant S as lib/store
+    participant A as 适配器（8 库）
+    participant DB as 数据库
+
+    U->>T: query/execute（conn_id, sql）
+    T->>S: 授权校验（项目路径 → 连接 → ro/rw）
+    alt 未授权
+        S-->>T: UNAUTHORIZED_PROJECT
+    else ro 授权 + 写操作
+        S-->>T: READ_ONLY（拒绝）
+    else 通过
+        T->>G: 语句分类
+        alt 危险操作（DDL/DML/维护命令）
+            G-->>T: NEEDS_CONFIRMATION + challengeId（一次性，5 分钟）
+            T-->>U: 说明语句与风险，等待明确同意
+            U->>T: 携同一 challengeId 重试
+            T->>G: 校验 challenge（绑定语句 hash）
+        end
+        T->>M: 执行
+        M->>A: query/execute（可选 database 跨库路由，pg/gaussdb）
+        A->>DB: 参数化 SQL（ro 会话级 READ ONLY 双保险）
+        DB-->>A: 结果
+        A-->>T: 规范化结果（DECIMAL→string 等）
+        T->>S: 审计记录
+        T-->>U: {columns, rows, rowCount} / {affectedRows, message}
+    end
+```
+
+## 3. 适配器体系（8 库 × 共享实现）
+
+```mermaid
+flowchart LR
+    subgraph 契约
+        T["types.ts<br/>DatabaseAdapter / TableInfo / ColumnInfo<br/>DbKind = 8 种"]
+    end
+    subgraph 工厂注册
+        R["adapters/index.ts<br/>kind → lazy import 工厂<br/>缺失驱动 → driverMissingError（附构建提示）"]
+    end
+    subgraph SQL系共享
+        PG["pg-like.ts<br/>PostgreSQL + GaussDB<br/>pool · ro 会话 · 跨库路由 ·<br/>库→schema→表 三层浏览"]
+        CM["common.ts<br/>assertIdent · quoteIdent<br/>clampLimit/Offset · normalizeCell"]
+    end
+    subgraph 独立实现
+        MY["mysql"]
+        SQ["sqlite"]
+        RD["redis（SCAN 禁 KEYS）"]
+        MG["mongodb（强制显式 filter）"]
+        OR["oracle"]
+        DM["dmdb"]
+    end
+    PG --> CM
+    MY & SQ & RD & MG & OR & DM -.-> CM
+    R --> PG & MY & SQ & RD & MG & OR & DM
+    PG -.->|"gaussdb 差异仅驱动加载<br/>createRequire vendor/gaussdb-pg"| G["gaussdb/index.ts"]
+    T --- R
+```
+
+## 4. 模块分层职责（cbm layers 数据）
+
+| 层 | 模块 | 特征 |
+|---|---|---|
+| entry | lib、script、e2e-mock | 仅出边（调用下游） |
+| api | http | 含 13 条 HTTP 路由定义 |
+| core | adapters（4 入 0 出）、store（12 入 0 出） | 高扇入核心，不依赖上层 |
+| internal | manager（7 入 12 出）、tool、http | 编排枢纽 |
+| leaf | guard | 仅入边，纯分类/判定 |
+
+## 5. GaussDB 专项链路
+
+```mermaid
+flowchart TB
+    T["DatabaseManager(query/execute/schema/preview, database=...)"] --> M["manager"]
+    M --> A3["gaussdb/index.ts<br/>loadGaussDriver()：createRequire<br/>vendor/gaussdb-pg/packages/pg（CJS）"]
+    A3 --> PL["sql-shared/pg-like.ts<br/>kind='gaussdb'"]
+    PL -->|poolConfig：host/port 8000/user/password/database/ssl| P["PgLikePool"]
+    PL -->|database 参数| PF["poolFor(db)：按库缓存池（Navicat 式跨库）"]
+    PL -->|ro 模式| SRO["每个新连接 SET SESSION CHARACTERISTICS<br/>AS TRANSACTION READ ONLY（fail-closed）"]
+    P --> DB[("GaussDB 服务端<br/>openGauss 协议")]
+```
+
+- 驱动构建：`scripts/build-gaussdb.sh` / `.ps1` → 克隆 openGauss-connector-nodejs → `vendor/gaussdb-pg/packages/pg`（gitignore）。
+- 测试：`tests/adapters-sql/gaussdb.test.ts`（驱动加载/工厂，mock 离线）+ `pg-like.test.ts`（pg/gaussdb 共享行为）。

package/docs/install.md

@@ -43,6 +43,8 @@ rm -rf ../gaussdb-pg && cp -r packages/pg ../gaussdb-pg
 
 产物为 `vendor/gaussdb-pg`（CJS，结构同 `pg`：`{ Pool, Client, ... }`）。
 
+> **Node 版本要求**：≥ 22.12。构建脚本会补装 `p-limit@7`（纯 ESM，源码 package.json 未声明），依赖 Node 原生 require(esm)；更旧 Node 加载 GaussDB 驱动会抛 `ERR_REQUIRE_ESM`（其余 7 库不受影响）。
+
 ## oracledb approve-scripts
 
 `oracledb` 安装时需要运行安装脚本编译/下载二进制。仓库 `package.json` 已配置白名单：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-db-tool",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "DSH community plugin: chat-operated multi-database admin tool with sidebar management, project-scoped grants, ro/rw modes and dangerous-operation confirmation",
   "type": "module",
   "license": "MIT",

package/skills/db-admin/SKILL.md

@@ -99,7 +99,7 @@ DatabaseManager({ action: "run_script", conn_id: "mongo1", code: '{"find":"users
 |---|---|---|---|---|
 | MySQL | `?` | `information_schema` | `LIMIT n OFFSET m` | |
 | PostgreSQL | `$1, $2…` | `information_schema` / `pg_catalog` | `LIMIT n OFFSET m` | |
-| GaussDB | `$1, $2…` | `information_schema` / `pg_catalog` | `LIMIT n OFFSET m` | PG 系 |
+| GaussDB | `$1, $2…` | `information_schema` / `pg_catalog` | `LIMIT n OFFSET m` | PG 系（默认端口 8000，见下方注记） |
 | SQLite | `?` | `sqlite_master` / `PRAGMA` | `LIMIT n OFFSET m` | 库列表固定 `['main']` |
 | Redis | 无（命令数组） | `SCAN`（禁用 `KEYS` 遍历） | `SCAN cursor` | `run_script` 传 `["SCAN","0","MATCH","user:*","COUNT","100"]` |
 | MongoDB | 无（BSON 文档） | `listCollections` | `find().skip().limit()` | `run_script` 传 `{"find":"users","filter":{},"limit":20,"skip":40}` |
@@ -108,6 +108,18 @@ DatabaseManager({ action: "run_script", conn_id: "mongo1", code: '{"find":"users
 
 **类型规范化**（工具返回值已自动处理，引用结果时注意）：`DECIMAL/NUMERIC` → string（避免精度丢失）；`Date/TIMESTAMP` → ISO 8601 string；`LOB/CLOB/BLOB` → string；MongoDB `ObjectId` → string。生成写语句时，DECIMAL 直接传字符串值、日期传 ISO 字符串即可。
 
+## GaussDB 官方对齐注记（HCS 26.861.0，集中式/分布式）
+
+依据华为云 GaussDB 官方文档（doc.hcs.huawei.com/db/zh-cn，26.861.0 双形态）与 openGauss 官方文档源仓库对齐；未真机验证处以代码内标注为准。
+
+- **认证**：驱动实现 openGauss SHA256 / MD5-SHA256 / SM3 握手，匹配服务端默认 `password_encryption_type = 2`（sha256）。连接报 `Invalid username/password, login denied` 时依次排查：① 认证配置（gs_hba.conf）需含 `host all all 0.0.0.0/0 sha256`；② 服务端密码加密方式变更后必须重设密码或新建用户（旧口令仍是旧加密）；③ 账号锁定用 `ALTER USER ... ACCOUNT UNLOCK`。
+- **默认端口 8000**（集中式 DN / 分布式 CN，官方 gsql 示例 `-p 8000`）；SSL 默认不强制（服务端可 require_ssl 强制）。本工具 SSL 仅开/关，**不支持** sslmode（require/verify-ca/verify-full）证书校验细分。
+- **ro 只读会话**：`SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY` 为官方语法（集中式/分布式均支持，rf-dist/gaussdb-08-0400、rf-cent/gaussdb-38-0416），连接建立时执行一次即对该连接所有后续事务生效。
+- **隔离级别差异**：READ UNCOMMITTED 等价 READ COMMITTED；**SERIALIZABLE 功能不支持，等价 REPEATABLE READ**——与 PG 真 SSI 行为不同，依赖 PG 串行化语义的脚本注意。
+- **元数据**：`pg_database` / `pg_catalog.pg_namespace` 为官方系统表；`information_schema.tables/columns` 集中式有官方视图文档，分布式参考无原生视图（仅 M-Compatibility 模式有），分布式实例上浏览以真机行为为准。
+- **兼容模式**：openGauss 有 sql_compatibility（A/B/C/PG）兼容模式，部分语法语义随模式变化（如 B 模式 SET SESSION TRANSACTION 需 `b_format_behavior_compat_options` 含 set_session_transaction 才生效），本工具按 PG 语义使用。
+- 驱动/默认值差异的代码内证据与证据 URL 见 `lib/adapters/gaussdb/index.ts` 头注释与 `lib/adapters/sql-shared/pg-like.ts`。
+
 ## 危险操作确认流程（NEEDS_CONFIRMATION）
 
 收到形如以下的返回时：