@metaobjectsdev/migrate-ts 0.9.0 → 0.11.0-rc.1

package/src/expected-schema.ts

@@ -1,11 +1,23 @@
 import type { ColumnNamingStrategy, MetaData, MetaObject, MetaRoot, MetaValidator } from "@metaobjectsdev/metadata";
 import {
   VALIDATOR_SUBTYPE_NUMERIC, VALIDATOR_SUBTYPE_LENGTH, VALIDATOR_SUBTYPE_REGEX,
+  VALIDATOR_SUBTYPE_COMPARISON, VALIDATOR_SUBTYPE_REQUIRED_WHEN,
+  VALIDATOR_SUBTYPE_PRESENT_IFF, VALIDATOR_SUBTYPE_AT_LEAST_ONE,
   VALIDATOR_ATTR_PATTERN,
+  VALIDATOR_ATTR_LEFT, VALIDATOR_ATTR_OP, VALIDATOR_ATTR_RIGHT,
+  VALIDATOR_ATTR_FIELD, VALIDATOR_ATTR_WHEN, VALIDATOR_ATTR_EQUALS, VALIDATOR_ATTR_FIELDS,
   TYPE_OBJECT,
+  TYPE_FIELD,
+  OBJECT_ATTR_DISCRIMINATOR,
+  OBJECT_ATTR_DISCRIMINATOR_VALUE,
   MetaSource,
   IDENTITY_ATTR_GENERATION,
   IDENTITY_ATTR_UNIQUE,
+  IDENTITY_ATTR_ORDERS,
+  IDENTITY_ATTR_WHERE,
+  IDENTITY_ATTR_EXPR,
+  IDENTITY_ATTR_USING,
+  IDENTITY_ATTR_CONSTRAINT_NAME,
   FIELD_ATTR_DEFAULT,
   FIELD_ATTR_MAX_LENGTH,
   FIELD_ATTR_PRECISION,
@@ -14,8 +26,6 @@ import {
   FIELD_SUBTYPE_STRING,
   FIELD_SUBTYPE_INT,
   FIELD_SUBTYPE_LONG,
-  FIELD_SUBTYPE_SHORT,
-  FIELD_SUBTYPE_BYTE,
   FIELD_SUBTYPE_DOUBLE,
   FIELD_SUBTYPE_FLOAT,
   FIELD_SUBTYPE_DECIMAL,
@@ -25,7 +35,6 @@ import {
   FIELD_SUBTYPE_TIME,
   FIELD_SUBTYPE_TIMESTAMP,
   FIELD_SUBTYPE_OBJECT,
-  FIELD_SUBTYPE_CLASS,
   FIELD_SUBTYPE_UUID,
   FIELD_SUBTYPE_ENUM,
   FIELD_ATTR_VALUES,
@@ -92,6 +101,9 @@ export function buildExpectedSchema(
     if (child.type !== TYPE_OBJECT) continue;
     if (child.isAbstract) continue;
     if (child.subType === "value") continue;
+    // FR-017 TPH: a subtype shares its discriminator base's single table, so it
+    // emits no table of its own. Its own columns are folded into the base below.
+    if (isTphSubtype(child)) continue;
     const hasReadOnlySource = child.ownChildren().some(
       (c) => c instanceof MetaSource && c.isReadOnly(),
     );
@@ -103,7 +115,14 @@ export function buildExpectedSchema(
     entities.push({ entity: child as MetaObject, tableName: resolveTableName(child) });
   }
   const entityToTable = new Map(entities.map((e) => [e.entity.name, e.tableName]));
-  const resolveTargetTable = (entityName: string) => entityToTable.get(entityName);
+  // A reference's targetEntity is package-qualified by the loader (e.g.
+  // "acme::a::Foo"), but entityToTable is keyed by the bare entity name ("Foo").
+  // Fall back to the bare suffix so cross-package FK targets resolve.
+  const resolveTargetTable = (entityName: string) =>
+    entityToTable.get(entityName) ??
+    (entityName.includes("::")
+      ? entityToTable.get(entityName.slice(entityName.lastIndexOf("::") + 2))
+      : undefined);
 
   // Pass 2: build full descriptors with FK resolution.
   // Schema is resolved here (not stored in Pass 1) to avoid exactOptionalPropertyTypes
@@ -179,6 +198,41 @@ function normalizeForSqlite(sqlType: SqlType): SqlType {
   }
 }
 
+// ---------------------------------------------------------------------------
+// FR-017 TPH (table-per-hierarchy) — single-table schema emission.
+// ---------------------------------------------------------------------------
+
+/** The @discriminator-bearing ancestor of `entity`, or undefined for non-TPH. */
+function discriminatorBaseOf(entity: MetaData): MetaData | undefined {
+  let a = entity.superResolved;
+  while (a !== undefined) {
+    if (a.ownAttr(OBJECT_ATTR_DISCRIMINATOR) !== undefined) return a;
+    a = a.superResolved;
+  }
+  return undefined;
+}
+
+/** True if `entity` is a TPH SUBTYPE (declares @discriminatorValue + has a
+ *  discriminator-bearing ancestor). Such an entity emits no table of its own. */
+function isTphSubtype(entity: MetaData): boolean {
+  return (
+    entity.ownAttr(OBJECT_ATTR_DISCRIMINATOR_VALUE) !== undefined &&
+    discriminatorBaseOf(entity) !== undefined
+  );
+}
+
+/** Concrete TPH subtypes whose discriminator base is `base` (root-level scan). */
+function tphConcreteSubtypes(base: MetaObject, root: MetaData): MetaObject[] {
+  if (base.ownAttr(OBJECT_ATTR_DISCRIMINATOR) === undefined) return [];
+  return root.ownChildren().filter(
+    (c): c is MetaObject =>
+      c.type === TYPE_OBJECT &&
+      !c.isAbstract &&
+      c.ownAttr(OBJECT_ATTR_DISCRIMINATOR_VALUE) !== undefined &&
+      discriminatorBaseOf(c) === base,
+  );
+}
+
 function buildTable(
   entity: MetaObject,
   tableName: string,
@@ -216,6 +270,24 @@ function buildTable(
     }
   }
 
+  // FR-017 TPH: if this is a discriminator base, fold each concrete subtype's
+  // OWN fields into the single table as NULLABLE columns (a row of any other
+  // subtype stores NULL there), even when the field is @required. Dedupe by
+  // column name so an inherited/overridden base column is not re-emitted.
+  if (entity.ownAttr(OBJECT_ATTR_DISCRIMINATOR) !== undefined) {
+    const existing = new Set(columns.map((c) => c.name));
+    for (const sub of tphConcreteSubtypes(entity, root)) {
+      for (const field of sub.ownChildren()) {
+        if (field.type !== TYPE_FIELD) continue;
+        const col = buildColumn(field, false, undefined, strategy);
+        if (existing.has(col.name)) continue;
+        col.nullable = true; // subtype-only columns are always nullable in TPH
+        columns.push(col);
+        existing.add(col.name);
+      }
+    }
+  }
+
   const descriptor: TableDescriptor = {
     name: tableName,
     columns,
@@ -263,18 +335,42 @@ function buildSecondaryIndexes(
   // Drizzle emits the index using the identity's @name attr directly (no table
   // prefix), so the expected name must match.
   for (const identity of entity.secondaryIdentities()) {
+    const exprRaw = identity.ownAttr(IDENTITY_ATTR_EXPR);
+    const expr = typeof exprRaw === "string" && exprRaw.trim().length > 0 ? exprRaw.trim() : undefined;
     const fieldNames = readIdentityFields(identity);
-    if (fieldNames.length === 0) continue;
+    // An expression index keys off @expr (not @fields); a plain index needs @fields.
+    if (fieldNames.length === 0 && expr === undefined) continue;
     const cols = fieldNames.map((jsName) => {
       const field = findField(entity, jsName);
       return field ? resolveColumnName(field, strategy) : applyColumnNamingStrategy(jsName, strategy);
     });
     const uniqueAttr = identity.ownAttr(IDENTITY_ATTR_UNIQUE);
-    indexes.push({
+    const index: IndexDescriptor = {
       name: identity.name,
-      columns: cols,
+      columns: expr ? [] : cols,
       unique: uniqueAttr !== false,
-    });
+    };
+    if (expr) index.expr = expr;
+    const usingRaw = identity.ownAttr(IDENTITY_ATTR_USING);
+    if (typeof usingRaw === "string" && usingRaw.trim().length > 0 && usingRaw.trim() !== "btree") {
+      index.using = usingRaw.trim();
+    }
+    // @orders — per-field sort direction (positional to @fields). Only attach when
+    // at least one field is descending (an all-ascending array is the default and
+    // must serialize identically to "no orders" for diff stability).
+    const ordersRaw = identity.ownAttr(IDENTITY_ATTR_ORDERS);
+    if (Array.isArray(ordersRaw)) {
+      const orders = cols.map((_, i) => (ordersRaw[i] === "desc" ? "desc" : "asc")) as (
+        "asc" | "desc"
+      )[];
+      if (orders.some((o) => o === "desc")) index.orders = orders;
+    }
+    // @where — partial-index predicate.
+    const whereRaw = identity.ownAttr(IDENTITY_ATTR_WHERE);
+    if (typeof whereRaw === "string" && whereRaw.trim().length > 0) {
+      index.where = whereRaw.trim();
+    }
+    indexes.push(index);
   }
   return indexes;
 }
@@ -297,20 +393,20 @@ function buildSecondaryIndexes(
  * column name verbatim (matching the enum-check convention).
  */
 function validatorCheck(
-  v: MetaValidator, col: string, tableName: string, dialect: Dialect | undefined,
+  v: MetaValidator, qcol: string, tableName: string, col: string, dialect: Dialect | undefined,
 ): CheckDescriptor | null {
   switch (v.subType) {
     case VALIDATOR_SUBTYPE_NUMERIC: {
       const parts: string[] = [];
-      if (v.min !== undefined) parts.push(`${col} >= ${v.min}`);
-      if (v.max !== undefined) parts.push(`${col} <= ${v.max}`);
+      if (v.min !== undefined) parts.push(`${qcol} >= ${v.min}`);
+      if (v.max !== undefined) parts.push(`${qcol} <= ${v.max}`);
       if (parts.length === 0) return null;
       return { name: `${tableName}_${col}_numeric_chk`, expression: parts.join(" AND ") };
     }
     case VALIDATOR_SUBTYPE_LENGTH: {
       const parts: string[] = [];
-      if (v.min !== undefined) parts.push(`length(${col}) >= ${v.min}`);
-      if (v.max !== undefined) parts.push(`length(${col}) <= ${v.max}`);
+      if (v.min !== undefined) parts.push(`length(${qcol}) >= ${v.min}`);
+      if (v.max !== undefined) parts.push(`length(${qcol}) <= ${v.max}`);
       if (parts.length === 0) return null;
       return { name: `${tableName}_${col}_length_chk`, expression: parts.join(" AND ") };
     }
@@ -321,7 +417,7 @@ function validatorCheck(
       if (typeof pattern !== "string" || pattern.length === 0) return null;
       return {
         name: `${tableName}_${col}_regex_chk`,
-        expression: `${col} ~ '${pattern.replace(/'/g, "''")}'`,
+        expression: `${qcol} ~ '${pattern.replace(/'/g, "''")}'`,
       };
     }
     default:
@@ -329,30 +425,140 @@ function validatorCheck(
   }
 }
 
+/**
+ * Quote a column identifier for embedding in a CHECK expression. Both Postgres
+ * and SQLite quote identifiers with double-quotes, so the dialect-neutral
+ * expression text can carry a quoted column. Quoting is REQUIRED for a
+ * mixed-case column (e.g. `enumVal`): a bare `enumVal IN (...)` folds to
+ * lowercase `enumval` and references a non-existent column. The check-expression
+ * comparator (`normalizeCheckExpr`) strips quotes so an introspected check still
+ * compares equal.
+ */
+function quoteCheckCol(col: string): string {
+  return `"${col.replace(/"/g, '""')}"`;
+}
+
 function buildChecks(
   entity: MetaObject, tableName: string, strategy: ColumnNamingStrategy, dialect: Dialect | undefined,
 ): CheckDescriptor[] {
   const checks: CheckDescriptor[] = [];
   for (const field of entity.fields()) {
     const col = resolveColumnName(field, strategy);
-    // Enum membership check (unchanged).
+    const qcol = quoteCheckCol(col);
+    // Enum membership check.
     if (field.subType === FIELD_SUBTYPE_ENUM) {
       const raw = field.attr(FIELD_ATTR_VALUES);
       if (Array.isArray(raw) && raw.length > 0) {
         const values = raw.map((v) => String(v));
-        const expression = `${col} IN (${values.map((v) => `'${v.replace(/'/g, "''")}'`).join(", ")})`;
+        const expression = `${qcol} IN (${values.map((v) => `'${v.replace(/'/g, "''")}'`).join(", ")})`;
         checks.push({ name: `${tableName}_${col}_chk`, expression });
       }
     }
     // Validator-derived checks.
     for (const v of field.validators()) {
-      const check = validatorCheck(v, col, tableName, dialect);
+      const check = validatorCheck(v, qcol, tableName, col, dialect);
       if (check) checks.push(check);
     }
   }
+  // Entity-scoped cross-field validators (comparison / requiredWhen / presentIff / atLeastOne).
+  for (const v of entity.validators()) {
+    const check = crossFieldCheck(v, entity, tableName, strategy, dialect);
+    if (check) checks.push(check);
+  }
   return checks;
 }
 
+const COMPARISON_SQL_OP: Record<string, string> = {
+  gt: ">", gte: ">=", lt: "<", lte: "<=", ne: "<>", eq: "=",
+};
+
+/** Resolve a by-name field reference to its physical column (quoted) + the MetaField, or null. */
+function resolveRef(
+  entity: MetaObject, name: unknown, strategy: ColumnNamingStrategy,
+): { qcol: string; field: ReturnType<MetaObject["fields"]>[number] } | null {
+  if (typeof name !== "string" || name.length === 0) return null;
+  const field = entity.fields().find((f) => f.name === name);
+  if (!field) return null;
+  return { qcol: quoteCheckCol(resolveColumnName(field, strategy)), field };
+}
+
+/**
+ * Render an @equals gating value as a SQL literal, typed by the gating field's
+ * subtype: boolean → TRUE/FALSE (1/0 on sqlite/d1), numeric → bare number,
+ * everything else → quoted string.
+ */
+function renderEquals(
+  raw: unknown, whenField: ReturnType<MetaObject["fields"]>[number], dialect: Dialect | undefined,
+): string {
+  const s = String(raw);
+  if (whenField.subType === FIELD_SUBTYPE_BOOLEAN) {
+    const truthy = s === "true" || s === "1" || s === "TRUE";
+    if (dialect === "sqlite" || dialect === "d1") return truthy ? "1" : "0";
+    return truthy ? "TRUE" : "FALSE";
+  }
+  const numeric = whenField.subType === FIELD_SUBTYPE_INT || whenField.subType === FIELD_SUBTYPE_LONG
+    || whenField.subType === FIELD_SUBTYPE_DOUBLE || whenField.subType === FIELD_SUBTYPE_FLOAT
+    || whenField.subType === FIELD_SUBTYPE_DECIMAL || whenField.subType === FIELD_SUBTYPE_CURRENCY;
+  if (numeric && /^-?\d+(\.\d+)?$/.test(s)) return s;
+  return `'${s.replace(/'/g, "''")}'`;
+}
+
+/**
+ * Derive a CHECK from an entity-scoped cross-field validator. Every reference is
+ * resolved to its physical column by name; nothing raw is read from metadata.
+ * Returns null (skips the check) if any referenced field is missing.
+ */
+function crossFieldCheck(
+  v: MetaValidator, entity: MetaObject, tableName: string,
+  strategy: ColumnNamingStrategy, dialect: Dialect | undefined,
+): CheckDescriptor | null {
+  switch (v.subType) {
+    case VALIDATOR_SUBTYPE_COMPARISON: {
+      const left = resolveRef(entity, v.ownAttr(VALIDATOR_ATTR_LEFT), strategy);
+      const right = resolveRef(entity, v.ownAttr(VALIDATOR_ATTR_RIGHT), strategy);
+      const op = COMPARISON_SQL_OP[String(v.ownAttr(VALIDATOR_ATTR_OP))];
+      if (!left || !right || !op) return null;
+      const lc = resolveColumnName(left.field, strategy);
+      return { name: `${tableName}_${lc}_cmp_chk`, expression: `${left.qcol} ${op} ${right.qcol}` };
+    }
+    case VALIDATOR_SUBTYPE_REQUIRED_WHEN: {
+      const target = resolveRef(entity, v.ownAttr(VALIDATOR_ATTR_FIELD), strategy);
+      const when = resolveRef(entity, v.ownAttr(VALIDATOR_ATTR_WHEN), strategy);
+      if (!target || !when) return null;
+      const lit = renderEquals(v.ownAttr(VALIDATOR_ATTR_EQUALS), when.field, dialect);
+      const fc = resolveColumnName(target.field, strategy);
+      return {
+        name: `${tableName}_${fc}_reqwhen_chk`,
+        expression: `(${when.qcol} IS DISTINCT FROM ${lit}) OR (${target.qcol} IS NOT NULL)`,
+      };
+    }
+    case VALIDATOR_SUBTYPE_PRESENT_IFF: {
+      const target = resolveRef(entity, v.ownAttr(VALIDATOR_ATTR_FIELD), strategy);
+      const when = resolveRef(entity, v.ownAttr(VALIDATOR_ATTR_WHEN), strategy);
+      if (!target || !when) return null;
+      const lit = renderEquals(v.ownAttr(VALIDATOR_ATTR_EQUALS), when.field, dialect);
+      const fc = resolveColumnName(target.field, strategy);
+      return {
+        name: `${tableName}_${fc}_presentiff_chk`,
+        expression: `(${target.qcol} IS NOT NULL) = (${when.qcol} IS NOT DISTINCT FROM ${lit})`,
+      };
+    }
+    case VALIDATOR_SUBTYPE_AT_LEAST_ONE: {
+      const raw = v.ownAttr(VALIDATOR_ATTR_FIELDS);
+      const names = Array.isArray(raw) ? raw : (typeof raw === "string" ? [raw] : []);
+      const refs = names.map((n) => resolveRef(entity, n, strategy));
+      if (refs.length === 0 || refs.some((r) => r === null)) return null;
+      const firstCol = resolveColumnName(refs[0]!.field, strategy);
+      return {
+        name: `${tableName}_${firstCol}_atleastone_chk`,
+        expression: refs.map((r) => `${r!.qcol} IS NOT NULL`).join(" OR "),
+      };
+    }
+    default:
+      return null;
+  }
+}
+
 function buildForeignKeys(
   entity: MetaObject,
   tableName: string,
@@ -386,7 +592,13 @@ function buildForeignKeys(
       : [applyColumnNamingStrategy(refChild.resolvedTargetPkField(root) ?? "id", strategy)];
 
     const { onDelete, onUpdate } = resolveReferentialActions(entity, refChild);
-    const constraintName = `${tableName}_${fkCols[0]}_fk`;
+    // An explicit @constraintName adopts an existing FK name (e.g. a database
+    // created by another toolchain); absent → the auto-derived default.
+    const constraintNameOverride = refChild.ownAttr(IDENTITY_ATTR_CONSTRAINT_NAME);
+    const constraintName =
+      typeof constraintNameOverride === "string" && constraintNameOverride.length > 0
+        ? constraintNameOverride
+        : `${tableName}_${fkCols[0]}_fk`;
 
     // Guard: ON DELETE SET NULL requires nullable FK columns.
     validateSetNullNullability(entity, refChild, onDelete, constraintName);
@@ -489,9 +701,7 @@ function subtypeToSqlType(field: MetaData): SqlType {
       const m = field.ownAttr(FIELD_ATTR_MAX_LENGTH);
       return typeof m === "number" ? { kind: "text", maxLength: m } : { kind: "text" };
     }
-    case FIELD_SUBTYPE_INT:
-    case FIELD_SUBTYPE_SHORT:
-    case FIELD_SUBTYPE_BYTE:      return { kind: "integer", bits: 32 };
+    case FIELD_SUBTYPE_INT:       return { kind: "integer", bits: 32 };
     case FIELD_SUBTYPE_LONG:
     case FIELD_SUBTYPE_CURRENCY:  return { kind: "integer", bits: 64 };
     case FIELD_SUBTYPE_DOUBLE:    return { kind: "real" };
@@ -513,8 +723,7 @@ function subtypeToSqlType(field: MetaData): SqlType {
     case FIELD_SUBTYPE_DATE:      return { kind: "date" };
     case FIELD_SUBTYPE_TIME:      return { kind: "time" }; // Postgres native TIME (whole-second wire form)
     case FIELD_SUBTYPE_TIMESTAMP: return { kind: "timestamp", withTimezone: false };
-    case FIELD_SUBTYPE_OBJECT:
-    case FIELD_SUBTYPE_CLASS:     return { kind: "json" };
+    case FIELD_SUBTYPE_OBJECT:    return { kind: "json" };
     case FIELD_SUBTYPE_UUID:      return { kind: "uuid" }; // R6 Plan 2a — Postgres native uuid
     default:                      return { kind: "text" }; // unknown → text fallback
   }

package/src/introspect/postgres.ts

@@ -151,25 +151,36 @@ export function pgTypeToSqlType(dataType: string, maxLength?: number | null): Sq
  * Returns undefined if the default is absent or empty.
  *
  * Classification rules:
- *   - Expressions: now(), CURRENT_TIMESTAMP, CURRENT_DATE, CURRENT_TIME,
- *     nextval(...), and any value that starts with a non-quote character and
- *     contains a `::` cast (i.e. bare identifier with cast, like `NULL::text`).
+ *   - Expressions: now(), CURRENT_TIMESTAMP, CURRENT_DATE, CURRENT_TIME, and any
+ *     bare function-call (e.g. nextval(...), gen_random_uuid(), uuid_generate_v4()),
+ *     plus any value that starts with a non-quote character and contains a `::` cast
+ *     (i.e. bare identifier with cast, like `NULL::text`).
  *   - Literals: `'value'` (optionally followed by `::type` cast, which PG
  *     commonly appends for clarity). The cast is stripped; the value is unquoted.
  *
  * PG stores literal booleans as `'true'::boolean`, integers as `'42'::integer`,
  * strings as `'hello'::text` — all are literals after stripping the cast.
+ *
+ * The bare function-call rule keeps this in lockstep with the metadata-side
+ * default classifier (expected-schema's EXPR_DEFAULT_PATTERNS, which treats any
+ * `()` default as an expression): without it, a `gen_random_uuid()` column default
+ * round-trips as a literal here but an expression there, producing a spurious
+ * column diff on every uuid-PK table.
  */
 export function parsePgDefault(raw: string | null | undefined): ColumnDefault | undefined {
   if (raw === undefined || raw === null || raw === "") return undefined;
 
-  // Function-call or keyword expressions
+  // Function-call or keyword expressions. The leading-identifier-then-"(" rule
+  // matches any bare function call (gen_random_uuid(), uuid_generate_v4(), …)
+  // while never matching a quoted literal (those start with a single quote and are
+  // handled below).
   if (
     /^now\(\)$/i.test(raw) ||
     /^current_timestamp\b/i.test(raw) ||
     /^current_date\b/i.test(raw) ||
     /^current_time\b/i.test(raw) ||
-    /^nextval\(/i.test(raw)
+    /^nextval\(/i.test(raw) ||
+    /^[a-zA-Z_][\w.]*\s*\(/.test(raw)
   ) {
     return { kind: "expr", value: raw };
   }
@@ -317,46 +328,132 @@ async function readPgIndexes(k: RawKysely, schema: string, table: string): Promi
   // pg-mem gap: array_position() is not implemented, so this query throws on
   // pg-mem. We catch and return [] so non-index tests still pass against pg-mem.
   // Real PG (Postgres 16) handles this correctly.
-  let rows: { rows: Array<{ index_name: string; is_unique: boolean; is_primary: boolean; column_name: string; ordinal: number }> };
+  // One row per index KEY, in key order, carrying: the column name (NULL for an
+  // expression key — attnum 0), the DESC bit from `indoption`, and the partial-index
+  // predicate (`indpred`, constant per index). unnest WITH ORDINALITY over indkey +
+  // indoption keeps the key order and pairs each key with its option flags.
+  let rows: {
+    rows: Array<{
+      index_name: string;
+      is_unique: boolean;
+      is_primary: boolean;
+      column_name: string | null;
+      ordinal: number;
+      is_desc: boolean;
+      predicate: string | null;
+      access_method: string;
+      indexdef: string;
+    }>;
+  };
   try {
     rows = await sql<{
       index_name: string;
       is_unique: boolean;
       is_primary: boolean;
-      column_name: string;
+      column_name: string | null;
       ordinal: number;
+      is_desc: boolean;
+      predicate: string | null;
+      access_method: string;
+      indexdef: string;
     }>`
       SELECT i.relname AS index_name,
              ix.indisunique AS is_unique,
              ix.indisprimary AS is_primary,
              a.attname AS column_name,
-             array_position(ix.indkey, a.attnum) AS ordinal
+             k.ord AS ordinal,
+             (COALESCE(opt.option, 0) & 1) = 1 AS is_desc,
+             pg_get_expr(ix.indpred, ix.indrelid) AS predicate,
+             am.amname AS access_method,
+             pg_get_indexdef(ix.indexrelid) AS indexdef
       FROM pg_index ix
       JOIN pg_class i ON i.oid = ix.indexrelid
       JOIN pg_class t ON t.oid = ix.indrelid
       JOIN pg_namespace n ON n.oid = t.relnamespace
-      JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = ANY(ix.indkey)
+      JOIN pg_am am ON am.oid = i.relam
+      CROSS JOIN LATERAL unnest(ix.indkey) WITH ORDINALITY AS k(attnum, ord)
+      LEFT JOIN LATERAL unnest(ix.indoption) WITH ORDINALITY AS opt(option, oord)
+        ON opt.oord = k.ord
+      LEFT JOIN pg_attribute a ON a.attrelid = ix.indrelid AND a.attnum = k.attnum
       WHERE n.nspname = ${schema}
         AND t.relname = ${table}
-      ORDER BY i.relname, ordinal
+      ORDER BY i.relname, k.ord
     `.execute(k);
   } catch {
-    // pg-mem: array_position() not implemented — return empty index list.
+    // pg-mem: unnest WITH ORDINALITY / pg_get_expr unsupported — return empty list.
     return [];
   }
 
-  const byName = new Map<string, { isUnique: boolean; isPrimary: boolean; cols: string[] }>();
+  const byName = new Map<
+    string,
+    {
+      isUnique: boolean;
+      isPrimary: boolean;
+      cols: string[];
+      orders: ("asc" | "desc")[];
+      predicate: string | null;
+      hasExpressionKey: boolean;
+      accessMethod: string;
+      indexdef: string;
+    }
+  >();
   for (const r of rows.rows) {
     let entry = byName.get(r.index_name);
     if (!entry) {
-      entry = { isUnique: r.is_unique, isPrimary: r.is_primary, cols: [] };
+      entry = {
+        isUnique: r.is_unique,
+        isPrimary: r.is_primary,
+        cols: [],
+        orders: [],
+        predicate: r.predicate,
+        hasExpressionKey: false,
+        accessMethod: r.access_method,
+        indexdef: r.indexdef,
+      };
       byName.set(r.index_name, entry);
     }
-    entry.cols.push(r.column_name);
+    if (r.column_name === null) {
+      // Expression key (attnum 0) — captured from the index def below.
+      entry.hasExpressionKey = true;
+    } else {
+      entry.cols.push(r.column_name);
+      entry.orders.push(r.is_desc ? "desc" : "asc");
+    }
   }
   return Array.from(byName.entries())
-    .filter(([, v]) => !v.isPrimary)        // PK index excluded — PK lives in TableDescriptor.primaryKey
-    .map(([name, v]) => ({ name, columns: v.cols, unique: v.isUnique }));
+    .filter(([, v]) => !v.isPrimary) // PK index excluded — PK lives in TableDescriptor.primaryKey
+    .map(([name, v]) => {
+      const using = v.accessMethod !== "btree" ? v.accessMethod : undefined;
+      if (v.hasExpressionKey) {
+        // Functional/expression index: lift the raw key expression out of the
+        // index def (between `USING <am> (` and its matching `)`, before WHERE).
+        const ix: IndexDescriptor = { name, columns: [], unique: v.isUnique, expr: indexDefKeyExpr(v.indexdef) };
+        if (using) ix.using = using;
+        if (v.predicate !== null) ix.where = v.predicate;
+        return ix;
+      }
+      const ix: IndexDescriptor = { name, columns: v.cols, unique: v.isUnique };
+      if (using) ix.using = using;
+      if (v.orders.some((o) => o === "desc")) ix.orders = v.orders;
+      if (v.predicate !== null) ix.where = v.predicate;
+      return ix;
+    });
+}
+
+/** Extract the raw key-expression text from a pg index def — the balanced `(...)`
+ *  after `USING <method> `, stripped of a trailing partial-index `WHERE`. */
+function indexDefKeyExpr(indexdef: string): string {
+  const open = indexdef.indexOf("(", indexdef.indexOf(" USING "));
+  if (open === -1) return indexdef;
+  let depth = 0;
+  for (let i = open; i < indexdef.length; i++) {
+    if (indexdef[i] === "(") depth++;
+    else if (indexdef[i] === ")") {
+      depth--;
+      if (depth === 0) return indexdef.slice(open + 1, i).trim();
+    }
+  }
+  return indexdef.slice(open + 1).trim();
 }
 
 async function readPgForeignKeys(k: RawKysely, schema: string, table: string): Promise<FkDescriptor[]> {

package/src/types.ts

@@ -66,6 +66,31 @@ export interface IndexDescriptor {
   name: string;
   columns: string[];
   unique: boolean;
+  /**
+   * Per-column sort direction, positional to `columns`. Omitted (or "asc") = the
+   * default ascending order, which Postgres does not render in an index def. A
+   * "desc" entry emits `<col> DESC` and is compared against the introspected
+   * `pg_index.indoption` DESC bit. Absent ⇒ all-ascending.
+   */
+  orders?: ("asc" | "desc")[];
+  /**
+   * Partial-index predicate (raw SQL, e.g. `delivered_at IS NULL`). Emitted as a
+   * trailing `WHERE (<predicate>)`; compared against the introspected
+   * `pg_get_expr(indpred, …)` after expression normalization. Absent ⇒ full index.
+   */
+  where?: string;
+  /**
+   * Raw key EXPRESSION for a functional/expression index (e.g. `lower((email)::text)`).
+   * When present, the index key is this expression and `columns` is empty —
+   * emitted as `(<expr>)` and compared against the introspected `pg_get_indexdef`
+   * key after normalization.
+   */
+  expr?: string;
+  /**
+   * Index access method (`gin`, `gist`, `hash`, …). Absent / `btree` is the
+   * default and not rendered. Emitted as `USING <method>` before the key list.
+   */
+  using?: string;
 }
 
 export interface CheckDescriptor {