@deepagents/text2sql 7.0.1 → 7.1.0

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

@@ -1,5 +1,6 @@
 // packages/text2sql/src/lib/adapters/adapter.ts
 import { format as formatSql } from "sql-formatter";
+import { z } from "zod";
 
 // packages/text2sql/src/lib/agents/exceptions.ts
 var sqlValidationMarker = /* @__PURE__ */ Symbol("SQLValidationError");
@@ -172,6 +173,16 @@ function createGroundingContext(options = {}) {
 }
 
 // packages/text2sql/src/lib/adapters/adapter.ts
+function groundingFor(adapterType, create) {
+  return (adapter) => {
+    if (!(adapter instanceof adapterType)) {
+      throw new Error(
+        `A ${adapterType.name} grounding needs a ${adapterType.name} adapter, not ${adapter.constructor.name}.`
+      );
+    }
+    return create(adapter);
+  };
+}
 var Adapter = class {
   #policyAnalyzer;
   /**
@@ -432,6 +443,40 @@ var Adapter = class {
     }
     return decoded;
   }
+  /**
+   * Run an introspection query and check every row against `row`, the shape
+   * the driver returns for that query. A row of any other shape throws.
+   */
+  async runQuery(sql, row) {
+    const rows = z.array(row).safeParse(await this.queryRows(sql));
+    if (!rows.success) {
+      throw new Error(
+        `${this.constructor.name} introspection query returned rows of an unexpected shape:
+${z.prettifyError(rows.error)}
+SQL: ${sql.trim()}`,
+        { cause: rows.error }
+      );
+    }
+    return rows.data;
+  }
+  /**
+   * The rows in a driver's execute() result: the result itself when it is an
+   * array, otherwise the first array found at one of `paths` (dot-separated,
+   * so `recordsets.0` reads `result.recordsets[0]`).
+   */
+  rowsFrom(result, paths) {
+    if (Array.isArray(result)) return result;
+    for (const path of paths) {
+      const rows = path.split(".").reduce(
+        (value, key) => typeof value === "object" && value !== null ? Reflect.get(value, key) : void 0,
+        result
+      );
+      if (Array.isArray(rows)) return rows;
+    }
+    throw new Error(
+      `${this.constructor.name} execute() must return an array of rows or an object holding one at ${paths.map((path) => `result.${path}`).join(", ")}.`
+    );
+  }
   /**
    * Convert unknown database value to number.
    * Handles number, bigint, and string types.
@@ -992,6 +1037,35 @@ var TableGrounding = class extends AbstractGrounding {
 };
 
 // packages/text2sql/src/lib/adapters/postgres/column-stats.postgres.grounding.ts
+import { z as z3 } from "zod";
+
+// packages/text2sql/src/lib/adapters/groundings/rows.ts
+import { z as z2 } from "zod";
+var nameRow = z2.object({ name: z2.string() });
+var versionRow = z2.object({ version: z2.string() });
+var databaseRow = z2.object({ db: z2.string() });
+var viewDefinitionRow = z2.object({
+  definition: z2.string().nullable()
+});
+var distinctValueRow = z2.object({ value: z2.unknown() });
+var textValueRow = z2.object({ value: z2.string() });
+var numericValue = z2.union([z2.number(), z2.bigint(), z2.string()]);
+
+// packages/text2sql/src/lib/adapters/postgres/column-stats.postgres.grounding.ts
+var pgStatsRow = z3.object({
+  schemaname: z3.string(),
+  tablename: z3.string(),
+  attname: z3.string(),
+  null_frac: z3.number().nullable(),
+  n_distinct: z3.number().nullable(),
+  histogram_bounds: z3.string().nullable(),
+  correlation: z3.number().nullable()
+});
+var liveStatsRow = z3.object({
+  min_value: z3.string().nullable(),
+  max_value: z3.string().nullable(),
+  null_fraction: numericValue.nullable()
+});
 var PostgresColumnStatsGrounding = class extends ColumnStatsGrounding {
   #adapter;
   #pgStatsCache = /* @__PURE__ */ new Map();
@@ -1010,7 +1084,8 @@ var PostgresColumnStatsGrounding = class extends ColumnStatsGrounding {
       const { schema, table: table2 } = this.#adapter.parseTableName(container.name);
       return `(schemaname = '${this.#adapter.escapeString(schema)}' AND tablename = '${this.#adapter.escapeString(table2)}')`;
     });
