@metaobjectsdev/migrate-ts 0.5.0-rc.1

package/src/diff/rename-heuristic.ts

@@ -0,0 +1,265 @@
+import type {
+  Change, AmbiguousCallback, AmbiguousChange, AmbiguousResolution, ColumnDescriptor,
+  TableDescriptor,
+} from "../types.js";
+import type { SqlType } from "../sql-type.js";
+import { sqlTypeEquals } from "../sql-type.js";
+import { DEFAULT_DB_SCHEMA_POSTGRES } from "@metaobjectsdev/metadata";
+
+const TABLE_RENAME_OVERLAP_THRESHOLD = 0.8;
+
+/**
+ * Mutates `changes` in place: detects (drop-table, create-table) pairs whose
+ * column sets have Jaccard similarity ≥ 0.8. Per spec §6.3.
+ *
+ * Must run BEFORE detectColumnRenames so a renamed table's columns aren't
+ * scanned as orphaned drop/add pairs.
+ *
+ * Side-channel: diff() attaches `_columns` to drop-table changes so this
+ * function has access to the dropped table's column list.
+ */
+export async function detectTableRenames(
+  changes: Change[],
+  onAmbiguous: AmbiguousCallback | undefined,
+): Promise<void> {
+  const drops: {
+    idx: number; tableName: string; schema: string | undefined; columns: ColumnDescriptor[];
+  }[] = [];
+  const creates: { idx: number; table: TableDescriptor }[] = [];
+
+  changes.forEach((c, idx) => {
+    if (c.kind === "drop-table") {
+      const aug = c as Change & { _columns?: ColumnDescriptor[] };
+      if (aug._columns) drops.push({ idx, tableName: c.table, schema: c.schema, columns: aug._columns });
+    } else if (c.kind === "create-table") {
+      creates.push({ idx, table: c.table });
+    }
+  });
+
+  if (drops.length === 0 || creates.length === 0) return;
+
+  const indicesToRemove = new Set<number>();
+  const renamesToInsert: { afterIdx: number; change: Change }[] = [];
+
+  for (const drop of drops) {
+    let bestOverlap = 0;
+    let bestCreate: typeof creates[number] | undefined;
+    for (const create of creates) {
+      if (indicesToRemove.has(create.idx)) continue;
+      // Only pair with creates in the SAME schema — cross-schema name collision
+      // is not a rename, it's a distinct entity.
+      if (!sameSchema(drop.schema, create.table.schema)) continue;
+      const overlap = columnSetOverlap(drop.columns, create.table.columns);
+      if (overlap > bestOverlap) {
+        bestOverlap = overlap;
+        bestCreate = create;
+      }
+    }
+    if (!bestCreate || bestOverlap < TABLE_RENAME_OVERLAP_THRESHOLD) continue;
+
+    const q: AmbiguousChange = {
+      kind: "possible-table-rename",
+      from: { name: drop.tableName, columnCount: drop.columns.length },
+      to: { name: bestCreate.table.name, columnCount: bestCreate.table.columns.length },
+      columnOverlap: bestOverlap,
+    };
+    const resolution: AmbiguousResolution = onAmbiguous ? await onAmbiguous(q) : "drop+add";
+    if (resolution === "abort") {
+      throw new Error(
+        `diff aborted by onAmbiguous: possible rename ${drop.tableName} → ${bestCreate.table.name}`,
+      );
+    }
+    if (resolution === "rename") {
+      indicesToRemove.add(drop.idx);
+      indicesToRemove.add(bestCreate.idx);
+      const renameChange: Change = {
+        kind: "rename-table",
+        from: drop.tableName,
+        to: bestCreate.table.name,
+        ...(drop.schema !== undefined ? { schema: drop.schema } : {}),
+        status: { state: "allowed" },
+      };
+      renamesToInsert.push({ afterIdx: drop.idx, change: renameChange });
+    }
+  }
+
+  if (indicesToRemove.size === 0) return;
+
+  const insertByIdx = new Map<number, Change>();
+  for (const r of renamesToInsert) insertByIdx.set(r.afterIdx, r.change);
+  const result: Change[] = [];
+  for (let i = 0; i < changes.length; i++) {
+    if (insertByIdx.has(i)) result.push(insertByIdx.get(i)!);
+    if (!indicesToRemove.has(i)) result.push(changes[i]!);
+  }
+  changes.length = 0;
+  changes.push(...result);
+}
+
+/**
+ * Compare two schema strings, treating undefined as equivalent to "public" (Postgres default).
+ * Used by the table-rename heuristic to avoid pairing drops and creates across schemas.
+ */
+function sameSchema(a: string | undefined, b: string | undefined): boolean {
+  return (a ?? DEFAULT_DB_SCHEMA_POSTGRES) === (b ?? DEFAULT_DB_SCHEMA_POSTGRES);
+}
+
+function columnSetOverlap(a: ColumnDescriptor[], b: ColumnDescriptor[]): number {
+  const aSet = new Set(a.map(colSig));
+  const bSet = new Set(b.map(colSig));
+  let intersection = 0;
+  for (const x of aSet) if (bSet.has(x)) intersection++;
+  const union = aSet.size + bSet.size - intersection;
+  if (union === 0) return 0;
+  return intersection / union;
+}
+
+function colSig(c: ColumnDescriptor): string {
+  return `${c.name}|${c.sqlType.kind}|${c.nullable}`;
+}
+
+/**
+ * Mutates `changes` in place: detects (drop-column 'old', add-column 'new') pairs
+ * on the same table that match the rename heuristic. Per spec §6.2.
+ *
+ * For each candidate: invokes onAmbiguous (default 'drop+add' if absent).
+ * - 'rename'  → replace the pair with a single rename-column Change.
+ * - 'drop+add'→ leave both as-is.
+ * - 'abort'   → throw.
+ */
+export async function detectColumnRenames(
+  changes: Change[],
+  onAmbiguous: AmbiguousCallback | undefined,
+): Promise<void> {
+  // Group drop-columns and add-columns by (schema, table) — same table name in
+  // different schemas must not cross-pair. Key: schema-or-public . table.
+  // Drop-columns carry side-channel _sqlType/_nullable fields added by diff().
+  type TableKey = string;                  // "schema.table"; "public.<n>" if schema undefined
+  type DropEntry = {
+    idx: number; table: string; schema: string | undefined;
+    column: string; sqlType: SqlType; nullable: boolean;
+  };
+  type AddEntry = {
+    idx: number; table: string; schema: string | undefined;
+    column: ColumnDescriptor;
+  };
+  const keyOf = (table: string, schema: string | undefined): TableKey =>
+    (schema ?? DEFAULT_DB_SCHEMA_POSTGRES) + "." + table;
+
+  const dropsByTable = new Map<TableKey, DropEntry[]>();
+  const addsByTable = new Map<TableKey, AddEntry[]>();
+
+  changes.forEach((c, idx) => {
+    if (c.kind === "drop-column") {
+      const aug = c as Change & { _sqlType?: SqlType; _nullable?: boolean };
+      if (aug._sqlType !== undefined && aug._nullable !== undefined) {
+        const k = keyOf(c.table, c.schema);
+        let arr = dropsByTable.get(k);
+        if (!arr) { arr = []; dropsByTable.set(k, arr); }
+        arr.push({
+          idx, table: c.table, schema: c.schema,
+          column: c.column, sqlType: aug._sqlType, nullable: aug._nullable,
+        });
+      }
+    } else if (c.kind === "add-column") {
+      const k = keyOf(c.table, c.schema);
+      let arr = addsByTable.get(k);
+      if (!arr) { arr = []; addsByTable.set(k, arr); }
+      arr.push({ idx, table: c.table, schema: c.schema, column: c.column });
+    }
+  });
+
+  const indicesToRemove = new Set<number>();
+  const renamesToInsert: { afterIdx: number; change: Change }[] = [];
+
+  for (const [k, drops] of dropsByTable) {
+    const adds = addsByTable.get(k) ?? [];
+    for (const drop of drops) {
+      // Find candidate adds matching same sqlType + same nullable + Levenshtein threshold.
+      const candidates = adds.filter((a) =>
+        sqlTypeEquals(a.column.sqlType, drop.sqlType)
+        && a.column.nullable === drop.nullable
+        && withinLevenshteinThreshold(drop.column, a.column.name),
+      );
+      if (candidates.length === 0) continue;
+
+      // Pick the closest candidate (smallest distance).
+      candidates.sort((a, b) =>
+        levenshtein(drop.column, a.column.name) - levenshtein(drop.column, b.column.name),
+      );
+      const winner = candidates[0]!;
+
+      const q: AmbiguousChange = {
+        kind: "possible-column-rename",
+        table: drop.table,
+        from: { name: drop.column, sqlType: drop.sqlType },
+        to: { name: winner.column.name, sqlType: winner.column.sqlType },
+      };
+
+      const resolution: AmbiguousResolution = onAmbiguous
+        ? await onAmbiguous(q)
+        : "drop+add";
+
+      if (resolution === "abort") {
+        throw new Error(
+          `diff aborted by onAmbiguous: possible rename ${drop.table}.${drop.column} → ${drop.table}.${winner.column.name}`,
+        );
+      }
+      if (resolution === "rename") {
+        indicesToRemove.add(drop.idx);
+        indicesToRemove.add(winner.idx);
+        const renameChange: Change = {
+          kind: "rename-column",
+          table: drop.table,
+          ...(drop.schema !== undefined ? { schema: drop.schema } : {}),
+          from: drop.column,
+          to: winner.column.name,
+          status: { state: "allowed" },
+        };
+        renamesToInsert.push({ afterIdx: drop.idx, change: renameChange });
+        // Remove winner from adds so it isn't paired again.
+        const wIdx = adds.indexOf(winner);
+        if (wIdx >= 0) adds.splice(wIdx, 1);
+      }
+      // 'drop+add' → no-op
+    }
+  }
+
+  if (indicesToRemove.size === 0) return;
+
+  // Build new array: filter out removed, insert renames at the right positions.
+  const insertByIdx = new Map<number, Change>();
+  for (const r of renamesToInsert) insertByIdx.set(r.afterIdx, r.change);
+
+  const result: Change[] = [];
+  for (let i = 0; i < changes.length; i++) {
+    if (insertByIdx.has(i)) result.push(insertByIdx.get(i)!);  // insert rename in place of drop
+    if (!indicesToRemove.has(i)) result.push(changes[i]!);
+  }
+  changes.length = 0;
+  changes.push(...result);
+}
+
+function withinLevenshteinThreshold(a: string, b: string): boolean {
+  const minLen = Math.min(a.length, b.length);
+  const threshold = Math.max(2, Math.floor(minLen / 3));
+  return levenshtein(a, b) <= threshold;
+}
+
+function levenshtein(a: string, b: string): number {
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  let prev = new Array<number>(b.length + 1).fill(0);
+  let curr = new Array<number>(b.length + 1).fill(0);
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1]! + 1, prev[j]! + 1, prev[j - 1]! + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[b.length]!;
+}

