@vibeorm/migrate 1.1.9 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibeorm/migrate",
-  "version": "1.1.9",
+  "version": "1.3.0",
   "description": "Migration, introspection, and schema diff toolkit for VibeORM",
   "license": "MIT",
   "keywords": [
@@ -37,6 +37,6 @@
     "bun": ">=1.1.0"
   },
   "dependencies": {
-    "@vibeorm/parser": "1.1.8"
+    "@vibeorm/parser": "1.3.0"
   }
 }

package/src/cascade-actions.ts

@@ -0,0 +1,88 @@
+/**
+ * Cascade-action resolution and SQL serialisation.
+ *
+ * Translates a `CascadeAction` from the parser IR into a Postgres
+ * `ON DELETE`/`ON UPDATE` clause, applying Prisma-compatible defaults when
+ * the schema doesn't specify an action explicitly.
+ *
+ * Defaults (matching Prisma's Postgres behaviour):
+ *   - `onDelete`: required FK → `Restrict`, optional FK → `SetNull`
+ *   - `onUpdate`: always → `Cascade`
+ */
+
+import type { CascadeAction, RelationField } from "@vibeorm/parser";
+
+const ACTION_TO_SQL: Record<CascadeAction, string> = {
+  Cascade: "CASCADE",
+  Restrict: "RESTRICT",
+  NoAction: "NO ACTION",
+  SetNull: "SET NULL",
+  SetDefault: "SET DEFAULT",
+};
+
+/**
+ * Inverse of {@link ACTION_TO_SQL} — used by the introspector when reading
+ * `pg_constraint.confdeltype`/`confupdtype`. The single-char codes are
+ * Postgres's catalog representation.
+ */
+export const PG_CHAR_TO_CASCADE_ACTION: Record<string, CascadeAction> = {
+  a: "NoAction",
+  r: "Restrict",
+  c: "Cascade",
+  n: "SetNull",
+  d: "SetDefault",
+};
+
+/**
+ * Resolve the effective onDelete action for a relation, applying the Prisma
+ * default when the schema didn't say anything explicit.
+ *
+ * `isRequired` is the FK column's nullability (Prisma's "required relation").
+ */
+export function resolveOnDelete(params: {
+  explicit: CascadeAction | undefined;
+  isRequired: boolean;
+}): CascadeAction {
+  if (params.explicit) return params.explicit;
+  return params.isRequired ? "Restrict" : "SetNull";
+}
+
+/** Resolve the effective onUpdate action. Prisma's Postgres default is Cascade. */
+export function resolveOnUpdate(params: {
+  explicit: CascadeAction | undefined;
+}): CascadeAction {
+  return params.explicit ?? "Cascade";
+}
+
+/** Convenience: serialise a CascadeAction to its Postgres clause body. */
+export function cascadeActionSql(params: { action: CascadeAction }): string {
+  return ACTION_TO_SQL[params.action];
+}
+
+/**
+ * Build the full `ON DELETE X ON UPDATE Y` clause for a relation field,
+ * applying defaults as needed.
+ */
+export function buildFkActionClause(params: { rel: RelationField }): string {
+  const { rel } = params;
+  const onDelete = resolveOnDelete({
+    explicit: rel.relation.onDelete,
+    isRequired: rel.isRequired,
+  });
+  const onUpdate = resolveOnUpdate({ explicit: rel.relation.onUpdate });
+  return `ON DELETE ${ACTION_TO_SQL[onDelete]} ON UPDATE ${ACTION_TO_SQL[onUpdate]}`;
+}
+
+/**
+ * Stable comparison key for whether two relations have the same effective
+ * cascade behaviour. Used by the differ to detect drift even when the schema
+ * was written without explicit actions (defaults must still be considered).
+ */
+export function fkActionFingerprint(params: { rel: RelationField }): string {
+  const onDelete = resolveOnDelete({
+    explicit: params.rel.relation.onDelete,
+    isRequired: params.rel.isRequired,
+  });
+  const onUpdate = resolveOnUpdate({ explicit: params.rel.relation.onUpdate });
+  return `${onDelete}|${onUpdate}`;
+}