-    const rows = await this.#adapter.runQuery(`
+    const rows = await this.#adapter.runQuery(
+      `
       SELECT
         schemaname,
         tablename,
@@ -1021,7 +1096,9 @@ var PostgresColumnStatsGrounding = class extends ColumnStatsGrounding {
         correlation
       FROM pg_stats
       WHERE ${conditions.join(" OR ")}
-    `);
+    `,
+      pgStatsRow
+    );
     for (const row of rows) {
       const tableName = allContainers.find((c) => {
         const { schema, table: table2 } = this.#adapter.parseTableName(c.name);
@@ -1068,13 +1145,16 @@ var PostgresColumnStatsGrounding = class extends ColumnStatsGrounding {
     const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
     const tableIdentifier = `${this.#adapter.quoteIdentifier(schema)}.${this.#adapter.quoteIdentifier(table2)}`;
     const columnIdentifier = this.#adapter.quoteIdentifier(column2.name);
-    const rows = await this.#adapter.runQuery(`
+    const rows = await this.#adapter.runQuery(
+      `
       SELECT
         MIN(${columnIdentifier})::text AS min_value,
         MAX(${columnIdentifier})::text AS max_value,
         AVG(CASE WHEN ${columnIdentifier} IS NULL THEN 1.0 ELSE 0.0 END) AS null_fraction
       FROM ${tableIdentifier}
-    `);
+    `,
+      liveStatsRow
+    );
     if (!rows.length) {
       return void 0;
     }
@@ -1133,6 +1213,17 @@ var PostgresColumnStatsGrounding = class extends ColumnStatsGrounding {
 };
 
 // packages/text2sql/src/lib/adapters/postgres/column-values.postgres.grounding.ts
+import { z as z4 } from "zod";
+var enumValueRow = z4.object({
+  type_name: z4.string(),
+  type_schema: z4.string(),
+  enum_value: z4.string()
+});
+var columnTypeRow = z4.object({
+  udt_name: z4.string(),
+  udt_schema: z4.string()
+});
+var textValueRow2 = z4.object({ value: z4.string().nullable() });
 var PostgresColumnValuesGrounding = class extends ColumnValuesGrounding {
   #adapter;
   #enumCache = /* @__PURE__ */ new Map();
@@ -1149,7 +1240,8 @@ var PostgresColumnValuesGrounding = class extends ColumnValuesGrounding {
     if (this.#enumCacheLoaded) {
       return;
     }
-    const rows = await this.#adapter.runQuery(`
+    const rows = await this.#adapter.runQuery(
+      `
       SELECT
         t.typname AS type_name,
         n.nspname AS type_schema,
@@ -1158,7 +1250,9 @@ var PostgresColumnValuesGrounding = class extends ColumnValuesGrounding {
       JOIN pg_enum e ON t.oid = e.enumtypid
       JOIN pg_namespace n ON n.oid = t.typnamespace
       ORDER BY t.typname, e.enumsortorder
-    `);
+    `,
+      enumValueRow
+    );
     for (const row of rows) {
       const key = `${row.type_schema}.${row.type_name}`;
       const existing = this.#enumCache.get(key) ?? [];
@@ -1177,13 +1271,16 @@ var PostgresColumnValuesGrounding = class extends ColumnValuesGrounding {
     }
     await this.#loadEnumCache();
     const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
-    const rows = await this.#adapter.runQuery(`
+    const rows = await this.#adapter.runQuery(
+      `
       SELECT udt_name, udt_schema
       FROM information_schema.columns
       WHERE table_schema = '${this.#adapter.escapeString(schema)}'
         AND table_name = '${this.#adapter.escapeString(table2)}'
         AND column_name = '${this.#adapter.escapeString(column2.name)}'
-    `);
+    `,
+      columnTypeRow
+    );
     if (!rows.length) {
       return void 0;
     }
@@ -1206,7 +1303,7 @@ var PostgresColumnValuesGrounding = class extends ColumnValuesGrounding {
       WHERE ${columnIdentifier} IS NOT NULL
       LIMIT ${limit}
     `;
-    const rows = await this.#adapter.runQuery(sql);
+    const rows = await this.#adapter.runQuery(sql, textValueRow2);
     if (!rows.length || rows.length > this.lowCardinalityLimit) {
       return void 0;
     }
@@ -1228,6 +1325,21 @@ var PostgresColumnValuesGrounding = class extends ColumnValuesGrounding {
 };
 
 // packages/text2sql/src/lib/adapters/postgres/constraint.postgres.grounding.ts