package/src/diff/status.ts

@@ -0,0 +1,55 @@
+import type { Change, AllowOptions } from "../types.js";
+import { isWidening } from "../sql-type.js";
+
+/**
+ * Mutates each Change's `status` field per the rules in spec §6.5.
+ * Destructive/lossy changes default to blocked unless the corresponding
+ * `allow.*` flag is set.
+ */
+export function applyStatus(changes: Change[], allow: AllowOptions = {}): void {
+  for (const c of changes) {
+    const blockedReason = blockedReasonFor(c, allow);
+    if (blockedReason !== null) {
+      c.status = { state: "blocked", blockedReason };
+    } else {
+      c.status = { state: "allowed" };
+    }
+  }
+}
+
+function blockedReasonFor(c: Change, allow: AllowOptions): string | null {
+  switch (c.kind) {
+    case "drop-column":
+      return allow.dropColumn ? null : "destructive: drop-column not allowed (pass allow.dropColumn)";
+    case "drop-table":
+      return allow.dropTable ? null : "destructive: drop-table not allowed (pass allow.dropTable)";
+    case "drop-index":
+      return allow.dropIndex ? null : "destructive: drop-index not allowed (pass allow.dropIndex)";
+    case "drop-fk":
+      return allow.dropFk ? null : "destructive: drop-fk not allowed (pass allow.dropFk)";
+
+    case "change-column-type":
+      if (isWidening(c.from, c.to)) return null;     // widening always allowed
+      return allow.typeChange ? null : "lossy type change (pass allow.typeChange)";
+
+    case "change-column-nullable":
+      // from = actual.nullable, to = expected.nullable
+      // notnull (false) → nullable (true): allowed
+      // nullable (true) → notnull (false): requires flag (existing data must satisfy)
+      if (c.from === false && c.to === true) return null;
+      return allow.nullableToNotNull ? null : "nullable→notnull requires existing data to satisfy (pass allow.nullableToNotNull)";
+
+    // Always-allowed kinds
+    case "create-table":
+    case "rename-table":
+    case "add-column":
+    case "rename-column":
+    case "change-column-default":
+    case "add-index":
+    case "add-fk":
+    case "create-view":
+    case "drop-view":
+    case "replace-view":
+      return null;
+  }
+}

