dsh-db-tool 0.1.0

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# dsh-db-tool bundle patch（dsh.bundle.patch：顶层数组 loader patch entries）
+# 本地开发安装：dsh plugin --profile web add "link:E:\Code\dsh\dsh-db-tool"
+# 发布安装（用户侧）：dsh plugin --profile web add "dsh-db-tool@github:<user>/dsh-db-tool"
+- insert:
+    - id: db-tool
+      name: dsh-db-tool

package/dist/adapters/dmdb/index.js

@@ -0,0 +1,326 @@
+/**
+ * 达梦 DM 适配器（dmdb 驱动，API 对齐 oracledb）。
+ *
+ * ⚠️ 推断标注（未真机验证项，由 env 门控真机集成测试覆盖）：
+ *  - 数据字典复用 Oracle 兼容视图 ALL_TABLES / ALL_TAB_COLUMNS / ALL_CONSTRAINTS /
+ *    ALL_CONS_COLUMNS（官方移植文档佐证的兼容行为）。
+ *  - 分页统一 `OFFSET n ROWS FETCH FIRST m ROWS ONLY`（ANSI 风格，不依赖 compatibleMode=oracle）。
+ *  - DDL 隐式提交语义按 Oracle 同等处理。
+ *  - 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（驱动默认非自动提交）。
+ *  - 返回 { metaData, rows, rowsAffected } 与 oracledb 兼容。
+ */
+import db from 'dmdb';
+const ROWS_MAX = 500;
+const CELL_TRUNC = 1000;
+const DDL_KEYWORDS = new Set([
+    'CREATE', 'ALTER', 'DROP', 'TRUNCATE', 'RENAME', 'GRANT', 'REVOKE',
+    'COMMENT', 'ANALYZE', 'AUDIT', 'NOAUDIT', 'FLASHBACK', 'PURGE',
+]);
+/** 标识符基本校验（DM 官方允许 $/# 开头等宽字符集，引用创建的名字可含任意字符）：
+ *  非空、≤128、无 NUL/换行。防注入靠数据字典参数绑定 + preview 处 escIdent 转义。 */
+export function sanitizeIdentifier(name, label) {
+    if (typeof name !== 'string' || name.length === 0 || name.length > 128 ||
+        /[\0\r\n]/.test(name)) {
+        throw new Error(`非法 DM ${label}「${name}」：不允许为空、超 128 字符或含 NUL/换行`);
+    }
+    return name;
+}
+/** 双引号标识符转义（" → ""），拼接进 SQL 前必须过此函数 */
+function escIdent(name) {
+    return name.replaceAll('"', '""');
+}
+function trunc(s, max = CELL_TRUNC) {
+    return s.length > max ? `${s.slice(0, max)}…[截断,共${s.length}字符]` : s;
+}
+/** 行值规范化为 NormalizedCell */
+async function normalizeCell(v) {
+    if (v === null || v === undefined)
+        return null;
+    if (typeof v === 'number')
+        return Number.isFinite(v) ? v : String(v);
+    if (typeof v === 'string')
+        return trunc(v);
+    if (v instanceof Date)
+        return v.toISOString();
+    if (typeof v === 'bigint')
+        return v.toString();
+    if (Buffer.isBuffer(v))
+        return trunc(`0x${v.toString('hex')}`);
+    return trunc(JSON.stringify(v));
+}
+export function humanizeDmError(e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return new Error(`达梦 DM 错误：${msg}（提示：请检查连接串/凭据；错误码含义见达梦官方《DM8 错误码手册》）`);
+}
+/** 连接参数解析：url（dm://user:pass@host:5236 直接可用）或 fields 拼 connectString */
+export function resolveDmConn(conn) {
+    if (conn.url) {
+        if (!conn.url.startsWith('dm://')) {
+            throw new Error('DM URL 应以 dm:// 开头，如 dm://user:pass@host:5236');
+        }
+        const u = new URL(conn.url);
+        return {
+            connectString: conn.url,
+            user: decodeURIComponent(u.username),
+            password: decodeURIComponent(u.password),
+        };
+    }
+    const f = conn.fields ?? {};
+    const host = typeof f.host === 'string' ? f.host : '';
+    const port = typeof f.port === 'number' ? f.port : 5236;
+    if (host === '') {
+        throw new Error('DM 连接需要 url（dm://user:pass@host:5236）或 fields（host/port）');
+    }
+    const user = typeof f.user === 'string' ? f.user : '';
+    const password = typeof f.password === 'string' ? f.password : '';
+    return { connectString: `dm://${encodeURIComponent(user)}:${encodeURIComponent(password)}@${host}:${port}`, user, password };
+}
+export async function createDmAdapter(conn, opts) {
+    const mode = opts?.mode ?? 'rw';
+    let pool;
+    if (opts?.pool) {
+        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);
+        }
+    }
+    /** 默认 execute 选项：显式 maxRows + 显式 autoCommit:true（dmdb 默认分别为 0/false，必须覆盖；SELECT 立即结束隐式事务，避免 ro 事务悬挂） */
+    const execOpts = { outFormat: db.OUT_FORMAT_OBJECT, maxRows: ROWS_MAX + 1, autoCommit: true };
+    /** 事务内 execute：显式关闭自动提交，由 tx 的 commit/rollback 收口 */
+    const execOptsTx = { ...execOpts, autoCommit: false };
+    /**
+     * 从池借一条连接执行后归还。⚠️ dmdb 的 Pool 没有 execute（与 oracledb 一致），
+     * 一切语句必须在 Connection 上执行；close() 即归还连接。
+     */
+    async function withConn(fn) {
+        const c = await pool.getConnection();
+        try {
+            return await fn(c);
+        }
+        finally {
+            await c.close().catch(() => { });
+        }
+    }
+    function requireRw(action) {
+        if (mode === 'ro') {
+            throw new Error(`连接为只读(ro)模式，拒绝执行${action}；请使用 rw 连接或只发查询(query)`);
+        }
+    }
+    function isDdl(sql) {
+        const first = sql.trim().split(/\s+/)[0]?.toUpperCase() ?? '';
+        return DDL_KEYWORDS.has(first);
+    }
+    async function toExecResult(sql, r) {
+        // ⚠️ 推断：DDL 隐式提交语义按 Oracle 同等处理（未真机验证）
+        const ddlNote = isDdl(sql) ? '（DDL 已隐式提交，不可回滚）' : '';
+        return {
+            affectedRows: typeof r.rowsAffected === 'number' && r.rowsAffected > 0 ? r.rowsAffected : undefined,
+            message: `${sql.trim().split(/\s+/)[0]?.toUpperCase() ?? 'SQL'} 完成${r.rowsAffected ? `，影响 ${r.rowsAffected} 行` : ''}${ddlNote}`,
+        };
+    }
+    async function rowsToQueryResult(r) {
+        const allRows = r.rows ?? [];
+        const truncated = allRows.length > ROWS_MAX;
+        const columns = (r.metaData ?? []).map((m) => m.name);
+        const rows = [];
+        for (const row of allRows.slice(0, ROWS_MAX)) {
+            rows.push(await Promise.all(Object.values(row).map(normalizeCell)));
+        }
+        return { columns, rows, rowCount: rows.length, truncated: truncated || undefined };
+    }
+    /** owner 解析：database 参数或默认当前用户（保留原样——引用创建的 schema 大小写敏感） */
+    function ownerOf(database) {
+        return sanitizeIdentifier(database ?? connUser, 'schema/owner 名');
+    }
+    /** DM 内建系统 schema：受安全体系保护，任何用户（含 SYSDBA）无 SELECT 权，列表中过滤 */
+    const DM_SYSTEM_SCHEMAS = new Set(['SYS', 'SYSSSO', 'SYSAUDITOR', 'SYSSCO', 'CTISYS']);
+    const connUser = resolveDmConn(conn).user.toUpperCase();
+    const adapter = {
+        kind: 'dmdb',
+        connId: conn.meta.id,
+        async testConnect() {
+            try {
+                const r = await withConn((c) => c.execute('SELECT BANNER FROM V$VERSION WHERE ROWNUM = 1', [], execOpts));
+                const row = r.rows?.[0];
+                const banner = row ? String(Object.values(row)[0] ?? '') : '';
+                return { ok: true, serverInfo: banner };
+            }
+            catch {
+                // V$VERSION 为推断兼容项（部分 DM 版本/驱动可能不可读）：
+                // 版本信息尽力而为，连通性本身用 dual 兜底判定，避免误报连接失败
+                try {
+                    await withConn((c) => c.execute('SELECT 1 FROM DUAL', [], execOpts));
+                    return { ok: true, serverInfo: 'DM 数据库（版本信息不可读：V$VERSION 不可用）' };
+                }
+                catch (e) {
+                    return { ok: false, error: humanizeDmError(e).message };
+                }
+            }
+        },
+        async query(sql, params) {
+            const head = sql.trim().split(/\s+/)[0]?.toUpperCase() ?? '';
+            if (head !== 'SELECT' && head !== 'WITH') {
+                throw new Error('DM query 仅允许 SELECT/WITH 语句；写操作或 DDL 请走 execute');
+            }
+            try {
+                const r = await withConn((c) => c.execute(sql, params ?? [], execOpts));
+                return await rowsToQueryResult(r);
+            }
+            catch (e) {
+                throw humanizeDmError(e);
+            }
+        },
+        async execute(statement, params) {
+            requireRw('execute');
+            try {
+                // 单语句语义：autoCommit: true（execOpts 默认已开启）
+                const r = await withConn((c) => c.execute(statement, params ?? [], execOpts));
+                return await toExecResult(statement, r);
+            }
+            catch (e) {
+                throw humanizeDmError(e);
+            }
+        },
+        /** 事务：专用连接多条语句，成功 commit、异常 rollback。DM 事务隐式开始，无需 SET TRANSACTION。 */
+        async tx(fn) {
+            requireRw('事务(tx)');
+            const c = await pool.getConnection();
+            try {
+                const exec = async (sql, binds) => {
+                    const r = await c.execute(sql, binds ?? [], execOptsTx);
+                    return toExecResult(sql, r);
+                };
+                const out = await fn(exec);
+                await c.commit();
+                return out;
+            }
+            catch (e) {
+                try {
+                    await c.rollback();
+                }
+                catch { /* 已断开等场景忽略 */ }
+                throw humanizeDmError(e);
+            }
+            finally {
+                try {
+                    await c.close();
+                }
+                catch { /* 归还失败忽略 */ }
+            }
+        },
+        async listDatabases() {
+            // DM 为单库多 schema 模型：「数据库」下拉列出可浏览的 schema（有表者），
+            // 失败回退当前用户 schema，绝不用 host 等占位值（会污染 owner 参数）。
+            // 系统安全 schema（SYSSSO=MAC 标记/SYSAUDITOR=审计/SYSSCO/CTISYS=全密/SYS）
+            // 连 SYSDBA 也无 SELECT 权（DM 有意保护），列出只会让展开时报 [-5504]，
+            // 故过滤（保留当前用户自身，支持直接以系统用户连接的场景）。
+            try {
+                const r = await withConn((c) => c.execute('SELECT DISTINCT OWNER FROM ALL_TABLES ORDER BY OWNER', [], execOpts));
+                const owners = (r.rows ?? [])
+                    .map((row) => String(Object.values(row)[0] ?? '').trim())
+                    .filter(Boolean)
+                    .filter((o) => o === connUser || !DM_SYSTEM_SCHEMAS.has(o.toUpperCase()));
+                return owners.length > 0 ? owners : [connUser];
+            }
+            catch {
+                return [connUser];
+            }
+        },
+        async listTables(database) {
+            const owner = ownerOf(database);
+            try {
+                // ⚠️ 推断：DM 兼容 Oracle 数据字典 ALL_TABLES（未真机验证）
+                const r = await withConn((c) => c.execute('SELECT TABLE_NAME FROM ALL_TABLES WHERE OWNER = :owner ORDER BY TABLE_NAME OFFSET 0 ROWS FETCH FIRST 500 ROWS ONLY', [owner], execOpts));
+                const rows = r.rows ?? [];
+                return rows.map((row) => ({ name: String(row.TABLE_NAME ?? ''), type: 'TABLE' }));
+            }
+            catch (e) {
+                throw humanizeDmError(e);
+            }
+        },
+        async describeTable(table, database) {
+            const owner = ownerOf(database);
+            // 原名精确匹配优先；未引用创建的表名在字典中为大写存储，UPPER 兜底
+            const tab = sanitizeIdentifier(table, '表名');
+            try {
+                // ⚠️ 推断：ALL_TAB_COLUMNS / ALL_CONSTRAINTS / ALL_CONS_COLUMNS 兼容（未真机验证）；同连接内两查保证一致性
+                const { colsR, pkR } = await withConn(async (c) => ({
+                    colsR: await c.execute(`SELECT COLUMN_NAME, DATA_TYPE, DATA_LENGTH, DATA_PRECISION, DATA_SCALE, NULLABLE, DATA_DEFAULT
+            FROM ALL_TAB_COLUMNS WHERE OWNER = :owner AND (TABLE_NAME = :tab OR TABLE_NAME = UPPER(:tab)) ORDER BY COLUMN_ID`, [owner, tab], execOpts),
+                    pkR: await c.execute(`SELECT COLS.COLUMN_NAME
+            FROM ALL_CONSTRAINTS CONS
+            JOIN ALL_CONS_COLUMNS COLS
+              ON CONS.OWNER = COLS.OWNER AND CONS.CONSTRAINT_NAME = COLS.CONSTRAINT_NAME
+            WHERE CONS.CONSTRAINT_TYPE = 'P' AND CONS.OWNER = :owner AND (CONS.TABLE_NAME = :tab OR CONS.TABLE_NAME = UPPER(:tab))`, [owner, tab], execOpts),
+                }));
+                const pkSet = new Set((pkR.rows ?? []).map((r2) => String(r2.COLUMN_NAME ?? '')));
+                return (colsR.rows ?? []).map((row) => {
+                    const dataType = String(row.DATA_TYPE ?? '');
+                    const precision = row.DATA_PRECISION;
+                    const scale = row.DATA_SCALE;
+                    const length = row.DATA_LENGTH;
+                    let typeStr = dataType;
+                    if (precision !== null && precision !== undefined) {
+                        typeStr = scale !== null && scale !== undefined && Number(scale) > 0
+                            ? `${dataType}(${Number(precision)},${Number(scale)})`
+                            : `${dataType}(${Number(precision)})`;
+                    }
+                    else if (/^(VARCHAR|NVARCHAR|CHAR|NCHAR|RAW|BIT)/.test(dataType) && length !== null && length !== undefined) {
+                        typeStr = `${dataType}(${Number(length)})`;
+                    }
+                    const def = row.DATA_DEFAULT;
+                    return {
+                        name: String(row.COLUMN_NAME ?? ''),
+                        dataType: typeStr,
+                        nullable: String(row.NULLABLE ?? 'Y') === 'Y',
+                        ...(pkSet.has(String(row.COLUMN_NAME ?? '')) ? { key: 'PRI' } : {}),
+                        default: def === null || def === undefined ? null : trunc(String(def).trim()),
+                    };
+                });
+            }
+            catch (e) {
+                throw humanizeDmError(e);
+            }
+        },
+        async previewRows(table, limit, database, offset) {
+            const owner = ownerOf(database);
+            const tab = sanitizeIdentifier(table, '表名'); // 拼接前经 escIdent 转义
+            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));
+                return await rowsToQueryResult(r);
+            }
+            catch (e) {
+                throw humanizeDmError(e);
+            }
+        },
+        async close() {
+            try {
+                await pool.close();
+            }
+            catch { /* 已关闭忽略 */ }
+        },
+    };
+    return adapter;
+}
+export const factory = async (conn) => createDmAdapter(conn);