+import { z as z5 } from "zod";
+var constraintRow = z5.object({
+  constraint_name: z5.string(),
+  constraint_type: z5.string(),
+  definition: z5.string().nullable(),
+  column_name: z5.string().nullable(),
+  ref_schema: z5.string().nullable(),
+  ref_table: z5.string().nullable(),
+  ref_column: z5.string().nullable()
+});
+var columnDefaultRow = z5.object({
+  column_name: z5.string(),
+  column_default: z5.string().nullable(),
+  is_nullable: z5.string()
+});
 var PostgresConstraintGrounding = class extends ConstraintGrounding {
   #adapter;
   constructor(adapter, config = {}) {
@@ -1237,7 +1349,8 @@ var PostgresConstraintGrounding = class extends ConstraintGrounding {
   async getConstraints(tableName) {
     const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
     const constraints2 = [];
-    const constraintRows = await this.#adapter.runQuery(`
+    const constraintRows = await this.#adapter.runQuery(
+      `
       SELECT
         con.conname AS constraint_name,
         con.contype AS constraint_type,
@@ -1259,7 +1372,9 @@ var PostgresConstraintGrounding = class extends ConstraintGrounding {
         AND rel.relname = '${this.#adapter.escapeString(table2)}'
         AND con.contype IN ('p', 'f', 'c', 'u')
       ORDER BY con.conname, key.ord
-    `);
+    `,
+      constraintRow
+    );
     const constraintMap = /* @__PURE__ */ new Map();
     for (const row of constraintRows) {
       const existing = constraintMap.get(row.constraint_name);
@@ -1312,7 +1427,8 @@ var PostgresConstraintGrounding = class extends ConstraintGrounding {
         });
       }
     }
-    const columnRows = await this.#adapter.runQuery(`
+    const columnRows = await this.#adapter.runQuery(
+      `
       SELECT
         column_name,
         column_default,
@@ -1320,7 +1436,9 @@ var PostgresConstraintGrounding = class extends ConstraintGrounding {
       FROM information_schema.columns
       WHERE table_schema = '${this.#adapter.escapeString(schema)}'
         AND table_name = '${this.#adapter.escapeString(table2)}'
-    `);
+    `,
+      columnDefaultRow
+    );
     for (const col of columnRows) {
       const pkConstraint = constraints2.find((c) => c.type === "PRIMARY_KEY");
       const isPkColumn = pkConstraint?.columns?.includes(col.column_name);
@@ -1345,17 +1463,24 @@ var PostgresConstraintGrounding = class extends ConstraintGrounding {
 };
 
 // packages/text2sql/src/lib/adapters/postgres/indexes.postgres.grounding.ts
+import { z as z6 } from "zod";
+var indexRow = z6.object({
+  index_name: z6.string(),
+  column_name: z6.string(),
+  is_unique: z6.boolean(),
+  index_type: z6.string(),
+  column_position: z6.number()
+});
 var PostgresIndexesGrounding = class extends IndexesGrounding {
   #adapter;
-  #schemas;
   constructor(adapter, config = {}) {
     super(config);
     this.#adapter = adapter;
-    this.#schemas = config.schemas;
   }
   async getIndexes(tableName) {
     const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
-    const rows = await this.#adapter.runQuery(`
+    const rows = await this.#adapter.runQuery(
+      `
       SELECT
         i.relname AS index_name,
         a.attname AS column_name,
@@ -1371,7 +1496,9 @@ var PostgresIndexesGrounding = class extends IndexesGrounding {
       WHERE n.nspname = '${this.#adapter.escapeString(schema)}'
         AND t.relname = '${this.#adapter.escapeString(table2)}'
       ORDER BY i.relname, array_position(ix.indkey, a.attnum)
-    `);
+    `,
+      indexRow
+    );
     return this.#groupIndexes(rows);
   }
   #groupIndexes(rows) {
@@ -1403,10 +1530,8 @@ var PostgresInfoGrounding = class extends InfoGrounding {
   }
   async collectInfo() {
     const [versionRows, dbRows] = await Promise.all([
-      this.#adapter.runQuery(
-        "SELECT version() AS version"
-      ),
-      this.#adapter.runQuery("SELECT current_database() AS db")
+      this.#adapter.runQuery("SELECT version() AS version", versionRow),
+      this.#adapter.runQuery("SELECT current_database() AS db", databaseRow)
     ]);
     return {
       dialect: "postgresql",
@@ -1801,9 +1926,6 @@ var POSTGRES_ERROR_MAP = {
     hint: "The function or operator you used is not recognized. Confirm its name and argument types."
   }
 };
-var LOW_CARDINALITY_LIMIT = 20;
-var noopProgress2 = () => {
-};
 function isPostgresError(error) {
   return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string";
 }
@@ -1857,9 +1979,6 @@ var Postgres = class extends Adapter {
       return JSON.stringify(formatPostgresError(sql, error));
     }
   }
-  async runQuery(sql) {
-    return this.#runIntrospectionQuery(sql);
-  }
   quoteIdentifier(name) {
     return `"${name.replace(/"/g, '""')}"`;
   }
@@ -1872,398 +1991,22 @@ var Postgres = class extends Adapter {
     const columnList = columns?.length ? columns.map((c) => this.quoteIdentifier(c)).join(", ") : "*";
     return `SELECT ${columnList} FROM ${tableIdentifier} LIMIT ${limit}`;
   }
