@metaobjectsdev/migrate-ts 0.15.20 → 0.15.21-rc.1

package/src/emit/sqlite.ts

@@ -27,6 +27,10 @@ const STAGE_ORDER: Record<Change["kind"], number> = {
 const RECREATE_TRIGGERING_KINDS = new Set<Change["kind"]>([
   "change-column-type", "change-column-nullable", "change-column-default",
   "add-fk", "drop-fk",
+  // CHECK constraints are create-time-only inline on SQLite (no ALTER … ADD/DROP
+  // CONSTRAINT), so any check change — e.g. an evolved `field.enum @values`
+  // membership — rebuilds the table with the new inline CHECK.
+  "add-check", "drop-check",
 ]);
 
 export function renderSqlite(
@@ -199,16 +203,14 @@ function renderUpNative(c: Change): string {
     case "drop-index":     return `DROP INDEX ${quote(c.index)};`;
     case "add-check":
     case "drop-check":
-      // Declared for future existing-table support; the diff does not yet produce
-      // these (checks are create-time-only, inlined in CREATE TABLE). Unreachable
-      // today — throw rather than silently mis-emit if one ever arrives here.
-      throw new Error("CHECK migration not implemented for sqlite (recreate path pending)");
     case "change-column-type":
     case "change-column-nullable":
     case "change-column-default":
     case "add-fk":
     case "drop-fk":
-      // These are handled by renderRecreate before reaching renderUpNative.
+      // These are handled by renderRecreate before reaching renderUpNative
+      // (checks are create-time-only inline on SQLite, so a check change is a
+      // recreate-triggering kind like the others).
       throw new Error(`renderUpNative: ${c.kind} should have been handled by recreate bundler`);
     // SQLite has no schema namespacing for views and no CREATE OR REPLACE VIEW;
     // a replace is DROP + CREATE. The view body lives in ViewDescriptor.sql.
@@ -237,16 +239,14 @@ function renderDownNative(c: Change): string {
     case "drop-index":     return `-- WARNING: down migration cannot restore the original index definition`;
     case "add-check":
     case "drop-check":
-      // Declared for future existing-table support; the diff does not yet produce
-      // these (checks are create-time-only, inlined in CREATE TABLE). Unreachable
-      // today — throw rather than silently mis-emit if one ever arrives here.
-      throw new Error("CHECK migration not implemented for sqlite (recreate path pending)");
     case "change-column-type":
     case "change-column-nullable":
     case "change-column-default":
     case "add-fk":
     case "drop-fk":
-      // These are handled by renderRecreate before reaching renderDownNative.
+      // These are handled by renderRecreate before reaching renderDownNative
+      // (checks are create-time-only inline on SQLite, so a check change is a
+      // recreate-triggering kind like the others).
       throw new Error(`renderDownNative: ${c.kind} should have been handled by recreate bundler`);
     case "create-view":   return `DROP VIEW IF EXISTS ${quote(c.view.name)};`;
     case "drop-view":     return `-- WARNING: down migration cannot restore the original view definition`;
@@ -272,8 +272,9 @@ function renderCreateTable(t: TableDescriptor): string {
     colDefs.push(clause);
   }
   // CHECK constraints are inlined into the CREATE TABLE DDL (SQLite supports
-  // inline named CHECK). Checks are create-time-only; the diff never produces
-  // add-check / drop-check, so this is the sole place SQLite emits a CHECK.
+  // inline named CHECK) — the sole place SQLite emits a CHECK. A check CHANGE
+  // on an existing table (add-check/drop-check from the diff) triggers
+  // recreate-and-copy, which lands back here with the updated check list.
   for (const chk of t.checks ?? []) {
     colDefs.push(`  CONSTRAINT ${quote(chk.name)} CHECK (${chk.expression})`);
   }
@@ -295,7 +296,7 @@ function renderColumnInline(c: ColumnDescriptor, isSinglePk = false): string {
   if (c.identity === "increment" && isSinglePk) s += " AUTOINCREMENT";
   s += c.nullable ? "" : " NOT NULL";
   if (c.default !== undefined) {
-    s += ` DEFAULT ${renderDefault(c.default)}`;
+    s += ` DEFAULT ${renderDefault(c.default, c.sqlType)}`;
   } else if (c.identity === "uuid") {
     // SQLite has no native uuid(); approximate via lower(hex(randomblob(16))).
     s += " DEFAULT (lower(hex(randomblob(16))))";
@@ -329,14 +330,60 @@ function sqliteType(t: SqlType, identity: ColumnDescriptor["identity"]): string
   }
 }
 
-function renderDefault(d: ColumnDefault): string {
+/** A literal safely emittable unquoted on a numeric-affinity column. */
+const NUMERIC_LITERAL = /^[-+]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][-+]?\d+)?$/;
+
+/**
+ * Render a literal default according to the column's declared SQL type.
+ *
+ * Quoting must NOT be unconditional. SQLite applies the column's affinity when
+ * storing a default: a quoted literal that does not *look* numeric (e.g. `'false'`)
+ * cannot be coerced under NUMERIC/INTEGER affinity, so it is stored verbatim as
+ * TEXT — a mistyped value that a later `col = 0` comparison silently misses.
+ * (A numeric-looking `'0'` *is* coerced, which is exactly why this stayed hidden.)
+ *
+ * SQLite has no boolean literal, so the canonical "true"/"false" become 1/0.
+ * Non-numeric junk on a numeric column still falls back to quoting rather than
+ * emitting bare invalid SQL — the loader should reject it long before here.
+ */
+function renderDefault(d: ColumnDefault, t: SqlType): string {
   if (d.kind === "expr") return d.value;
-  return `'${d.value.replace(/'/g, "''")}'`;
+  const quoted = `'${d.value.replace(/'/g, "''")}'`;
+  switch (t.kind) {
+    case "boolean":
+      if (d.value === "true") return "1";
+      if (d.value === "false") return "0";
+      return NUMERIC_LITERAL.test(d.value) ? d.value : quoted;
+    case "integer":
+    case "real":
+    case "real4":
+    case "numeric":
+      return NUMERIC_LITERAL.test(d.value) ? d.value : quoted;
+    default:
+      return quoted;
+  }
 }
 
 function renderCreateIndex(table: string, ix: IndexDescriptor): string {
   const u = ix.unique ? "UNIQUE " : "";
-  return `CREATE ${u}INDEX ${quote(ix.name)} ON ${quote(table)} (${ix.columns.map(quote).join(", ")});`;
+  // SQLite natively supports expression indexes, per-column DESC, and partial
+  // (WHERE) indexes — render all three. Dropping them is not an option:
+  //   - a dropped @expr leaves `();` (invalid SQL — the apply fails outright);
+  //   - a dropped @where turns a partial UNIQUE into a FULL unique constraint,
+  //     silently rejecting inserts the model says are valid;
+  //   - a dropped DESC churns drop/add on every diff once introspection reads
+  //     the real ordering back.
+  // @using is deliberately NOT rendered: SQLite has exactly one index access
+  // method (b-tree) and no USING clause — a plain index is the closest physical
+  // realization. The expected snapshot strips `using` for sqlite (Pass 3 in
+  // buildExpectedSchema) so the diff stays convergent.
+  const keys = ix.expr
+    ? ix.expr
+    : ix.columns
+        .map((c, i) => (ix.orders?.[i] === "desc" ? `${quote(c)} DESC` : quote(c)))
+        .join(", ");
+  const where = ix.where ? ` WHERE (${ix.where})` : "";
+  return `CREATE ${u}INDEX ${quote(ix.name)} ON ${quote(table)} (${keys})${where};`;
 }
 
 function quote(ident: string): string {

package/src/expected-schema.ts

@@ -152,7 +152,45 @@ export function buildExpectedSchema(
   if (dialect === "sqlite") {
     for (const table of tables) {
       for (const col of table.columns) {
+        const kindBefore = col.sqlType.kind;
         col.sqlType = normalizeForSqlite(col.sqlType);
+        // The default VALUE must be normalized alongside the TYPE, or the three layers
+        // disagree. A boolean column becomes an integer column here, so its canonical
+        // "true"/"false" literal must become "1"/"0" too:
+        //   - leave it as "false" → the emitter sees an integer column with a
+        //     non-numeric literal and quotes it (`DEFAULT 'false'`), which SQLite
+        //     stores as TEXT in a numeric-affinity column, so `WHERE col = 0` silently
+        //     matches nothing;
+        //   - emit `0` while the expected side still says "false" → introspection reads
+        //     back "0", `columnDefaultsEqual` is a strict string compare, and the diff
+        //     reports `change-column-default` forever — which on SQLite means a
+        //     destructive recreate-and-copy of the whole table on EVERY migrate.
+        // Normalizing here keeps expected == emitted == introspected.
+        if (kindBefore === "boolean" && col.default?.kind === "literal") {
+          const normalized = normalizeBooleanLiteralForSqlite(col.default.value);
+          if (normalized !== undefined) col.default = { kind: "literal", value: normalized };
+        }
+        // `now()` is Postgres-only; SQLite has no such function, so a
+        // `DEFAULT now()` (the @autoSet insert-time default, and any authored
+        // @default "now()") makes the emitted CREATE TABLE un-appliable
+        // (`near "(": syntax error`). Normalize to the SQL-standard
+        // CURRENT_TIMESTAMP *here* — not at emit time — so all three layers
+        // agree: emit renders `DEFAULT CURRENT_TIMESTAMP`, sqlite stores that
+        // token verbatim, and introspection reads back the identical expr,
+        // keeping the re-diff empty (an emit-only mapping would report
+        // change-column-default forever → recreate-and-copy on every run).
+        if (col.default?.kind === "expr" && /^now\(\)$/i.test(col.default.value.trim())) {
+          col.default = { kind: "expr", value: "CURRENT_TIMESTAMP" };
+        }
+      }
+      // `@using` names a Postgres index access method (gin/gist/hash/…).
+      // SQLite has exactly ONE access method (b-tree) and no USING clause, so
+      // the attr is physically meaningless there: the emitter cannot render it
+      // and introspection can never read it back. Strip it from the expected
+      // snapshot — the closest physical realization is a plain index — so the
+      // diff converges instead of proposing drop/add on every run.
+      for (const index of table.indexes) {
+        delete index.using;
       }
     }
   }
@@ -181,6 +219,25 @@ export function buildExpectedSchema(
  * sqlite stores all integers (including booleans) as INTEGER, and uses TEXT for
  * date/time/timestamp affinities by default.
  */
+/**
+ * SQLite has no boolean literal: the canonical "true"/"false" become 1/0 so the value
+ * matches the integer column the type is normalized to. Returns undefined for anything
+ * unrecognized (the loader validates coercibility long before here) so we never silently
+ * rewrite a value we don't understand.
+ */
+function normalizeBooleanLiteralForSqlite(value: string): string | undefined {
+  switch (value.trim().toLowerCase()) {
+    case "true":
+    case "1":
+      return "1";
+    case "false":
+    case "0":
+      return "0";
+    default:
+      return undefined;
+  }
+}
+
 function normalizeForSqlite(sqlType: SqlType): SqlType {
   switch (sqlType.kind) {
     case "boolean":
@@ -511,6 +568,14 @@ function buildChecks(
 ): CheckDescriptor[] {
   const checks: CheckDescriptor[] = [];
   for (const field of entity.fields()) {
+    // No field-level CHECKs on array columns: the derived expressions assume a
+    // SCALAR column. `"labels" IN ('A','B')` against a text[] is a type error at
+    // CREATE TABLE; `length(col)`/range checks are equally scalar-shaped. Array
+    // element validation (enum membership, ranges) is enforced app-side (Zod /
+    // per-port validators), matching codegen-ts's column-mapper which also skips
+    // the enum literal-union for isArray columns.
+    // ADR-0039: resolving — array-ness may be inherited via extends.
+    if (field.resolvedIsArray()) continue;
     const col = resolveColumnName(field, strategy);
     const qcol = quoteCheckCol(col);
     // Enum membership check.
@@ -770,17 +835,43 @@ function buildColumn(
 /**
  * The native Postgres array ELEMENT SqlType for an `isArray` scalar field, or
  * undefined when the subtype has no native-array form (object/map → single jsonb
- * column; everything else falls through to the scalar subtype default).
+ * column carrying the JSON array).
  *
- * dbColumnType slim-and-derive Phase 1 wires the two derived cases the design calls
- * out: `field.string` → `text[]`, `field.uuid` → `uuid[]`. This mirrors codegen-ts's
- * column-mapper, which emits native `.array()` for the same scalar subtypes.
+ * MUST agree with codegen-ts's column-mapper, which emits Drizzle `.array()` for
+ * EVERY scalar `@isArray` field on postgres (everything except object/map). When
+ * this mapped only string/uuid, `field.int @isArray` got a SCALAR integer DB
+ * column under an `integer("x").array()` Drizzle column — the first insert
+ * failed (`column "x" is of type integer but expression is of type integer[]`)
+ * with no drift signal, because both diff sides carried the same wrong scalar.
+ *
+ * Elements are deliberately UNQUALIFIED — bare `text` (no maxLength), bare
+ * `numeric` (no precision/scale): information_schema reports NO qualifiers for
+ * array elements (character_maximum_length / numeric_precision are NULL when
+ * data_type = 'ARRAY'; verified on live PG 16), so a qualified expected element
+ * could never converge with introspection and would churn change-column-type on
+ * every run. The element qualifier is a codegen/validation concern, not a
+ * migratable physical property.
  */
 function arrayElementSqlType(field: MetaData): SqlType | undefined {
   switch (field.subType) {
-    case FIELD_SUBTYPE_STRING: return { kind: "text" };
-    case FIELD_SUBTYPE_UUID:   return { kind: "uuid" };
-    default:                   return undefined;
+    case FIELD_SUBTYPE_STRING:
+    case FIELD_SUBTYPE_ENUM:      // enum[] stores as text[]; membership is app-level (no CHECK — see buildChecks)
+    case FIELD_SUBTYPE_URI:       return { kind: "text" };
+    case FIELD_SUBTYPE_UUID:      return { kind: "uuid" };
+    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" };
+    case FIELD_SUBTYPE_FLOAT:     return { kind: "real4" };
+    case FIELD_SUBTYPE_DECIMAL:   return { kind: "numeric" };
+    case FIELD_SUBTYPE_BOOLEAN:   return { kind: "boolean" };
+    case FIELD_SUBTYPE_DATE:      return { kind: "date" };
+    case FIELD_SUBTYPE_TIME:      return { kind: "time" };
+    case FIELD_SUBTYPE_TIMESTAMP:
+      // ADR-0039: resolving — @localTime may be inherited via extends.
+      return { kind: "timestamp", withTimezone: field.attr(FIELD_ATTR_LOCAL_TIME) !== true };
+    case FIELD_SUBTYPE_INET:      return { kind: "inet" };
+    default:                      return undefined; // object/map → single jsonb column
   }
 }
 

package/src/introspect/d1.ts

@@ -2,7 +2,10 @@ import type {
   SchemaSnapshot, TableDescriptor, ColumnDescriptor, SnapshotMeta,
   IndexDescriptor, FkDescriptor, FkAction, ViewDescriptor,
 } from "../types.js";
-import { parseSqliteDefault, sqliteTypeToSqlType, sqliteRuleToAction } from "./sqlite-shared.js";
+import {
+  parseSqliteDefault, sqliteTypeToSqlType, sqliteRuleToAction, parseSqliteChecks,
+  buildSqliteIndexDescriptor,
+} from "./sqlite-shared.js";
 
 /**
  * Runner contract: takes a SQL command string and returns wrangler's raw
@@ -48,8 +51,30 @@ export async function introspectD1(opts: IntrospectD1Options): Promise<SchemaSna
   }
   const meta: SnapshotMeta = { sqliteVersion };
 
+  // Beyond SQLite's own `sqlite_%` and our rename-shadow `__new_%` tables, D1 carries
+  // two infrastructure tables that were never part of the declared schema and must
+  // never reach the diff:
+  //
+  //   `_cf_%`         Cloudflare/miniflare reserved bookkeeping (e.g. `_cf_METADATA`).
+  //                   It appears the moment ANY write touches a local D1, and D1's
+  //                   authorizer then denies even a bare `pragma_table_info` against it
+  //                   (SQLITE_AUTH). Since we call readTableInfo once per enumerated
+  //                   table, leaving it in the list aborts introspection outright — which
+  //                   breaks every second-and-later `meta migrate --dialect d1` (the first
+  //                   migration is the very write that creates it, so it is invisible until
+  //                   the first incremental run).
+  //
+  //   `d1_migrations` wrangler's own migration-tracking table. Queryable, so it doesn't
+  //                   crash — it just reads as an undeclared "extra" table, and the diff
+  //                   then proposes DROP TABLE on wrangler's own bookkeeping.
+  //
+  // Filter in the query, not after: `_cf_METADATA` must never even be fetched.
   const tableRows = await exec(
-    "SELECT name, sql FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '__new_%' ORDER BY name",
+    "SELECT name, sql FROM sqlite_master WHERE type='table'"
+      + " AND name NOT LIKE 'sqlite\\_%' ESCAPE '\\'"
+      + " AND name NOT LIKE '\\_\\_new\\_%' ESCAPE '\\'"
+      + " AND name NOT LIKE '\\_cf\\_%' ESCAPE '\\'"
+      + " AND name != 'd1_migrations' ORDER BY name",
   );
 
   const tables: TableDescriptor[] = [];
@@ -71,7 +96,9 @@ export async function introspectD1(opts: IntrospectD1Options): Promise<SchemaSna
       columns: cols,
       indexes: await readIndexes(exec, name),
       foreignKeys: await readForeignKeys(exec, name),
-      checks: [], // CHECK introspection is out of scope; expected-side derives them
+      // Named CHECKs parsed from the stored CREATE TABLE DDL — required for
+      // check evolution (enum @values changes) to converge on sqlite/D1.
+      checks: parseSqliteChecks(createSql),
       primaryKey: pk,
     });
   }
@@ -129,17 +156,26 @@ function extractPrimaryKey(rows: Record<string, unknown>[]): string[] {
 
 async function readIndexes(exec: Exec, table: string): Promise<IndexDescriptor[]> {
   const list = await exec(`SELECT * FROM pragma_index_list(${sqliteIdent(table)})`);
+  // Stored CREATE INDEX DDL per index — the only catalog for expression keys and
+  // partial-index predicates (mirrors introspectSqlite's readSqliteIndexes).
+  const ddlRows = await exec(
+    `SELECT name, sql FROM sqlite_master WHERE type='index' AND tbl_name = ${sqliteLiteral(table)}`,
+  );
+  const ddlByName = new Map(ddlRows.map((r) => [String(r.name), r.sql === null ? null : String(r.sql)] as const));
   const indexes: IndexDescriptor[] = [];
   for (const ix of list) {
     if (String(ix.origin) === "pk") continue;
-    if (Number(ix.partial) === 1) continue;
     const ixName = String(ix.name);
-    const cols = await exec(`SELECT seqno, cid, name FROM pragma_index_info(${sqliteIdent(ixName)}) ORDER BY seqno`);
-    indexes.push({
-      name: ixName,
-      columns: cols.map((c) => String(c.name)),
-      unique: Number(ix.unique) === 1,
-    });
+    // pragma_index_xinfo: DESC bit + key-vs-auxiliary flag; expression keys have
+    // name NULL (cid -2).
+    const keyRows = await exec(`SELECT * FROM pragma_index_xinfo(${sqliteIdent(ixName)}) ORDER BY seqno`);
+    indexes.push(buildSqliteIndexDescriptor(
+      { name: ixName, unique: Number(ix.unique) === 1, partial: Number(ix.partial) === 1 },
+      keyRows
+        .filter((c) => Number(c.key) === 1)
+        .map((c) => ({ name: c.name === null ? null : String(c.name), desc: Number(c.desc) === 1 })),
+      ddlByName.get(ixName) ?? null,
+    ));
   }
   return indexes;
 }
@@ -181,7 +217,9 @@ async function readViews(exec: Exec): Promise<ViewDescriptor[]> {
   // D1 gets the same view-body drift detection as the kysely sqlite path — the
   // diff's comparator strips the leading CREATE VIEW before comparing bodies.
   const rows = await exec(
-    "SELECT name, sql FROM sqlite_master WHERE type='view' AND name NOT LIKE 'sqlite_%' ORDER BY name",
+    "SELECT name, sql FROM sqlite_master WHERE type='view'"
+      + " AND name NOT LIKE 'sqlite\\_%' ESCAPE '\\'"
+      + " AND name NOT LIKE '\\_cf\\_%' ESCAPE '\\' ORDER BY name",
   );
   return rows.map((r) => {
     const view: ViewDescriptor = { name: String(r.name) };
@@ -201,3 +239,11 @@ function sqliteIdent(name: string): string {
   return `"${name.replace(/"/g, '""')}"`;
 }
 
+/**
+ * Quote a VALUE as a SQL string literal (single quotes, '' escaping) for the
+ * same no-bind-params wrangler constraint sqliteIdent works around.
+ */
+function sqliteLiteral(value: string): string {
+  return `'${value.replace(/'/g, "''")}'`;
+}
+

package/src/introspect/postgres.ts

@@ -200,8 +200,12 @@ export function parsePgDefault(raw: string | null | undefined): ColumnDefault |
   if (raw.startsWith("'")) {
     // Strip the cast suffix (e.g. `::boolean`, `::text`, `::integer`)
     const withoutCast = raw.replace(/::[^']+$/, "");
-    // Strip the surrounding single-quotes
-    const cleaned = withoutCast.replace(/^'(.*)'$/, "$1");
+    // Strip the surrounding single-quotes, then un-double the embedded `''`
+    // escapes PG stores verbatim (e.g. `'don''t'::text`) — without this the
+    // introspected value never equals the expected literal and the diff issues
+    // a bogus SET DEFAULT on every run.
+    const m = /^'(.*)'$/.exec(withoutCast);
+    const cleaned = m !== null ? m[1]!.replace(/''/g, "'") : withoutCast;
     return { kind: "literal", value: cleaned };
   }
 
@@ -239,18 +243,36 @@ async function readTableNames(k: Kysely<any>): Promise<SchemaTableRef[]> {
 }
 
 async function readPgViews(k: RawKysely): Promise<ViewDescriptor[]> {
-  // pg-mem gap: information_schema.views is not supported — the query throws
-  // "relation views does not exist". We catch and return [] so other tests
-  // still pass on pg-mem. Real PG (Postgres 16) handles this correctly.
+  // pg-mem gap: the catalog joins below are not supported — the query throws.
+  // We catch and return [] so other tests still pass on pg-mem. Real PG
+  // (Postgres 16) handles this correctly.
   try {
-    // information_schema.views.view_definition is the SELECT body (not the
-    // full CREATE VIEW statement). We carry it through on the descriptor so the
-    // diff can detect view-body drift (not just name presence).
+    // pg_get_viewdef returns the SELECT body (not the full CREATE VIEW
+    // statement — same shape information_schema.view_definition had). We carry
+    // it through on the descriptor so the diff can detect view-body drift (not
+    // just name presence).
+    //
+    // EXTENSION-OWNED views are excluded (pg_depend deptype 'e'): a view that
+    // `CREATE EXTENSION` installed (e.g. pg_stat_statements drops one into
+    // `public`) belongs to the extension, not the model — reporting it makes
+    // the very next migrate propose `DROP VIEW "pg_stat_statements";`, and
+    // dropping it would break the extension.
     const rows = await sql<{ table_name: string; table_schema: string; view_definition: string | null }>`
-      SELECT table_name, table_schema, view_definition FROM information_schema.views
-      WHERE table_schema NOT IN ('pg_catalog', 'information_schema')
-        AND table_schema NOT LIKE 'pg_%'
-      ORDER BY table_schema, table_name
+      SELECT c.relname AS table_name,
+             n.nspname AS table_schema,
+             pg_get_viewdef(c.oid) AS view_definition
+      FROM pg_class c
+      JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE c.relkind = 'v'
+        AND n.nspname NOT IN ('pg_catalog', 'information_schema')
+        AND n.nspname NOT LIKE 'pg_%'
+        AND NOT EXISTS (
+          SELECT 1 FROM pg_depend d
+          WHERE d.classid = 'pg_class'::regclass
+            AND d.objid = c.oid
+            AND d.deptype = 'e'
+        )
+      ORDER BY n.nspname, c.relname
     `.execute(k);
     return rows.rows.map((r) => {
       const view: ViewDescriptor = { name: r.table_name, schema: r.table_schema };
@@ -258,7 +280,7 @@ async function readPgViews(k: RawKysely): Promise<ViewDescriptor[]> {
       return view;
     });
   } catch {
-    // pg-mem: information_schema.views not supported — return empty view list.
+    // pg-mem: pg_class/pg_depend catalog introspection not supported — return empty view list.
     return [];
   }
 }