package/dist/adapters/gaussdb/index.js

@@ -0,0 +1,32 @@
+/**
+ * GaussDB（openGauss）适配器。
+ *
+ * ⚠️ 官方驱动 openGauss-connector-nodejs 未发布 npm，按 openGauss 官方 README/文档实现，
+ * 使用 vendor/gaussdb-pg 构建产物（fork 自 pg 8.7 时代，API 与 pg 完全兼容），未真机验证。
+ *
+ * 构建方式：bash scripts/build-gaussdb.sh（或 npm run build:gaussdb）
+ * 核心逻辑与 postgresql 适配器共享（sql-shared/pg-like.ts）。
+ */
+import { createRequire } from 'node:module';
+import { createPgLikeAdapter, } from '../sql-shared/pg-like.js';
+const require = createRequire(import.meta.url);
+// packages 布局：pg lib 内 require('../../pg-protocol'/'../../pg-pool') 按 monorepo 假设向上两级解析
+// 相对 createRequire base（lib/adapters/gaussdb/）需三级到项目根：gaussdb/ → adapters/ → lib/ → root
+const VENDOR_PATH = '../../../vendor/gaussdb-pg/packages/pg';
+function loadGaussDriver() {
+    try {
+        // vendor 为 CJS 产物，结构同 pg：module.exports = { Pool, Client, ... }
+        return require(VENDOR_PATH);
+    }
+    catch (e) {
+        // 附原始错误：区分「vendor 未构建」与「构建产物损坏/依赖缺失」两类故障
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new Error('GaussDB 驱动未找到：官方 openGauss-connector-nodejs 未发布 npm，' +
+            '请先执行 bash scripts/build-gaussdb.sh（或 npm run build:gaussdb）构建 vendor/gaussdb-pg。' +
+            `原始错误: ${msg}`);
+    }
+}
+export async function createGaussdbAdapter(conn, opts) {
+    return createPgLikeAdapter('gaussdb', loadGaussDriver(), conn, opts);
+}
+export const factory = (conn) => createGaussdbAdapter(conn);