-  async #loadTables() {
-    const rows = await this.#runIntrospectionQuery(`
-      SELECT
-        c.table_schema,
-        c.table_name,
-        c.column_name,
-        c.data_type
-      FROM information_schema.columns AS c
-      JOIN information_schema.tables AS t
-        ON c.table_schema = t.table_schema
-        AND c.table_name = t.table_name
-      WHERE t.table_type = 'BASE TABLE'
-        ${this.#buildSchemaFilter("c.table_schema")}
-      ORDER BY c.table_schema, c.table_name, c.ordinal_position
-    `);
-    const tables2 = /* @__PURE__ */ new Map();
-    for (const row of rows) {
-      if (!row.table_name) {
-        continue;
-      }
-      const schema = row.table_schema ?? "public";
-      const tableName = row.table_name;
-      const qualifiedName = `${schema}.${tableName}`;
-      const table2 = tables2.get(qualifiedName) ?? {
-        name: qualifiedName,
-        schema,
-        rawName: tableName,
-        columns: []
-      };
-      table2.columns.push({
-        name: row.column_name ?? "unknown",
-        type: row.data_type ?? "unknown"
-      });
-      tables2.set(qualifiedName, table2);
-    }
-    return Array.from(tables2.values());
-  }
-  async #loadRelationships(filterTableNames) {
-    const tableFilter = this.#buildTableNamesFilter(filterTableNames);
-    const rows = await this.#runIntrospectionQuery(`
-      SELECT
-        tc.constraint_name,
-        tc.table_schema,
-        tc.table_name,
-        kcu.column_name,
-        ccu.table_schema AS foreign_table_schema,
-        ccu.table_name AS foreign_table_name,
-        ccu.column_name AS foreign_column_name
-      FROM information_schema.table_constraints AS tc
-      JOIN information_schema.key_column_usage AS kcu
-        ON tc.constraint_name = kcu.constraint_name
-        AND tc.table_schema = kcu.table_schema
-      JOIN information_schema.constraint_column_usage AS ccu
-        ON ccu.constraint_name = tc.constraint_name
-        AND ccu.table_schema = tc.table_schema
-      WHERE tc.constraint_type = 'FOREIGN KEY'
-        ${this.#buildSchemaFilter("tc.table_schema")}
-        ${tableFilter}
-      ORDER BY tc.table_schema, tc.table_name, tc.constraint_name, kcu.ordinal_position
-    `);
-    const relationships = /* @__PURE__ */ new Map();
-    for (const row of rows) {
-      if (!row.table_name || !row.foreign_table_name || !row.constraint_name) {
-        continue;
-      }
-      const schema = row.table_schema ?? "public";
-      const referencedSchema = row.foreign_table_schema ?? "public";
-      const key = `${schema}.${row.table_name}:${row.constraint_name}`;
-      const relationship2 = relationships.get(key) ?? {
-        table: `${schema}.${row.table_name}`,
-        from: [],
-        referenced_table: `${referencedSchema}.${row.foreign_table_name}`,
-        to: []
-      };
-      relationship2.from.push(row.column_name ?? "unknown");
-      relationship2.to.push(row.foreign_column_name ?? "unknown");
-      relationships.set(key, relationship2);
-    }
-    return Array.from(relationships.values());
-  }
-  async #annotateRowCounts(tables2, onProgress = noopProgress2) {
-    const total = tables2.length;
-    for (let i = 0; i < tables2.length; i++) {
-      const table2 = tables2[i];
-      const tableIdentifier = this.#formatQualifiedTableName(table2);
-      onProgress({
-        type: "phase:progress",
-        phase: "row_counts",
-        table: table2.name,
-        message: `Counting rows in ${table2.name}...`,
-        current: i + 1,
-        total
-      });
-      try {
-        const rows = await this.#runIntrospectionQuery(`SELECT COUNT(*) as count FROM ${tableIdentifier}`);
-        const rowCount2 = this.#toNumber(rows[0]?.count);
-        if (rowCount2 != null) {
-          table2.rowCount = rowCount2;
-          table2.sizeHint = this.#classifyRowCount(rowCount2);
-        }
-      } catch {
-        continue;
-      }
-    }
-  }
-  async #annotateIndexes(tables2) {
-    if (!tables2.length) {
-      return;
-    }
-    const tableMap = new Map(tables2.map((table2) => [table2.name, table2]));
-    const rows = await this.#runIntrospectionQuery(`
-      SELECT
-        n.nspname AS table_schema,
-        t.relname AS table_name,
-        i.relname AS index_name,
-        a.attname AS column_name,
-        ix.indisunique,
-        ix.indisprimary,
-        ix.indisclustered,
-        am.amname AS method
-      FROM pg_index ix
-      JOIN pg_class t ON t.oid = ix.indrelid
-      JOIN pg_namespace n ON n.oid = t.relnamespace
-      JOIN pg_class i ON i.oid = ix.indexrelid
-      JOIN pg_am am ON am.oid = i.relam
-      LEFT JOIN LATERAL unnest(ix.indkey) WITH ORDINALITY AS key(attnum, ordinality) ON TRUE
-      LEFT JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = key.attnum
-      WHERE t.relkind = 'r'
-        ${this.#buildSchemaFilter("n.nspname")}
-      ORDER BY n.nspname, t.relname, i.relname, key.ordinality
-    `);
-    const indexMap = /* @__PURE__ */ new Map();
-    for (const row of rows) {
-      if (!row.table_name || !row.index_name) {
-        continue;
-      }
-      const schema = row.table_schema ?? "public";
-      const tableKey = `${schema}.${row.table_name}`;
-      const table2 = tableMap.get(tableKey);
-      if (!table2) {
-        continue;
-      }
-      const indexKey = `${tableKey}:${row.index_name}`;
-      let index2 = indexMap.get(indexKey);
-      if (!index2) {
-        index2 = {
-          name: row.index_name,
-          columns: [],
-          unique: Boolean(row.indisunique ?? false),
-          type: row.indisclustered ? "clustered" : row.method ?? void 0
-        };
-        indexMap.set(indexKey, index2);
-        if (!table2.indexes) {
-          table2.indexes = [];
-        }
-        table2.indexes.push(index2);
-      }
-      if (row.column_name) {
-        index2.columns.push(row.column_name);
-        const column2 = table2.columns.find(
-          (col) => col.name === row.column_name
-        );
-        if (column2) {
-          column2.isIndexed = true;
-        }
-      }
-    }
-  }
-  async #annotateColumnStats(tables2, onProgress = noopProgress2) {
-    if (!tables2.length) {
-      return;
-    }
-    const total = tables2.length;
-    for (let i = 0; i < tables2.length; i++) {
-      const table2 = tables2[i];
-      const tableIdentifier = this.#formatQualifiedTableName(table2);
-      onProgress({
-        type: "phase:progress",
-        phase: "column_stats",
-        table: table2.name,
-        message: `Collecting stats for ${table2.name}...`,
-        current: i + 1,
-        total
-      });
-      for (const column2 of table2.columns) {
-        if (!this.#shouldCollectStats(column2.type)) {
-          continue;
-        }
-        const columnIdentifier = this.#quoteIdentifier(column2.name);
-        const sql = `
-          SELECT
-            MIN(${columnIdentifier})::text AS min_value,
-            MAX(${columnIdentifier})::text AS max_value,
-            AVG(CASE WHEN ${columnIdentifier} IS NULL THEN 1.0 ELSE 0.0 END)::float AS null_fraction
-          FROM ${tableIdentifier}
-        `;
-        try {
-          const rows = await this.#runIntrospectionQuery(sql);
-          if (!rows.length) {
-            continue;
-          }
-          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) {
-            column2.stats = {
-              min,
-              max,
-              nullFraction: nullFraction != null && Number.isFinite(nullFraction) ? Math.max(0, Math.min(1, nullFraction)) : void 0
-            };
-          }
-        } catch {
-          continue;
-        }
-      }
-    }
-  }
-  async #annotateLowCardinalityColumns(tables2, onProgress = noopProgress2) {
-    const total = tables2.length;
-    for (let i = 0; i < tables2.length; i++) {
-      const table2 = tables2[i];
-      const tableIdentifier = this.#formatQualifiedTableName(table2);
-      onProgress({
-        type: "phase:progress",
-        phase: "low_cardinality",
-        table: table2.name,
-        message: `Analyzing cardinality in ${table2.name}...`,
-        current: i + 1,
-        total
-      });
-      for (const column2 of table2.columns) {
-        const columnIdentifier = this.#quoteIdentifier(column2.name);
-        const limit = LOW_CARDINALITY_LIMIT + 1;
-        const sql = `
-          SELECT DISTINCT ${columnIdentifier} AS value
-          FROM ${tableIdentifier}
-          WHERE ${columnIdentifier} IS NOT NULL
-          LIMIT ${limit}
-        `;
-        let rows = [];
-        try {
-          rows = await this.#runIntrospectionQuery(sql);
-        } catch {
-          continue;
-        }
-        if (!rows.length || rows.length > LOW_CARDINALITY_LIMIT) {
-          continue;
-        }
-        const values = [];
-        let shouldSkip = false;
-        for (const row of rows) {
-          const formatted = this.#normalizeValue(row.value);
-          if (formatted == null) {
-            shouldSkip = true;
-            break;
-          }
-          values.push(formatted);
-        }
-        if (shouldSkip || !values.length) {
-          continue;
-        }
-        column2.kind = "LowCardinality";
-        column2.values = values;
-      }
-    }
-  }
-  #buildSchemaFilter(columnName) {
-    if (this.#options.schemas && this.#options.schemas.length > 0) {
-      const values = this.#options.schemas.map((schema) => `'${schema.replace(/'/g, "''")}'`).join(", ");
-      return `AND ${columnName} IN (${values})`;
-    }
-    return `AND ${columnName} NOT IN ('pg_catalog', 'information_schema')`;
-  }
   /**
-   * Build a filter for table names (qualified as schema.table).
-   * Matches if either the source table or referenced table is in the list.
+   * The schemas introspection is limited to; table and view discovery use
+   * them unless a grounding lists its own.
    */
