@vibeorm/migrate 1.0.0

package/src/schema-differ.ts

@@ -0,0 +1,673 @@
+/**
+ * Schema Differ — Diff Two Schema IRs → Migration Operations
+ *
+ * Compares a "previous" and "current" Schema IR and produces
+ * an ordered list of DDL operations to migrate between them.
+ */
+
+import type {
+  Schema,
+  Model,
+  Field,
+  ScalarField,
+  EnumField,
+  RelationField,
+  Enum,
+  UniqueConstraint,
+  IndexDefinition,
+} from "@vibeorm/parser";
+import { PRISMA_TO_PG } from "@vibeorm/parser";
+
+// ─── Types ────────────────────────────────────────────────────────
+
+export type DiffOperationType =
+  | "createEnum"
+  | "addEnumValue"
+  | "removeEnumValue"
+  | "dropEnum"
+  | "createTable"
+  | "dropTable"
+  | "addColumn"
+  | "dropColumn"
+  | "alterColumnType"
+  | "alterColumnNullability"
+  | "alterColumnDefault"
+  | "addUnique"
+  | "dropUnique"
+  | "addIndex"
+  | "dropIndex"
+  | "addForeignKey"
+  | "dropForeignKey"
+  | "createJoinTable"
+  | "dropJoinTable";
+
+export type DiffOperation = {
+  type: DiffOperationType;
+  sql: string;
+  isDestructive: boolean;
+  description: string;
+};
+
+// ─── Helpers ──────────────────────────────────────────────────────
+
+function q(params: { name: string }): string {
+  return `"${params.name}"`;
+}
+
+function getScalarFields(params: { model: Model }): (ScalarField | EnumField)[] {
+  return params.model.fields.filter(
+    (f): f is ScalarField | EnumField => f.kind === "scalar" || f.kind === "enum"
+  );
+}
+
+function getRelationFields(params: { model: Model }): RelationField[] {
+  return params.model.fields.filter((f): f is RelationField => f.kind === "relation");
+}
+
+function resolveColumnType(params: { field: ScalarField | EnumField; enums: Enum[] }): string {
+  const { field, enums } = params;
+  if (field.kind === "enum") {
+    const enumDef = enums.find((e) => e.name === field.enumName);
+    return q({ name: enumDef?.dbName ?? field.enumName });
+  }
+  if (field.default?.kind === "autoincrement") {
+    return field.prismaType === "BigInt" ? "BIGSERIAL" : "SERIAL";
+  }
+  if (field.nativeType) return field.nativeType;
+  if (field.isList) return `${PRISMA_TO_PG[field.prismaType]}[]`;
+  return PRISMA_TO_PG[field.prismaType];
+}
+
+/** Resolve to the base column type (no SERIAL — used for FK reference columns in join tables) */
+function resolveBaseColumnType(params: { field: ScalarField | EnumField; enums: Enum[] }): string {
+  const { field, enums } = params;
+  if (field.kind === "enum") {
+    const enumDef = enums.find((e) => e.name === field.enumName);
+    return q({ name: enumDef?.dbName ?? field.enumName });
+  }
+  if (field.nativeType) return field.nativeType;
+  if (field.isList) return `${PRISMA_TO_PG[field.prismaType]}[]`;
+  return PRISMA_TO_PG[field.prismaType];
+}
+
+function resolveDefault(params: { field: ScalarField | EnumField }): string | undefined {
+  const { field } = params;
+  const def = field.default;
+  if (!def) return undefined;
+  switch (def.kind) {
+    case "autoincrement": return undefined;
+    case "now": return "CURRENT_TIMESTAMP";
+    case "uuid": return "gen_random_uuid()::TEXT";
+    case "cuid": return undefined;
+    case "nanoid": return undefined;
+    case "ulid": return undefined;
+    case "dbgenerated": return def.value;
+    case "literal": {
+      const val = def.value;
+      if (typeof val === "string") return `'${val.replace(/'/g, "''")}'`;
+      if (typeof val === "boolean") return val ? "true" : "false";
+      return String(val);
+    }
+    default: return undefined;
+  }
+}
+
+function uniqueKey(params: { uc: UniqueConstraint; model: Model }): string {
+  return params.uc.fields
+    .map((f: string) => resolveFieldDbName({ model: params.model, fieldName: f }))
+    .sort()
+    .join(",");
+}
+
+function indexKey(params: { idx: IndexDefinition; model: Model }): string {
+  return params.idx.fields
+    .map((f: string) => resolveFieldDbName({ model: params.model, fieldName: f }))
+    .sort()
+    .join(",");
+}
+
+function fkKey(params: { rel: RelationField; model: Model; allModels: Model[] }): string {
+  const { rel, model, allModels } = params;
+  const resolvedFields = rel.relation.fields
+    .map((f: string) => resolveFieldDbName({ model, fieldName: f }))
+    .join(",");
+  const relatedModel = allModels.find((m: Model) => m.name === rel.relatedModel);
+  const relatedTableName = relatedModel?.dbName ?? rel.relatedModel;
+  const resolvedRefs = rel.relation.references
+    .map((f: string) => {
+      if (relatedModel) return resolveFieldDbName({ model: relatedModel, fieldName: f });
+      return f;
+    })
+    .join(",");
+  return `${resolvedFields}->${relatedTableName}.${resolvedRefs}`;
+}
+
+/** Resolve a logical field name to its dbName by looking up the model's fields. */
+function resolveFieldDbName(params: { model: Model; fieldName: string }): string {
+  const { model, fieldName } = params;
+  const field = model.fields.find((f: Field) => f.name === fieldName);
+  if (field && field.kind !== "relation") return field.dbName;
+  return fieldName;
+}
+
+// ─── Implicit M:N Detection ──────────────────────────────────────
+
+type JoinTableInfo = {
+  modelA: string;
+  modelB: string;
+  tableName: string;
+};
+
+function detectImplicitManyToMany(params: { schema: Schema }): JoinTableInfo[] {
+  const { schema } = params;
+  const result: JoinTableInfo[] = [];
+  const seen = new Set<string>();
+
+  for (const model of schema.models) {
+    for (const field of model.fields) {
+      if (field.kind !== "relation") continue;
+      if (!field.isList) continue;
+      if (field.relation.isForeignKey) continue;
+      if (field.relation.fields.length > 0) continue;
+
+      const relatedModel = schema.models.find((m: Model) => m.name === field.relatedModel);
+      if (!relatedModel) continue;
+
+      const backRef = relatedModel.fields.find(
+        (f: Field) =>
+          f.kind === "relation" &&
+          f.relatedModel === model.name &&
+          f.isList &&
+          !f.relation.isForeignKey &&
+          f.relation.fields.length === 0
+      );
+      if (!backRef) continue;
+
+      const sorted = [model.name, relatedModel.name].sort();
+      const nameA = sorted[0]!;
+      const nameB = sorted[1]!;
+      const key = `${nameA}_${nameB}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      result.push({
+        modelA: nameA,
+        modelB: nameB,
+        tableName: `_${nameA}To${nameB}`,
+      });
+    }
+  }
+
+  return result;
+}
+
+// ─── Main Differ ──────────────────────────────────────────────────
+
+export function diffSchemas(params: { previous: Schema; current: Schema }): DiffOperation[] {
+  const { previous, current } = params;
+  const ops: DiffOperation[] = [];
+
+  // Match models by dbName so that @@map("table_name") models match introspected models
+  const prevModelMap = new Map(previous.models.map((m: Model) => [m.dbName, m]));
+  const currModelMap = new Map(current.models.map((m: Model) => [m.dbName, m]));
+  const prevEnumMap = new Map(previous.enums.map((e: Enum) => [e.dbName ?? e.name, e]));
+  const currEnumMap = new Map(current.enums.map((e: Enum) => [e.dbName ?? e.name, e]));
+
+  // ─── Enum Diffs ───────────────────────────────────────────────
+
+  // New enums
+  for (const [name, enumDef] of currEnumMap) {
+    if (!prevEnumMap.has(name)) {
+      const typeName = enumDef.dbName ?? enumDef.name;
+      const values = enumDef.values
+        .map((v) => `'${(v.dbName ?? v.name).replace(/'/g, "''")}'`)
+        .join(", ");
+      ops.push({
+        type: "createEnum",
+        sql: `DO $$ BEGIN\n  CREATE TYPE ${q({ name: typeName })} AS ENUM (${values});\nEXCEPTION WHEN duplicate_object THEN NULL;\nEND $$;`,
+        isDestructive: false,
+        description: `Create enum type "${name}"`,
+      });
+    }
+  }
+
+  // Dropped enums
+  for (const [name, enumDef] of prevEnumMap) {
+    if (!currEnumMap.has(name)) {
+      const typeName = enumDef.dbName ?? enumDef.name;
+      ops.push({
+        type: "dropEnum",
+        sql: `DROP TYPE IF EXISTS ${q({ name: typeName })};`,
+        isDestructive: true,
+        description: `Drop enum type "${name}"`,
+      });
+    }
+  }
+
+  // Modified enums (added/removed values)
+  for (const [name, currEnum] of currEnumMap) {
+    const prevEnum = prevEnumMap.get(name);
+    if (!prevEnum) continue;
+
+    const typeName = currEnum.dbName ?? currEnum.name;
+    const prevValues = new Set(prevEnum.values.map((v) => v.name));
+    const currValues = new Set(currEnum.values.map((v) => v.name));
+
+    // Added values
+    for (const val of currEnum.values) {
+      if (!prevValues.has(val.name)) {
+        const dbVal = val.dbName ?? val.name;
+        ops.push({
+          type: "addEnumValue",
+          sql: `ALTER TYPE ${q({ name: typeName })} ADD VALUE IF NOT EXISTS '${dbVal.replace(/'/g, "''")}';`,
+          isDestructive: false,
+          description: `Add value "${val.name}" to enum "${name}"`,
+        });
+      }
+    }
+
+    // Removed values (destructive — PG doesn't support DROP VALUE easily)
+    for (const val of prevEnum.values) {
+      if (!currValues.has(val.name)) {
+        ops.push({
+          type: "removeEnumValue",
+          sql: `-- WARNING: PostgreSQL does not support removing enum values directly.\n-- You need to recreate the type. Value "${val.name}" removed from enum "${name}".`,
+          isDestructive: true,
+          description: `Remove value "${val.name}" from enum "${name}" (requires type recreation)`,
+        });
+      }
+    }
+  }
+
+  // ─── Table Diffs ──────────────────────────────────────────────
+
+  // New tables
+  for (const [name, model] of currModelMap) {
+    if (prevModelMap.has(name)) continue;
+
+    const tableName = model.dbName;
+    const columns: string[] = [];
+
+    for (const field of getScalarFields({ model })) {
+      const colName = field.dbName;
+      const colType = resolveColumnType({ field, enums: current.enums });
+      let colDef = `  ${q({ name: colName })} ${colType}`;
+
+      if (field.kind === "scalar" && field.isRequired && field.default?.kind !== "autoincrement") {
+        colDef += " NOT NULL";
+      } else if (field.kind === "enum" && field.isRequired) {
+        colDef += " NOT NULL";
+      }
+
+      const defaultExpr = resolveDefault({ field });
+      if (defaultExpr) colDef += ` DEFAULT ${defaultExpr}`;
+      if (field.isUnique) colDef += " UNIQUE";
+      columns.push(colDef);
+    }
+
+    const pkFields = model.primaryKey.fields
+      .map((f: string) => {
+        const fld = model.fields.find((mf: Field) => mf.name === f);
+        if (fld && fld.kind !== "relation") return q({ name: fld.dbName });
+        return q({ name: f });
+      })
+      .join(", ");
+
+    columns.push(`  CONSTRAINT ${q({ name: `${tableName}_pkey` })} PRIMARY KEY (${pkFields})`);
+
+    ops.push({
+      type: "createTable",
+      sql: `CREATE TABLE ${q({ name: tableName })} (\n${columns.join(",\n")}\n);`,
+      isDestructive: false,
+      description: `Create table "${name}"`,
+    });
+  }
+
+  // Unique constraints, indexes, and foreign keys for new tables
+  for (const [name, model] of currModelMap) {
+    if (prevModelMap.has(name)) continue;
+
+    const tableName = model.dbName;
+
+    // Composite unique constraints
+    for (const uc of model.uniqueConstraints) {
+      const cols = uc.fields.map((f: string) => q({ name: resolveFieldDbName({ model, fieldName: f }) })).join(", ");
+      const resolvedFieldNames = uc.fields.map((f: string) => resolveFieldDbName({ model, fieldName: f }));
+      const idxName = uc.name ?? `${tableName}_${resolvedFieldNames.join("_")}_key`;
+      ops.push({
+        type: "addUnique",
+        sql: `CREATE UNIQUE INDEX ${q({ name: idxName })} ON ${q({ name: tableName })} (${cols});`,
+        isDestructive: false,
+        description: `Add unique constraint on (${uc.fields.join(", ")}) in "${name}"`,
+      });
+    }
+
+    // Regular indexes
+    for (const idx of model.indexes) {
+      const cols = idx.fields.map((f: string) => q({ name: resolveFieldDbName({ model, fieldName: f }) })).join(", ");
+      const resolvedFieldNames = idx.fields.map((f: string) => resolveFieldDbName({ model, fieldName: f }));
+      const idxName = idx.name ?? `${tableName}_${resolvedFieldNames.join("_")}_idx`;
+      ops.push({
+        type: "addIndex",
+        sql: `CREATE INDEX ${q({ name: idxName })} ON ${q({ name: tableName })} (${cols});`,
+        isDestructive: false,
+        description: `Add index on (${idx.fields.join(", ")}) in "${name}"`,
+      });
+    }
+
+    // Foreign keys
+    const fkRels = getRelationFields({ model })
+      .filter((r: RelationField) => r.relation.isForeignKey && r.relation.fields.length > 0);
+    for (const rel of fkRels) {
+      const fkCols = rel.relation.fields.map((f: string) => q({ name: resolveFieldDbName({ model, fieldName: f }) })).join(", ");
+      const relatedModel = current.models.find((m: Model) => m.name === rel.relatedModel);
+      const relatedTableName = relatedModel?.dbName ?? rel.relatedModel;
+      const refCols = rel.relation.references.map((f: string) => {
+        if (relatedModel) return q({ name: resolveFieldDbName({ model: relatedModel, fieldName: f }) });
+        return q({ name: f });
+      }).join(", ");
+      const resolvedFkNames = rel.relation.fields.map((f: string) => resolveFieldDbName({ model, fieldName: f }));
+      const constraintName = `${tableName}_${resolvedFkNames.join("_")}_fkey`;
+      ops.push({
+        type: "addForeignKey",
+        sql: `ALTER TABLE ${q({ name: tableName })} ADD CONSTRAINT ${q({ name: constraintName })} FOREIGN KEY (${fkCols}) REFERENCES ${q({ name: relatedTableName })} (${refCols}) ON DELETE RESTRICT ON UPDATE CASCADE;`,
+        isDestructive: false,
+        description: `Add foreign key on "${name}" (${rel.relation.fields.join(", ")}) \u2192 "${rel.relatedModel}"`,
+      });
+    }
+  }
+
+  // Dropped tables
+  for (const [name, model] of prevModelMap) {
+    if (currModelMap.has(name)) continue;
+    ops.push({
+      type: "dropTable",
+      sql: `DROP TABLE IF EXISTS ${q({ name: model.dbName })} CASCADE;`,
+      isDestructive: true,
+      description: `Drop table "${name}"`,
+    });
+  }
+
+  // ─── Column Diffs (for surviving models) ──────────────────────
+
+  for (const [name, currModel] of currModelMap) {
+    const prevModel = prevModelMap.get(name);
+    if (!prevModel) continue; // New table, already handled
+
+    const tableName = currModel.dbName;
+    const prevFields = new Map(
+      getScalarFields({ model: prevModel }).map((f) => [f.dbName, f])
+    );
+    const currFields = new Map(
+      getScalarFields({ model: currModel }).map((f) => [f.dbName, f])
+    );
+
+    // Added columns
+    for (const [fieldName, field] of currFields) {
+      if (prevFields.has(fieldName)) continue;
+
+      const colName = field.dbName;
+      const colType = resolveColumnType({ field, enums: current.enums });
+      const defaultExpr = resolveDefault({ field });
+
+      // Safe if nullable or has default
+      const isDestructive = field.isRequired && !defaultExpr;
+
+      let colDef = `${colType}`;
+      if (field.kind === "scalar" && field.isRequired && field.default?.kind !== "autoincrement") {
+        colDef += " NOT NULL";
+      } else if (field.kind === "enum" && field.isRequired) {
+        colDef += " NOT NULL";
+      }
+      if (defaultExpr) colDef += ` DEFAULT ${defaultExpr}`;
+
+      ops.push({
+        type: "addColumn",
+        sql: `ALTER TABLE ${q({ name: tableName })} ADD COLUMN ${q({ name: colName })} ${colDef};`,
+        isDestructive,
+        description: `Add column "${fieldName}" to "${name}"`,
+      });
+    }
+
+    // Dropped columns
+    for (const [fieldName, field] of prevFields) {
+      if (currFields.has(fieldName)) continue;
+      ops.push({
+        type: "dropColumn",
+        sql: `ALTER TABLE ${q({ name: tableName })} DROP COLUMN IF EXISTS ${q({ name: field.dbName })};`,
+        isDestructive: true,
+        description: `Drop column "${fieldName}" from "${name}"`,
+      });
+    }
+
+    // Modified columns
+    for (const [fieldName, currField] of currFields) {
+      const prevField = prevFields.get(fieldName);
+      if (!prevField) continue;
+
+      const colName = currField.dbName;
+      const prevType = resolveColumnType({ field: prevField, enums: previous.enums });
+      const currType = resolveColumnType({ field: currField, enums: current.enums });
+
+      // Type change
+      if (prevType !== currType) {
+        ops.push({
+          type: "alterColumnType",
+          sql: `ALTER TABLE ${q({ name: tableName })} ALTER COLUMN ${q({ name: colName })} SET DATA TYPE ${currType};`,
+          isDestructive: true,
+          description: `Change type of "${fieldName}" in "${name}" from ${prevType} to ${currType}`,
+        });
+      }
+
+      // Nullability change
+      if (prevField.isRequired !== currField.isRequired) {
+        if (currField.isRequired) {
+          ops.push({
+            type: "alterColumnNullability",
+            sql: `ALTER TABLE ${q({ name: tableName })} ALTER COLUMN ${q({ name: colName })} SET NOT NULL;`,
+            isDestructive: true,
+            description: `Set NOT NULL on "${fieldName}" in "${name}"`,
+          });
+        } else {
+          ops.push({
+            type: "alterColumnNullability",
+            sql: `ALTER TABLE ${q({ name: tableName })} ALTER COLUMN ${q({ name: colName })} DROP NOT NULL;`,
+            isDestructive: false,
+            description: `Drop NOT NULL on "${fieldName}" in "${name}"`,
+          });
+        }
+      }
+
+      // Default change
+      const prevDefault = resolveDefault({ field: prevField });
+      const currDefault = resolveDefault({ field: currField });
+      if (prevDefault !== currDefault) {
+        if (currDefault) {
+          ops.push({
+            type: "alterColumnDefault",
+            sql: `ALTER TABLE ${q({ name: tableName })} ALTER COLUMN ${q({ name: colName })} SET DEFAULT ${currDefault};`,
+            isDestructive: false,
+            description: `Set default on "${fieldName}" in "${name}" to ${currDefault}`,
+          });
+        } else {
+          ops.push({
+            type: "alterColumnDefault",
+            sql: `ALTER TABLE ${q({ name: tableName })} ALTER COLUMN ${q({ name: colName })} DROP DEFAULT;`,
+            isDestructive: false,
+            description: `Drop default on "${fieldName}" in "${name}"`,
+          });
+        }
+      }
+    }
+
+    // ─── Unique Constraint Diffs ──────────────────────────────
+
+    const prevUniques = new Map(
+      prevModel.uniqueConstraints.map((uc: UniqueConstraint) => [uniqueKey({ uc, model: prevModel }), uc])
+    );
+    const currUniques = new Map(
+      currModel.uniqueConstraints.map((uc: UniqueConstraint) => [uniqueKey({ uc, model: currModel }), uc])
+    );
+
+    for (const [key, uc] of currUniques) {
+      if (prevUniques.has(key)) continue;
+      const cols = uc.fields.map((f: string) => q({ name: resolveFieldDbName({ model: currModel, fieldName: f }) })).join(", ");
+      const resolvedFieldNames = uc.fields.map((f: string) => resolveFieldDbName({ model: currModel, fieldName: f }));
+      const idxName = uc.name ?? `${tableName}_${resolvedFieldNames.join("_")}_key`;
+      ops.push({
+        type: "addUnique",
+        sql: `CREATE UNIQUE INDEX ${q({ name: idxName })} ON ${q({ name: tableName })} (${cols});`,
+        isDestructive: false,
+        description: `Add unique constraint on (${uc.fields.join(", ")}) in "${name}"`,
+      });
+    }
+
+    for (const [key, uc] of prevUniques) {
+      if (currUniques.has(key)) continue;
+      const resolvedFieldNames = uc.fields.map((f: string) => resolveFieldDbName({ model: prevModel, fieldName: f }));
+      const idxName = uc.name ?? `${tableName}_${resolvedFieldNames.join("_")}_key`;
+      ops.push({
+        type: "dropUnique",
+        sql: `DROP INDEX IF EXISTS ${q({ name: idxName })};`,
+        isDestructive: true,
+        description: `Drop unique constraint on (${uc.fields.join(", ")}) in "${name}"`,
+      });
+    }
+
+    // ─── Index Diffs ──────────────────────────────────────────
+
+    const prevIndexes = new Map(
+      prevModel.indexes.map((idx: IndexDefinition) => [indexKey({ idx, model: prevModel }), idx])
+    );
+    const currIndexes = new Map(
+      currModel.indexes.map((idx: IndexDefinition) => [indexKey({ idx, model: currModel }), idx])
+    );
+
+    for (const [key, idx] of currIndexes) {
+      if (prevIndexes.has(key)) continue;
+      const cols = idx.fields.map((f: string) => q({ name: resolveFieldDbName({ model: currModel, fieldName: f }) })).join(", ");
+      const resolvedFieldNames = idx.fields.map((f: string) => resolveFieldDbName({ model: currModel, fieldName: f }));
+      const idxName = idx.name ?? `${tableName}_${resolvedFieldNames.join("_")}_idx`;
+      ops.push({
+        type: "addIndex",
+        sql: `CREATE INDEX ${q({ name: idxName })} ON ${q({ name: tableName })} (${cols});`,
+        isDestructive: false,
+        description: `Add index on (${idx.fields.join(", ")}) in "${name}"`,
+      });
+    }
+
+    for (const [key, idx] of prevIndexes) {
+      if (currIndexes.has(key)) continue;
+      const resolvedFieldNames = idx.fields.map((f: string) => resolveFieldDbName({ model: prevModel, fieldName: f }));
+      const idxName = idx.name ?? `${tableName}_${resolvedFieldNames.join("_")}_idx`;
+      ops.push({
+        type: "dropIndex",
+        sql: `DROP INDEX IF EXISTS ${q({ name: idxName })};`,
+        isDestructive: true,
+        description: `Drop index on (${idx.fields.join(", ")}) in "${name}"`,
+      });
+    }
+
+    // ─── Foreign Key Diffs ────────────────────────────────────
+
+    const prevFKs = new Map(
+      getRelationFields({ model: prevModel })
+        .filter((r: RelationField) => r.relation.isForeignKey && r.relation.fields.length > 0)
+        .map((r: RelationField) => [fkKey({ rel: r, model: prevModel, allModels: previous.models }), r])
+    );
+    const currFKs = new Map(
+      getRelationFields({ model: currModel })
+        .filter((r: RelationField) => r.relation.isForeignKey && r.relation.fields.length > 0)
+        .map((r: RelationField) => [fkKey({ rel: r, model: currModel, allModels: current.models }), r])
+    );
+
+    for (const [key, rel] of currFKs) {
+      if (prevFKs.has(key)) continue;
+      const fkCols = rel.relation.fields.map((f: string) => q({ name: resolveFieldDbName({ model: currModel, fieldName: f }) })).join(", ");
+      const relatedModel = current.models.find((m: Model) => m.name === rel.relatedModel);
+      const relatedTableName = relatedModel?.dbName ?? rel.relatedModel;
+      const refCols = rel.relation.references.map((f: string) => {
+        if (relatedModel) return q({ name: resolveFieldDbName({ model: relatedModel, fieldName: f }) });
+        return q({ name: f });
+      }).join(", ");
+      const resolvedFkNames = rel.relation.fields.map((f: string) => resolveFieldDbName({ model: currModel, fieldName: f }));
+      const constraintName = `${tableName}_${resolvedFkNames.join("_")}_fkey`;
+      ops.push({
+        type: "addForeignKey",
+        sql: `ALTER TABLE ${q({ name: tableName })} ADD CONSTRAINT ${q({ name: constraintName })} FOREIGN KEY (${fkCols}) REFERENCES ${q({ name: relatedTableName })} (${refCols}) ON DELETE RESTRICT ON UPDATE CASCADE;`,
+        isDestructive: false,
+        description: `Add foreign key on "${name}" (${rel.relation.fields.join(", ")}) → "${rel.relatedModel}"`,
+      });
+    }
+
+    for (const [key, rel] of prevFKs) {
+      if (currFKs.has(key)) continue;
+      const resolvedFkNames = rel.relation.fields.map((f: string) => resolveFieldDbName({ model: prevModel, fieldName: f }));
+      const constraintName = `${tableName}_${resolvedFkNames.join("_")}_fkey`;
+      ops.push({
+        type: "dropForeignKey",
+        sql: `ALTER TABLE ${q({ name: tableName })} DROP CONSTRAINT IF EXISTS ${q({ name: constraintName })};`,
+        isDestructive: true,
+        description: `Drop foreign key on "${name}" (${rel.relation.fields.join(", ")}) → "${rel.relatedModel}"`,
+      });
+    }
+  }
+
+  // ─── Implicit M:N Join Table Diffs ────────────────────────────
+
+  const prevJoinTables = detectImplicitManyToMany({ schema: previous });
+  const currJoinTables = detectImplicitManyToMany({ schema: current });
+
+  const prevJoinSet = new Set(prevJoinTables.map((j: JoinTableInfo) => j.tableName));
+  const currJoinSet = new Set(currJoinTables.map((j: JoinTableInfo) => j.tableName));
+
+  for (const jt of currJoinTables) {
+    if (prevJoinSet.has(jt.tableName)) continue;
+
+    const modelADef = currModelMap.get(jt.modelA);
+    const modelBDef = currModelMap.get(jt.modelB);
+    if (!modelADef || !modelBDef) continue;
+
+    const pkFieldA = modelADef.primaryKey.fields[0]!;
+    const pkFieldB = modelBDef.primaryKey.fields[0]!;
+
+    // Resolve PK types
+    const pkFieldDefA = modelADef.fields.find((f: Field) => f.name === pkFieldA);
+    const pkFieldDefB = modelBDef.fields.find((f: Field) => f.name === pkFieldB);
+
+    const pkTypeA = pkFieldDefA && (pkFieldDefA.kind === "scalar" || pkFieldDefA.kind === "enum")
+      ? resolveBaseColumnType({ field: pkFieldDefA, enums: current.enums })
+      : "INTEGER";
+    const pkTypeB = pkFieldDefB && (pkFieldDefB.kind === "scalar" || pkFieldDefB.kind === "enum")
+      ? resolveBaseColumnType({ field: pkFieldDefB, enums: current.enums })
+      : "INTEGER";
+
+    const tableA = modelADef.dbName;
+    const tableB = modelBDef.dbName;
+
+    ops.push({
+      type: "createJoinTable",
+      sql: [
+        `CREATE TABLE ${q({ name: jt.tableName })} (\n  "A" ${pkTypeA} NOT NULL,\n  "B" ${pkTypeB} NOT NULL\n);`,
+        `CREATE UNIQUE INDEX ${q({ name: `${jt.tableName}_AB_unique` })} ON ${q({ name: jt.tableName })} ("A", "B");`,
+        `CREATE INDEX ${q({ name: `${jt.tableName}_B_index` })} ON ${q({ name: jt.tableName })} ("B");`,
+        `ALTER TABLE ${q({ name: jt.tableName })} ADD CONSTRAINT ${q({ name: `${jt.tableName}_A_fkey` })} FOREIGN KEY ("A") REFERENCES ${q({ name: tableA })} ("${pkFieldA}") ON DELETE CASCADE ON UPDATE CASCADE;`,
+        `ALTER TABLE ${q({ name: jt.tableName })} ADD CONSTRAINT ${q({ name: `${jt.tableName}_B_fkey` })} FOREIGN KEY ("B") REFERENCES ${q({ name: tableB })} ("${pkFieldB}") ON DELETE CASCADE ON UPDATE CASCADE;`,
+      ].join("\n"),
+      isDestructive: false,
+      description: `Create join table "${jt.tableName}" for ${jt.modelA} ↔ ${jt.modelB}`,
+    });
+  }
+
+  for (const jt of prevJoinTables) {
+    if (currJoinSet.has(jt.tableName)) continue;
+    ops.push({
+      type: "dropJoinTable",
+      sql: `DROP TABLE IF EXISTS ${q({ name: jt.tableName })} CASCADE;`,
+      isDestructive: true,
+      description: `Drop join table "${jt.tableName}" for ${jt.modelA} ↔ ${jt.modelB}`,
+    });
+  }
+
+  return ops;
+}