@nsyan/db 1.0.0

package/src/dialects/hive.ts

@@ -0,0 +1,124 @@
+// src/dialects/hive.ts —— Hive 方言（BigDataDialect + hive-driver HS2）
+// Spike 结论（Task 8）：本机无可用 Hive/Spark Thrift 端点，SPIKE-SKIPPED；
+// 写法依据 hive-driver@1.0.1 实际 API（HiveClient.connect → openSession →
+// session.executeStatement → operation.fetch/hasMoreRows/getSchema/getData/flush/cancel/close），
+// 与 brief 示例的裸 client.fetchResults 写法不同，按实际调整。live 端到端待真实环境验证。
+// 注：hive-driver 的 dist/index.js 无 default export（经 macOS tsx 实测确认：
+// `import hive from` 得 undefined，必须用 namespace import），故用 `import * as`。
+import * as hive from "hive-driver";
+import type { ConnConfig, DbConnection, ParsedTarget,
+  DescribeTableResult, ColumnInfo } from "../core/types.js";
+import { BigDataDialect, type Hs2Session } from "./bigdata-dialect.js";
+import { register, type Fingerprints } from "./dialect.js";
+
+// ── URL 解析：jdbc:hive2://host:port/database（默认端口 10000）───
+const HIVE2_RE = /^jdbc:hive2:\/\/([^:/?#]+)(?::(\d+))?\/([^?#]*)$/;
+const DEFAULT_PORT = 10000;
+
+function parseHiveUrl(url: string): ParsedTarget | null {
+  const clean = url.split("?")[0];
+  const m = clean.match(HIVE2_RE);
+  if (!m) return null;
+  const host = m[1];
+  const port = m[2] ? parseInt(m[2], 10) : DEFAULT_PORT;
+  const database = m[3] || undefined;
+  if (!host) return null;
+  return { host, port, database };
+}
+
+const { TCLIService, TCLIService_types } = hive.thrift as unknown as {
+  TCLIService: object; TCLIService_types: { TProtocolVersion: Record<string, number> };
+};
+
+export function buildSessionConfig(config: ConnConfig): Record<string, string> {
+  const vars: Record<string, string> = {};
+  for (const [k, v] of Object.entries(config.options ?? {})) {
+    const key = k.startsWith("hive.") ? k : `hive.${k}`;
+    vars[key] = v;
+  }
+  return vars;
+}
+
+class HiveDialect extends BigDataDialect {
+  id = "hive" as const;
+  label = "Hive";
+  family = "bigdata" as const;
+  defaultPort = DEFAULT_PORT;
+  fingerprints: Fingerprints = {
+    urlPatterns: [/^jdbc:hive2:\/\//],
+    configKeys: ["spring.datasource.url"],
+  };
+  // Task 1 WRITE_RE 已含 MSCK|CACHE|REFRESH；家族集补 HiveQL 特有写形态
+  protected writeKeywords = /\b(INSERT\s+(INTO|OVERWRITE)|CREATE\s+TABLE(\s+AS)?|LOAD\s+DATA|MSCK|ALTER|DROP)\b/i;
+  protected sessionPrefix = "hive.";
+
+  parseUrl(url: string): ParsedTarget | null {
+    return parseHiveUrl(url);
+  }
+
+  displayUrl(config: ConnConfig): string {
+    return `jdbc:hive2://${config.host}:${config.port ?? DEFAULT_PORT}/${config.database ?? "default"}`;
+  }
+
+  protected async doConnect(config: ConnConfig, timeoutMs: number): Promise<DbConnection> {
+    const client = new hive.HiveClient(TCLIService, TCLIService_types);
+    await client.connect(
+      { host: config.host ?? "localhost", port: config.port ?? DEFAULT_PORT },
+      new hive.connections.TcpConnection(),
+      config.password
+        ? new hive.auth.PlainTcpAuthentication({ username: config.username ?? "", password: config.password })
+        : new hive.auth.NoSaslAuthentication(),
+    );
+    const configuration = buildSessionConfig(config);
+    if (config.database) configuration["hive.cli.currentDb"] = config.database;
+    const session = await client.openSession({
+      client_protocol: TCLIService_types.TProtocolVersion.HIVE_CLI_SERVICE_PROTOCOL_V10,
+      username: config.username || undefined,
+      password: config.password || undefined,
+      configuration,
+    });
+    void timeoutMs;
+    const hs2session = session as unknown as Hs2Session;
+    return {
+      type: "hive",
+      client: hs2session,
+      async close() {
+        try { await session.close(); } catch { /* ignore */ }
+        client.close();
+      },
+    };
+  }
+
+  async versionQuery(conn: DbConnection): Promise<string> {
+    const session = conn.client as Hs2Session;
+    // 走基类受保护拉取路径（超时 + cancel + close），Hive 无统一版本函数时兜底 "unknown"
+    return this.fetchVersion(session);
+  }
+
+  // DESCRIBE FORMATTED → 列名/类型/注释（遇 # 分区信息段即停）
+  async describeTable(config: ConnConfig, table: string): Promise<DescribeTableResult> {
+    if (!table.trim()) {
+      return { success: false, error: "表名不能为空" };
+    }
+    try {
+      const columns: ColumnInfo[] = await this.withConnection(config, async (conn) => {
+        const session = conn.client as Hs2Session;
+        const r = await this.runStatement(session, `DESCRIBE FORMATTED ${table}`,
+          { readonly: true, maxRows: 500, timeoutSec: 30 });
+        const cols: ColumnInfo[] = [];
+        for (const row of r.rows) {
+          const [name, type, comment] = row.map((v) => String(v ?? "").trim());
+          if (!name || name.startsWith("#")) break;
+          cols.push({ name, type, nullable: true, default: null, primaryKey: false, comment: comment ?? "" });
+        }
+        return cols;
+      });
+      return { success: true, columns, count: columns.length };
+    } catch (err: unknown) {
+      return { success: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  }
+}
+
+export const hiveDialect = new HiveDialect();
+register(hiveDialect);

package/src/dialects/index.ts

@@ -0,0 +1,12 @@
+// src/dialects/index.ts —— 聚合各方言（新增方言时加一行 re-export；
+// 方言文件自带 register() 副作用，遗漏聚合行时 registry 规模断言失败）
+export { registry, register } from "./dialect.js";
+export type { Dialect, Verdict, Fingerprints } from "./dialect.js";
+export { postgresqlDialect } from "./postgresql.js";
+export { mysqlDialect } from "./mysql.js";
+export { oracleDialect } from "./oracle.js";
+export { dmDialect } from "./dm.js";
+export { redisDialect } from "./redis.js";
+export { esDialect } from "./elasticsearch.js";
+export { hiveDialect } from "./hive.js";
+export { sparkDialect } from "./spark.js";

package/src/dialects/kv-dialect.ts

@@ -0,0 +1,127 @@
+// dialects/kv-dialect.ts —— KV 家族基类（命令切分、白名单 verdict、sendCommand 执行）
+import type { ConnConfig, DbConnection, ExecOpts, ParsedTarget,
+  QueryResult } from "../core/types.js";
+import { matchCommand } from "../core/whitelist.js";
+import type { Dialect, Verdict, Fingerprints } from "./dialect.js";
+
+// ── 命令切分（空白 + 双引号）───
+// 注：Redis 无分号语句概念，sql 整体视为一条命令
+export function splitCommand(input: string): string[] {
+  const parts: string[] = [];
+  let cur = "";
+  let inQuote = false;
+  for (let i = 0; i < input.length; i++) {
+    const ch = input[i];
+    if (inQuote) {
+      if (ch === '"') {
+        inQuote = false;
+      } else {
+        cur += ch;
+      }
+      continue;
+    }
+    if (ch === '"') { inQuote = true; continue; }
+    if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r") {
+      if (cur) { parts.push(cur); cur = ""; }
+      continue;
+    }
+    cur += ch;
+  }
+  if (cur) parts.push(cur);
+  return parts;
+}
+
+// ── 只读命令白名单（Spec §4.2；KEYS 已移除，生产库一律 SCAN）───
+const READ_CMDS = [
+  "GET", "MGET", "HGETALL", "HGET", "HMGET", "HKEYS", "HVALS", "HLEN",
+  "LRANGE", "LLEN", "LINDEX", "SMEMBERS", "SCARD", "SISMEMBER",
+  "ZRANGE", "ZSCORE", "ZCARD", "SCAN", "TYPE", "TTL", "PTTL", "EXISTS",
+  "STRLEN", "GETRANGE", "INFO", "DBSIZE", "RANDOMKEY", "OBJECT", "MEMORY",
+];
+
+// ── 恒拒命令（与只读开关无关；CONFIG 一刀切含 CONFIG GET，有意从紧）───
+const DENY_ALWAYS = ["FLUSHALL", "FLUSHDB", "CONFIG", "SHUTDOWN", "SLAVEOF", "REPLICAOF", "DEBUG"];
+
+export abstract class KvDialect implements Dialect {
+  abstract id: Dialect["id"];
+  abstract label: string;
+  abstract family: Dialect["family"];
+  abstract defaultPort: number;
+  abstract fingerprints: Fingerprints;
+  abstract parseUrl(url: string): ParsedTarget | null;
+  abstract displayUrl(config: ConnConfig): string;
+  abstract versionQuery(conn: DbConnection): Promise<string>;
+  protected abstract doConnect(config: ConnConfig, timeoutMs: number): Promise<DbConnection>;
+  // 注：doSendCommand 直接收驱动 client（unknown），各方言内部收窄为私有连接类型
+  protected abstract doSendCommand(client: unknown, args: string[]): Promise<unknown>;
+
+  isAllowed(sql: string, readonly: boolean): Verdict {
+    const args = splitCommand(sql);
+    if (args.length === 0) return { ok: false, reason: "命令为空" };
+    const cmd = args[0].toUpperCase();
+    const rest = args.slice(1).join(" ");
+    const summary = `${cmd}${rest ? " " + rest.slice(0, 40) : ""}`;
+    if (matchCommand(cmd, DENY_ALWAYS)) {
+      return { ok: false, reason: `禁止执行危险命令：${cmd}`, isWrite: true, summary: `${cmd}（硬限制）` };
+    }
+    if (matchCommand(cmd, READ_CMDS)) {
+      return { ok: true, isWrite: false, summary };
+    }
+    if (readonly) {
+      return { ok: false, reason: `只读模式下不允许执行写命令：${cmd}`, isWrite: true, summary };
+    }
+    return { ok: true, isWrite: true, summary };
+  }
+
+  async executeOn(config: ConnConfig, sql: string, opts: ExecOpts): Promise<QueryResult> {
+    const start = Date.now();
+    const args = splitCommand(sql);
+    if (args.length === 0) {
+      return { success: false, error: "命令为空" };
+    }
+    try {
+      const raw = await this.withConnection(config, (conn) => this.doSendCommand(conn.client, args), opts.timeoutSec * 1000);
+      const rows = toRows(args[0], raw).slice(0, opts.maxRows);
+      const columns = ["result"];
+      return { success: true, columns, rows, rowCount: rows.length, duration: `${Date.now() - start}ms` };
+    } catch (err: unknown) {
+      return { success: false, error: err instanceof Error ? err.message : String(err), duration: `${Date.now() - start}ms` };
+    }
+  }
+
+  async withConnection<T>(config: ConnConfig, fn: (conn: DbConnection) => Promise<T>, timeoutMs = 10_000): Promise<T> {
+    const conn = await this.doConnect(config, timeoutMs);
+    try { return await fn(conn); }
+    finally { await conn.close(); }
+  }
+
+  async testConnection(config: ConnConfig): Promise<import("../core/types.js").TestConnectionResult> {
+    const start = Date.now();
+    try {
+      const version = await this.withConnection(config, (conn) => this.versionQuery(conn));
+      return { success: true, version, latency: `${Date.now() - start}ms` };
+    } catch (err: unknown) {
+      return { success: false, error: err instanceof Error ? err.message : String(err), latency: `${Date.now() - start}ms` };
+    }
+  }
+  abstract listTables(config: ConnConfig, pattern?: string): Promise<import("../core/types.js").ListTablesResult>;
+  abstract describeTable(config: ConnConfig, target: string): Promise<import("../core/types.js").DescribeTableResult>;
+}
+
+// ── 命令结果转行（展示层统一转字符串，保持原类型）───
+function toRows(cmd: string, raw: unknown): unknown[][] {
+  if (raw === null || raw === undefined) return [];
+  if (Array.isArray(raw)) {
+    // 偶数长度数组（HGETALL 等）按 k/v 配对展示
+    if (cmd.toUpperCase() === "HGETALL" && raw.length % 2 === 0) {
+      const out: unknown[][] = [];
+      for (let i = 0; i < raw.length; i += 2) out.push([raw[i], raw[i + 1]]);
+      return out;
+    }
+    return raw.map((v) => [Array.isArray(v) ? JSON.stringify(v) : v]);
+  }
+  if (typeof raw === "object") {
+    return Object.entries(raw as Record<string, unknown>).map(([k, v]) => [k, v]);
+  }
+  return [[raw]];
+}

package/src/dialects/mysql.ts

@@ -0,0 +1,158 @@
+// src/dialects/mysql.ts
+import mysql from "mysql2/promise";
+import type { ConnConfig, DbConnection, ExecOpts, ParsedTarget,
+  ListTablesResult, DescribeTableResult, ColumnInfo } from "../core/types.js";
+import { RelationalDialect } from "./relational-dialect.js";
+import { register, filterTables, type Fingerprints } from "./dialect.js";
+
+// ── URL 解析（JDBC + 原生 URI 双形态，Spec §7）───
+
+const JDBC_RE = /^jdbc:mysql:\/\/([^:/?#]+)(?::(\d+))?\/([^?#]+).*$/;
+const NATIVE_RE = /^mysql:\/\/(?:([^:/?#@]+)(?::([^/?#@]*))?@)?([^:/?#]+)(?::(\d+))?\/([^?#]+).*$/;
+
+function parseMysqlUrl(url: string): ParsedTarget | null {
+  const clean = url.split("?")[0];
+  const m = clean.match(JDBC_RE);
+  if (m) {
+    const host = m[1];
+    const port = m[2] ? parseInt(m[2], 10) : 3306;
+    const database = m[3];
+    if (!host || !database) return null;
+    return { host, port, database };
+  }
+  const n = clean.match(NATIVE_RE);
+  if (n) {
+    const host = n[3];
+    const port = n[4] ? parseInt(n[4], 10) : 3306;
+    const database = n[5];
+    if (!host || !database) return null;
+    const out: ParsedTarget = { host, port, database };
+    if (n[1] !== undefined) out.username = decodeURIComponent(n[1]);
+    if (n[2] !== undefined) out.password = decodeURIComponent(n[2]);
+    return out;
+  }
+  return null;
+}
+
+// ── MySQL 方言（逻辑从 src/db.ts 原样搬入）───
+
+class MysqlDialect extends RelationalDialect {
+  id = "mysql" as const;
+  label = "MySQL";
+  family = "relational" as const;
+  defaultPort = 3306;
+  fingerprints: Fingerprints = {
+    urlPatterns: [/^jdbc:mysql:\/\//, /^mysql:\/\//],
+    configKeys: ["spring.datasource.url"],
+  };
+
+  parseUrl(url: string): ParsedTarget | null {
+    return parseMysqlUrl(url);
+  }
+
+  displayUrl(config: ConnConfig): string {
+    return `jdbc:mysql://${config.host}:${config.port}/${config.database}`;
+  }
+
+  protected async doConnect(config: ConnConfig, _timeoutMs: number): Promise<DbConnection> {
+    const conn = await mysql.createConnection({
+      host: config.host,
+      port: config.port,
+      user: config.username,
+      password: config.password,
+      database: config.database,
+      charset: "utf8mb4",
+    });
+    return {
+      type: "mysql",
+      client: conn,
+      async close() { await conn.end(); },
+    };
+  }
+
+  protected async doExecute(client: unknown, stmt: string, opts: ExecOpts): Promise<{ columns: string[]; rows: unknown[][]; rowCount: number }> {
+    const mysqlConn = client as mysql.Connection;
+    const timeoutMs = opts.timeoutSec * 1000;
+    const maxRows = opts.maxRows;
+    // 设置 max_execution_time；老版本服务端（<5.7.8）SET 失败时忽略，客户端超时仍生效
+    try {
+      await mysqlConn.execute(`SET max_execution_time = ${timeoutMs}`);
+    } catch { /* ignore: server too old for max_execution_time */ }
+    const [rows, fields] = await mysqlConn.execute(stmt);
+    if (Array.isArray(fields) && fields.length > 0) {
+      const columns = fields.map((f: any) => f.name);
+      const data = (rows as any[]).slice(0, maxRows).map((r: any) => columns.map((col: string) => r[col]));
+      return { columns, rows: data, rowCount: (rows as any[]).length };
+    }
+    const affected = (rows as any)?.affectedRows ?? 0;
+    return { columns: [], rows: [], rowCount: affected };
+  }
+
+  async versionQuery(conn: DbConnection): Promise<string> {
+    const mysqlConn = conn.client as mysql.Connection;
+    const [rows] = await mysqlConn.execute("SELECT version() AS v");
+    return (rows as any[])[0].v;
+  }
+
+  async listTables(config: ConnConfig, pattern?: string): Promise<ListTablesResult> {
+    try {
+      const tables = await this.withConnection(config, async (conn) => {
+        const mysqlConn = conn.client as mysql.Connection;
+        const [rows] = await mysqlConn.execute(
+          "SELECT TABLE_NAME, TABLE_TYPE, TABLE_COMMENT FROM information_schema.TABLES WHERE TABLE_SCHEMA = ? ORDER BY TABLE_NAME",
+          [config.database],
+        );
+        const all = (rows as any[]).map((r: any) => ({
+          schema: "",
+          name: r.TABLE_NAME,
+          type: r.TABLE_TYPE === "BASE TABLE" ? "TABLE" : r.TABLE_TYPE,
+          description: r.TABLE_COMMENT || "",
+        }));
+        return filterTables(all, pattern);
+      });
+      return { success: true, tables, count: tables.length };
+    } catch (err: unknown) {
+      return { success: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  }
+
+  async describeTable(config: ConnConfig, table: string): Promise<DescribeTableResult> {
+    if (!table.trim()) {
+      return { success: false, error: "表名不能为空" };
+    }
+    try {
+      const columns: ColumnInfo[] = await this.withConnection(config, async (conn) => {
+        const mysqlConn = conn.client as mysql.Connection;
+        const safeTable = table.replace(/`/g, "``");
+        const [rows] = await mysqlConn.execute(`DESCRIBE \`${safeTable}\``);
+        const cols: ColumnInfo[] = (rows as any[]).map((r: any) => ({
+          name: r.Field,
+          type: r.Type,
+          nullable: r.Null === "YES",
+          default: r.Default,
+          primaryKey: r.Key === "PRI",
+          comment: "",
+        }));
+
+        // 获取注释
+        try {
+          const [commentRows] = await mysqlConn.execute(
+            "SELECT COLUMN_NAME, COLUMN_COMMENT FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?",
+            [config.database, table],
+          );
+          const commentMap = new Map((commentRows as any[]).map((r: any) => [r.COLUMN_NAME, r.COLUMN_COMMENT]));
+          for (const col of cols) {
+            col.comment = commentMap.get(col.name) || "";
+          }
+        } catch { /* ignore */ }
+        return cols;
+      });
+      return { success: true, columns, count: columns.length };
+    } catch (err: unknown) {
+      return { success: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  }
+}
+
+export const mysqlDialect = new MysqlDialect();
+register(mysqlDialect);

package/src/dialects/oracle.ts

@@ -0,0 +1,177 @@
+// src/dialects/oracle.ts
+import oracledb from "oracledb";
+import type { ConnConfig, DbConnection, ExecOpts, ParsedTarget,
+  ListTablesResult, DescribeTableResult, ColumnInfo, TestConnectionResult } from "../core/types.js";
+import { RelationalDialect } from "./relational-dialect.js";
+import { register, filterTables, type Fingerprints } from "./dialect.js";
+
+// ── URL 解析（从 index.ts parseJdbcUrl 原样搬入：service 名 + SID 双分支）───
+
+const SVC_RE = /^jdbc:oracle:thin:@\/\/([^:/?#]+)(?::(\d+))?\/([^?#]+)$/;
+const SID_RE = /^jdbc:oracle:thin:@([^:/?#]+)(?::(\d+))?:([^?#]+)$/;
+
+function parseOracleUrl(url: string): ParsedTarget | null {
+  const clean = url.split("?")[0];
+  const svc = clean.match(SVC_RE);
+  if (svc) {
+    const host = svc[1];
+    const port = svc[2] ? parseInt(svc[2], 10) : 1521;
+    const database = svc[3];
+    if (!host || !database) return null;
+    return { host, port, database };
+  }
+  const sid = clean.match(SID_RE);
+  if (sid) {
+    const host = sid[1];
+    const port = sid[2] ? parseInt(sid[2], 10) : 1521;
+    const database = sid[3];
+    if (!host || !database) return null;
+    return { host, port, database };
+  }
+  return null;
+}
+
+// ── Oracle 方言（逻辑从 src/db.ts 原样搬入）───
+
+class OracleDialect extends RelationalDialect {
+  id = "oracle" as const;
+  label = "Oracle";
+  family = "relational" as const;
+  defaultPort = 1521;
+  fingerprints: Fingerprints = {
+    urlPatterns: [/^jdbc:oracle:thin:@/],
+    configKeys: ["spring.datasource.url"],
+  };
+
+  parseUrl(url: string): ParsedTarget | null {
+    return parseOracleUrl(url);
+  }
+
+  displayUrl(config: ConnConfig): string {
+    return `jdbc:oracle:thin:@//${config.host}:${config.port}/${config.database}`;
+  }
+
+  // Spec §12：Thin 模式硬性要求 DB ≥12.1；连接失败且疑似老版本时给出版本原因指引
+  async testConnection(config: ConnConfig): Promise<TestConnectionResult> {
+    const result = await super.testConnection(config);
+    if (!result.success
+        && /ORA-28040|ORA-03134|no matching authentication protocol/i.test(result.error ?? "")) {
+      result.error += "\n疑似 Oracle 服务端版本过低（<12.1）：Thin 模式要求服务端 ≥12.1，11g 及以下需 Thick 模式（Instant Client），暂未支持。请联系 DBA 升级或使用其他客户端。";
+    }
+    return result;
+  }
+
+  protected async doConnect(config: ConnConfig, _timeoutMs: number): Promise<DbConnection> {
+    const conn = await oracledb.getConnection({
+      user: config.username,
+      password: config.password,
+      connectString: `${config.host}:${config.port}/${config.database}`,
+    });
+    return {
+      type: "oracle",
+      client: conn,
+      async close() { await conn.close(); },
+    };
+  }
+
+  protected async doExecute(client: unknown, stmt: string, opts: ExecOpts): Promise<{ columns: string[]; rows: unknown[][]; rowCount: number }> {
+    const oracleConn = client as oracledb.Connection;
+    const timeoutMs = opts.timeoutSec * 1000;
+    const maxRows = opts.maxRows;
+    const res = await oracleConn.execute(stmt, [], {
+      maxRows,
+      fetchArraySize: maxRows,
+      timeout: timeoutMs,
+    });
+    if (res.metaData && res.metaData.length > 0) {
+      const columns = res.metaData.map((m: any) => m.name);
+      const rows = (res.rows ?? []).slice(0, maxRows).map((r: any) => [...r]);
+      return { columns, rows, rowCount: res.rows?.length ?? 0 };
+    }
+    return { columns: [], rows: [], rowCount: res.rowsAffected ?? 0 };
+  }
+
+  async versionQuery(conn: DbConnection): Promise<string> {
+    const oracleConn = conn.client as oracledb.Connection;
+    const res = await oracleConn.execute("SELECT version FROM v$instance");
+    return (res.rows ?? [])[0]?.[0] as string ?? "unknown";
+  }
+
+  async listTables(config: ConnConfig, pattern?: string): Promise<ListTablesResult> {
+    try {
+      const tables = await this.withConnection(config, async (conn) => {
+        const oracleConn = conn.client as oracledb.Connection;
+        const res = await oracleConn.execute(
+          `SELECT TABLE_NAME, OWNER, COMMENTS FROM ALL_TABLES T
+           LEFT JOIN ALL_TAB_COMMENTS C ON T.TABLE_NAME = C.TABLE_NAME AND T.OWNER = C.OWNER
+           WHERE T.OWNER NOT IN ('SYS', 'SYSTEM', 'DBSNMP', 'XDB')
+           ORDER BY T.OWNER, T.TABLE_NAME`,
+        );
+        const all = (res.rows ?? []).map((r: any) => ({
+          schema: r[1],
+          name: r[0],
+          type: "TABLE",
+          description: r[2] || "",
+        }));
+        return filterTables(all, pattern);
+      });
+      return { success: true, tables, count: tables.length };
+    } catch (err: unknown) {
+      return { success: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  }
+
+  async describeTable(config: ConnConfig, table: string): Promise<DescribeTableResult> {
+    if (!table.trim()) {
+      return { success: false, error: "表名不能为空" };
+    }
+    try {
+      const columns: ColumnInfo[] = await this.withConnection(config, async (conn) => {
+        const oracleConn = conn.client as oracledb.Connection;
+        const res = await oracleConn.execute(
+          `SELECT
+            COLUMN_NAME,
+            DATA_TYPE || CASE WHEN DATA_PRECISION IS NOT NULL THEN '(' || DATA_PRECISION || ',' || DATA_SCALE || ')' WHEN DATA_LENGTH IS NOT NULL AND DATA_TYPE LIKE '%CHAR%' THEN '(' || DATA_LENGTH || ')' ELSE '' END,
+            NULLABLE,
+            DATA_DEFAULT,
+            COMMENTS
+          FROM ALL_TAB_COLUMNS C
+          LEFT JOIN ALL_COL_COMMENTS COM ON C.TABLE_NAME = COM.TABLE_NAME AND C.COLUMN_NAME = COM.COLUMN_NAME AND C.OWNER = COM.OWNER
+          WHERE C.TABLE_NAME = :1 AND C.OWNER NOT IN ('SYS', 'SYSTEM', 'DBSNMP', 'XDB')
+          ORDER BY C.COLUMN_ID`,
+          [table.toUpperCase()],
+        );
+        const cols: ColumnInfo[] = (res.rows ?? []).map((r: any) => ({
+          name: r[0],
+          type: r[1],
+          nullable: r[2] === "Y",
+          default: r[3] || null,
+          primaryKey: false,
+          comment: r[4] || "",
+        }));
+
+        // 查主键
+        try {
+          const pkRes = await oracleConn.execute(
+            `SELECT cc.COLUMN_NAME
+             FROM ALL_CONS_COLUMNS cc
+             JOIN ALL_CONSTRAINTS c ON cc.CONSTRAINT_NAME = c.CONSTRAINT_NAME AND cc.OWNER = c.OWNER
+             WHERE c.CONSTRAINT_TYPE = 'P' AND c.TABLE_NAME = :1`,
+            [table.toUpperCase()],
+          );
+          const pkSet = new Set((pkRes.rows ?? []).map((r: any) => r[0]));
+          for (const col of cols) {
+            if (pkSet.has(col.name)) col.primaryKey = true;
+          }
+        } catch { /* ignore */ }
+        return cols;
+      });
+      return { success: true, columns, count: columns.length };
+    } catch (err: unknown) {
+      return { success: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  }
+}
+
+export const oracleDialect = new OracleDialect();
+register(oracleDialect);