package/dist/adapters/index.js

@@ -0,0 +1,41 @@
+const LOADERS = {
+    mysql: () => import('./mysql/index.js').then((m) => m.createMysqlAdapter),
+    postgresql: () => import('./postgresql/index.js').then((m) => m.createPostgresqlAdapter),
+    gaussdb: () => import('./gaussdb/index.js').then((m) => m.createGaussdbAdapter),
+    sqlite: () => import('./sqlite/index.js').then((m) => m.createSqliteAdapter),
+    redis: () => import('./redis/index.js').then((m) => m.createRedisAdapter),
+    mongodb: () => import('./mongodb/index.js').then((m) => m.createMongoAdapter),
+    oracle: () => import('./oracle/index.js').then((m) => m.createOracleAdapter),
+    dmdb: () => import('./dmdb/index.js').then((m) => m.createDmAdapter),
+};
+/** 驱动缺失时的安装指引 */
+const INSTALL_HINTS = {
+    mysql: 'npm install mysql2',
+    postgresql: 'npm install pg',
+    gaussdb: 'npm run build:gaussdb（构建 vendor/gaussdb-pg）',
+    sqlite: 'npm install better-sqlite3',
+    redis: 'npm install redis',
+    mongodb: 'npm install mongodb',
+    oracle: 'npm install oracledb',
+    dmdb: 'npm install dmdb',
+};
+/** 生成带安装指引的驱动缺失错误 */
+export function driverMissingError(kind, cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause ?? '');
+    const err = new Error(`${kind} 驱动不可用${detail ? `：${detail}` : ''}。请安装/构建后重试：${INSTALL_HINTS[kind]}`);
+    err.name = 'DriverMissingError';
+    return err;
+}
+const cache = new Map();
+/** 取某 kind 的适配器工厂（惰性加载并缓存；失败清缓存以便重试） */
+export function getAdapter(kind) {
+    let p = cache.get(kind);
+    if (!p) {
+        p = LOADERS[kind]().catch((e) => {
+            cache.delete(kind);
+            throw driverMissingError(kind, e);
+        });
+        cache.set(kind, p);
+    }
+    return p;
+}