package/src/ddl-builder.ts

@@ -7,6 +7,7 @@
 
 import type { Schema, Model, Field, ScalarField, EnumField, RelationField, DefaultValue, Enum, EnumValue } from "@vibeorm/parser";
 import { PRISMA_TO_PG } from "@vibeorm/parser";
+import { buildFkActionClause } from "./cascade-actions.ts";
 
 export type DDLResult = {
   /** The full DDL SQL wrapped in BEGIN/COMMIT */
@@ -271,10 +272,11 @@ function buildForeignKeyStatements(params: { model: Model; allModels: Model[] })
       .join(", ");
 
     const constraintName = `${tableName}_${field.relation.fields.join("_")}_fkey`;
+    const actionClause = buildFkActionClause({ rel: field });
     statements.push(
       `ALTER TABLE ${q({ name: tableName })} ADD CONSTRAINT ${q({ name: constraintName })} ` +
       `FOREIGN KEY (${fkCols}) REFERENCES ${q({ name: relatedTableName })} (${refCols}) ` +
-      `ON DELETE RESTRICT ON UPDATE CASCADE;`
+      `${actionClause};`
     );
   }
 

package/src/introspector.ts

@@ -20,9 +20,11 @@ import type {
   PrismaScalarType,
   PostgresType,
   DefaultValue,
+  CascadeAction,
 } from "@vibeorm/parser";
 import { PRISMA_TO_TS, PRISMA_TO_PG } from "@vibeorm/parser";
 import type { SqlExecutor } from "./types.ts";
+import { PG_CHAR_TO_CASCADE_ACTION } from "./cascade-actions.ts";
 
 // ─── Reverse Type Mapping ─────────────────────────────────────────
 
