@nsyan/db 1.0.0

package/src/dialects/bigdata-dialect.ts

@@ -0,0 +1,197 @@
+// src/dialects/bigdata-dialect.ts —— 大数据 SQL 引擎家族基类（Hive / Spark Thrift Server 共享 HS2 协议栈）
+// 注：Hive 与 Spark Thrift Server 同协议（HiveServer2 Thrift），连接建立、会话变量、
+// 会话关闭、batch 拉取、取消 operation 全部在基类实现，方言只提供差异点
+// （写关键字集、会话变量前缀、版本查询、DESCRIBE 解析）。
+import type { ConnConfig, DbConnection, ExecOpts, QueryResult,
+  ListTablesResult, DescribeTableResult, TestConnectionResult, TableInfo } from "../core/types.js";
+import { splitStatements, isWriteStatement, isDropStatement } from "../core/sql-text.js";
+import type { Dialect, Verdict, Fingerprints } from "./dialect.js";
+import { likeMatch } from "./dialect.js";
+
+// ── HS2 会话/操作最小结构（按 hive-driver 实际 API: HiveSession/HiveOperation）───
+// 用 unknown + 收窄避免对 hive-driver 强类型依赖；仅单元测试可构造 FakeHs2Session。
+export interface Hs2Operation {
+  setMaxRows(n: number): void;
+  fetch(): Promise<Hs2Status>;
+  hasMoreRows(): boolean;
+  getSchema(): { columns: Array<{ columnName: string; comment?: string }> } | null;
+  getData(): Array<{ rows?: Array<{ colVals: Array<{ value?: unknown }> }> }>;
+  flush(): void;
+  cancel(): Promise<unknown>;
+  close(): Promise<unknown>;
+}
+export interface Hs2Session {
+  executeStatement(stmt: string): Promise<Hs2Operation>;
+  close(): Promise<unknown>;
+}
+interface Hs2Status { statusCode?: number; errorMessage?: string; }
+
+function statusFailed(s: Hs2Status): string | null {
+  const code = s?.statusCode;
+  if (code === undefined || code === 0) return null;
+  return s.errorMessage || `operation failed (statusCode=${code})`;
+}
+
+function withTimeout<T>(promise: Promise<T>, timeoutMs: number, label: string): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`${label} 超时（超过 ${timeoutMs / 1000} 秒）`));
+    }, timeoutMs);
+    promise.then(
+      (val) => { clearTimeout(timer); resolve(val); },
+      (err) => { clearTimeout(timer); reject(err); }
+    );
+  });
+}
+
+export abstract class BigDataDialect implements Dialect {
+  abstract id: Dialect["id"];
+  abstract label: string;
+  abstract family: Dialect["family"];
+  abstract defaultPort: number;
+  abstract fingerprints: Fingerprints;
+  abstract parseUrl(url: string): ReturnType<Dialect["parseUrl"]>;
+  abstract displayUrl(config: ConnConfig): string;
+  abstract versionQuery(conn: DbConnection): Promise<string>;
+  /** 方言的写关键字集（大小写不敏感正则片段，逐语句匹配） */
+  protected abstract writeKeywords: RegExp;
+  /** 会话变量前缀：hive. / spark.（SET <prefix>key=value 在 withConnection 内下发） */
+  protected abstract sessionPrefix: string;
+
+  // ── HS2 会话建立：openSession 由方言 doConnect 完成，client 即 Hs2Session ──
+  protected abstract doConnect(config: ConnConfig, timeoutMs: number): Promise<DbConnection>;
+
+  async withConnection<T>(config: ConnConfig, fn: (conn: DbConnection) => Promise<T>, timeoutMs = 30_000): Promise<T> {
+    // 建连（TCP 握手 + openSession）同样纳入超时，避免无界挂起；
+    // 默认 30s（HS2 握手慢于关系型），各方言不再各自加超时
+    const conn = await withTimeout(this.doConnect(config, timeoutMs), timeoutMs, "连接数据库");
+    try { return await fn(conn); }
+    finally { await conn.close(); }
+  }
+
+  // ── 只读检查：复用 sql-text 逐语句机制 + 家族写关键字（与 Task 1 WRITE_RE 一致方向）───
+  isAllowed(sql: string, readonly: boolean): Verdict {
+    const stmts = splitStatements(sql);
+    if (stmts.length === 0) return { ok: false, reason: "SQL 语句为空" };
+    for (const s of stmts) {
+      if (isDropStatement(s)) {
+        return { ok: false, reason: `禁止执行 DROP 操作：${s.slice(0, 80)}`, summary: `DROP（硬限制）: ${s.slice(0, 60)}` };
+      }
+    }
+    const first = stmts[0];
+    const kind = /^\s*(\w+)/.exec(first)?.[1]?.toUpperCase() ?? "SQL";
+    const targets = [...first.matchAll(/\b(?:FROM|INTO|UPDATE|TABLE)\s+([A-Za-z0-9_."]+)/gi)].map((m) => m[1]).slice(0, 3).join(", ");
+    const summary = `${kind}${targets ? " " + targets : ""}（共 ${stmts.length} 条语句）`;
+    const flagged = (s: string): boolean => isWriteStatement(s) || this.writeKeywords.test(s);
+    if (readonly) {
+      for (const s of stmts) {
+        if (flagged(s)) {
+          return { ok: false, reason: `只读模式下不允许执行非查询语句：${s.slice(0, 80)}`, isWrite: true, summary };
+        }
+      }
+    }
+    const isWrite = stmts.some(flagged);
+    return { ok: true, isWrite, summary };
+  }
+
+  // ── 执行：executeStatement → 循环 fetch batch → 达 maxRows 即停 + truncated 标注 ──
+  // 超时用客户端 withTimeout 兜底，超时后尝试 cancel 释放服务端资源
+  protected async runStatement(session: Hs2Session, stmt: string, opts: ExecOpts): Promise<{ columns: string[]; rows: unknown[][]; rowCount: number; truncated: boolean }> {
+    const op = await session.executeStatement(stmt);
+    const execMs = opts.timeoutSec * 1000;
+    try {
+      const maxRows = Math.max(1, opts.maxRows);
+      const status = await withTimeout(op.fetch(), execMs, "执行查询");
+      const failed = statusFailed(status);
+      if (failed) throw new Error(failed);
+      op.setMaxRows(Math.min(maxRows, 1000));
+      const schema = op.getSchema();
+      const columns = (schema?.columns ?? []).map((c) => c.columnName);
+      const rows: unknown[][] = [];
+      let truncated = false;
+      // 首批已在 fetch() 内拉取；逐批 hasMoreRows 拉取，达 maxRows 即停
+      for (;;) {
+        for (const rs of op.getData()) {
+          for (const row of rs.rows ?? []) {
+            if (rows.length >= maxRows) { truncated = true; break; }
+            rows.push((row.colVals ?? []).map((cv) => cv?.value ?? null));
+          }
+          if (truncated) break;
+        }
+        op.flush();
+        if (truncated || !op.hasMoreRows()) break;
+        const st = await withTimeout(op.fetch(), execMs, "拉取结果");
+        const f = statusFailed(st);
+        if (f) throw new Error(f);
+      }
+      return { columns, rows, rowCount: rows.length, truncated };
+    } catch (err: unknown) {
+      try { await op.cancel(); } catch { /* 释放资源尽力而为 */ }
+      throw err;
+    } finally {
+      try { await op.close(); } catch { /* ignore */ }
+    }
+  }
+
+  // 版本查询统一走 runStatement 的受保护拉取路径（超时 + cancel + close），失败兜底 "unknown"
+  protected async fetchVersion(session: Hs2Session, stmt = "SELECT version()", timeoutSec = 30): Promise<string> {
+    try {
+      const r = await this.runStatement(session, stmt, { readonly: true, maxRows: 1, timeoutSec });
+      const val = r.rows[0]?.[0];
+      return val !== undefined && val !== null ? String(val) : "unknown";
+    } catch {
+      return "unknown";
+    }
+  }
+  async executeOn(config: ConnConfig, sql: string, opts: ExecOpts): Promise<QueryResult> {
+    const start = Date.now();
+    const stmts = splitStatements(sql);
+    try {
+      let last = { columns: [] as string[], rows: [] as unknown[][], rowCount: 0 };
+      let truncated = false;
+      await this.withConnection(config, async (conn) => {
+        const session = conn.client as Hs2Session;
+        for (const s of stmts) {
+          const r = await this.runStatement(session, s, opts);
+          last = { columns: r.columns, rows: r.rows, rowCount: r.rowCount };
+          if (r.truncated) truncated = true;
+        }
+      }, opts.timeoutSec * 1000);
+      const duration = `${Date.now() - start}ms`;
+      return { success: true, ...last, duration, truncated: truncated || undefined };
+    } catch (err: unknown) {
+      return { success: false, error: err instanceof Error ? err.message : String(err), duration: `${Date.now() - start}ms` };
+    }
+  }
+
+  async testConnection(config: ConnConfig): Promise<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` };
+    }
+  }
+
+  // SHOW TABLES + 可选 pattern 过滤（HS2 无 LIKE 下推，内存过滤）
+  async listTables(config: ConnConfig, pattern?: string): Promise<ListTablesResult> {
+    try {
+      const tables = await this.withConnection(config, async (conn) => {
+        const session = conn.client as Hs2Session;
+        const r = await this.runStatement(session, "SHOW TABLES", { readonly: true, maxRows: 5000, timeoutSec: 30 });
+        const nameIdx = r.columns.findIndex((c) => /table/i.test(c));
+        const rows: TableInfo[] = r.rows
+          .map((row) => String(row[nameIdx >= 0 ? nameIdx : 0] ?? ""))
+          .filter((name) => name && (!pattern || likeMatch(name, pattern)))
+          .map((name) => ({ schema: config.database ?? "", name, type: "TABLE", description: "" }));
+        return rows;
+      });
+      return { success: true, tables, count: tables.length };
+    } catch (err: unknown) {
+      return { success: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  }
+
+  abstract describeTable(config: ConnConfig, target: string): Promise<DescribeTableResult>;
+}

package/src/dialects/dialect.ts

@@ -0,0 +1,38 @@
+// dialects/dialect.ts
+import type { ConnConfig, ParsedTarget, DbConnection, ExecOpts, DbTypeId, DbFamily,
+  QueryResult, ListTablesResult, DescribeTableResult, TestConnectionResult } from "../core/types.js";
+
+export interface Fingerprints { urlPatterns: RegExp[]; configKeys: string[]; }
+export interface Verdict { ok: boolean; reason?: string; isWrite?: boolean; summary?: string; }
+
+export interface Dialect {
+  id: DbTypeId;
+  label: string;
+  family: DbFamily;
+  defaultPort: number;
+  fingerprints: Fingerprints;
+  parseUrl(url: string): ParsedTarget | null;
+  withConnection<T>(config: ConnConfig, fn: (conn: DbConnection) => Promise<T>, timeoutMs?: number): Promise<T>;
+  testConnection(config: ConnConfig): Promise<TestConnectionResult>;
+  isAllowed(sql: string, readonly: boolean): Verdict;
+  executeOn(config: ConnConfig, sql: string, opts: ExecOpts): Promise<QueryResult>;
+  listTables(config: ConnConfig, pattern?: string): Promise<ListTablesResult>;
+  describeTable(config: ConnConfig, target: string): Promise<DescribeTableResult>;
+  displayUrl(config: ConnConfig): string;
+  versionQuery(conn: DbConnection): Promise<string>;
+}
+
+export const registry = new Map<DbTypeId, Dialect>();
+export function register(d: Dialect): void { registry.set(d.id, d); }
+
+// SQL LIKE（%/_）转正则，listTables(pattern) 内存过滤共用（Spec §11.1 P0）
+export function likeMatch(name: string, pattern: string): boolean {
+  const re = new RegExp("^" + pattern.split("").map((ch) =>
+    ch === "%" ? ".*" : ch === "_" ? "." : ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("") + "$", "i");
+  return re.test(name);
+}
+
+export function filterTables<T extends { name: string; schema?: string }>(tables: T[], pattern?: string): T[] {
+  if (!pattern) return tables;
+  return tables.filter((t) => likeMatch(t.name, pattern) || (t.schema ? likeMatch(t.schema, pattern) : false));
+}

package/src/dialects/dm.ts

@@ -0,0 +1,159 @@
+// src/dialects/dm.ts
+import dmdb from "dmdb";
+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 DM_DEFAULT_PORT = 5236;
+const JDBC_RE = /^jdbc:dm:\/\/([^:/?#]+)(?::(\d+))?\/([^?#]+)$/;
+const NATIVE_RE = /^dm:\/\/([^:/?#@]+)(?::(\d+))?\/([^?#]+)$/;
+
+function parseDmUrl(url: string): ParsedTarget | null {
+  const clean = url.split("?")[0];
+  const m = clean.match(JDBC_RE) ?? clean.match(NATIVE_RE);
+  if (!m) return null;
+  const host = m[1];
+  const port = m[2] ? parseInt(m[2], 10) : DM_DEFAULT_PORT;
+  const database = m[3];
+  if (!host || !database) return null;
+  return { host, port, database };
+}
+
+// ── DM（达梦）方言 ─────────────────────────────────
+// 注：dmdb 为官方 JS 驱动（API 仿 oracledb），macOS ARM64 已验证可安装加载
+// （见 Task 9 spike）。DM9 兼容性未验证（Spec §12：仅声明测过 DM8）。
+
+class DmDialect extends RelationalDialect {
+  id = "dm" as const;
+  label = "DM";
+  family = "relational" as const;
+  defaultPort = DM_DEFAULT_PORT;
+  fingerprints: Fingerprints = {
+    urlPatterns: [/^jdbc:dm:\/\//, /^dm:\/\//],
+    configKeys: ["spring.datasource.url"],
+  };
+
+  parseUrl(url: string): ParsedTarget | null {
+    return parseDmUrl(url);
+  }
+
+  displayUrl(config: ConnConfig): string {
+    return `jdbc:dm://${config.host}:${config.port}/${config.database}`;
+  }
+
+  protected async doConnect(config: ConnConfig, _timeoutMs: number): Promise<DbConnection> {
+    const conn = await dmdb.getConnection({
+      user: config.username,
+      password: config.password,
+      connectString: `${config.host}:${config.port}`,
+      schema: config.database,
+    });
+    return {
+      type: "dm",
+      client: conn,
+      async close() { await conn.close(); },
+    };
+  }
+
+  protected async doExecute(client: unknown, stmt: string, opts: ExecOpts): Promise<{ columns: string[]; rows: unknown[][]; rowCount: number }> {
+    const dmConn = client as dmdb.Connection;
+    const maxRows = opts.maxRows;
+    const res = await dmConn.execute(stmt, [], {
+      maxRows,
+      fetchArraySize: maxRows,
+    });
+    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 dmConn = conn.client as dmdb.Connection;
+    const res = await dmConn.execute("SELECT * FROM V$VERSION");
+    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 dmConn = conn.client as dmdb.Connection;
+        const res = await dmConn.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', 'SYSDBA', 'SYSSSO', 'CTISYS')
+           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 dmConn = conn.client as dmdb.Connection;
+        const res = await dmConn.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', 'SYSDBA', 'SYSSSO', 'CTISYS')
+          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 dmConn.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 dmDialect = new DmDialect();
+register(dmDialect);

package/src/dialects/elasticsearch.ts

@@ -0,0 +1,219 @@
+// dialects/elasticsearch.ts —— Elasticsearch 方言（SearchDialect + v7/v8 双客户端分发）
+import { Client as ClientV8 } from "@elastic/elasticsearch";
+import { Client as ClientV7 } from "es7";
+import type { ConnConfig, DbConnection, ExecOpts, ParsedTarget,
+  TestConnectionResult, ListTablesResult, DescribeTableResult,
+  TableInfo, ColumnInfo } from "../core/types.js";
+import { SearchDialect, type DslKind } from "./search-dialect.js";
+import { register, filterTables, type Fingerprints } from "./dialect.js";
+
+// ── URL 解析：http(s)://host:port（认证走账号/密码字段，API Key 二期）───
+const ES_RE = /^(https?):\/\/([^:/?#@]+)(?::(\d+))?(\/.*)?$/;
+
+function parseEsUrl(url: string): ParsedTarget | null {
+  const clean = url.split("?")[0].replace(/\/+$/, "");
+  const m = clean.match(ES_RE);
+  if (!m) return null;
+  const host = m[2];
+  const defaultPort = m[1] === "https" ? 443 : 9200;
+  const port = m[3] ? parseInt(m[3], 10) : defaultPort;
+  const ssl = m[1] === "https";
+  if (!host) return null;
+  return { host, port, ssl };
+}
+
+/** 从 `version.number`（如 "7.17.0"）取大版本号 */
+export function pickMajor(versionNumber: string): number {
+  const major = parseInt(versionNumber.split(".")[0], 10);
+  return Number.isNaN(major) ? 0 : major;
+}
+
+type AnyClient = ClientV8 | ClientV7;
+
+function makeClient(config: ConnConfig, ClientClass: new (opts: Record<string, unknown>) => AnyClient): AnyClient {
+  const scheme = (config.port === 443 || config.options?.scheme === "https") ? "https" : "http";
+  const node = `${scheme}://${config.host ?? "localhost"}:${config.port ?? 9200}`;
+  const opts: Record<string, unknown> = { node, requestTimeout: 30_000 };
+  if (config.username) {
+    opts.auth = { username: config.username, password: config.password ?? "" };
+  }
+  return new ClientClass(opts);
+}
+
+class ElasticsearchDialect extends SearchDialect {
+  id = "elasticsearch" as const;
+  label = "Elasticsearch";
+  family = "search" as const;
+  defaultPort = 9200;
+  fingerprints: Fingerprints = {
+    urlPatterns: [/^https?:\/\/[^/]*:9200/],
+    configKeys: ["spring.elasticsearch.uris", "spring.data.elasticsearch.client.reactive.endpoints", "spring.data.elasticsearch.uris"],
+  };
+
+  parseUrl(url: string): ParsedTarget | null {
+    return parseEsUrl(url);
+  }
+
+  displayUrl(config: ConnConfig): string {
+    const scheme = (config.port === 443 || config.options?.scheme === "https") ? "https" : "http";
+    return `${scheme}://${config.host}:${config.port}`;
+  }
+
+  protected async doConnect(config: ConnConfig, timeoutMs: number): Promise<DbConnection> {
+    // 先用"最新客户端"做无版本探测 GET /（testConnection 与 withConnection 共用）；
+    // GET / 返回 version.number 后按大版本分发（详见 testConnection）
+    const probe = makeClient(config, ClientV8 as unknown as new (opts: Record<string, unknown>) => AnyClient);
+    try {
+      const info = await (probe as ClientV8).info();
+      const versionNumber = (info as unknown as { version?: { number?: string } }).version?.number ?? "";
+      const major = pickMajor(versionNumber);
+      if (major === 7) {
+        const v7 = makeClient(config, ClientV7 as unknown as new (opts: Record<string, unknown>) => AnyClient);
+        return { type: "elasticsearch", client: v7, async close() { await v7.close(); } };
+      }
+      // 8 及未知更高大版本：一律用最新客户端尝试（未知版本不硬拒，warning 由 testConnection 给出）
+      return { type: "elasticsearch", client: probe, async close() { await probe.close(); } };
+    } catch (err: unknown) {
+      try { await probe.close(); } catch { /* ignore */ }
+      throw err;
+    }
+  }
+
+  async versionQuery(conn: DbConnection): Promise<string> {
+    // 连接建立时已做版本探测，这里复用一次 GET / 取完整版本号
+    const client = conn.client as ClientV8;
+    const info = await client.info();
+    return (info as unknown as { version?: { number?: string } }).version?.number ?? "unknown";
+  }
+
+  // testConnection 复写基类：同时返回服务端版本号 + 未知大版本的 warning（Spec §12）
+  async testConnection(config: ConnConfig): Promise<TestConnectionResult> {
+    const start = Date.now();
+    try {
+      const probe = makeClient(config, ClientV8 as unknown as new (opts: Record<string, unknown>) => AnyClient);
+      let versionNumber = "";
+      try {
+        const info = await (probe as ClientV8).info();
+        versionNumber = (info as unknown as { version?: { number?: string } }).version?.number ?? "";
+      } finally {
+        try { await probe.close(); } catch { /* ignore */ }
+      }
+      const major = pickMajor(versionNumber);
+      if (major !== 7 && major !== 8) {
+        // 未知/更高大版本：用最新客户端建连验证 + 版本警告（不硬拒）
+        const version = await this.withConnection(config, (conn) => this.versionQuery(conn));
+        return { success: true, version, latency: `${Date.now() - start}ms`, warning: `未识别的 ES 大版本（${versionNumber || "unknown"}），已用最新客户端尝试，结果可能不准确` };
+      }
+      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` };
+    }
+  }
+
+  protected async doSearch(client: unknown, config: ConnConfig, sql: string, kind: DslKind, opts: ExecOpts): Promise<{ columns: string[]; rows: unknown[][]; rowCount: number }> {
+    const es = client as ClientV8;
+    const index = config.database;
+    if (!index) throw new Error("ES 连接缺少默认 index（database 字段）");
+    // 注：DSL 需整体透传为 body——kind 只做分类，原文从 sql 取（JSON.parse 失败即 query_string，已在上游分支处理）
+    const body = kind.type === "read" && kind.endpoint === "_search"
+      ? (JSON.parse(sql) as Record<string, unknown>)
+      : undefined;
+    if (kind.type === "query_string") {
+      const res = await es.search({ index, size: opts.maxRows, q: kind.text });
+      return hitsToRows(res);
+    }
+    if (kind.type === "read") {
+      if (kind.endpoint === "_count") {
+        const res = await es.count({ index });
+        const count = (res as unknown as { count?: number }).count ?? 0;
+        return { columns: ["count"], rows: [[count]], rowCount: count };
+      }
+      if (kind.endpoint === "_mget") {
+        const res = await es.mget({ index, body: { docs: [] } });
+        return docsToRows(res);
+      }
+      // _search：DSL 整体即 body
+      const res = await es.search({ index, body, size: opts.maxRows });
+      return hitsToRows(res);
+    }
+    throw new Error(`ES 写端点 ${kind.endpoint} 需走非只读确认流程执行，本方言 executeOn 仅执行读查询`);
+  }
+
+  // listTables → cat.indices（名称/健康/文档数/大小）
+  async listTables(config: ConnConfig, pattern?: string): Promise<ListTablesResult> {
+    try {
+      const tables: TableInfo[] = await this.withConnection(config, async (conn) => {
+        const es = conn.client as ClientV8;
+        const res = await es.cat.indices({ format: "json", h: "index,health,docs.count,store.size", s: "index" });
+        const rows = (res as unknown as Array<Record<string, string>>).slice(0, 500);
+        return filterTables(rows.map((r) => ({
+          schema: "",
+          name: r["index"] ?? "",
+          type: "INDEX",
+          description: `健康:${r["health"] ?? "?"} 文档数:${r["docs.count"] ?? "?"} 大小:${r["store.size"] ?? "?"}`,
+        })), pattern);
+      });
+      return { success: true, tables, count: tables.length };
+    } catch (err: unknown) {
+      return { success: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  }
+
+  // describeTable → getMapping + getSettings（字段/类型/可搜索性 + 分片副本）
+  async describeTable(config: ConnConfig, target: string): Promise<DescribeTableResult> {
+    if (!target.trim()) {
+      return { success: false, error: "index 名不能为空" };
+    }
+    try {
+      const columns: ColumnInfo[] = await this.withConnection(config, async (conn) => {
+        const es = conn.client as ClientV8;
+        const mappingRes = await es.indices.getMapping({ index: target });
+        const settingsRes = await es.indices.getSettings({ index: target });
+        const mapping = mappingRes as unknown as Record<string, { mappings?: { properties?: Record<string, { type?: string; index?: boolean; analyzer?: string }> } }>;
+        const props = mapping[target]?.mappings?.properties ?? {};
+        const settings = settingsRes as unknown as Record<string, { settings?: { index?: Record<string, string> } }>;
+        const idxSettings = settings[target]?.settings?.index ?? {};
+        const cols: ColumnInfo[] = Object.entries(props).map(([name, def]) => ({
+          name,
+          type: def.type ?? "object",
+          nullable: true,
+          default: null,
+          primaryKey: false,
+          comment: def.index === false ? "不可搜索" : (def.analyzer ? `analyzer:${def.analyzer}` : ""),
+        }));
+        cols.push({
+          name: "_settings",
+          type: "meta",
+          nullable: true,
+          default: null,
+          primaryKey: false,
+          comment: `分片:${idxSettings["number_of_shards"] ?? "?"} 副本:${idxSettings["number_of_replicas"] ?? "?"}`,
+        });
+        return cols;
+      });
+      return { success: true, columns, count: columns.length };
+    } catch (err: unknown) {
+      return { success: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  }
+}
+
+// ── 结果转换 ──────────────────────────────
+function hitsToRows(res: unknown): { columns: string[]; rows: unknown[][]; rowCount: number } {
+  const body = res as { hits?: { total?: number | { value?: number }; hits?: Array<{ _id?: string; _source?: unknown }> } };
+  const hits = body.hits?.hits ?? [];
+  const total = typeof body.hits?.total === "number" ? body.hits.total : (body.hits?.total?.value ?? hits.length);
+  const rows = hits.map((h) => [h._id, typeof h._source === "object" ? JSON.stringify(h._source) : h._source]);
+  return { columns: ["_id", "_source"], rows, rowCount: typeof total === "number" ? total : hits.length };
+}
+
+function docsToRows(res: unknown): { columns: string[]; rows: unknown[][]; rowCount: number } {
+  const body = res as { docs?: Array<{ _id?: string; _source?: unknown; found?: boolean }> };
+  const docs = body.docs ?? [];
+  const rows = docs.map((d) => [d._id, d.found ? JSON.stringify(d._source) : "not found"]);
+  return { columns: ["_id", "_source"], rows, rowCount: rows.length };
+}
+
+export const esDialect = new ElasticsearchDialect();
+register(esDialect);