-  #buildTableNamesFilter(tableNames) {
-    if (!tableNames || tableNames.length === 0) {
-      return "";
-    }
-    const conditions = [];
-    for (const name of tableNames) {
-      if (name.includes(".")) {
-        const [schema, ...rest] = name.split(".");
-        const tableName = rest.join(".");
-        const escapedSchema = schema.replace(/'/g, "''");
-        const escapedTable = tableName.replace(/'/g, "''");
-        conditions.push(
-          `(tc.table_schema = '${escapedSchema}' AND tc.table_name = '${escapedTable}')`
-        );
-        conditions.push(
-          `(ccu.table_schema = '${escapedSchema}' AND ccu.table_name = '${escapedTable}')`
-        );
-      } else {
-        const escaped = name.replace(/'/g, "''");
-        conditions.push(`tc.table_name = '${escaped}'`);
-        conditions.push(`ccu.table_name = '${escaped}'`);
-      }
-    }
-    return `AND (${conditions.join(" OR ")})`;
-  }
-  async #runIntrospectionQuery(sql) {
-    const result = await this.#options.execute(sql);
-    if (Array.isArray(result)) {
-      return result;
-    }
-    if (result && typeof result === "object" && "rows" in result && Array.isArray(result.rows)) {
-      return result.rows;
-    }
-    throw new Error(
-      "Postgres adapter execute() must return an array of rows or an object with a rows array when introspecting."
-    );
-  }
-  #quoteIdentifier(name) {
-    return `"${name.replace(/"/g, '""')}"`;
-  }
-  #formatQualifiedTableName(table2) {
-    if (table2.schema && table2.rawName) {
-      return `${this.#quoteIdentifier(table2.schema)}.${this.#quoteIdentifier(table2.rawName)}`;
-    }
-    if (table2.name.includes(".")) {
-      const [schemaPart, ...rest] = table2.name.split(".");
-      const tablePart = rest.join(".") || schemaPart;
-      if (rest.length === 0) {
-        return this.#quoteIdentifier(schemaPart);
-      }
-      return `${this.#quoteIdentifier(schemaPart)}.${this.#quoteIdentifier(tablePart)}`;
-    }
-    return this.#quoteIdentifier(table2.name);
+  get schemas() {
+    return this.#options.schemas;
   }
