@deepagents/text2sql 0.7.0 → 0.8.0

package/dist/lib/adapters/mysql/index.js

@@ -0,0 +1,1597 @@
+// packages/text2sql/src/lib/adapters/groundings/context.ts
+function createGroundingContext() {
+  return {
+    tables: [],
+    views: [],
+    relationships: [],
+    info: void 0
+  };
+}
+
+// packages/text2sql/src/lib/adapters/adapter.ts
+var Adapter = class {
+  async introspect(ctx = createGroundingContext()) {
+    const lines = [];
+    for (const fn of this.grounding) {
+      const grounding = fn(this);
+      lines.push({
+        tag: grounding.tag,
+        fn: await grounding.execute(ctx)
+      });
+    }
+    return lines.map(({ fn, tag }) => {
+      const description = fn();
+      if (description === null) {
+        return "";
+      }
+      return `<${tag}>
+${description}
+</${tag}>`;
+    }).join("\n");
+  }
+  /**
+   * Convert unknown database value to number.
+   * Handles number, bigint, and string types.
+   */
+  toNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+    if (typeof value === "bigint") {
+      return Number(value);
+    }
+    if (typeof value === "string" && value.trim() !== "") {
+      const parsed = Number(value);
+      return Number.isFinite(parsed) ? parsed : void 0;
+    }
+    return void 0;
+  }
+  /**
+   * Parse a potentially qualified table name into schema and table parts.
+   */
+  parseTableName(name) {
+    if (name.includes(".")) {
+      const [schema, ...rest] = name.split(".");
+      return { schema, table: rest.join(".") };
+    }
+    return { schema: this.defaultSchema ?? "", table: name };
+  }
+  /**
+   * Escape a string value for use in SQL string literals (single quotes).
+   * Used in WHERE clauses like: WHERE name = '${escapeString(value)}'
+   */
+  escapeString(value) {
+    return value.replace(/'/g, "''");
+  }
+  /**
+   * Build a SQL filter clause to include/exclude schemas.
+   * @param columnName - The schema column name (e.g., 'TABLE_SCHEMA')
+   * @param allowedSchemas - If provided, filter to these schemas only
+   */
+  buildSchemaFilter(columnName, allowedSchemas) {
+    if (allowedSchemas && allowedSchemas.length > 0) {
+      const values = allowedSchemas.map((s) => `'${this.escapeString(s)}'`).join(", ");
+      return `AND ${columnName} IN (${values})`;
+    }
+    if (this.systemSchemas.length > 0) {
+      const values = this.systemSchemas.map((s) => `'${this.escapeString(s)}'`).join(", ");
+      return `AND ${columnName} NOT IN (${values})`;
+    }
+    return "";
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/abstract.grounding.ts
+var AbstractGrounding = class {
+  tag;
+  constructor(tag) {
+    this.tag = tag;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/column-stats.grounding.ts
+var ColumnStatsGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("column_stats");
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates columns in ctx.tables and ctx.views with statistics.
+   */
+  async execute(ctx) {
+    const allContainers = [...ctx.tables, ...ctx.views];
+    for (const container of allContainers) {
+      for (const column of container.columns) {
+        try {
+          const stats = await this.collectStats(container.name, column);
+          if (stats) {
+            column.stats = stats;
+          }
+        } catch (error) {
+          console.warn(
+            "Error collecting stats for",
+            container.name,
+            column.name,
+            error
+          );
+        }
+      }
+    }
+    return () => this.#describe();
+  }
+  #describe() {
+    return null;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/column-values.grounding.ts
+var ColumnValuesGrounding = class extends AbstractGrounding {
+  lowCardinalityLimit;
+  constructor(config = {}) {
+    super("column_values");
+    this.lowCardinalityLimit = config.lowCardinalityLimit ?? 20;
+  }
+  /**
+   * Get values for native ENUM type columns.
+   * Return undefined if column is not an ENUM type.
+   * Default implementation returns undefined (no native ENUM support).
+   */
+  async collectEnumValues(_tableName, _column) {
+    return void 0;
+  }
+  /**
+   * Parse CHECK constraint for enum-like IN clause.
+   * Extracts values from patterns like:
+   * - CHECK (status IN ('active', 'inactive'))
+   * - CHECK ((status)::text = ANY (ARRAY['a'::text, 'b'::text]))
+   * - CHECK (status = 'active' OR status = 'inactive')
+   */
+  parseCheckConstraint(constraint, columnName) {
+    if (constraint.type !== "CHECK" || !constraint.definition) {
+      return void 0;
+    }
+    if (constraint.columns && !constraint.columns.includes(columnName)) {
+      return void 0;
+    }
+    const def = constraint.definition;
+    const escapedCol = this.escapeRegex(columnName);
+    const colPattern = `(?:\\(?\\(?${escapedCol}\\)?(?:::(?:text|varchar|character varying))?\\)?)`;
+    const inMatch = def.match(
+      new RegExp(`${colPattern}\\s+IN\\s*\\(([^)]+)\\)`, "i")
+    );
+    if (inMatch) {
+      return this.extractStringValues(inMatch[1]);
+    }
+    const anyMatch = def.match(
+      new RegExp(
+        `${colPattern}\\s*=\\s*ANY\\s*\\(\\s*(?:ARRAY)?\\s*\\[([^\\]]+)\\]`,
+        "i"
+      )
+    );
+    if (anyMatch) {
+      return this.extractStringValues(anyMatch[1]);
+    }
+    const orPattern = new RegExp(
+      `\\b${this.escapeRegex(columnName)}\\b\\s*=\\s*'([^']*)'`,
+      "gi"
+    );
+    const orMatches = [...def.matchAll(orPattern)];
+    if (orMatches.length >= 2) {
+      return orMatches.map((m) => m[1]);
+    }
+    return void 0;
+  }
+  /**
+   * Extract string values from a comma-separated list.
+   */
+  extractStringValues(input) {
+    const values = [];
+    const matches = input.matchAll(/'([^']*)'/g);
+    for (const match of matches) {
+      values.push(match[1]);
+    }
+    return values.length > 0 ? values : void 0;
+  }
+  /**
+   * Escape special regex characters in a string.
+   */
+  escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  }
+  /**
+   * Get the table from context by name.
+   */
+  getTable(ctx, name) {
+    return ctx.tables.find((t) => t.name === name);
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates columns in ctx.tables and ctx.views with values.
+   */
+  async execute(ctx) {
+    const allContainers = [...ctx.tables, ...ctx.views];
+    for (const container of allContainers) {
+      const table = this.getTable(ctx, container.name);
+      for (const column of container.columns) {
+        try {
+          const result = await this.resolveColumnValues(
+            container.name,
+            column,
+            table?.constraints
+          );
+          if (result) {
+            column.kind = result.kind;
+            column.values = result.values;
+          }
+        } catch (error) {
+          console.warn(
+            "Error collecting column values for",
+            container.name,
+            column.name,
+            error
+          );
+        }
+      }
+    }
+    return () => this.#describe();
+  }
+  /**
+   * Resolve column values from all sources in priority order.
+   */
+  async resolveColumnValues(tableName, column, constraints2) {
+    const enumValues = await this.collectEnumValues(tableName, column);
+    if (enumValues?.length) {
+      return { kind: "Enum", values: enumValues };
+    }
+    if (constraints2) {
+      for (const constraint of constraints2) {
+        const checkValues = this.parseCheckConstraint(constraint, column.name);
+        if (checkValues?.length) {
+          return { kind: "Enum", values: checkValues };
+        }
+      }
+    }
+    const lowCardValues = await this.collectLowCardinality(tableName, column);
+    if (lowCardValues?.length) {
+      return { kind: "LowCardinality", values: lowCardValues };
+    }
+    return void 0;
+  }
+  #describe() {
+    return null;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/constraint.grounding.ts
+var ConstraintGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("constraints");
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates tables in ctx.tables with their constraints.
+   */
+  async execute(ctx) {
+    for (const table of ctx.tables) {
+      try {
+        table.constraints = await this.getConstraints(table.name);
+      } catch (error) {
+        console.warn("Error collecting constraints for", table.name, error);
+      }
+    }
+    return () => null;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/indexes.grounding.ts
+var IndexesGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("indexes");
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates tables in ctx.tables with their indexes and marks indexed columns.
+   */
+  async execute(ctx) {
+    for (const table of ctx.tables) {
+      table.indexes = await this.getIndexes(table.name);
+      for (const index of table.indexes ?? []) {
+        for (const colName of index.columns) {
+          const column = table.columns.find((c) => c.name === colName);
+          if (column) {
+            column.isIndexed = true;
+          }
+        }
+      }
+    }
+    return () => null;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/info.grounding.ts
+var InfoGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("dialect_info");
+  }
+  /**
+   * Execute the grounding process.
+   * Writes database info to ctx.info.
+   */
+  async execute(ctx) {
+    ctx.info = await this.collectInfo();
+    const lines = [`Dialect: ${ctx.info.dialect ?? "unknown"}`];
+    if (ctx.info.version) {
+      lines.push(`Version: ${ctx.info.version}`);
+    }
+    if (ctx.info.database) {
+      lines.push(`Database: ${ctx.info.database}`);
+    }
+    if (ctx.info.details && Object.keys(ctx.info.details).length) {
+      lines.push(`Details: ${JSON.stringify(ctx.info.details)}`);
+    }
+    return () => lines.join("\n");
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/report.grounding.ts
+import { groq } from "@ai-sdk/groq";
+import { tool } from "ai";
+import dedent from "dedent";
+import z from "zod";
+import {
+  agent,
+  generate,
+  toState,
+  user
+} from "@deepagents/agent";
+var ReportGrounding = class extends AbstractGrounding {
+  #adapter;
+  #model;
+  #cache;
+  #forceRefresh;
+  constructor(adapter, config = {}) {
+    super("business_context");
+    this.#adapter = adapter;
+    this.#model = config.model ?? groq("openai/gpt-oss-20b");
+    this.#cache = config.cache;
+    this.#forceRefresh = config.forceRefresh ?? false;
+  }
+  async execute(ctx) {
+    if (!this.#forceRefresh && this.#cache) {
+      const cached = await this.#cache.get();
+      if (cached) {
+        ctx.report = cached;
+        return () => cached;
+      }
+    }
+    const report2 = await this.#generateReport();
+    ctx.report = report2;
+    if (this.#cache) {
+      await this.#cache.set(report2);
+    }
+    return () => report2;
+  }
+  async #generateReport() {
+    const reportAgent = agent({
+      name: "db-report-agent",
+      model: this.#model,
+      prompt: () => dedent`
+        <identity>
+          You are a database analyst expert. Your job is to understand what
+          a database represents and provide business context about it.
+          You have READ-ONLY access to the database.
+        </identity>
+
+        <instructions>
+          Write a business context that helps another agent answer questions accurately.
+
+          For EACH table, do queries ONE AT A TIME:
+          1. SELECT COUNT(*) to get row count
+          2. SELECT * LIMIT 3 to see sample data
+
+          Then write a report with:
+          - What business this database is for
+          - For each table: purpose, row count, and example of what the data looks like
+
+          Include concrete examples like "Track prices are $0.99",
+          "Customer names like 'Luís Gonçalves'", etc.
+
+          Keep it 400-600 words, conversational style.
+        </instructions>
+      `,
+      tools: {
+        query_database: tool({
+          description: "Execute a SELECT query to explore the database and gather insights.",
+          inputSchema: z.object({
+            sql: z.string().describe("The SELECT query to execute"),
+            purpose: z.string().describe(
+              "What insight you are trying to gather with this query"
+            )
+          }),
+          execute: ({ sql }, options) => {
+            const state = toState(options);
+            return state.adapter.execute(sql);
+          }
+        })
+      }
+    });
+    const { text } = await generate(
+      reportAgent,
+      [
+        user(
+          "Please analyze the database and write a contextual report about what this database represents."
+        )
+      ],
+      { adapter: this.#adapter }
+    );
+    return text;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/row-count.grounding.ts
+var RowCountGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("row_counts");
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates tables in ctx.tables with row counts and size hints.
+   */
+  async execute(ctx) {
+    for (const table of ctx.tables) {
+      const count = await this.getRowCount(table.name);
+      if (count != null) {
+        table.rowCount = count;
+        table.sizeHint = this.#classifyRowCount(count);
+      }
+    }
+    return () => null;
+  }
+  /**
+   * Classify row count into a size hint category.
+   */
+  #classifyRowCount(count) {
+    if (count < 100) return "tiny";
+    if (count < 1e3) return "small";
+    if (count < 1e4) return "medium";
+    if (count < 1e5) return "large";
+    return "huge";
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/table.grounding.ts
+import pluralize from "pluralize";
+var TableGrounding = class extends AbstractGrounding {
+  #filter;
+  #forward;
+  #backward;
+  constructor(config = {}) {
+    super("tables");
+    this.#filter = config.filter;
+    this.#forward = config.forward;
+    this.#backward = config.backward;
+  }
+  /**
+   * Execute the grounding process.
+   * Writes discovered tables and relationships to the context.
+   */
+  async execute(ctx) {
+    const seedTables = await this.applyFilter();
+    const forward = this.#forward;
+    const backward = this.#backward;
+    if (!forward && !backward) {
+      const tables3 = await Promise.all(
+        seedTables.map((name) => this.getTable(name))
+      );
+      ctx.tables.push(...tables3);
+      return () => this.#describeTables(tables3);
+    }
+    const tables2 = {};
+    const allRelationships = [];
+    const seenRelationships = /* @__PURE__ */ new Set();
+    const forwardQueue = [];
+    const backwardQueue = [];
+    const forwardVisited = /* @__PURE__ */ new Set();
+    const backwardVisited = /* @__PURE__ */ new Set();
+    for (const name of seedTables) {
+      if (forward) forwardQueue.push({ name, depth: 0 });
+      if (backward) backwardQueue.push({ name, depth: 0 });
+    }
+    const forwardLimit = forward === true ? Infinity : forward || 0;
+    while (forwardQueue.length > 0) {
+      const item = forwardQueue.shift();
+      if (!item) break;
+      const { name, depth } = item;
+      if (forwardVisited.has(name)) continue;
+      forwardVisited.add(name);
+      if (!tables2[name]) {
+        tables2[name] = await this.getTable(name);
+      }
+      if (depth < forwardLimit) {
+        const rels = await this.findOutgoingRelations(name);
+        for (const rel of rels) {
+          this.addRelationship(rel, allRelationships, seenRelationships);
+          if (!forwardVisited.has(rel.referenced_table)) {
+            forwardQueue.push({ name: rel.referenced_table, depth: depth + 1 });
+          }
+        }
+      }
+    }
+    const backwardLimit = backward === true ? Infinity : backward || 0;
+    while (backwardQueue.length > 0) {
+      const item = backwardQueue.shift();
+      if (!item) break;
+      const { name, depth } = item;
+      if (backwardVisited.has(name)) continue;
+      backwardVisited.add(name);
+      if (!tables2[name]) {
+        tables2[name] = await this.getTable(name);
+      }
+      if (depth < backwardLimit) {
+        const rels = await this.findIncomingRelations(name);
+        for (const rel of rels) {
+          this.addRelationship(rel, allRelationships, seenRelationships);
+          if (!backwardVisited.has(rel.table)) {
+            backwardQueue.push({ name: rel.table, depth: depth + 1 });
+          }
+        }
+      }
+    }
+    const tablesList = Object.values(tables2);
+    ctx.tables.push(...tablesList);
+    ctx.relationships.push(...allRelationships);
+    return () => this.#describeTables(tablesList);
+  }
+  /**
+   * Apply the filter to get seed table names.
+   * If filter is an explicit array, skip querying all table names.
+   */
+  async applyFilter() {
+    const filter = this.#filter;
+    if (Array.isArray(filter)) {
+      return filter;
+    }
+    const names = await this.getAllTableNames();
+    if (!filter) {
+      return names;
+    }
+    if (filter instanceof RegExp) {
+      return names.filter((name) => filter.test(name));
+    }
+    return names.filter(filter);
+  }
+  /**
+   * Add a relationship to the collection, deduplicating by key.
+   */
+  addRelationship(rel, all, seen) {
+    const key = `${rel.table}:${rel.from.join(",")}:${rel.referenced_table}:${rel.to.join(",")}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      all.push(rel);
+    }
+  }
+  #describeTables(tables2) {
+    if (!tables2.length) {
+      return "Schema unavailable.";
+    }
+    return tables2.map((table) => {
+      const rowCountInfo = table.rowCount != null ? ` [rows: ${table.rowCount}${table.sizeHint ? `, size: ${table.sizeHint}` : ""}]` : "";
+      const pkConstraint = table.constraints?.find(
+        (c) => c.type === "PRIMARY_KEY"
+      );
+      const pkColumns = new Set(pkConstraint?.columns ?? []);
+      const notNullColumns = new Set(
+        table.constraints?.filter((c) => c.type === "NOT_NULL").flatMap((c) => c.columns ?? []) ?? []
+      );
+      const defaultByColumn = /* @__PURE__ */ new Map();
+      for (const c of table.constraints?.filter(
+        (c2) => c2.type === "DEFAULT"
+      ) ?? []) {
+        for (const col of c.columns ?? []) {
+          if (c.defaultValue != null) {
+            defaultByColumn.set(col, c.defaultValue);
+          }
+        }
+      }
+      const uniqueColumns = new Set(
+        table.constraints?.filter((c) => c.type === "UNIQUE" && c.columns?.length === 1).flatMap((c) => c.columns ?? []) ?? []
+      );
+      const fkByColumn = /* @__PURE__ */ new Map();
+      for (const c of table.constraints?.filter(
+        (c2) => c2.type === "FOREIGN_KEY"
+      ) ?? []) {
+        const cols = c.columns ?? [];
+        const refCols = c.referencedColumns ?? [];
+        for (let i = 0; i < cols.length; i++) {
+          const refCol = refCols[i] ?? refCols[0] ?? cols[i];
+          fkByColumn.set(cols[i], `${c.referencedTable}.${refCol}`);
+        }
+      }
+      const columns = table.columns.map((column) => {
+        const annotations = [];
+        const isPrimaryKey = pkColumns.has(column.name);
+        if (isPrimaryKey) {
+          annotations.push("PK");
+        }
+        if (fkByColumn.has(column.name)) {
+          annotations.push(`FK -> ${fkByColumn.get(column.name)}`);
+        }
+        if (uniqueColumns.has(column.name)) {
+          annotations.push("UNIQUE");
+        }
+        if (notNullColumns.has(column.name)) {
+          annotations.push("NOT NULL");
+        }
+        if (defaultByColumn.has(column.name)) {
+          annotations.push(`DEFAULT: ${defaultByColumn.get(column.name)}`);
+        }
+        if (column.isIndexed && !isPrimaryKey) {
+          annotations.push("Indexed");
+        }
+        if (column.kind === "Enum" && column.values?.length) {
+          annotations.push(`Enum: ${column.values.join(", ")}`);
+        } else if (column.kind === "LowCardinality" && column.values?.length) {
+          annotations.push(`LowCardinality: ${column.values.join(", ")}`);
+        }
+        if (column.stats) {
+          const statParts = [];
+          if (column.stats.min != null || column.stats.max != null) {
+            const minText = column.stats.min ?? "n/a";
+            const maxText = column.stats.max ?? "n/a";
+            statParts.push(`range ${minText} \u2192 ${maxText}`);
+          }
+          if (column.stats.nullFraction != null && Number.isFinite(column.stats.nullFraction)) {
+            const percent = Math.round(column.stats.nullFraction * 1e3) / 10;
+            statParts.push(`null\u2248${percent}%`);
+          }
+          if (statParts.length) {
+            annotations.push(statParts.join(", "));
+          }
+        }
+        const annotationText = annotations.length ? ` [${annotations.join(", ")}]` : "";
+        return `    - ${column.name} (${column.type})${annotationText}`;
+      }).join("\n");
+      const indexes2 = table.indexes?.length ? `
+  Indexes:
+${table.indexes.map((index) => {
+        const props = [];
+        if (index.unique) {
+          props.push("UNIQUE");
+        }
+        if (index.type) {
+          props.push(index.type);
+        }
+        const propsText = props.length ? ` (${props.join(", ")})` : "";
+        const columnsText = index.columns?.length ? index.columns.join(", ") : "expression";
+        return `    - ${index.name}${propsText}: ${columnsText}`;
+      }).join("\n")}` : "";
+      const multiColumnUniques = table.constraints?.filter(
+        (c) => c.type === "UNIQUE" && (c.columns?.length ?? 0) > 1
+      ) ?? [];
+      const uniqueConstraints = multiColumnUniques.length ? `
+  Unique Constraints:
+${multiColumnUniques.map((c) => `    - ${c.name}: (${c.columns?.join(", ")})`).join("\n")}` : "";
+      const checkConstraints = table.constraints?.filter((c) => c.type === "CHECK") ?? [];
+      const checks = checkConstraints.length ? `
+  Check Constraints:
+${checkConstraints.map((c) => `    - ${c.name}: ${c.definition}`).join("\n")}` : "";
+      return `- Table: ${table.name}${rowCountInfo}
+  Columns:
+${columns}${indexes2}${uniqueConstraints}${checks}`;
+    }).join("\n\n");
+  }
+  #formatTableLabel = (tableName) => {
+    const base = tableName.split(".").pop() ?? tableName;
+    return base.replace(/_/g, " ");
+  };
+  #describeRelationships = (tables2, relationships) => {
+    if (!relationships.length) {
+      return "None detected";
+    }
+    const tableMap = new Map(tables2.map((table) => [table.name, table]));
+    return relationships.map((relationship) => {
+      const sourceLabel = this.#formatTableLabel(relationship.table);
+      const targetLabel = this.#formatTableLabel(
+        relationship.referenced_table
+      );
+      const singularSource = pluralize.singular(sourceLabel);
+      const pluralSource = pluralize.plural(sourceLabel);
+      const singularTarget = pluralize.singular(targetLabel);
+      const pluralTarget = pluralize.plural(targetLabel);
+      const sourceTable = tableMap.get(relationship.table);
+      const targetTable = tableMap.get(relationship.referenced_table);
+      const sourceCount = sourceTable?.rowCount;
+      const targetCount = targetTable?.rowCount;
+      const ratio = sourceCount != null && targetCount != null && targetCount > 0 ? sourceCount / targetCount : null;
+      let cardinality = "each";
+      if (ratio != null) {
+        if (ratio > 5) {
+          cardinality = `many-to-one (\u2248${sourceCount} vs ${targetCount})`;
+        } else if (ratio < 1.2 && ratio > 0.8) {
+          cardinality = `roughly 1:1 (${sourceCount} vs ${targetCount})`;
+        } else if (ratio < 0.2) {
+          cardinality = `one-to-many (${sourceCount} vs ${targetCount})`;
+        }
+      }
+      const mappings = relationship.from.map((fromCol, idx) => {
+        const targetCol = relationship.to[idx] ?? relationship.to[0] ?? fromCol;
+        return `${relationship.table}.${fromCol} -> ${relationship.referenced_table}.${targetCol}`;
+      }).join(", ");
+      return `- ${relationship.table} (${relationship.from.join(", ")}) -> ${relationship.referenced_table} (${relationship.to.join(", ")}) [${cardinality}]`;
+    }).join("\n");
+  };
+};
+
+// packages/text2sql/src/lib/adapters/mysql/column-stats.mysql.grounding.ts
+var MysqlColumnStatsGrounding = class extends ColumnStatsGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async collectStats(tableName, column) {
+    if (!this.#shouldCollectStats(column.type)) {
+      return void 0;
+    }
+    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const database = schema || await this.#getCurrentDatabase();
+    const tableIdentifier = `${this.#adapter.quoteIdentifier(database)}.${this.#adapter.quoteIdentifier(table)}`;
+    const columnIdentifier = this.#adapter.quoteIdentifier(column.name);
+    try {
+      const rows = await this.#adapter.runQuery(`
+        SELECT
+          CAST(MIN(${columnIdentifier}) AS CHAR) AS min_value,
+          CAST(MAX(${columnIdentifier}) AS CHAR) AS max_value,
+          AVG(CASE WHEN ${columnIdentifier} IS NULL THEN 1.0 ELSE 0.0 END) AS null_fraction
+        FROM ${tableIdentifier}
+      `);
+      if (!rows.length) {
+        return void 0;
+      }
+      const min = rows[0]?.min_value ?? void 0;
+      const max = rows[0]?.max_value ?? void 0;
+      const nullFraction = this.#toNumber(rows[0]?.null_fraction);
+      if (min == null && max == null && nullFraction == null) {
+        return void 0;
+      }
+      return {
+        min,
+        max,
+        nullFraction: nullFraction != null && Number.isFinite(nullFraction) ? Math.max(0, Math.min(1, nullFraction)) : void 0
+      };
+    } catch {
+      return void 0;
+    }
+  }
+  #shouldCollectStats(type) {
+    if (!type) {
+      return false;
+    }
+    const normalized = type.toLowerCase();
+    return /int|numeric|decimal|double|float|real|date|time|timestamp|datetime|bool|bit|year/.test(
+      normalized
+    );
+  }
+  #toNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+    if (typeof value === "bigint") {
+      return Number(value);
+    }
+    if (typeof value === "string" && value.trim() !== "") {
+      const parsed = Number(value);
+      return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+  }
+  async #getCurrentDatabase() {
+    const rows = await this.#adapter.runQuery(
+      "SELECT DATABASE() AS db"
+    );
+    return rows[0]?.db ?? "";
+  }
+};
+
+// packages/text2sql/src/lib/adapters/mysql/column-values.mysql.grounding.ts
+var MysqlColumnValuesGrounding = class extends ColumnValuesGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  /**
+   * Detect native MySQL ENUM types and extract their values.
+   */
+  async collectEnumValues(tableName, column) {
+    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const database = schema || await this.#getCurrentDatabase();
+    const rows = await this.#adapter.runQuery(`
+      SELECT COLUMN_TYPE
+      FROM INFORMATION_SCHEMA.COLUMNS
+      WHERE TABLE_SCHEMA = '${this.#adapter.escapeString(database)}'
+        AND TABLE_NAME = '${this.#adapter.escapeString(table)}'
+        AND COLUMN_NAME = '${this.#adapter.escapeString(column.name)}'
+    `);
+    const columnType = rows[0]?.COLUMN_TYPE;
+    if (!columnType) return void 0;
+    const enumMatch = columnType.match(/^enum\((.+)\)$/i);
+    if (!enumMatch) return void 0;
+    return this.#parseEnumValues(enumMatch[1]);
+  }
+  /**
+   * Collect distinct values for low cardinality columns.
+   */
+  async collectLowCardinality(tableName, column) {
+    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const database = schema || await this.#getCurrentDatabase();
+    const tableIdentifier = `${this.#adapter.quoteIdentifier(database)}.${this.#adapter.quoteIdentifier(table)}`;
+    const columnIdentifier = this.#adapter.quoteIdentifier(column.name);
+    const limit = this.lowCardinalityLimit + 1;
+    try {
+      const rows = await this.#adapter.runQuery(`
+        SELECT DISTINCT ${columnIdentifier} AS value
+        FROM ${tableIdentifier}
+        WHERE ${columnIdentifier} IS NOT NULL
+        LIMIT ${limit}
+      `);
+      if (!rows.length || rows.length > this.lowCardinalityLimit) {
+        return void 0;
+      }
+      const values = [];
+      for (const row of rows) {
+        const formatted = this.#normalizeValue(row.value);
+        if (formatted === null) {
+          return void 0;
+        }
+        values.push(formatted);
+      }
+      return values.length > 0 ? values : void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  /**
+   * Parse ENUM values from the COLUMN_TYPE string.
+   * Input: "'val1','val2','val3'"
+   * Output: ['val1', 'val2', 'val3']
+   */
+  #parseEnumValues(enumString) {
+    const values = [];
+    const regex = /'((?:[^'\\]|\\.|'')*)'/g;
+    let match;
+    while ((match = regex.exec(enumString)) !== null) {
+      const value = match[1].replace(/''/g, "'").replace(/\\'/g, "'").replace(/\\\\/g, "\\");
+      values.push(value);
+    }
+    return values;
+  }
+  #normalizeValue(value) {
+    if (value === null || value === void 0) {
+      return null;
+    }
+    if (typeof value === "string") {
+      return value;
+    }
+    if (typeof value === "number" || typeof value === "bigint") {
+      return String(value);
+    }
+    if (typeof value === "boolean") {
+      return value ? "true" : "false";
+    }
+    if (value instanceof Date) {
+      return value.toISOString();
+    }
+    if (typeof Buffer !== "undefined" && Buffer.isBuffer(value)) {
+      return value.toString("utf-8");
+    }
+    return null;
+  }
+  async #getCurrentDatabase() {
+    const rows = await this.#adapter.runQuery(
+      "SELECT DATABASE() AS db"
+    );
+    return rows[0]?.db ?? "";
+  }
+};
+
+// packages/text2sql/src/lib/adapters/mysql/constraint.mysql.grounding.ts
+var MysqlConstraintGrounding = class extends ConstraintGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async getConstraints(tableName) {
+    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const database = schema || await this.#getCurrentDatabase();
+    const constraints2 = [];
+    const constraintRows = await this.#adapter.runQuery(`
+      SELECT
+        tc.CONSTRAINT_NAME,
+        tc.CONSTRAINT_TYPE,
+        kcu.COLUMN_NAME,
+        kcu.REFERENCED_TABLE_SCHEMA,
+        kcu.REFERENCED_TABLE_NAME,
+        kcu.REFERENCED_COLUMN_NAME
+      FROM INFORMATION_SCHEMA.TABLE_CONSTRAINTS tc
+      LEFT JOIN INFORMATION_SCHEMA.KEY_COLUMN_USAGE kcu
+        ON tc.CONSTRAINT_NAME = kcu.CONSTRAINT_NAME
+        AND tc.TABLE_SCHEMA = kcu.TABLE_SCHEMA
+        AND tc.TABLE_NAME = kcu.TABLE_NAME
+      WHERE tc.TABLE_SCHEMA = '${this.#adapter.escapeString(database)}'
+        AND tc.TABLE_NAME = '${this.#adapter.escapeString(table)}'
+        AND tc.CONSTRAINT_TYPE IN ('PRIMARY KEY', 'UNIQUE', 'FOREIGN KEY')
+      ORDER BY tc.CONSTRAINT_NAME, kcu.ORDINAL_POSITION
+    `);
+    const constraintMap = /* @__PURE__ */ new Map();
+    for (const row of constraintRows) {
+      if (!row.CONSTRAINT_NAME || !row.COLUMN_NAME) continue;
+      const existing = constraintMap.get(row.CONSTRAINT_NAME);
+      if (existing) {
+        existing.columns.push(row.COLUMN_NAME);
+        if (row.REFERENCED_COLUMN_NAME) {
+          existing.referencedColumns = existing.referencedColumns ?? [];
+          existing.referencedColumns.push(row.REFERENCED_COLUMN_NAME);
+        }
+      } else {
+        const type = this.#mapConstraintType(row.CONSTRAINT_TYPE);
+        if (!type) continue;
+        const entry = {
+          type,
+          columns: [row.COLUMN_NAME]
+        };
+        if (type === "FOREIGN_KEY" && row.REFERENCED_TABLE_NAME) {
+          entry.referencedTable = row.REFERENCED_TABLE_SCHEMA ? `${row.REFERENCED_TABLE_SCHEMA}.${row.REFERENCED_TABLE_NAME}` : row.REFERENCED_TABLE_NAME;
+          if (row.REFERENCED_COLUMN_NAME) {
+            entry.referencedColumns = [row.REFERENCED_COLUMN_NAME];
+          }
+        }
+        constraintMap.set(row.CONSTRAINT_NAME, entry);
+      }
+    }
+    for (const [name, data] of constraintMap) {
+      constraints2.push({
+        name,
+        type: data.type,
+        columns: data.columns,
+        referencedTable: data.referencedTable,
+        referencedColumns: data.referencedColumns
+      });
+    }
+    const columnRows = await this.#adapter.runQuery(`
+      SELECT COLUMN_NAME, IS_NULLABLE, COLUMN_DEFAULT
+      FROM INFORMATION_SCHEMA.COLUMNS
+      WHERE TABLE_SCHEMA = '${this.#adapter.escapeString(database)}'
+        AND TABLE_NAME = '${this.#adapter.escapeString(table)}'
+    `);
+    const pkConstraint = constraints2.find((c) => c.type === "PRIMARY_KEY");
+    const pkColumns = new Set(pkConstraint?.columns ?? []);
+    for (const row of columnRows) {
+      if (!row.COLUMN_NAME) continue;
+      if (row.IS_NULLABLE === "NO" && !pkColumns.has(row.COLUMN_NAME)) {
+        constraints2.push({
+          name: `${row.COLUMN_NAME}_not_null`,
+          type: "NOT_NULL",
+          columns: [row.COLUMN_NAME]
+        });
+      }
+      if (row.COLUMN_DEFAULT !== null) {
+        constraints2.push({
+          name: `${row.COLUMN_NAME}_default`,
+          type: "DEFAULT",
+          columns: [row.COLUMN_NAME],
+          defaultValue: row.COLUMN_DEFAULT
+        });
+      }
+    }
+    try {
+      const checkRows = await this.#adapter.runQuery(`
+        SELECT CONSTRAINT_NAME, CHECK_CLAUSE
+        FROM INFORMATION_SCHEMA.CHECK_CONSTRAINTS
+        WHERE CONSTRAINT_SCHEMA = '${this.#adapter.escapeString(database)}'
+      `);
+      const checkTableRows = await this.#adapter.runQuery(`
+        SELECT CONSTRAINT_NAME, TABLE_NAME
+        FROM INFORMATION_SCHEMA.TABLE_CONSTRAINTS
+        WHERE TABLE_SCHEMA = '${this.#adapter.escapeString(database)}'
+          AND TABLE_NAME = '${this.#adapter.escapeString(table)}'
+          AND CONSTRAINT_TYPE = 'CHECK'
+      `);
+      const checkTableMap = new Map(
+        checkTableRows.map((r) => [r.CONSTRAINT_NAME, r.TABLE_NAME])
+      );
+      for (const row of checkRows) {
+        if (!row.CONSTRAINT_NAME) continue;
+        if (checkTableMap.get(row.CONSTRAINT_NAME) !== table) continue;
+        constraints2.push({
+          name: row.CONSTRAINT_NAME,
+          type: "CHECK",
+          definition: row.CHECK_CLAUSE ?? void 0
+        });
+      }
+    } catch {
+    }
+    return constraints2;
+  }
+  #mapConstraintType(type) {
+    switch (type) {
+      case "PRIMARY KEY":
+        return "PRIMARY_KEY";
+      case "UNIQUE":
+        return "UNIQUE";
+      case "FOREIGN KEY":
+        return "FOREIGN_KEY";
+      default:
+        return null;
+    }
+  }
+  async #getCurrentDatabase() {
+    const rows = await this.#adapter.runQuery(
+      "SELECT DATABASE() AS db"
+    );
+    return rows[0]?.db ?? "";
+  }
+};
+
+// packages/text2sql/src/lib/adapters/mysql/indexes.mysql.grounding.ts
+var MysqlIndexesGrounding = class extends IndexesGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async getIndexes(tableName) {
+    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const database = schema || await this.#getCurrentDatabase();
+    const rows = await this.#adapter.runQuery(`
+      SELECT
+        INDEX_NAME,
+        COLUMN_NAME,
+        NON_UNIQUE,
+        INDEX_TYPE,
+        SEQ_IN_INDEX
+      FROM INFORMATION_SCHEMA.STATISTICS
+      WHERE TABLE_SCHEMA = '${this.#adapter.escapeString(database)}'
+        AND TABLE_NAME = '${this.#adapter.escapeString(table)}'
+      ORDER BY INDEX_NAME, SEQ_IN_INDEX
+    `);
+    const indexMap = /* @__PURE__ */ new Map();
+    for (const row of rows) {
+      if (!row.INDEX_NAME) continue;
+      let index = indexMap.get(row.INDEX_NAME);
+      if (!index) {
+        index = {
+          name: row.INDEX_NAME,
+          columns: [],
+          unique: row.NON_UNIQUE === 0,
+          type: row.INDEX_TYPE ?? void 0
+        };
+        indexMap.set(row.INDEX_NAME, index);
+      }
+      if (row.COLUMN_NAME) {
+        index.columns.push(row.COLUMN_NAME);
+      }
+    }
+    return Array.from(indexMap.values());
+  }
+  async #getCurrentDatabase() {
+    const rows = await this.#adapter.runQuery(
+      "SELECT DATABASE() AS db"
+    );
+    return rows[0]?.db ?? "";
+  }
+};
+
+// packages/text2sql/src/lib/adapters/mysql/info.mysql.grounding.ts
+var MysqlInfoGrounding = class extends InfoGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async collectInfo() {
+    const [versionRows, dbRows] = await Promise.all([
+      this.#adapter.runQuery(
+        "SELECT VERSION() AS version"
+      ),
+      this.#adapter.runQuery("SELECT DATABASE() AS db")
+    ]);
+    const version = versionRows[0]?.version;
+    const database = dbRows[0]?.db ?? void 0;
+    const isMariadb = version?.toLowerCase().includes("mariadb") ?? false;
+    const dialect = isMariadb ? "mariadb" : "mysql";
+    return {
+      dialect,
+      version,
+      database
+    };
+  }
+};
+
+// packages/text2sql/src/lib/adapters/mysql/mysql.ts
+var MYSQL_ERROR_MAP = {
+  "1146": {
+    type: "MISSING_TABLE",
+    hint: "Check the database for the correct table name. Include the database prefix if necessary."
+  },
+  "1054": {
+    type: "INVALID_COLUMN",
+    hint: "Verify the column exists on the referenced table and use table aliases to disambiguate."
+  },
+  "1064": {
+    type: "SYNTAX_ERROR",
+    hint: "There is a SQL syntax error. Review keywords, punctuation, and the overall query shape."
+  },
+  "1630": {
+    type: "INVALID_FUNCTION",
+    hint: "The function does not exist or the arguments are invalid."
+  },
+  "1305": {
+    type: "INVALID_FUNCTION",
+    hint: "The function or procedure you used is not recognized. Confirm its name and argument types."
+  },
+  "1109": {
+    type: "MISSING_TABLE",
+    hint: "Unknown table in the query. Verify table name and database."
+  },
+  "1051": {
+    type: "MISSING_TABLE",
+    hint: "Unknown table. Check if the table exists in the current database."
+  }
+};
+function isMysqlError(error) {
+  return typeof error === "object" && error !== null && ("errno" in error || "code" in error);
+}
+function formatMysqlError(sql, error) {
+  const errorMessage = error instanceof Error ? error.message : typeof error === "string" ? error : "Unknown error occurred";
+  if (isMysqlError(error)) {
+    const errorCode = error.errno?.toString() ?? error.code ?? "";
+    const metadata = MYSQL_ERROR_MAP[errorCode];
+    if (metadata) {
+      return {
+        error: errorMessage,
+        error_type: metadata.type,
+        suggestion: metadata.hint,
+        sql_attempted: sql
+      };
+    }
+  }
+  return {
+    error: errorMessage,
+    error_type: "UNKNOWN_ERROR",
+    suggestion: "Review the query and try again",
+    sql_attempted: sql
+  };
+}
+var Mysql = class extends Adapter {
+  #options;
+  grounding;
+  defaultSchema = void 0;
+  systemSchemas = [
+    "mysql",
+    "information_schema",
+    "performance_schema",
+    "sys"
+  ];
+  constructor(options) {
+    super();
+    if (!options || typeof options.execute !== "function") {
+      throw new Error("Mysql adapter requires an execute function.");
+    }
+    this.#options = {
+      ...options,
+      databases: options.databases?.length ? options.databases : void 0
+    };
+    this.grounding = options.grounding;
+  }
+  async execute(sql) {
+    return this.#options.execute(sql);
+  }
+  async validate(sql) {
+    const validator = this.#options.validate ?? (async (text) => {
+      await this.#options.execute(`EXPLAIN ${text}`);
+    });
+    try {
+      return await validator(sql);
+    } catch (error) {
+      return JSON.stringify(formatMysqlError(sql, error));
+    }
+  }
+  async runQuery(sql) {
+    return this.#runIntrospectionQuery(sql);
+  }
+  quoteIdentifier(name) {
+    return `\`${name.replace(/`/g, "``")}\``;
+  }
+  escape(value) {
+    return value.replace(/`/g, "``");
+  }
+  buildSampleRowsQuery(tableName, columns, limit) {
+    const { schema, table } = this.parseTableName(tableName);
+    const tableIdentifier = schema ? `${this.quoteIdentifier(schema)}.${this.quoteIdentifier(table)}` : this.quoteIdentifier(table);
+    const columnList = columns?.length ? columns.map((c) => this.quoteIdentifier(c)).join(", ") : "*";
+    return `SELECT ${columnList} FROM ${tableIdentifier} LIMIT ${limit}`;
+  }
+  /**
+   * Get the configured databases filter.
+   */
+  get databases() {
+    return this.#options.databases;
+  }
+  async #runIntrospectionQuery(sql) {
+    const result = await this.#options.execute(sql);
+    if (Array.isArray(result)) {
+      if (result.length >= 1 && Array.isArray(result[0]) && (result.length === 1 || result.length === 2 && !Array.isArray(result[1]?.[0]))) {
+        return result[0];
+      }
+      return result;
+    }
+    if (result && typeof result === "object" && "rows" in result && Array.isArray(result.rows)) {
+      return result.rows;
+    }
+    throw new Error(
+      "Mysql adapter execute() must return an array of rows or an object with a rows array when introspecting."
+    );
+  }
+};
+
+// packages/text2sql/src/lib/adapters/mysql/row-count.mysql.grounding.ts
+var MysqlRowCountGrounding = class extends RowCountGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async getRowCount(tableName) {
+    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const database = schema || await this.#getCurrentDatabase();
+    const tableIdentifier = `${this.#adapter.quoteIdentifier(database)}.${this.#adapter.quoteIdentifier(table)}`;
+    try {
+      const rows = await this.#adapter.runQuery(`SELECT COUNT(*) AS count FROM ${tableIdentifier}`);
+      return this.#toNumber(rows[0]?.count);
+    } catch {
+      return void 0;
+    }
+  }
+  #toNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+    if (typeof value === "bigint") {
+      return Number(value);
+    }
+    if (typeof value === "string" && value.trim() !== "") {
+      const parsed = Number(value);
+      return Number.isFinite(parsed) ? parsed : void 0;
+    }
+    return void 0;
+  }
+  async #getCurrentDatabase() {
+    const rows = await this.#adapter.runQuery(
+      "SELECT DATABASE() AS db"
+    );
+    return rows[0]?.db ?? "";
+  }
+};
+
+// packages/text2sql/src/lib/adapters/mysql/table.mysql.grounding.ts
+var MysqlTableGrounding = class extends TableGrounding {
+  #adapter;
+  #databases;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+    this.#databases = config.databases ?? adapter.databases;
+  }
+  async getAllTableNames() {
+    const rows = await this.#adapter.runQuery(`
+      SELECT DISTINCT CONCAT(TABLE_SCHEMA, '.', TABLE_NAME) AS name
+      FROM INFORMATION_SCHEMA.TABLES
+      WHERE TABLE_TYPE = 'BASE TABLE'
+        ${this.#buildDatabaseFilter("TABLE_SCHEMA")}
+      ORDER BY name
+    `);
+    return rows.map((r) => r.name);
+  }
+  async getTable(tableName) {
+    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const database = schema || await this.#getCurrentDatabase();
+    const columns = await this.#adapter.runQuery(`
+      SELECT COLUMN_NAME, DATA_TYPE, COLUMN_TYPE
+      FROM INFORMATION_SCHEMA.COLUMNS
+      WHERE TABLE_SCHEMA = '${this.#adapter.escapeString(database)}'
+        AND TABLE_NAME = '${this.#adapter.escapeString(table)}'
+      ORDER BY ORDINAL_POSITION
+    `);
+    return {
+      name: tableName,
+      schema: database,
+      rawName: table,
+      columns: columns.map((col) => ({
+        name: col.COLUMN_NAME ?? "unknown",
+        type: col.DATA_TYPE ?? "unknown"
+      }))
+    };
+  }
+  async findOutgoingRelations(tableName) {
+    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const database = schema || await this.#getCurrentDatabase();
+    const rows = await this.#adapter.runQuery(`
+      SELECT
+        kcu.CONSTRAINT_NAME,
+        kcu.TABLE_SCHEMA,
+        kcu.TABLE_NAME,
+        kcu.COLUMN_NAME,
+        kcu.REFERENCED_TABLE_SCHEMA,
+        kcu.REFERENCED_TABLE_NAME,
+        kcu.REFERENCED_COLUMN_NAME
+      FROM INFORMATION_SCHEMA.KEY_COLUMN_USAGE kcu
+      WHERE kcu.TABLE_SCHEMA = '${this.#adapter.escapeString(database)}'
+        AND kcu.TABLE_NAME = '${this.#adapter.escapeString(table)}'
+        AND kcu.REFERENCED_TABLE_NAME IS NOT NULL
+      ORDER BY kcu.CONSTRAINT_NAME, kcu.ORDINAL_POSITION
+    `);
+    return this.#groupRelationships(rows);
+  }
+  async findIncomingRelations(tableName) {
+    const { schema, table } = this.#adapter.parseTableName(tableName);
+    const database = schema || await this.#getCurrentDatabase();
+    const rows = await this.#adapter.runQuery(`
+      SELECT
+        kcu.CONSTRAINT_NAME,
+        kcu.TABLE_SCHEMA,
+        kcu.TABLE_NAME,
+        kcu.COLUMN_NAME,
+        kcu.REFERENCED_TABLE_SCHEMA,
+        kcu.REFERENCED_TABLE_NAME,
+        kcu.REFERENCED_COLUMN_NAME
+      FROM INFORMATION_SCHEMA.KEY_COLUMN_USAGE kcu
+      WHERE kcu.REFERENCED_TABLE_SCHEMA = '${this.#adapter.escapeString(database)}'
+        AND kcu.REFERENCED_TABLE_NAME = '${this.#adapter.escapeString(table)}'
+      ORDER BY kcu.CONSTRAINT_NAME, kcu.ORDINAL_POSITION
+    `);
+    return this.#groupRelationships(rows);
+  }
+  #groupRelationships(rows) {
+    const relationships = /* @__PURE__ */ new Map();
+    for (const row of rows) {
+      if (!row.TABLE_NAME || !row.REFERENCED_TABLE_NAME || !row.CONSTRAINT_NAME) {
+        continue;
+      }
+      const schema = row.TABLE_SCHEMA ?? "";
+      const referencedSchema = row.REFERENCED_TABLE_SCHEMA ?? "";
+      const key = `${schema}.${row.TABLE_NAME}:${row.CONSTRAINT_NAME}`;
+      const relationship = relationships.get(key) ?? {
+        table: `${schema}.${row.TABLE_NAME}`,
+        from: [],
+        referenced_table: `${referencedSchema}.${row.REFERENCED_TABLE_NAME}`,
+        to: []
+      };
+      relationship.from.push(row.COLUMN_NAME ?? "unknown");
+      relationship.to.push(row.REFERENCED_COLUMN_NAME ?? "unknown");
+      relationships.set(key, relationship);
+    }
+    return Array.from(relationships.values());
+  }
+  #buildDatabaseFilter(columnName) {
+    if (this.#databases && this.#databases.length > 0) {
+      const values = this.#databases.map((db) => `'${this.#adapter.escapeString(db)}'`).join(", ");
+      return `AND ${columnName} IN (${values})`;
+    }
+    const systemDbs = this.#adapter.systemSchemas.map((db) => `'${this.#adapter.escapeString(db)}'`).join(", ");
+    return `AND ${columnName} NOT IN (${systemDbs})`;
+  }
+  async #getCurrentDatabase() {
+    const rows = await this.#adapter.runQuery(
+      "SELECT DATABASE() AS db"
+    );
+    return rows[0]?.db ?? "";
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/view.grounding.ts
+var ViewGrounding = class extends AbstractGrounding {
+  #filter;
+  constructor(config = {}) {
+    super("views");
+    this.#filter = config.filter;
+  }
+  /**
+   * Execute the grounding process.
+   * Writes discovered views to the context.
+   */
+  async execute(ctx) {
+    const viewNames = await this.applyFilter();
+    const views2 = await Promise.all(
+      viewNames.map((name) => this.getView(name))
+    );
+    ctx.views.push(...views2);
+    return () => this.#describe(views2);
+  }
+  #describe(views2) {
+    if (!views2.length) {
+      return "No views available.";
+    }
+    return views2.map((view) => {
+      const columns = view.columns.map((column) => {
+        const annotations = [];
+        if (column.kind === "LowCardinality" && column.values?.length) {
+          annotations.push(`LowCardinality: ${column.values.join(", ")}`);
+        }
+        if (column.stats) {
+          const statParts = [];
+          if (column.stats.min != null || column.stats.max != null) {
+            const minText = column.stats.min ?? "n/a";
+            const maxText = column.stats.max ?? "n/a";
+            statParts.push(`range ${minText} \u2192 ${maxText}`);
+          }
+          if (column.stats.nullFraction != null && Number.isFinite(column.stats.nullFraction)) {
+            const percent = Math.round(column.stats.nullFraction * 1e3) / 10;
+            statParts.push(`null\u2248${percent}%`);
+          }
+          if (statParts.length) {
+            annotations.push(statParts.join(", "));
+          }
+        }
+        const annotationText = annotations.length ? ` [${annotations.join(", ")}]` : "";
+        return `    - ${column.name} (${column.type})${annotationText}`;
+      }).join("\n");
+      const definition = view.definition ? `
+  Definition: ${view.definition.length > 200 ? view.definition.slice(0, 200) + "..." : view.definition}` : "";
+      return `- View: ${view.name}${definition}
+  Columns:
+${columns}`;
+    }).join("\n\n");
+  }
+  /**
+   * Apply the filter to get view names.
+   * If filter is an explicit array, skip querying all view names.
+   */
+  async applyFilter() {
+    const filter = this.#filter;
+    if (Array.isArray(filter)) {
+      return filter;
+    }
+    const names = await this.getAllViewNames();
+    if (!filter) {
+      return names;
+    }
+    if (filter instanceof RegExp) {
+      return names.filter((name) => filter.test(name));
+    }
+    return names.filter(filter);
+  }
+};
+
+// packages/text2sql/src/lib/adapters/mysql/view.mysql.grounding.ts
+var MysqlViewGrounding = class extends ViewGrounding {
+  #adapter;
+  #databases;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+    this.#databases = config.databases ?? adapter.databases;
+  }
+  async getAllViewNames() {
+    const rows = await this.#adapter.runQuery(`
+      SELECT DISTINCT CONCAT(TABLE_SCHEMA, '.', TABLE_NAME) AS name
+      FROM INFORMATION_SCHEMA.VIEWS
+      WHERE 1=1
+        ${this.#buildDatabaseFilter("TABLE_SCHEMA")}
+      ORDER BY name
+    `);
+    return rows.map((r) => r.name);
+  }
+  async getView(viewName) {
+    const { schema, table } = this.#adapter.parseTableName(viewName);
+    const database = schema || await this.#getCurrentDatabase();
+    const columns = await this.#adapter.runQuery(`
+      SELECT COLUMN_NAME, DATA_TYPE
+      FROM INFORMATION_SCHEMA.COLUMNS
+      WHERE TABLE_SCHEMA = '${this.#adapter.escapeString(database)}'
+        AND TABLE_NAME = '${this.#adapter.escapeString(table)}'
+      ORDER BY ORDINAL_POSITION
+    `);
+    const viewRows = await this.#adapter.runQuery(`
+      SELECT VIEW_DEFINITION
+      FROM INFORMATION_SCHEMA.VIEWS
+      WHERE TABLE_SCHEMA = '${this.#adapter.escapeString(database)}'
+        AND TABLE_NAME = '${this.#adapter.escapeString(table)}'
+    `);
+    return {
+      name: viewName,
+      schema: database,
+      rawName: table,
+      definition: viewRows[0]?.VIEW_DEFINITION ?? void 0,
+      columns: columns.map((col) => ({
+        name: col.COLUMN_NAME ?? "unknown",
+        type: col.DATA_TYPE ?? "unknown"
+      }))
+    };
+  }
+  #buildDatabaseFilter(columnName) {
+    if (this.#databases && this.#databases.length > 0) {
+      const values = this.#databases.map((db) => `'${this.#adapter.escapeString(db)}'`).join(", ");
+      return `AND ${columnName} IN (${values})`;
+    }
+    const systemDbs = this.#adapter.systemSchemas.map((db) => `'${this.#adapter.escapeString(db)}'`).join(", ");
+    return `AND ${columnName} NOT IN (${systemDbs})`;
+  }
+  async #getCurrentDatabase() {
+    const rows = await this.#adapter.runQuery(
+      "SELECT DATABASE() AS db"
+    );
+    return rows[0]?.db ?? "";
+  }
+};
+
+// packages/text2sql/src/lib/adapters/mysql/index.ts
+function tables(config = {}) {
+  return (adapter) => new MysqlTableGrounding(adapter, config);
+}
+function info(config = {}) {
+  return (adapter) => new MysqlInfoGrounding(adapter, config);
+}
+function views(config = {}) {
+  return (adapter) => {
+    return new MysqlViewGrounding(adapter, config);
+  };
+}
+function columnStats(config = {}) {
+  return (adapter) => {
+    return new MysqlColumnStatsGrounding(adapter, config);
+  };
+}
+function columnValues(config = {}) {
+  return (adapter) => {
+    return new MysqlColumnValuesGrounding(adapter, config);
+  };
+}
+function indexes(config = {}) {
+  return (adapter) => {
+    return new MysqlIndexesGrounding(adapter, config);
+  };
+}
+function rowCount(config = {}) {
+  return (adapter) => {
+    return new MysqlRowCountGrounding(adapter, config);
+  };
+}
+function constraints(config = {}) {
+  return (adapter) => {
+    return new MysqlConstraintGrounding(adapter, config);
+  };
+}
+function report(config = {}) {
+  return (adapter) => new ReportGrounding(adapter, config);
+}
+var mysql_default = {
+  tables,
+  info,
+  views,
+  columnStats,
+  columnValues,
+  indexes,
+  rowCount,
+  constraints,
+  report,
+  Mysql,
+  Mariadb: Mysql
+};
+export {
+  Mysql as Mariadb,
+  Mysql,
+  columnStats,
+  columnValues,
+  constraints,
+  mysql_default as default,
+  formatMysqlError,
+  indexes,
+  info,
+  report,
+  rowCount,
+  tables,
+  views
+};
+//# sourceMappingURL=index.js.map