package/src/emit/index.ts

@@ -0,0 +1,38 @@
+import type { Change, EmitResult, Dialect, SchemaSnapshot, SnapshotMeta } from "../types.js";
+import { BlockedChangesError } from "../errors.js";
+import { renderPostgres } from "./postgres.js";
+import { renderSqlite } from "./sqlite.js";
+
+export interface EmitOptions {
+  dialect: Dialect;
+  /**
+   * Required when dialect="sqlite" AND any change triggers recreate-and-copy
+   * (change-column-type, change-column-nullable, change-column-default, add-fk, drop-fk).
+   * Used to look up the post-migration table descriptor for the recreate recipe.
+   */
+  expectedSchema?: SchemaSnapshot;
+  /**
+   * Per spec §7.4: if SQLite version < 3.35 (DROP COLUMN) or < 3.25 (RENAME COLUMN),
+   * fall back to recreate-and-copy. Unknown/absent version → assume modern.
+   */
+  actualMeta?: SnapshotMeta;
+}
+
+const VIEW_KINDS = new Set<Change["kind"]>(["create-view", "drop-view", "replace-view"]);
+
+export function emit(changes: Change[], opts: EmitOptions): EmitResult {
+  const blocked = changes.filter((c) => c.status.state === "blocked");
+  if (blocked.length > 0) throw new BlockedChangesError(blocked);
+
+  const viewChanges = changes.filter((c) => VIEW_KINDS.has(c.kind));
+  if (viewChanges.length > 0) {
+    throw new Error(
+      `view migration not implemented in v0.1 (${viewChanges.length} view-targeting change(s); deferred to v0.3)`,
+    );
+  }
+
+  switch (opts.dialect) {
+    case "postgres": return renderPostgres(changes);
+    case "sqlite":   return renderSqlite(changes, opts.expectedSchema, opts.actualMeta);
+  }
+}