-  #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;
-  }
-  #shouldCollectStats(type) {
-    if (!type) {
-      return false;
-    }
-    const normalized = type.toLowerCase();
-    return /int|numeric|decimal|double|real|money|date|time|timestamp|bool/.test(
-      normalized
-    );
-  }
-  #classifyRowCount(count) {
-    if (count < 100) {
-      return "tiny";
-    }
-    if (count < 1e3) {
-      return "small";
-    }
-    if (count < 1e4) {
-      return "medium";
-    }
-    if (count < 1e5) {
-      return "large";
-    }
-    return "huge";
-  }
-  #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 queryRows(sql) {
+    return this.rowsFrom(await this.#options.execute(sql), ["rows"]);
   }
 };
 
 // packages/text2sql/src/lib/adapters/postgres/row-count.postgres.grounding.ts
+import { z as z7 } from "zod";
+var estimateRow = z7.object({ estimate: numericValue.nullable() });
+var countRow = z7.object({ count: numericValue.nullable() });
 var PostgresRowCountGrounding = class extends RowCountGrounding {
   #adapter;
   constructor(adapter, config = {}) {
@@ -2279,51 +2022,82 @@ var PostgresRowCountGrounding = class extends RowCountGrounding {
   }
   async #getEstimatedRowCount(tableName) {
     const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
-    const rows = await this.#adapter.runQuery(`
+    const rows = await this.#adapter.runQuery(
+      `
       SELECT c.reltuples::bigint AS estimate
       FROM pg_class c
       JOIN pg_namespace n ON n.oid = c.relnamespace
       WHERE n.nspname = '${this.#adapter.escapeString(schema)}'
         AND c.relname = '${this.#adapter.escapeString(table2)}'
-    `);
+    `,
+      estimateRow
+    );
     return this.#adapter.toNumber(rows[0]?.estimate);
   }
   async #getLiveRowCount(tableName) {
     const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
     const tableIdentifier = `${this.#adapter.quoteIdentifier(schema)}.${this.#adapter.quoteIdentifier(table2)}`;
-    const rows = await this.#adapter.runQuery(`SELECT COUNT(*) as count FROM ${tableIdentifier}`);
+    const rows = await this.#adapter.runQuery(
+      `SELECT COUNT(*) as count FROM ${tableIdentifier}`,
+      countRow
+    );
     return this.#adapter.toNumber(rows[0]?.count);
   }
 };
 
 // packages/text2sql/src/lib/adapters/postgres/table.postgres.grounding.ts
