@nsyan/db 1.0.0

package/src/dialects/postgresql.ts

@@ -0,0 +1,168 @@
+// src/dialects/postgresql.ts
+import pg from "pg";
+import type { ConnConfig, DbConnection, ExecOpts, ParsedTarget,
+  ListTablesResult, DescribeTableResult } 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:postgresql:\/\/([^:/?#]+)(?::(\d+))?\/([^?#]+).*$/;
+const NATIVE_RE = /^postgresql:\/\/(?:([^:/?#@]+)(?::([^/?#@]*))?@)?([^:/?#]+)(?::(\d+))?\/([^?#]+).*$/;
+
+function parsePostgresUrl(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) : 5432;
+    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) : 5432;
+    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;
+}
+
+// ── PostgreSQL 方言（逻辑从 src/db.ts 原样搬入）───
+
+class PostgresqlDialect extends RelationalDialect {
+  id = "postgresql" as const;
+  label = "PostgreSQL";
+  family = "relational" as const;
+  defaultPort = 5432;
+  fingerprints: Fingerprints = {
+    urlPatterns: [/^jdbc:postgresql:\/\//, /^postgresql:\/\//],
+    configKeys: ["spring.datasource.url"],
+  };
+
+  parseUrl(url: string): ParsedTarget | null {
+    return parsePostgresUrl(url);
+  }
+
+  displayUrl(config: ConnConfig): string {
+    return `jdbc:postgresql://${config.host}:${config.port}/${config.database}`;
+  }
+
+  protected async doConnect(config: ConnConfig, _timeoutMs: number): Promise<DbConnection> {
+    const client = new pg.Client({
+      host: config.host,
+      port: config.port,
+      user: config.username,
+      password: config.password,
+      database: config.database,
+    });
+    await client.connect();
+    return {
+      type: "postgresql",
+      client,
+      async close() { await client.end(); },
+    };
+  }
+
+  protected async doExecute(client: unknown, stmt: string, opts: ExecOpts): Promise<{ columns: string[]; rows: unknown[][]; rowCount: number }> {
+    const pgClient = client as pg.Client;
+    const timeoutMs = opts.timeoutSec * 1000;
+    const maxRows = opts.maxRows;
+    // 设置 statement_timeout
+    await pgClient.query(`SET statement_timeout = '${timeoutMs}'`);
+    const res = await pgClient.query(stmt);
+    if (res.fields && res.fields.length > 0) {
+      const columns = res.fields.map((f: any) => f.name);
+      const rows = res.rows.slice(0, maxRows).map((r: any) => columns.map((col: string) => r[col]));
+      return { columns, rows, rowCount: res.rows.length };
+    }
+    return { columns: [], rows: [], rowCount: res.rowCount ?? 0 };
+  }
+
+  async versionQuery(conn: DbConnection): Promise<string> {
+    const pgClient = conn.client as pg.Client;
+    const res = await pgClient.query("SELECT version()");
+    return res.rows[0].version.split(",")[0].trim();
+  }
+
+  async listTables(config: ConnConfig, pattern?: string): Promise<ListTablesResult> {
+    try {
+      const tables = await this.withConnection(config, async (conn) => {
+        const pgClient = conn.client as pg.Client;
+        const res = await pgClient.query(`
+          SELECT schemaname, tablename, obj_description(c.oid) AS description
+          FROM pg_catalog.pg_tables t
+          JOIN pg_catalog.pg_class c ON c.relname = t.tablename AND c.relnamespace = (
+            SELECT oid FROM pg_catalog.pg_namespace WHERE nspname = t.schemaname
+          )
+          WHERE schemaname NOT IN ('pg_catalog', 'information_schema')
+          ORDER BY schemaname, tablename
+        `);
+        const all = res.rows.map((r: any) => ({
+          schema: r.schemaname,
+          name: r.tablename,
+          type: "TABLE",
+          description: r.description || "",
+        }));
+        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 = await this.withConnection(config, async (conn) => {
+        const pgClient = conn.client as pg.Client;
+        const parts = table.split(".");
+        const schema = parts.length === 2 ? parts[0] : "public";
+        const tableName = parts.length === 2 ? parts[1] : table;
+        const res = await pgClient.query(`
+          SELECT
+            a.attname AS name,
+            pg_catalog.format_type(a.atttypid, a.atttypmod) AS type,
+            NOT a.attnotnull AS nullable,
+            COALESCE(pg_catalog.pg_get_expr(ad.adbin, ad.adrelid), '') AS default_val,
+            COALESCE(ct.contype = 'p', FALSE) AS primary_key,
+            COALESCE(cd.description, '') AS comment
+          FROM pg_catalog.pg_attribute a
+          LEFT JOIN pg_catalog.pg_attrdef ad ON a.attrelid = ad.adrelid AND a.attnum = ad.adnum
+          LEFT JOIN pg_catalog.pg_description cd ON a.attrelid = cd.objoid AND a.attnum = cd.objsubid
+          LEFT JOIN pg_catalog.pg_constraint ct ON a.attrelid = ct.conrelid
+              AND ct.contype = 'p' AND a.attnum = ANY(ct.conkey)
+          WHERE a.attrelid = (
+            SELECT c.oid FROM pg_catalog.pg_class c
+            JOIN pg_catalog.pg_namespace n ON c.relnamespace = n.oid
+            WHERE c.relname = $1 AND n.nspname = $2
+          ) AND a.attnum > 0 AND NOT a.attisdropped
+          ORDER BY a.attnum
+        `, [tableName, schema]);
+        return res.rows.map((r: any) => ({
+          name: r.name,
+          type: r.type,
+          nullable: r.nullable,
+          default: r.default_val || null,
+          primaryKey: r.primary_key,
+          comment: r.comment,
+        }));
+      });
+      return { success: true, columns, count: columns.length };
+    } catch (err: unknown) {
+      return { success: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  }
+}
+
+export const postgresqlDialect = new PostgresqlDialect();
+register(postgresqlDialect);

package/src/dialects/redis.ts

@@ -0,0 +1,190 @@
+// dialects/redis.ts —— Redis 方言（KvDialect + ioredis）
+import Redis from "ioredis";
+import type { ConnConfig, DbConnection, ParsedTarget,
+  ListTablesResult, DescribeTableResult, TableInfo } from "../core/types.js";
+import { KvDialect } from "./kv-dialect.js";
+import { register, filterTables, type Fingerprints } from "./dialect.js";
+
+// ── URL 解析：redis(s)://[:password@]host:port[/db] ───
+const REDIS_RE = /^(rediss?):\/\/(?:[^/@]*@)?([^:/?#@]+)(?::(\d+))?(?:\/(\d+))?$/;
+
+function parseRedisUrl(url: string): ParsedTarget | null {
+  const clean = url.split("?")[0];
+  const m = clean.match(REDIS_RE);
+  if (!m) return null;
+  const ssl = m[1] === "rediss";
+  // 密码段（:password@ 或 user:password@）只取 @ 前冒号后部分
+  let password: string | undefined;
+  const atIdx = clean.indexOf("@");
+  if (atIdx >= 0) {
+    const auth = clean.slice(clean.indexOf("://") + 3, atIdx);
+    const colonIdx = auth.indexOf(":");
+    password = colonIdx >= 0 ? auth.slice(colonIdx + 1) : undefined;
+    if (password === "") password = undefined;
+  }
+  const host = m[2];
+  const port = m[3] ? parseInt(m[3], 10) : 6379;
+  const dbIndex = m[4] !== undefined ? parseInt(m[4], 10) : undefined;
+  if (!host) return null;
+  return { host, port, password, dbIndex, ssl };
+}
+
+class RedisDialect extends KvDialect {
+  id = "redis" as const;
+  label = "Redis";
+  family = "kv" as const;
+  defaultPort = 6379;
+  fingerprints: Fingerprints = {
+    urlPatterns: [/^rediss?:\/\//],
+    configKeys: ["spring.data.redis.host", "spring.redis.host", "redisson.address"],
+  };
+
+  parseUrl(url: string): ParsedTarget | null {
+    return parseRedisUrl(url);
+  }
+
+  displayUrl(config: ConnConfig): string {
+    const scheme = "redis";
+    const port = config.port ?? 6379;
+    const db = config.dbIndex ?? 0;
+    return `${scheme}://${config.host}:${port}/${db}`;
+  }
+
+  protected async doConnect(config: ConnConfig, timeoutMs: number): Promise<DbConnection> {
+    const client = new Redis({
+      host: config.host ?? "localhost",
+      port: config.port ?? 6379,
+      password: config.password || undefined,
+      db: config.dbIndex ?? 0,
+      lazyConnect: true,
+      connectTimeout: timeoutMs,
+      maxRetriesPerRequest: 1,
+    });
+    await client.connect();
+    if (config.dbIndex !== undefined && config.dbIndex !== 0) {
+      await client.select(config.dbIndex);
+    }
+    return {
+      type: "redis",
+      client,
+      async close() { client.disconnect(); },
+    };
+  }
+
+  protected async doSendCommand(client: unknown, args: string[]): Promise<unknown> {
+    const redis = client as Redis;
+    return redis.sendCommand(new Redis.Command(args[0], args.slice(1)));
+  }
+
+  async versionQuery(conn: DbConnection): Promise<string> {
+    const redis = conn.client as Redis;
+    const info = await redis.info("server");
+    const m = /^redis_version:(.+)$/m.exec(info ?? "");
+    return m ? m[1].trim() : "unknown";
+  }
+
+  // Redis 无表概念 → keyspace 概览：DBSIZE + SCAN 采样≤200 统计各类型 key 数量
+  async listTables(config: ConnConfig, pattern?: string): Promise<ListTablesResult> {
+    try {
+      const tables: TableInfo[] = await this.withConnection(config, async (conn) => {
+        const redis = conn.client as Redis;
+        const total = await redis.dbsize();
+        const typeCounts = new Map<string, number>();
+        let sampled = 0;
+        let cursor = "0";
+        // LIKE（%/_）→ SCAN 通配（*/?），全局替换（String.replace 单次替换是 bug）
+        const matchArgs = pattern ? ["MATCH", pattern.split("").map((ch) => ch === "%" ? "*" : ch === "_" ? "?" : ch).join("")] : [];
+        do {
+          const [next, keys] = await redis.scan(cursor, "COUNT", 100, ...matchArgs);
+          cursor = next;
+          for (const key of keys) {
+            if (sampled >= 200) break;
+            const t = await redis.type(key);
+            typeCounts.set(t, (typeCounts.get(t) ?? 0) + 1);
+            sampled++;
+          }
+        } while (cursor !== "0" && sampled < 200);
+        const rows: TableInfo[] = [...typeCounts.entries()].map(([type, n]) => ({
+          schema: "",
+          name: type,
+          type: "KEYSPACE",
+          description: `采样 ${sampled} 个 key 中该类型约 ${n} 个（共 ${total} 个 key，Redis 无表，用 SCAN 浏览 key）`,
+        }));
+        return rows;
+      });
+      return { success: true, tables, count: tables.length };
+    } catch (err: unknown) {
+      return { success: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  }
+
+  // describeTable(key) → TYPE + 长度 + TTL + MEMORY USAGE（≥4.0 失败跳过）+ OBJECT ENCODING + 值预览
+  async describeTable(config: ConnConfig, key: string): Promise<DescribeTableResult> {
+    if (!key.trim()) {
+      return { success: false, error: "key 不能为空" };
+    }
+    try {
+      const columns = await this.withConnection(config, async (conn) => {
+        const redis = conn.client as Redis;
+        const exists = await redis.exists(key);
+        if (!exists) throw new Error(`key 不存在: ${key}`);
+        const type = await redis.type(key);
+        const ttl = await redis.ttl(key);
+        // 长度命令按类型分发
+        const lengthCmd: Record<string, string[]> = {
+          string: ["STRLEN", key],
+          list: ["LLEN", key],
+          set: ["SCARD", key],
+          hash: ["HLEN", key],
+          zset: ["ZCARD", key],
+        };
+        let length = "";
+        if (lengthCmd[type]) {
+          try {
+            length = String(await redis.sendCommand(new Redis.Command(lengthCmd[type][0], [key])));
+          } catch { /* ignore */ }
+        }
+        // MEMORY USAGE 需 ≥4.0，低版本失败时降级跳过
+        let memory = "";
+        try {
+          memory = String(await redis.sendCommand(new Redis.Command("MEMORY", ["USAGE", key])));
+        } catch { /* ignore */ }
+        // OBJECT ENCODING 服务 key 探测
+        let encoding = "";
+        try {
+          encoding = String(await redis.sendCommand(new Redis.Command("OBJECT", ["ENCODING", key])));
+        } catch { /* ignore */ }
+        // 值预览（截断）
+        let preview = "";
+        try {
+          if (type === "string") {
+            preview = String(await redis.get(key) ?? "").slice(0, 200);
+          } else if (type === "hash") {
+            preview = JSON.stringify(await redis.hgetall(key)).slice(0, 200);
+          } else if (type === "list") {
+            preview = JSON.stringify(await redis.lrange(key, 0, 9)).slice(0, 200);
+          } else if (type === "set") {
+            preview = JSON.stringify(await redis.smembers(key)).slice(0, 200);
+          } else if (type === "zset") {
+            preview = JSON.stringify(await redis.zrange(key, 0, 9, "WITHSCORES")).slice(0, 200);
+          }
+        } catch { /* ignore */ }
+        return [
+          { name: "key", type: "string", nullable: false, default: null, primaryKey: true, comment: "" },
+          { name: "type", type: "string", nullable: false, default: type, primaryKey: false, comment: "" },
+          { name: "length", type: "integer", nullable: true, default: length || null, primaryKey: false, comment: "按类型取 STRLEN/LLEN/SCARD/HLEN/ZCARD" },
+          { name: "ttl", type: "integer", nullable: false, default: String(ttl), primaryKey: false, comment: "-1=持久 -2=不存在（此处已确认存在）" },
+          { name: "memory_usage", type: "integer", nullable: true, default: memory || null, primaryKey: false, comment: "需 Redis ≥4.0，低版本为空" },
+          { name: "encoding", type: "string", nullable: true, default: encoding || null, primaryKey: false, comment: "OBJECT ENCODING" },
+          { name: "preview", type: "string", nullable: true, default: preview || null, primaryKey: false, comment: "值预览（截断 200 字符）" },
+        ];
+      });
+      return { success: true, columns, count: columns.length };
+    } catch (err: unknown) {
+      return { success: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  }
+}
+
+export const redisDialect = new RedisDialect();
+register(redisDialect);

package/src/dialects/relational-dialect.ts

@@ -0,0 +1,76 @@
+// src/dialects/relational-dialect.ts
+import type { ConnConfig, DbConnection, ExecOpts, ParsedTarget } from "../core/types.js";
+import type { QueryResult } from "../core/types.js";
+import { splitStatements, isWriteStatement, isDropStatement } from "../core/sql-text.js";
+import type { Dialect, Verdict, Fingerprints } from "./dialect.js";
+
+export abstract class RelationalDialect 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>;
+  // 注：doExecute 直接收驱动 client（unknown），各方言内部收窄为私有连接类型
+  protected abstract doExecute(client: unknown, stmt: string, opts: ExecOpts): Promise<{ columns: string[]; rows: unknown[][]; rowCount: number }>;
+
+  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(); }
+  }
+
+  // testConnection 复用 withConnection（连接泄漏防护）；versionQuery 由各方言实现
+
+  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} 条语句）`;
+    if (readonly) {
+      for (const s of stmts) {
+        if (isWriteStatement(s)) {
+          return { ok: false, reason: `只读模式下不允许执行非查询语句：${s.slice(0, 80)}`, isWrite: true, summary };
+        }
+      }
+    }
+    const isWrite = stmts.some(isWriteStatement);
+    return { ok: true, isWrite, summary };
+  }
+
+  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 };
+      await this.withConnection(config, async (conn) => {
+        for (const s of stmts) last = await this.doExecute(conn.client, s, opts);
+      }, opts.timeoutSec * 1000);
+      return { success: true, ...last, 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 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>;
+}

package/src/dialects/search-dialect.ts

@@ -0,0 +1,128 @@
+// dialects/search-dialect.ts —— 搜索家族基类（DSL 解析、端点白名单 verdict）
+// 注：搜索交互是"发 DSL JSON、拿文档结果"，与关系型/KV 的语句·命令语义不同，独立成基类
+
+import type { ConnConfig, DbConnection, ExecOpts, ParsedTarget,
+  QueryResult } from "../core/types.js";
+import type { Dialect, Verdict, Fingerprints } from "./dialect.js";
+
+// ── DSL 解封（Spec §4.3 DSL 信封约定）───
+// JSON 顶层 key 映射端点：query/count→读（_search/_count）；mget/mget_docs→读（_mget）；
+// bulk/doc_write/delete/update/mapping/settings→写；非 JSON 纯字符串→query_string 简化搜索
+export type DslKind =
+  | { type: "read"; endpoint: "_search" | "_count" | "_mget"; detail: string }
+  | { type: "write"; endpoint: string; detail: string }
+  | { type: "query_string"; text: string };
+
+const READ_KEYS: Record<string, "_search" | "_count" | "_mget"> = {
+  query: "_search",
+  count: "_count",
+  mget: "_mget",
+  mget_docs: "_mget",
+};
+
+const WRITE_KEYS = ["bulk", "doc_write", "delete", "update", "mapping", "settings"];
+
+// `DELETE <index>` 纯字符串形式（删索引）恒拒——大小写不敏感、前导空白容忍
+const DELETE_INDEX_RE = /^\s*DELETE\s+\S+/i;
+
+export function parseDsl(input: string): DslKind {
+  const trimmed = input.trim();
+  try {
+    const body = JSON.parse(trimmed) as Record<string, unknown>;
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+      return { type: "query_string", text: trimmed };
+    }
+    const keys = Object.keys(body);
+    for (const k of keys) {
+      const ep = READ_KEYS[k.toLowerCase()];
+      if (ep) return { type: "read", endpoint: ep, detail: describeDetail(body) };
+    }
+    for (const k of keys) {
+      if (WRITE_KEYS.includes(k.toLowerCase())) {
+        return { type: "write", endpoint: k, detail: describeDetail(body) };
+      }
+    }
+    // JSON 但无已知信封 key——保守按写处理（未知操作的写意图不可排除）
+    return { type: "write", endpoint: keys[0] ?? "unknown", detail: describeDetail(body) };
+  } catch {
+    return { type: "query_string", text: trimmed };
+  }
+}
+
+function describeDetail(body: Record<string, unknown>): string {
+  const keys = Object.keys(body);
+  const first = keys[0] ?? "";
+  const sub = body[first];
+  if (sub !== null && typeof sub === "object" && !Array.isArray(sub)) {
+    const subKeys = Object.keys(sub as Record<string, unknown>);
+    if (subKeys.length > 0) return `${first}/${subKeys[0]}`;
+  }
+  return first;
+}
+
+export abstract class SearchDialect 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>;
+  // 注：doSearch 直接收驱动 client（unknown），各方言内部收窄为私有客户端类型
+  protected abstract doSearch(client: unknown, config: ConnConfig, sql: string, kind: DslKind, opts: ExecOpts): Promise<{ columns: string[]; rows: unknown[][]; rowCount: number }>;
+
+  isAllowed(sql: string, readonly: boolean): Verdict {
+    const trimmed = sql.trim();
+    if (!trimmed) return { ok: false, reason: "查询内容为空" };
+    // DELETE <index> 纯字符串形式恒拒（与只读开关无关）
+    if (DELETE_INDEX_RE.test(trimmed)) {
+      return { ok: false, reason: `禁止删除索引：${trimmed.slice(0, 80)}`, isWrite: true, summary: `DELETE 索引（硬限制）: ${trimmed.slice(0, 40)}` };
+    }
+    const kind = parseDsl(trimmed);
+    if (kind.type === "query_string") {
+      const summary = `SEARCH（query_string 简化搜索）`;
+      return { ok: true, isWrite: false, summary };
+    }
+    if (kind.type === "read") {
+      const summary = `SEARCH（${kind.endpoint}/${kind.detail || "match"}）`;
+      return { ok: true, isWrite: false, summary };
+    }
+    // 写端点
+    const summary = `SEARCH（${kind.endpoint}/${kind.detail || "write"}）`;
+    if (readonly) {
+      return { ok: false, reason: `只读模式下不允许执行写端点：${kind.endpoint}`, isWrite: true, summary };
+    }
+    return { ok: true, isWrite: true, summary };
+  }
+
+  async executeOn(config: ConnConfig, sql: string, opts: ExecOpts): Promise<QueryResult> {
+    const start = Date.now();
+    const kind = parseDsl(sql.trim());
+    try {
+      const last = await this.withConnection(config, (conn) => this.doSearch(conn.client, config, sql, kind, opts), opts.timeoutSec * 1000);
+      return { success: true, ...last, 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>;
+}

package/src/dialects/spark.ts

@@ -0,0 +1,120 @@
+// src/dialects/spark.ts —— Spark 方言（Spark Thrift Server，同 HS2 协议栈）
+// 与 Hive 共享 BigDataDialect 基类；差异：写关键字 +CACHE|REFRESH|UNCACHE、
+// 会话变量前缀 spark.、DESCRIBE 输出列差异适配。Spark Connect（DataFrame/gRPC）
+// 明确不支持（Spec §1 非目标）。
+// 注：hive-driver 无 default export（见 hive.ts），用 namespace import。
+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";
+
+const HIVE2_RE = /^jdbc:hive2:\/\/([^:/?#]+)(?::(\d+))?\/([^?#]*)$/;
+const DEFAULT_PORT = 10000; // Spark Thrift Server 默认 10000（部分发行版 10015，可配）
+
+function parseSparkUrl(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 buildSparkSessionConfig(config: ConnConfig): Record<string, string> {
+  const vars: Record<string, string> = {};
+  for (const [k, v] of Object.entries(config.options ?? {})) {
+    const key = k.startsWith("spark.") ? k : `spark.${k}`;
+    vars[key] = v;
+  }
+  return vars;
+}
+
+class SparkDialect extends BigDataDialect {
+  id = "spark" as const;
+  label = "Spark";
+  family = "bigdata" as const;
+  defaultPort = DEFAULT_PORT;
+  fingerprints: Fingerprints = {
+    urlPatterns: [/^jdbc:hive2:\/\//],
+    configKeys: ["spring.datasource.url"],
+  };
+  // Hive 集 + SparkSQL 特有：CACHE|REFRESH|UNCACHE
+  protected writeKeywords = /\b(INSERT\s+(INTO|OVERWRITE)|CREATE\s+TABLE(\s+AS)?|LOAD\s+DATA|MSCK|ALTER|DROP|CACHE\s+TABLE|UNCACHE\s+TABLE|REFRESH(\s+TABLE|\s+RESOURCE|\s+CACHE)?)\b/i;
+  protected sessionPrefix = "spark.";
+
+  parseUrl(url: string): ParsedTarget | null {
+    return parseSparkUrl(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 = buildSparkSessionConfig(config);
+    if (config.database) configuration["spark.sql.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: "spark",
+      client: hs2session,
+      async close() {
+        try { await session.close(); } catch { /* ignore */ }
+        client.close();
+      },
+    };
+  }
+
+  async versionQuery(conn: DbConnection): Promise<string> {
+    const session = conn.client as Hs2Session;
+    return this.fetchVersion(session);
+  }
+
+  // DESCRIBE TABLE → col_name/data_type/comment；Spark 输出含 # Partition Information 等段，遇 # 段即停
+  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 TABLE ${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 sparkDialect = new SparkDialect();
+register(sparkDialect);