package/src/emit/postgres.ts

@@ -0,0 +1,189 @@
+import type {
+  Change, EmitResult, ColumnDescriptor, IndexDescriptor, FkDescriptor,
+  TableDescriptor, ColumnDefault, FkAction,
+} from "../types.js";
+import type { SqlType } from "../sql-type.js";
+import { DEFAULT_DB_SCHEMA_POSTGRES } from "@metaobjectsdev/metadata";
+
+const STAGE_ORDER: Record<Change["kind"], number> = {
+  "create-table": 1,
+  "add-column": 2, "drop-column": 2,
+  "change-column-type": 2, "change-column-nullable": 2, "change-column-default": 2,
+  "rename-column": 3, "rename-table": 3,
+  "add-index": 4, "drop-index": 4,
+  "add-fk": 5, "drop-fk": 5,
+  "drop-table": 6,
+  // view kinds — never reach here (filtered in emit())
+  "create-view": 99, "drop-view": 99, "replace-view": 99,
+};
+
+export function renderPostgres(changes: Change[]): EmitResult {
+  const sorted = [...changes].sort((a, b) => STAGE_ORDER[a.kind] - STAGE_ORDER[b.kind]);
+  const upStmts: string[] = [];
+  const downStmts: string[] = [];
+  for (const c of sorted) {
+    upStmts.push(renderUp(c));
+    downStmts.push(renderDown(c));
+  }
+  // Down runs in reverse order (so creates undo correctly w.r.t. FKs).
+  return {
+    up: upStmts.join("\n\n"),
+    down: [...downStmts].reverse().join("\n\n"),
+    recreatedTables: new Set(), // postgres alters in place; no recreate-and-copy
+  };
+}
+
+function renderUp(c: Change): string {
+  switch (c.kind) {
+    case "create-table":           return renderCreateTable(c.table);
+    case "drop-table":             return `DROP TABLE ${quoteQualified(c.table, c.schema)};`;
+    case "rename-table":           return `ALTER TABLE ${quoteQualified(c.from, c.schema)} RENAME TO ${quote(c.to)};`;
+    case "add-column":             return `ALTER TABLE ${quoteQualified(c.table, c.schema)} ADD COLUMN ${renderColumn(c.column)};`;
+    case "drop-column":            return `ALTER TABLE ${quoteQualified(c.table, c.schema)} DROP COLUMN ${quote(c.column)};`;
+    case "rename-column":          return `ALTER TABLE ${quoteQualified(c.table, c.schema)} RENAME COLUMN ${quote(c.from)} TO ${quote(c.to)};`;
+    case "change-column-type":     return `ALTER TABLE ${quoteQualified(c.table, c.schema)} ALTER COLUMN ${quote(c.column)} TYPE ${pgType(c.to)};`;
+    case "change-column-nullable":
+      return c.to
+        ? `ALTER TABLE ${quoteQualified(c.table, c.schema)} ALTER COLUMN ${quote(c.column)} DROP NOT NULL;`
+        : `ALTER TABLE ${quoteQualified(c.table, c.schema)} ALTER COLUMN ${quote(c.column)} SET NOT NULL;`;
+    case "change-column-default":
+      return c.to !== undefined
+        ? `ALTER TABLE ${quoteQualified(c.table, c.schema)} ALTER COLUMN ${quote(c.column)} SET DEFAULT ${renderDefault(c.to)};`
+        : `ALTER TABLE ${quoteQualified(c.table, c.schema)} ALTER COLUMN ${quote(c.column)} DROP DEFAULT;`;
+    case "add-index":              return renderCreateIndex(c.table, c.schema, c.index);
+    case "drop-index":             return `DROP INDEX ${quoteIndexQualified(c.index, c.schema)};`;
+    case "add-fk":                 return renderAddFk(c.table, c.schema, c.fk);
+    case "drop-fk":                return `ALTER TABLE ${quoteQualified(c.table, c.schema)} DROP CONSTRAINT ${quote(c.fk)};`;
+    case "create-view":
+    case "drop-view":
+    case "replace-view":
+      // emit() filters these; defensive throw if reached.
+      throw new Error(`unexpected view-kind in renderPostgres: ${c.kind}`);
+  }
+}
+
+function renderDown(c: Change): string {
+  switch (c.kind) {
+    case "create-table":           return `DROP TABLE ${quoteQualified(c.table.name, c.table.schema)};`;
+    case "drop-table":             return `-- WARNING: down migration cannot restore data\n-- TODO: restore table "${c.table}" structure manually`;
+    case "rename-table":           return `ALTER TABLE ${quoteQualified(c.to, c.schema)} RENAME TO ${quote(c.from)};`;
+    case "add-column":             return `ALTER TABLE ${quoteQualified(c.table, c.schema)} DROP COLUMN ${quote(c.column.name)};`;
+    case "drop-column":            return `-- WARNING: down migration cannot restore data\n-- TODO: re-add dropped column "${c.column}" manually with original type/nullable/default`;
+    case "rename-column":          return `ALTER TABLE ${quoteQualified(c.table, c.schema)} RENAME COLUMN ${quote(c.to)} TO ${quote(c.from)};`;
+    case "change-column-type":     return `ALTER TABLE ${quoteQualified(c.table, c.schema)} ALTER COLUMN ${quote(c.column)} TYPE ${pgType(c.from)};`;
+    case "change-column-nullable":
+      return c.from
+        ? `ALTER TABLE ${quoteQualified(c.table, c.schema)} ALTER COLUMN ${quote(c.column)} DROP NOT NULL;`
+        : `ALTER TABLE ${quoteQualified(c.table, c.schema)} ALTER COLUMN ${quote(c.column)} SET NOT NULL;`;
+    case "change-column-default":
+      return c.from !== undefined
+        ? `ALTER TABLE ${quoteQualified(c.table, c.schema)} ALTER COLUMN ${quote(c.column)} SET DEFAULT ${renderDefault(c.from)};`
+        : `ALTER TABLE ${quoteQualified(c.table, c.schema)} ALTER COLUMN ${quote(c.column)} DROP DEFAULT;`;
+    case "add-index":              return `DROP INDEX ${quoteIndexQualified(c.index.name, c.schema)};`;
+    case "drop-index":             return `-- WARNING: down migration cannot restore the original index definition`;
+    case "add-fk":                 return `ALTER TABLE ${quoteQualified(c.table, c.schema)} DROP CONSTRAINT ${quote(c.fk.name)};`;
+    case "drop-fk":                return `-- WARNING: down migration cannot restore the original FK definition`;
+    case "create-view":
+    case "drop-view":
+    case "replace-view":
+      throw new Error(`unexpected view-kind in renderPostgres: ${c.kind}`);
+  }
+}
+
+function renderCreateTable(t: TableDescriptor): string {
+  const colDefs = t.columns.map((c) => `  ${renderColumn(c)}`);
+  if (t.primaryKey.length > 0) {
+    colDefs.push(`  CONSTRAINT ${quote(t.name + "_pkey")} PRIMARY KEY (${t.primaryKey.map(quote).join(", ")})`);
+  }
+  return `CREATE TABLE ${quoteQualified(t.name, t.schema)} (\n${colDefs.join(",\n")}\n);`;
+}
+
+function renderColumn(c: ColumnDescriptor): string {
+  let s = `${quote(c.name)} ${pgType(c.sqlType)}`;
+  if (c.identity === "increment") s += " GENERATED BY DEFAULT AS IDENTITY";
+  if (c.identity === "uuid")      s += " DEFAULT gen_random_uuid()";
+  s += c.nullable ? "" : " NOT NULL";
+  if (c.default !== undefined && c.identity !== "uuid") {
+    // For uuid identity we already set DEFAULT gen_random_uuid(); don't duplicate.
+    s += ` DEFAULT ${renderDefault(c.default)}`;
+  }
+  return s;
+}
+
+function pgType(t: SqlType): string {
+  switch (t.kind) {
+    case "text":      return t.maxLength !== undefined ? `VARCHAR(${t.maxLength})` : "TEXT";
+    case "integer":   return t.bits === 64 ? "BIGINT" : "INTEGER";
+    case "real":      return "DOUBLE PRECISION";
+    case "numeric":   {
+      if (t.precision !== undefined && t.scale !== undefined) return `NUMERIC(${t.precision},${t.scale})`;
+      if (t.precision !== undefined) return `NUMERIC(${t.precision})`;
+      return "NUMERIC";
+    }
+    case "boolean":   return "BOOLEAN";
+    case "timestamp": return t.withTimezone ? "TIMESTAMPTZ" : "TIMESTAMP";
+    case "date":      return "DATE";
+    case "json":      return "JSONB";
+    case "blob":      return "BYTEA";
+    case "uuid":      return "UUID";
+  }
+}
+
+function renderDefault(d: ColumnDefault): string {
+  if (d.kind === "expr") return d.value;
+  // Literal: quote string-form values.
+  return `'${d.value.replace(/'/g, "''")}'`;
+}
+
+function renderCreateIndex(table: string, schema: string | undefined, ix: IndexDescriptor): string {
+  const u = ix.unique ? "UNIQUE " : "";
+  // Index name itself is unqualified in CREATE INDEX (Postgres places the index
+  // in the same schema as the table being indexed). Only the ON clause needs qualification.
+  return `CREATE ${u}INDEX ${quote(ix.name)} ON ${quoteQualified(table, schema)} (${ix.columns.map(quote).join(", ")});`;
+}
+
+function renderAddFk(table: string, schema: string | undefined, fk: FkDescriptor): string {
+  let s = `ALTER TABLE ${quoteQualified(table, schema)} ADD CONSTRAINT ${quote(fk.name)} `;
+  s += `FOREIGN KEY (${fk.columns.map(quote).join(", ")}) `;
+  // v1 limitation: FkDescriptor does not carry the ref-table's schema today.
+  // Assume the referenced table lives in the same schema as the FK-owner.
+  // For cross-schema FKs, add `refSchema?` to FkDescriptor in a follow-up.
+  s += `REFERENCES ${quoteQualified(fk.refTable, schema)} (${fk.refColumns.map(quote).join(", ")})`;
+  if (fk.onDelete) s += ` ON DELETE ${fkActionSql(fk.onDelete)}`;
+  if (fk.onUpdate) s += ` ON UPDATE ${fkActionSql(fk.onUpdate)}`;
+  return s + ";";
+}
+
+function fkActionSql(a: FkAction): string {
+  switch (a) {
+    case "cascade":   return "CASCADE";
+    case "set-null":  return "SET NULL";
+    case "restrict":  return "RESTRICT";
+    case "no-action": return "NO ACTION";
+  }
+}
+
+function quote(ident: string): string {
+  // Conservative double-quoting; reject embedded quotes (defense).
+  if (ident.includes('"')) throw new Error(`unsafe identifier: ${ident}`);
+  return `"${ident}"`;
+}
+
+/**
+ * Quote a table identifier, prefixing the schema when non-default. The Postgres
+ * default schema is `public`; undefined and "public" both mean "no prefix needed."
+ */
+function quoteQualified(table: string, schema: string | undefined): string {
+  if (!schema || schema === DEFAULT_DB_SCHEMA_POSTGRES) return quote(table);
+  return quote(schema) + "." + quote(table);
+}
+
+/**
+ * Quote an index identifier for DROP INDEX, prefixing the schema when non-default.
+ * In Postgres, indexes live in the same schema as their owning table; DROP INDEX
+ * accepts the qualified form `"schema"."index"`.
+ */
+function quoteIndexQualified(index: string, schema: string | undefined): string {
+  if (!schema || schema === DEFAULT_DB_SCHEMA_POSTGRES) return quote(index);
+  return quote(schema) + "." + quote(index);
+}