+import { z as z9 } from "zod";
+
+// packages/text2sql/src/lib/adapters/postgres/postgres-rows.ts
+import { z as z8 } from "zod";
+var columnRow = z8.object({
+  column_name: z8.string().nullable(),
+  data_type: z8.string().nullable()
+});
+
+// packages/text2sql/src/lib/adapters/postgres/table.postgres.grounding.ts
+var relationshipRow = z9.object({
+  constraint_name: z9.string(),
+  table_schema: z9.string(),
+  table_name: z9.string(),
+  column_name: z9.string(),
+  foreign_table_schema: z9.string(),
+  foreign_table_name: z9.string(),
+  foreign_column_name: z9.string()
+});
 var PostgresTableGrounding = class extends TableGrounding {
   #adapter;
   #schemas;
   constructor(adapter, config = {}) {
     super(config);
     this.#adapter = adapter;
-    this.#schemas = config.schemas;
+    this.#schemas = config.schemas ?? adapter.schemas;
   }
   async getAllTableNames() {
-    const rows = await this.#adapter.runQuery(`
+    const rows = await this.#adapter.runQuery(
+      `
       SELECT DISTINCT table_schema || '.' || table_name AS name
       FROM information_schema.tables
       WHERE table_type = 'BASE TABLE'
         ${this.#adapter.buildSchemaFilter("table_schema", this.#schemas)}
       ORDER BY name
-    `);
+    `,
+      nameRow
+    );
     return rows.map((r) => r.name);
   }
   async getTable(tableName) {
     const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
-    const columns = await this.#adapter.runQuery(`
+    const columns = await this.#adapter.runQuery(
+      `
       SELECT column_name, data_type
       FROM information_schema.columns
       WHERE table_schema = '${this.#adapter.escapeString(schema)}'
         AND table_name = '${this.#adapter.escapeString(table2)}'
       ORDER BY ordinal_position
-    `);
+    `,
+      columnRow
+    );
     return {
       name: tableName,
       schema,
@@ -2336,72 +2110,64 @@ var PostgresTableGrounding = class extends TableGrounding {
   }
   async findOutgoingRelations(tableName) {
     const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
-    const rows = await this.#adapter.runQuery(`
-      SELECT
-        tc.constraint_name,
-        tc.table_schema,
-        tc.table_name,
-        kcu.column_name,
-        ccu.table_schema AS foreign_table_schema,
-        ccu.table_name AS foreign_table_name,
-        ccu.column_name AS foreign_column_name
-      FROM information_schema.table_constraints AS tc
-      JOIN information_schema.key_column_usage AS kcu
-        ON tc.constraint_name = kcu.constraint_name
-        AND tc.table_schema = kcu.table_schema
-      JOIN information_schema.constraint_column_usage AS ccu
-        ON ccu.constraint_name = tc.constraint_name
-        AND ccu.table_schema = tc.table_schema
-      WHERE tc.constraint_type = 'FOREIGN KEY'
-        AND tc.table_schema = '${this.#adapter.escapeString(schema)}'
-        AND tc.table_name = '${this.#adapter.escapeString(table2)}'
-      ORDER BY tc.constraint_name, kcu.ordinal_position
-    `);
-    return this.#groupRelationships(rows);
+    return this.#foreignKeys(
+      `nsp.nspname = '${this.#adapter.escapeString(schema)}'
+        AND rel.relname = '${this.#adapter.escapeString(table2)}'`
+    );
   }
   async findIncomingRelations(tableName) {
     const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
-    const rows = await this.#adapter.runQuery(`
+    return this.#foreignKeys(
+      `ref_nsp.nspname = '${this.#adapter.escapeString(schema)}'
+        AND ref_rel.relname = '${this.#adapter.escapeString(table2)}'`
+    );
+  }
+  /**
+   * The foreign keys matching `where`. unnest(conkey, confkey) WITH
+   * ORDINALITY pairs each column with the column it references by position,
+   * and each side carries its own schema, so composite and cross-schema keys
+   * come back whole.
+   */
+  async #foreignKeys(where) {
+    const rows = await this.#adapter.runQuery(
+      `
       SELECT
-        tc.constraint_name,
-        tc.table_schema,
-        tc.table_name,
-        kcu.column_name,
-        ccu.table_schema AS foreign_table_schema,
-        ccu.table_name AS foreign_table_name,
-        ccu.column_name AS foreign_column_name
-      FROM information_schema.table_constraints AS tc
-      JOIN information_schema.key_column_usage AS kcu
-        ON tc.constraint_name = kcu.constraint_name
-        AND tc.table_schema = kcu.table_schema
-      JOIN information_schema.constraint_column_usage AS ccu
-        ON ccu.constraint_name = tc.constraint_name
-        AND ccu.table_schema = tc.table_schema
-      WHERE tc.constraint_type = 'FOREIGN KEY'
-        AND ccu.table_schema = '${this.#adapter.escapeString(schema)}'
-        AND ccu.table_name = '${this.#adapter.escapeString(table2)}'
-      ORDER BY tc.constraint_name, kcu.ordinal_position
-    `);
-    return this.#groupRelationships(rows);
-  }
-  #groupRelationships(rows) {
+        con.conname AS constraint_name,
+        nsp.nspname AS table_schema,
+        rel.relname AS table_name,
+        att.attname AS column_name,
+        ref_nsp.nspname AS foreign_table_schema,
+        ref_rel.relname AS foreign_table_name,
+        ref_att.attname AS foreign_column_name
+      FROM pg_constraint AS con
+      JOIN pg_class AS rel ON rel.oid = con.conrelid
+      JOIN pg_namespace AS nsp ON nsp.oid = rel.relnamespace
+      JOIN pg_class AS ref_rel ON ref_rel.oid = con.confrelid
+      JOIN pg_namespace AS ref_nsp ON ref_nsp.oid = ref_rel.relnamespace
+      CROSS JOIN LATERAL unnest(con.conkey, con.confkey)
+        WITH ORDINALITY AS key(attnum, ref_attnum, ord)
+      JOIN pg_attribute AS att
+        ON att.attrelid = con.conrelid AND att.attnum = key.attnum
+      JOIN pg_attribute AS ref_att
+        ON ref_att.attrelid = con.confrelid AND ref_att.attnum = key.ref_attnum
+      WHERE con.contype = 'f'
+        AND ${where}
+      ORDER BY nsp.nspname, rel.relname, con.conname, key.ord
+    `,
+      relationshipRow
+    );
     const relationships = /* @__PURE__ */ new Map();
-    const defaultSchema = this.#adapter.defaultSchema ?? "public";
     for (const row of rows) {
-      if (!row.table_name || !row.foreign_table_name || !row.constraint_name) {
-        continue;
-      }
-      const schema = row.table_schema ?? defaultSchema;
-      const referencedSchema = row.foreign_table_schema ?? defaultSchema;
-      const key = `${schema}.${row.table_name}:${row.constraint_name}`;
+      const table2 = `${row.table_schema}.${row.table_name}`;
+      const key = `${table2}:${row.constraint_name}`;
       const relationship2 = relationships.get(key) ?? {
-        table: `${schema}.${row.table_name}`,
+        table: table2,
         from: [],
-        referenced_table: `${referencedSchema}.${row.foreign_table_name}`,
+        referenced_table: `${row.foreign_table_schema}.${row.foreign_table_name}`,
         to: []
       };
-      relationship2.from.push(row.column_name ?? "unknown");
-      relationship2.to.push(row.foreign_column_name ?? "unknown");
+      relationship2.from.push(row.column_name);
+      relationship2.to.push(row.foreign_column_name);
       relationships.set(key, relationship2);
     }
     return Array.from(relationships.values());
@@ -2470,37 +2236,46 @@ var PostgresViewGrounding = class extends ViewGrounding {
   constructor(adapter, config = {}) {
     super(config);
     this.#adapter = adapter;
-    this.#schemas = config.schemas;
+    this.#schemas = config.schemas ?? adapter.schemas;
   }
   async getAllViewNames() {
-    const rows = await this.#adapter.runQuery(`
+    const rows = await this.#adapter.runQuery(
+      `
       SELECT table_schema || '.' || table_name AS name
       FROM information_schema.views
       WHERE 1=1
         ${this.#adapter.buildSchemaFilter("table_schema", this.#schemas)}
       ORDER BY name
-    `);
+    `,
+      nameRow
+    );
     return rows.map((r) => r.name);
   }
   async getView(viewName) {
     const { schema, table: view2 } = this.#adapter.parseTableName(viewName);
     let definition;
     if (this.includeDefinition) {
-      const defRows = await this.#adapter.runQuery(`
+      const defRows = await this.#adapter.runQuery(
+        `
         SELECT definition
         FROM pg_views
         WHERE schemaname = '${this.#adapter.escapeString(schema)}'
           AND viewname = '${this.#adapter.escapeString(view2)}'
-      `);
+      `,
+        viewDefinitionRow
+      );
       definition = defRows[0]?.definition ?? void 0;
     }
-    const columns = await this.#adapter.runQuery(`
+    const columns = await this.#adapter.runQuery(
+      `
       SELECT column_name, data_type
       FROM information_schema.columns
       WHERE table_schema = '${this.#adapter.escapeString(schema)}'
         AND table_name = '${this.#adapter.escapeString(view2)}'
       ORDER BY ordinal_position
-    `);
+    `,
+      columnRow
+    );
     return {
       name: viewName,
       schema,
@@ -2516,15 +2291,19 @@ var PostgresViewGrounding = class extends ViewGrounding {
 
 // packages/text2sql/src/lib/adapters/postgres/index.ts
 function tables(config = {}) {
-  return (adapter) => new PostgresTableGrounding(adapter, config);
+  return groundingFor(
+    Postgres,
+    (adapter) => new PostgresTableGrounding(adapter, config)
+  );
 }
 function info(config = {}) {
   return (adapter) => new PostgresInfoGrounding(adapter, config);
 }
 function views(config = {}) {
-  return (adapter) => {
-    return new PostgresViewGrounding(adapter, config);
-  };
+  return groundingFor(
+    Postgres,
+    (adapter) => new PostgresViewGrounding(adapter, config)
+  );
 }
 function columnStats(config = {}) {
   return (adapter) => {