dsh-db-tool 0.1.0

package/dist/adapters/mysql/index.js

@@ -0,0 +1,222 @@
+/**
+ * MySQL 适配器（mysql2/promise）。
+ * query=读用 pool.query()；execute=写用 pool.execute()（真 prepare，占位符 ?）。
+ * DECIMAL 官方默认 string 保持；dateStrings:true 使 DATE/DATETIME 直接输出字符串。
+ * ro 模式：multipleStatements 固定 false（防堆叠注入）；建连后会话级只读（SET SESSION
+ * TRANSACTION READ ONLY）+ query 首词只读白名单双保险；服务层拦截 execute。
+ */
+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;
+function connOptions(conn) {
+    const base = {
+        waitForConnections: true,
+        connectionLimit: 10,
+        maxIdle: 10,
+        idleTimeout: 60000,
+        queueLimit: 0,
+        enableKeepAlive: true,
+        keepAliveInitialDelay: 0,
+        multipleStatements: false,
+        dateStrings: true,
+        connectTimeout: 10000,
+        charset: 'utf8mb4_general_ci',
+    };
+    if (conn.url) {
+        const u = new URL(conn.url);
+        base.host = u.hostname;
+        base.port = Number(u.port) || 3306;
+        try {
+            if (u.username)
+                base.user = decodeURIComponent(u.username);
+            if (u.password)
+                base.password = decodeURIComponent(u.password);
+        }
+        catch {
+            throw new Error('mysql 连接 URL 的用户名或密码 percent 编码非法（如含未编码的 %），请 URL 编码后重试');
+        }
+        const db = u.pathname.replace(/^\//, '');
+        if (db)
+            base.database = db;
+        const ssl = u.searchParams.get('ssl');
+        if (conn.ssl || ssl === 'true' || ssl === 'require')
+            base.ssl = { rejectUnauthorized: false };
+    }
+    else if (conn.fields) {
+        const f = conn.fields;
+        base.host = String(f.host ?? '127.0.0.1');
+        base.port = Number(f.port ?? 3306);
+        base.user = String(f.user ?? f.username ?? 'root');
+        if (f.password != null)
+            base.password = String(f.password);
+        if (f.database != null)
+            base.database = String(f.database);
+        if (conn.ssl)
+            base.ssl = { rejectUnauthorized: false };
+    }
+    else {
+        throw new Error('mysql 连接缺少 url 或 fields 配置');
+    }
+    return base;
+}
+export async function createMysqlAdapter(conn, opts) {
+    const pool = mysql.createPool(connOptions(conn));
+    const readOnly = opts?.mode === 'ro';
+    if (readOnly) {
+        // 服务器级 ro 强制：每个新底层连接自动设为只读会话（应用层另有 query 白名单双保险）。
+        // 运行时连接可能是 promise 包装或 callback 版：query() 返回 promise 才需要吞掉 SET 失败。
+        pool.on('connection', (c) => {
+            const r = c.query('SET SESSION TRANSACTION READ ONLY');
+            if (r && typeof r.catch === 'function') {
+                void r.catch(() => { });
+            }
+        });
+    }
+    /** 事务激活期间路由到同一连接，保证 BEGIN/COMMIT 生效 */
+    let txConn = null;
+    // PoolConnection 与 Pool 的联合会让 mysql2 的 query/execute 重载解析失败，收窄为 Pool 视图
+    const runner = () => (txConn ?? pool);
+    function toQueryResult(rows, fields) {
+        const columns = fields.map((f) => String(f.name));
+        return {
+            columns,
+            rows: rows.map((r) => columns.map((c) => normalizeCell(r[c]))),
+            rowCount: rows.length,
+        };
+    }
+    const tx = {
+        begin: () => humanize('mysql 事务开启', async () => {
+            if (txConn)
+                throw new Error('事务已开启，请勿重复 begin');
+            txConn = await pool.getConnection();
+            try {
+                await txConn.beginTransaction();
+            }
+            catch (e) {
+                txConn.release();
+                txConn = null;
+                throw e;
+            }
+        }),
+        commit: () => humanize('mysql 事务提交', async () => {
+            const c = txConn;
+            if (!c)
+                throw new Error('没有进行中的事务');
+            txConn = null;
+            try {
+                await c.commit();
+            }
+            finally {
+                c.release();
+            }
+        }),
+        rollback: () => humanize('mysql 事务回滚', async () => {
+            const c = txConn;
+            if (!c)
+                throw new Error('没有进行中的事务');
+            txConn = null;
+            try {
+                await c.rollback();
+            }
+            finally {
+                c.release();
+            }
+        }),
+    };
+    const defaultDb = () => {
+        let db = conn.fields?.database != null ? String(conn.fields.database) : '';
+        if (!db && conn.url) {
+            // URL 配置：默认库取 pathname 首段（与 connOptions 的解析一致）
+            const p = new URL(conn.url).pathname.slice(1);
+            if (p)
+                db = p;
+        }
+        if (!db)
+            throw new Error('未指定数据库：请传入 database 参数或配置默认库');
+        // fields/URL 提供的库名统一过标识符校验（防注入）
+        return assertIdent(db, '库名');
+    };
+    return {
+        kind: 'mysql',
+        connId: conn.meta.id,
+        tx,
+        testConnect: () => humanize('mysql 连接测试', async () => {
+            const [rows] = await pool.query('SELECT VERSION() AS v');
+            return { ok: true, serverInfo: `MySQL ${String(rows[0]?.v ?? '')}` };
+        }),
+        query: (sql, params) => humanize('mysql 查询失败', async () => {
+            if (readOnly && !RO_READ_PREFIX.test(sql.trimStart())) {
+                throw new Error('DRIVER_ERROR: 只读(ro)模式下 query 仅允许读语句（select/show/desc/describe/explain/use/help/table），写操作请使用可写连接');
+            }
+            const [rows, fields] = await runner().query(sql, params ?? []);
+            if (!Array.isArray(rows))
+                return { columns: [], rows: [], rowCount: 0 };
+            return toQueryResult(rows, fields);
+        }),
+        execute: (statement, params) => humanize('mysql 执行失败', async () => {
+            // mysql2 的 ExecuteValues 不接受 unknown[]，此处值均为绑定参数（string|number|null）
+            const [result] = await runner().execute(statement, (params ?? []));
+            const header = (Array.isArray(result) ? result[0] : result);
+            const n = header?.affectedRows;
+            return {
+                affectedRows: typeof n === 'number' ? n : undefined,
+                message: typeof n === 'number'
+                    ? `执行成功，受影响 ${n} 行`
+                    : '执行成功',
+            };
+        }),
+        listDatabases: () => humanize('mysql 列出数据库', async () => {
+            const [rows] = await pool.query('SELECT SCHEMA_NAME FROM information_schema.SCHEMATA ORDER BY SCHEMA_NAME');
+            return rows.map((r) => String(r.SCHEMA_NAME));
+        }),
+        listTables: (database) => humanize('mysql 列出表', async () => {
+            const db = database ? assertIdent(database, '库名') : defaultDb();
+            const [rows] = await pool.query(`SELECT TABLE_NAME, TABLE_TYPE, TABLE_COMMENT FROM information_schema.TABLES
+           WHERE TABLE_SCHEMA = ? ORDER BY TABLE_NAME`, [db]);
+            return rows.map((r) => {
+                const rawType = String(r.TABLE_TYPE);
+                const comment = r.TABLE_COMMENT;
+                return {
+                    name: String(r.TABLE_NAME),
+                    type: rawType === 'BASE TABLE' ? 'TABLE' : rawType,
+                    comment: comment != null && comment !== '' ? String(comment) : undefined,
+                    database: db,
+                };
+            });
+        }),
+        describeTable: (table, database) => humanize('mysql 查看表结构', async () => {
+            const db = database ? assertIdent(database, '库名') : defaultDb();
+            const tbl = assertIdent(table, '表名');
+            const [rows] = await pool.query(`SELECT COLUMN_NAME, COLUMN_TYPE, IS_NULLABLE, COLUMN_KEY, COLUMN_DEFAULT, COLUMN_COMMENT
+           FROM information_schema.COLUMNS
+           WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ? ORDER BY ORDINAL_POSITION`, [db, tbl]);
+            if (rows.length === 0)
+                throw new Error(`表不存在: ${db}.${tbl}`);
+            return rows.map((r) => {
+                const dflt = r.COLUMN_DEFAULT;
+                const comment = r.COLUMN_COMMENT;
+                return {
+                    name: String(r.COLUMN_NAME),
+                    dataType: String(r.COLUMN_TYPE),
+                    nullable: r.IS_NULLABLE === 'YES',
+                    key: r.COLUMN_KEY ? String(r.COLUMN_KEY) : undefined,
+                    default: dflt == null ? null : String(dflt),
+                    comment: comment != null && comment !== '' ? String(comment) : undefined,
+                };
+            });
+        }),
+        previewRows: (table, limit, database, offset) => humanize('mysql 预览行', async () => {
+            const db = quoteIdent(database ? assertIdent(database, '库名') : defaultDb(), '`');
+            const tbl = quoteIdent(assertIdent(table, '表名'), '`');
+            const lim = clampLimit(limit);
+            const off = clampOffset(offset);
+            const [rows, fields] = await pool.query(`SELECT * FROM ${db}.${tbl} LIMIT ? OFFSET ?`, [lim, off]);
+            if (!Array.isArray(rows))
+                return { columns: [], rows: [], rowCount: 0 };
+            return toQueryResult(rows, fields);
+        }),
+        close: () => humanize('mysql 关闭连接', () => pool.end()),
+    };
+}
+export const factory = (conn) => createMysqlAdapter(conn);

package/dist/adapters/oracle/index.js

@@ -0,0 +1,369 @@
+/**
+ * Oracle 适配器（oracledb v7 thin 模式，DB 12.1+）。
+ *
+ * 设计要点（依据官方文档调研）：
+ *  - oracledb.createPool({ user, password, connectString, poolMin: 1, poolMax: 10, poolTimeout: 60 })。
+ *    禁止 SYSDBA 等特权连接（不透传 privilege）。
+ *  - CLOB 经全局 fetchAsString 转字符串；BLOB 经 execute 的 fetchInfo 转 string。
+ *    NUMBER 保持 number（超精度损失由用户承担，见文档标注）。
+ *  - query() 仅允许 SELECT/WITH；execute() DML/DDL，autoCommit: true 单语句语义。
+ *  - Oracle 无 BEGIN，事务用 SET TRANSACTION READ WRITE + commit/rollback（tx 成员）。
+ *  - DDL 隐式提交：execute 对 DDL 的 message 附注「DDL 已隐式提交，不可回滚」。
+ *  - 标识符默认大写存储：listTables/describeTable 内部统一 toUpperCase 匹配。
+ *  - 锁号/密码验证器等常见连接错误转人类可读提示（见 ORA_HINTS）。
+ */
+import oracledb from 'oracledb';
+// CLOB 统一按字符串返回（BLOB 不能走 fetchAsString，须用 execute 的 fetchInfo）
+if (!oracledb.fetchAsString.includes(oracledb.CLOB)) {
+    oracledb.fetchAsString = [...oracledb.fetchAsString, oracledb.CLOB];
+}
+/** BLOB → string（execute 级选项） */
+const BLOB_FETCH = {
+    fetchInfo: { BLOB: { type: oracledb.STRING } },
+};
+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',
+]);
+/** 常见 ORA 错误 → 人类可读提示 */
+export const ORA_HINTS = [
+    [/ORA-01017/, '用户名或密码错误'],
+    [/ORA-12154/, '无法解析连接串中的服务名，请检查 connectString / service_name'],
+    [/ORA-12505/, '监听器不认识该 SID：请使用服务名(service_name)而非 SID'],
+    [/ORA-12514/, '监听器当前未注册该服务名，请检查服务名拼写与数据库注册状态'],
+    [/ORA-12541/, '无法连接监听器，请检查主机与端口'],
+    [/ORA-12543/, '网络无法到达目标主机，请检查主机/端口/防火墙'],
+    [/ORA-12560/, 'TNS 协议适配器错误，请检查连接串格式（应为 host:port/service_name）'],
+    [/ORA-28040/, '客户端与服务器密码验证器版本不兼容（服务器 SQLNET.ALLOWED_LOGON_VERSION_SERVER 需放宽）'],
+    [/ORA-28000/, '账号已被锁定，请联系 DBA 解锁'],
+    [/ORA-28001/, '密码已过期，请联系 DBA 重置'],
+    [/ORA-00942/, '表或视图不存在（Oracle 标识符默认大写存储，注意大小写与 owner）'],
+    [/ORA-00904/, '列名无效（Oracle 标识符默认大写存储，注意大小写）'],
+];
+export function humanizeOraError(e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    const hint = ORA_HINTS.find(([re]) => re.test(msg))?.[1];
+    return new Error(hint ? `Oracle 错误：${msg}（提示：${hint}）` : `Oracle 错误：${msg}`);
+}
+/** 标识符基本校验（引用创建的 Oracle 名字可含任意字符，白名单会误杀）：
+ *  非空、≤128、无 NUL/换行。防注入靠数据字典参数绑定 + preview 处 escIdent 转义。
+ *  保留原名不强制大写：describeTable 的 SQL 用 UPPER(:tab) 兜底匹配未引用建表。 */
+export function sanitizeIdentifier(name, label) {
+    if (typeof name !== 'string' || name.length === 0 || name.length > 128 ||
+        /[\0\r\n]/.test(name)) {
+        throw new Error(`非法 Oracle ${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（Lob 兜底转字符串并截断） */
+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 === 'object' && v.constructor?.name === 'Lob') {
+        const s = await v.toString();
+        return trunc(s);
+    }
+    return trunc(String(v));
+}
+/** 连接参数解析：url（oracle://user:pass@host:1521/service）或 fields */
+export function resolveOracleConn(conn) {
+    if (conn.url) {
+        const u = new URL(conn.url);
+        const service = u.pathname.replace(/^\//, '');
+        if (!u.hostname || service === '') {
+            throw new Error('Oracle URL 格式应为 oracle://user:pass@host:1521/SERVICE_NAME');
+        }
+        const user = decodeURIComponent(u.username);
+        if (user === '') {
+            throw new Error('Oracle URL 缺少用户名：应为 oracle://user:pass@host:1521/SERVICE_NAME');
+        }
+        return {
+            user,
+            password: decodeURIComponent(u.password),
+            connectString: `${u.hostname}:${u.port || 1521}/${service}`,
+        };
+    }
+    const f = conn.fields ?? {};
+    const host = typeof f.host === 'string' ? f.host : '';
+    const port = typeof f.port === 'number' ? f.port : 1521;
+    const service = typeof f.service === 'string' ? f.service : typeof f.database === 'string' ? f.database : '';
+    if (host === '' || service === '') {
+        throw new Error('Oracle 连接需要 url（oracle://user:pass@host:1521/SERVICE）或 fields（host/port/service）');
+    }
+    const user = typeof f.user === 'string' ? f.user : '';
+    if (user === '') {
+        throw new Error('Oracle 连接缺少用户名（fields.user）');
+    }
+    return {
+        user,
+        password: typeof f.password === 'string' ? f.password : '',
+        connectString: `${host}:${port}/${service}`,
+    };
+}
+export async function createOracleAdapter(conn, opts) {
+    const mode = opts?.mode ?? 'rw';
+    let pool;
+    if (opts?.pool) {
+        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);
+        }
+    }
+    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) {
+        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}`,
+        };
+    }
+    // autoCommit 默认 true：query/元数据 SELECT 结束隐式事务避免 ro 事务悬挂；tx 专用连接显式 autoCommit:false 覆盖
+    const execOpts = { outFormat: oracledb.OBJECT, maxRows: ROWS_MAX + 1, autoCommit: true, ...BLOB_FETCH };
+    /**
+     * 从池借一条连接执行后归还。⚠️ oracledb 的 Pool 没有 execute，
+     * 一切语句必须在 Connection 上执行；close() 即归还连接。
+     */
+    async function withConn(fn) {
+        const c = await pool.getConnection();
+        try {
+            return await fn(c);
+        }
+        finally {
+            await c.close().catch(() => { });
+        }
+    }
+    // 注意：currentUser / 系统 schema 名单在 adapter 对象之前声明，
+    // 不再依赖「方法仅运行期调用」的隐式 TDZ 保证（审查项：脆弱模式消除）
+    const currentUser = resolveOracleConn(conn).user.toUpperCase();
+    /** Oracle 内建系统 schema（核心名单 + APEX/flows 组件前缀）：业务不可查询，列表中过滤 */
+    const ORA_SYSTEM_SCHEMAS = new Set([
+        'SYS', 'SYSTEM', 'OUTLN', 'XDB', 'CTXSYS', 'MDSYS', 'OLAPSYS', 'ORDDATA', 'ORDSYS',
+        'WMSYS', 'DBSNMP', 'APPQOSSYS', 'AUDSYS', 'LBACSYS', 'DVSYS', 'OJVMSYS', 'DBSFWUSER',
+        'GSMADMIN_INTERNAL', 'GSMCATUSER', 'GGSYS', 'REMOTE_SCHEDULER_AGENT', 'ANONYMOUS',
+    ]);
+    const isOraSystemSchema = (o) => ORA_SYSTEM_SCHEMAS.has(o) || /^(APEX|FLOWS)_/.test(o);
+    /** owner 解析：database 参数或默认当前用户（保留原样——引用创建的 schema 大小写敏感） */
+    function ownerOf(database) {
+        return sanitizeIdentifier(database ?? currentUser, 'schema/owner 名');
+    }
+    const adapter = {
+        kind: 'oracle',
+        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 在部分受限环境对普通用户不可读（ORA-00942/ORA-01031）：
+                // 版本信息尽力而为，连通性本身用 dual 兜底判定，避免误报连接失败
+                try {
+                    await withConn((c) => c.execute('SELECT 1 FROM dual', [], execOpts));
+                    return { ok: true, serverInfo: 'Oracle（版本信息不可读：v$version 无权限）' };
+                }
+                catch (e) {
+                    return { ok: false, error: humanizeOraError(e).message };
+                }
+            }
+        },
+        async query(sql, params) {
+            const head = sql.trim().split(/\s+/)[0]?.toUpperCase() ?? '';
+            if (head !== 'SELECT' && head !== 'WITH') {
+                throw new Error('Oracle query 仅允许 SELECT/WITH 语句；写操作或 DDL 请走 execute');
+            }
+            try {
+                const r = await withConn((c) => c.execute(sql, params ?? [], execOpts));
+                const allRows = r.rows ?? [];
+                const truncated = allRows.length > ROWS_MAX;
+                const rows = allRows.slice(0, ROWS_MAX);
+                const columns = (r.metaData ?? []).map((m) => m.name);
+                const normRows = [];
+                for (const row of rows) {
+                    normRows.push(await Promise.all(Object.values(row).map(normalizeCell)));
+                }
+                return { columns, rows: normRows, rowCount: normRows.length, truncated: truncated || undefined };
+            }
+            catch (e) {
+                throw humanizeOraError(e);
+            }
+        },
+        async execute(statement, params) {
+            requireRw('execute');
+            try {
+                const r = await withConn((c) => c.execute(statement, params ?? [], execOpts));
+                return await toExecResult(statement, r);
+            }
+            catch (e) {
+                throw humanizeOraError(e);
+            }
+        },
+        /**
+         * 事务：从池取专用连接执行多条语句，成功 commit、异常 rollback。
+         * Oracle 无 BEGIN，用 SET TRANSACTION READ WRITE 开始显式事务。
+         */
+        async tx(fn) {
+            requireRw('事务(tx)');
+            const c = await pool.getConnection();
+            try {
+                await c.execute('SET TRANSACTION READ WRITE');
+                const exec = async (sql, binds) => {
+                    const r = await c.execute(sql, binds ?? [], { ...execOpts, autoCommit: false });
+                    return toExecResult(sql, r);
+                };
+                const out = await fn(exec);
+                await c.commit();
+                return out;
+            }
+            catch (e) {
+                try {
+                    await c.rollback();
+                }
+                catch { /* 已断开等场景忽略 */ }
+                throw humanizeOraError(e);
+            }
+            finally {
+                try {
+                    await c.close();
+                }
+                catch { /* 归还失败忽略 */ }
+            }
+        },
+        async listDatabases() {
+            // Oracle 为单库多 schema 模型：「数据库」下拉列出可浏览的 schema（有表者），
+            // 失败回退当前用户 schema，绝不用 service 名等占位值（会污染 owner 参数）。
+            // 内建系统 schema（数据字典/组件账户）业务不可查询，列出只会让展开时报
+            // ORA-00942/ORA-01031 类错误，故过滤（保留当前用户自身）。
+            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(row.OWNER ?? '').trim())
+                    .filter(Boolean)
+                    .filter((o) => o === currentUser || !isOraSystemSchema(o.toUpperCase()));
+                return owners.length > 0 ? owners : [currentUser];
+            }
+            catch {
+                return [currentUser];
+            }
+        },
+        async listTables(database) {
+            const owner = ownerOf(database);
+            try {
+                const r = await withConn((c) => c.execute('SELECT table_name FROM all_tables WHERE owner = :owner ORDER BY table_name 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 humanizeOraError(e);
+            }
+        },
+        async describeTable(table, database) {
+            const owner = ownerOf(database);
+            // 原名精确匹配优先；未引用创建的表名在字典中为大写存储，UPPER 兜底
+            const tab = sanitizeIdentifier(table, '表名');
+            try {
+                // 同连接内两查保证一致性
+                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)/.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 humanizeOraError(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 {
+                const r = await withConn((c) => c.execute(`SELECT * FROM "${escIdent(owner)}"."${escIdent(tab)}" OFFSET :o ROWS FETCH NEXT :n ROWS ONLY`, [off, n], execOpts));
+                const rows = r.rows ?? [];
+                const columns = (r.metaData ?? []).map((m) => m.name);
+                const normRows = [];
+                for (const row of rows) {
+                    normRows.push(await Promise.all(Object.values(row).map(normalizeCell)));
+                }
+                return { columns, rows: normRows, rowCount: normRows.length };
+            }
+            catch (e) {
+                throw humanizeOraError(e);
+            }
+        },
+        async close() {
+            try {
+                await pool.close();
+            }
+            catch { /* 已关闭忽略 */ }
+        },
+    };
+    return adapter;
+}
+export const factory = async (conn) => createOracleAdapter(conn);

package/dist/adapters/postgresql/index.js

@@ -0,0 +1,15 @@
+/**
+ * PostgreSQL 适配器（pg 8.x）。核心逻辑在 sql-shared/pg-like.ts，此处仅做驱动绑定。
+ * ro 模式：pool 'connect' 事件设只读会话（服务器级）+ 服务层拦截 execute（双保险）。
+ *
+ * 说明：pg 包未提供 ESM 类型入口（exports 无 types 条件），统一用 createRequire
+ * 加载 CJS 入口并按 PgLikeDriver 结构使用——与 gaussdb vendor 加载路径对称。
+ */
+import { createRequire } from 'node:module';
+import { createPgLikeAdapter } from '../sql-shared/pg-like.js';
+const require = createRequire(import.meta.url);
+export async function createPostgresqlAdapter(conn, opts) {
+    const driver = require('pg');
+    return createPgLikeAdapter('postgresql', driver, conn, opts);
+}
+export const factory = (conn) => createPostgresqlAdapter(conn);