@@ -83,6 +85,10 @@ type ForeignKeyInfo = {
   columnName: string;
   foreignTableName: string;
   foreignColumnName: string;
+  /** ON DELETE action from `pg_constraint.confdeltype` (mapped to CascadeAction). */
+  onDelete: CascadeAction;
+  /** ON UPDATE action from `pg_constraint.confupdtype` (mapped to CascadeAction). */
+  onUpdate: CascadeAction;
 };
 
 type EnumInfo = {
@@ -138,23 +144,36 @@ const CONSTRAINTS_QUERY = `
   ORDER BY tc.table_name, tc.constraint_name, kcu.ordinal_position;
 `;
 
+/**
+ * Foreign keys via pg_catalog rather than information_schema, because
+ * information_schema's `referential_constraints.delete_rule` exposes the rule
+ * but doesn't preserve the column ordering of composite FKs reliably across
+ * server versions. The pg_catalog path with `unnest(...) WITH ORDINALITY`
+ * pairs up `conkey` / `confkey` in declaration order and also surfaces
+ * `confdeltype` / `confupdtype` directly.
+ */
 const FOREIGN_KEYS_QUERY = `
   SELECT
-    tc.constraint_name,
-    tc.table_name,
-    kcu.column_name,
-    ccu.table_name AS foreign_table_name,
-    ccu.column_name AS foreign_column_name
-  FROM information_schema.table_constraints tc
-  JOIN information_schema.key_column_usage kcu
-    ON tc.constraint_name = kcu.constraint_name
-    AND tc.table_schema = kcu.table_schema
-  JOIN information_schema.constraint_column_usage ccu
-    ON tc.constraint_name = ccu.constraint_name
-    AND tc.table_schema = ccu.table_schema
-  WHERE tc.table_schema = 'public'
-    AND tc.constraint_type = 'FOREIGN KEY'
-  ORDER BY tc.table_name, tc.constraint_name;
+    c.conname  AS constraint_name,
+    cl.relname AS table_name,
+    att.attname AS column_name,
+    fcl.relname AS foreign_table_name,
+    fatt.attname AS foreign_column_name,
+    c.confdeltype AS on_delete_char,
+    c.confupdtype AS on_update_char
+  FROM pg_catalog.pg_constraint c
+  JOIN pg_catalog.pg_class cl       ON cl.oid = c.conrelid
+  JOIN pg_catalog.pg_namespace n    ON n.oid = cl.relnamespace
+  JOIN pg_catalog.pg_class fcl      ON fcl.oid = c.confrelid
+  JOIN pg_catalog.pg_namespace fn   ON fn.oid = fcl.relnamespace
+  JOIN unnest(c.conkey)  WITH ORDINALITY AS lk(attnum, ord) ON true
+  JOIN unnest(c.confkey) WITH ORDINALITY AS rk(attnum, ord) ON lk.ord = rk.ord
+  JOIN pg_catalog.pg_attribute att  ON att.attrelid = c.conrelid  AND att.attnum = lk.attnum
+  JOIN pg_catalog.pg_attribute fatt ON fatt.attrelid = c.confrelid AND fatt.attnum = rk.attnum
+  WHERE c.contype = 'f'
+    AND n.nspname = 'public'
+    AND fn.nspname = 'public'
+  ORDER BY cl.relname, c.conname, lk.ord;
 `;
 
 const ENUMS_QUERY = `
@@ -289,13 +308,22 @@ export async function introspect(params: { executor: SqlExecutor }): Promise<Sch
     columnName: r.column_name as string,
   }));
 
-  const foreignKeys: ForeignKeyInfo[] = foreignKeysRaw.map((r) => ({
-    constraintName: r.constraint_name as string,
-    tableName: r.table_name as string,
-    columnName: r.column_name as string,
-    foreignTableName: r.foreign_table_name as string,
-    foreignColumnName: r.foreign_column_name as string,
-  }));
+  const foreignKeys: ForeignKeyInfo[] = foreignKeysRaw.map((r) => {
+    // Postgres uses single-char codes: a=NoAction, r=Restrict, c=Cascade,
+    // n=SetNull, d=SetDefault. Fall back to NoAction (the Postgres default)
+    // if we ever see an unrecognised char from a future PG version.
+    const onDeleteChar = (r.on_delete_char as string) ?? "a";
+    const onUpdateChar = (r.on_update_char as string) ?? "a";
+    return {
+      constraintName: r.constraint_name as string,
+      tableName: r.table_name as string,
+      columnName: r.column_name as string,
+      foreignTableName: r.foreign_table_name as string,
+      foreignColumnName: r.foreign_column_name as string,
+      onDelete: PG_CHAR_TO_CASCADE_ACTION[onDeleteChar] ?? "NoAction",
+      onUpdate: PG_CHAR_TO_CASCADE_ACTION[onUpdateChar] ?? "NoAction",
+    };
+  });
 
   const enumInfos: EnumInfo[] = enumsRaw.map((r) => ({
     typeName: r.type_name as string,
@@ -387,14 +415,23 @@ export async function introspect(params: { executor: SqlExecutor }): Promise<Sch
     const tableUniques = uniqueConstraints.get(tableName) ?? new Map<string, string[]>();
     const tableFKs = foreignKeys.filter((fk) => fk.tableName === tableName);
 
-    // Group FKs by constraint for multi-column FK support
-    const fkGroups = new Map<string, { localCols: string[]; foreignTable: string; foreignCols: string[] }>();
+    // Group FKs by constraint for multi-column FK support. Cascade actions are
+    // a property of the constraint as a whole, so we carry them once per group.
+    const fkGroups = new Map<string, {
+      localCols: string[];
+      foreignTable: string;
+      foreignCols: string[];
+      onDelete: CascadeAction;
+      onUpdate: CascadeAction;
+    }>();
     for (const fk of tableFKs) {
       if (!fkGroups.has(fk.constraintName)) {
         fkGroups.set(fk.constraintName, {
           localCols: [],
           foreignTable: fk.foreignTableName,
           foreignCols: [],
+          onDelete: fk.onDelete,
+          onUpdate: fk.onUpdate,
         });
       }
       const group = fkGroups.get(fk.constraintName)!;
@@ -410,7 +447,7 @@ export async function introspect(params: { executor: SqlExecutor }): Promise<Sch
       const isUnique = uniqueColumns.has(`${tableName}.${col.columnName}`);
       const parsedDefault = parseDefault({ columnDefault: col.columnDefault, dataType: col.dataType });
 
-      // Check if this is an enum column
+      // Branch 1: scalar enum column (data_type=USER-DEFINED, udt_name=EnumName).
       if (col.dataType === "USER-DEFINED" && enumNames.has(col.udtName)) {
         const enumField: EnumField = {
           kind: "enum",
@@ -425,8 +462,33 @@ export async function introspect(params: { executor: SqlExecutor }): Promise<Sch
           documentation: undefined,
         };
         fields.push(enumField);
-      } else {
-        // Map PG type to Prisma type
+      }
+      // Branch 2: enum-array column. Postgres reports the underlying array type
+      // as `_EnumName` (the leading underscore is the array-type naming convention),
+      // and `data_type` is `ARRAY`. Without this branch the field would be parsed
+      // as `String[]` and the round-trip drift differ would always want to ALTER it.
+      // Bug 2 — see .ai/bug-report-2026-05-24.md.
+      else if (
+        col.dataType === "ARRAY" &&
+        col.udtName.startsWith("_") &&
+        enumNames.has(col.udtName.slice(1))
+      ) {
+        const enumField: EnumField = {
+          kind: "enum",
+          name: col.columnName,
+          dbName: col.columnName,
+          enumName: col.udtName.slice(1),
+          isRequired: !col.isNullable,
+          isList: true,
+          isId,
+          isUnique,
+          default: parsedDefault,
+          documentation: undefined,
+        };
+        fields.push(enumField);
+      }
+      // Branch 3: scalar / scalar-array fallback.
+      else {
         const pgType = col.dataType === "ARRAY" ? col.udtName.replace(/^_/, "") : col.udtName;
         const prismaType = PG_TO_PRISMA[pgType] ?? PG_TO_PRISMA[col.dataType] ?? "String";
         const isArray = col.dataType === "ARRAY";
@@ -473,6 +535,8 @@ export async function introspect(params: { executor: SqlExecutor }): Promise<Sch
           relatedModel: group.foreignTable,
           type: isOneToOne ? "oneToOne" : "manyToOne",
           isForeignKey: true,
+          onDelete: group.onDelete,
+          onUpdate: group.onUpdate,
         },
       };
       fields.push(relationField);

package/src/schema-differ.ts

@@ -17,6 +17,7 @@ import type {
   IndexDefinition,
 } from "@vibeorm/parser";
 import { PRISMA_TO_PG } from "@vibeorm/parser";
+import { buildFkActionClause, fkActionFingerprint } from "./cascade-actions.ts";
 
 // ─── Types ────────────────────────────────────────────────────────
 
@@ -71,8 +72,11 @@ function getRelationFields(params: { model: Model }): RelationField[] {
 function resolveColumnType(params: { field: ScalarField | EnumField; enums: Enum[] }): string {
   const { field, enums } = params;
   if (field.kind === "enum") {
+    // Enum lists must emit `EnumName[]`, not the scalar enum type. Mirrors
+    // `ddl-builder.ts:135-141`. Bug 2 — see .ai/bug-report-2026-05-24.md.
     const enumDef = enums.find((e) => e.name === field.enumName);
-    return q({ name: enumDef?.dbName ?? field.enumName });
+    const enumType = q({ name: enumDef?.dbName ?? field.enumName });
+    return field.isList ? `${enumType}[]` : enumType;
   }
   if (field.default?.kind === "autoincrement") {
     return field.prismaType === "BigInt" ? "BIGSERIAL" : "SERIAL";
@@ -86,8 +90,10 @@ function resolveColumnType(params: { field: ScalarField | EnumField; enums: Enum
 function resolveBaseColumnType(params: { field: ScalarField | EnumField; enums: Enum[] }): string {
   const { field, enums } = params;
   if (field.kind === "enum") {
+    // Same enum-list handling as resolveColumnType (Bug 2).
     const enumDef = enums.find((e) => e.name === field.enumName);
-    return q({ name: enumDef?.dbName ?? field.enumName });
+    const enumType = q({ name: enumDef?.dbName ?? field.enumName });
+    return field.isList ? `${enumType}[]` : enumType;
   }
   if (field.nativeType) return field.nativeType.toLowerCase();
   if (field.isList) return `${PRISMA_TO_PG[field.prismaType]}[]`;
@@ -426,9 +432,10 @@ export function diffSchemas(params: { previous: Schema; current: Schema }): Diff
       }).join(", ");
       const resolvedFkNames = rel.relation.fields.map((f: string) => resolveFieldDbName({ model, fieldName: f }));
       const constraintName = `${tableName}_${resolvedFkNames.join("_")}_fkey`;
+      const actionClause = buildFkActionClause({ rel });
       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;`,
+        sql: `ALTER TABLE ${q({ name: tableName })} ADD CONSTRAINT ${q({ name: constraintName })} FOREIGN KEY (${fkCols}) REFERENCES ${q({ name: relatedTableName })} (${refCols}) ${actionClause};`,
         downSql: `ALTER TABLE ${q({ name: tableName })} DROP CONSTRAINT IF EXISTS ${q({ name: constraintName })};`,
         isDestructive: false,
         isReversible: true,
@@ -554,11 +561,25 @@ export function diffSchemas(params: { previous: Schema; current: Schema }): Diff
 
       // Type change — reverse is setting back to the previous type
       if (prevType !== currType) {
+        // Detect scalar -> array transition of same base type. PG can't implicit-cast,
+        // so we add a USING clause that wraps the existing value in a 1-element array
+        // (or NULL if the column is NULL). This heals databases broken by an earlier
+        // enum-array bug (Bug 2) where the column was created as the scalar type.
+        // We intentionally do NOT handle the reverse direction (array -> scalar) — that
+        // is lossy and the user must decide which element to keep.
+        const isScalarToArray =
+          currType.endsWith("[]") && !prevType.endsWith("[]") &&
+          currType.slice(0, -2) === prevType;
+
+        const usingClause = isScalarToArray
+          ? ` USING CASE WHEN ${q({ name: colName })} IS NULL THEN NULL ELSE ARRAY[${q({ name: colName })}] END`
+          : "";
+
         ops.push({
           type: "alterColumnType",
-          sql: `ALTER TABLE ${q({ name: tableName })} ALTER COLUMN ${q({ name: colName })} SET DATA TYPE ${currType};`,
+          sql: `ALTER TABLE ${q({ name: tableName })} ALTER COLUMN ${q({ name: colName })} SET DATA TYPE ${currType}${usingClause};`,
           downSql: `ALTER TABLE ${q({ name: tableName })} ALTER COLUMN ${q({ name: colName })} SET DATA TYPE ${prevType};`,
-          isDestructive: true,
+          isDestructive: !isScalarToArray, // scalar -> array is non-destructive (data preserved as 1-element arrays)
           isReversible: true,
           description: `Change type of "${fieldName}" in "${name}" from ${prevType} to ${currType}`,
         });
@@ -709,7 +730,7 @@ export function diffSchemas(params: { previous: Schema; current: Schema }): Diff
     );
 
     for (const [key, rel] of currFKs) {
-      if (prevFKs.has(key)) continue;
+      const prev = prevFKs.get(key);
       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;
@@ -719,14 +740,43 @@ export function diffSchemas(params: { previous: Schema; current: Schema }): Diff
       }).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;`,
-        downSql: `ALTER TABLE ${q({ name: tableName })} DROP CONSTRAINT IF EXISTS ${q({ name: constraintName })};`,
-        isDestructive: false,
-        isReversible: true,
-        description: `Add foreign key on "${name}" (${rel.relation.fields.join(", ")}) → "${rel.relatedModel}"`,
-      });
+      const actionClause = buildFkActionClause({ rel });
+
+      if (!prev) {
+        ops.push({
+          type: "addForeignKey",
+          sql: `ALTER TABLE ${q({ name: tableName })} ADD CONSTRAINT ${q({ name: constraintName })} FOREIGN KEY (${fkCols}) REFERENCES ${q({ name: relatedTableName })} (${refCols}) ${actionClause};`,
+          downSql: `ALTER TABLE ${q({ name: tableName })} DROP CONSTRAINT IF EXISTS ${q({ name: constraintName })};`,
+          isDestructive: false,
+          isReversible: true,
+          description: `Add foreign key on "${name}" (${rel.relation.fields.join(", ")}) → "${rel.relatedModel}"`,
+        });
+        continue;
+      }
+
+      // FK exists on both sides — detect cascade-action drift. Postgres has no
+      // `ALTER CONSTRAINT ... ON DELETE` for FKs, so we emit a DROP + ADD pair.
+      const prevFingerprint = fkActionFingerprint({ rel: prev });
+      const currFingerprint = fkActionFingerprint({ rel });
+      if (prevFingerprint !== currFingerprint) {
+        const prevActionClause = buildFkActionClause({ rel: prev });
+        ops.push({
+          type: "dropForeignKey",
+          sql: `ALTER TABLE ${q({ name: tableName })} DROP CONSTRAINT IF EXISTS ${q({ name: constraintName })};`,
+          downSql: `ALTER TABLE ${q({ name: tableName })} ADD CONSTRAINT ${q({ name: constraintName })} FOREIGN KEY (${fkCols}) REFERENCES ${q({ name: relatedTableName })} (${refCols}) ${prevActionClause};`,
+          isDestructive: false,
+          isReversible: true,
+          description: `Drop foreign key on "${name}" (${rel.relation.fields.join(", ")}) to change cascade actions`,
+        });
+        ops.push({
+          type: "addForeignKey",
+          sql: `ALTER TABLE ${q({ name: tableName })} ADD CONSTRAINT ${q({ name: constraintName })} FOREIGN KEY (${fkCols}) REFERENCES ${q({ name: relatedTableName })} (${refCols}) ${actionClause};`,
+          downSql: `ALTER TABLE ${q({ name: tableName })} DROP CONSTRAINT IF EXISTS ${q({ name: constraintName })};`,
+          isDestructive: false,
+          isReversible: true,
+          description: `Re-add foreign key on "${name}" (${rel.relation.fields.join(", ")}) with new cascade actions (${currFingerprint.replace("|", " / ")})`,
+        });
+      }
     }
 
     for (const [key, rel] of prevFKs) {
@@ -740,10 +790,11 @@ export function diffSchemas(params: { previous: Schema; current: Schema }): Diff
       }).join(", ");
       const resolvedFkNames = rel.relation.fields.map((f: string) => resolveFieldDbName({ model: prevModel, fieldName: f }));
       const constraintName = `${tableName}_${resolvedFkNames.join("_")}_fkey`;
+      const actionClause = buildFkActionClause({ rel });
       ops.push({
         type: "dropForeignKey",
         sql: `ALTER TABLE ${q({ name: tableName })} DROP CONSTRAINT IF EXISTS ${q({ name: constraintName })};`,
-        downSql: `ALTER TABLE ${q({ name: tableName })} ADD CONSTRAINT ${q({ name: constraintName })} FOREIGN KEY (${fkCols}) REFERENCES ${q({ name: relatedTableName })} (${refCols}) ON DELETE RESTRICT ON UPDATE CASCADE;`,
+        downSql: `ALTER TABLE ${q({ name: tableName })} ADD CONSTRAINT ${q({ name: constraintName })} FOREIGN KEY (${fkCols}) REFERENCES ${q({ name: relatedTableName })} (${refCols}) ${actionClause};`,
         isDestructive: true,
         isReversible: true,
         description: `Drop foreign key on "${name}" (${rel.relation.fields.join(", ")}) → "${rel.relatedModel}"`,

package/src/schema-printer.ts

@@ -14,7 +14,9 @@ import type {
   RelationField,
   Enum,
   DefaultValue,
+  CascadeAction,
 } from "@vibeorm/parser";
+import { resolveOnDelete, resolveOnUpdate } from "./cascade-actions.ts";
 
 // ─── Helpers ──────────────────────────────────────────────────────
 
@@ -105,12 +107,21 @@ function printRelationField(params: { field: RelationField }): string {
   if (field.relation.isForeignKey && field.relation.fields.length > 0) {
     const fieldsStr = field.relation.fields.map((f: string) => f).join(", ");
     const refsStr = field.relation.references.map((f: string) => f).join(", ");
-    let relAttr = `@relation(fields: [${fieldsStr}], references: [${refsStr}]`;
-    if (field.relation.name) {
-      relAttr = `@relation("${field.relation.name}", fields: [${fieldsStr}], references: [${refsStr}]`;
-    }
-    relAttr += ")";
-    parts.push(relAttr);
+
+    // Only emit cascade actions when they differ from the Prisma default for
+    // this relation's optionality. Keeps `db pull` output minimal and matches
+    // what users would have hand-written.
+    const explicitOnDelete = nonDefaultOnDelete({ field });
+    const explicitOnUpdate = nonDefaultOnUpdate({ field });
+
+    const segments: string[] = [];
+    if (field.relation.name) segments.push(`"${field.relation.name}"`);
+    segments.push(`fields: [${fieldsStr}]`);
+    segments.push(`references: [${refsStr}]`);
+    if (explicitOnDelete) segments.push(`onDelete: ${explicitOnDelete}`);
+    if (explicitOnUpdate) segments.push(`onUpdate: ${explicitOnUpdate}`);
+
+    parts.push(`@relation(${segments.join(", ")})`);
   } else if (field.relation.name) {
     parts.push(`@relation("${field.relation.name}")`);
   }
@@ -118,6 +129,28 @@ function printRelationField(params: { field: RelationField }): string {
   return indent({ text: parts.join(" ") });
 }
 
+/**
+ * Returns the onDelete action only if it differs from the Prisma default for
+ * this relation's optionality. Returns `undefined` when the action is the
+ * default (in which case we omit it from the printed `@relation(...)`).
+ */
+function nonDefaultOnDelete(params: { field: RelationField }): CascadeAction | undefined {
+  const { field } = params;
+  if (field.relation.onDelete === undefined) return undefined;
+  const effectiveDefault = resolveOnDelete({
+    explicit: undefined,
+    isRequired: field.isRequired,
+  });
+  return field.relation.onDelete === effectiveDefault ? undefined : field.relation.onDelete;
+}
+
+function nonDefaultOnUpdate(params: { field: RelationField }): CascadeAction | undefined {
+  const { field } = params;
+  if (field.relation.onUpdate === undefined) return undefined;
+  const effectiveDefault = resolveOnUpdate({ explicit: undefined });
+  return field.relation.onUpdate === effectiveDefault ? undefined : field.relation.onUpdate;
+}
+
 function printField(params: { field: Field }): string {
   switch (params.field.kind) {
     case "scalar":