@supabase/pg-delta 1.0.0-alpha.3 → 1.0.0-alpha.30

package/src/core/objects/table/table.diff.ts

@@ -0,0 +1,1034 @@
+import { diffObjects } from "../base.diff.ts";
+import {
+  diffPrivileges,
+  emitColumnPrivilegeChanges,
+} from "../base.privilege-diff.ts";
+import type { ObjectDiffContext } from "../diff-context.ts";
+import { diffSecurityLabels } from "../security-label.types.ts";
+import { deepEqual } from "../utils.ts";
+import {
+  AlterTableAddColumn,
+  AlterTableAddConstraint,
+  AlterTableAlterColumnAddIdentity,
+  AlterTableAlterColumnDropDefault,
+  AlterTableAlterColumnDropIdentity,
+  AlterTableAlterColumnDropNotNull,
+  AlterTableAlterColumnSetDefault,
+  AlterTableAlterColumnSetGenerated,
+  AlterTableAlterColumnSetNotNull,
+  AlterTableAlterColumnType,
+  AlterTableAttachPartition,
+  AlterTableChangeOwner,
+  AlterTableDetachPartition,
+  AlterTableDisableRowLevelSecurity,
+  AlterTableDropColumn,
+  AlterTableDropConstraint,
+  AlterTableEnableRowLevelSecurity,
+  AlterTableForceRowLevelSecurity,
+  AlterTableNoForceRowLevelSecurity,
+  AlterTableResetStorageParams,
+  AlterTableSetLogged,
+  AlterTableSetReplicaIdentity,
+  AlterTableSetStorageParams,
+  AlterTableSetUnlogged,
+  AlterTableValidateConstraint,
+} from "./changes/table.alter.ts";
+import {
+  CreateCommentOnColumn,
+  CreateCommentOnConstraint,
+  CreateCommentOnTable,
+  DropCommentOnColumn,
+  DropCommentOnConstraint,
+  DropCommentOnTable,
+} from "./changes/table.comment.ts";
+import { CreateTable } from "./changes/table.create.ts";
+import { DropTable } from "./changes/table.drop.ts";
+import {
+  GrantTablePrivileges,
+  RevokeGrantOptionTablePrivileges,
+  RevokeTablePrivileges,
+} from "./changes/table.privilege.ts";
+import {
+  CreateSecurityLabelOnColumn,
+  CreateSecurityLabelOnTable,
+  DropSecurityLabelOnColumn,
+  DropSecurityLabelOnTable,
+} from "./changes/table.security-label.ts";
+import type { TableChange } from "./changes/table.types.ts";
+import { Table } from "./table.model.ts";
+
+function createAlterConstraintChange(mainTable: Table, branchTable: Table) {
+  const changes: TableChange[] = [];
+
+  // Note: Table renaming would also use ALTER TABLE ... RENAME TO ...
+  // But since our Table model uses 'name' as the identity field,
+  // a name change would be handled as drop + create by diffObjects()
+
+  // TABLE CONSTRAINTS
+  const mainByName = new Map(
+    (mainTable.constraints ?? []).map((c) => [c.name, c]),
+  );
+  const branchByName = new Map(
+    (branchTable.constraints ?? []).map((c) => [c.name, c]),
+  );
+
+  // Created constraints
+  for (const [name, c] of branchByName) {
+    // Skip constraint clones on partitions - they are automatically created when the parent constraint is created
+    if (c.is_partition_clone) {
+      continue;
+    }
+
+    if (!mainByName.has(name)) {
+      changes.push(
+        new AlterTableAddConstraint({
+          table: branchTable,
+          constraint: c,
+        }),
+      );
+      // Add comment for newly created constraint
+      if (c.comment !== null) {
+        changes.push(
+          new CreateCommentOnConstraint({
+            table: branchTable,
+            constraint: c,
+          }),
+        );
+      }
+    }
+  }
+
+  // Dropped constraints
+  for (const [name, c] of mainByName) {
+    // Skip constraint clones on partitions - they are automatically dropped when the parent constraint is dropped
+    if (c.is_partition_clone) {
+      continue;
+    }
+
+    if (!branchByName.has(name)) {
+      changes.push(
+        new AlterTableDropConstraint({ table: mainTable, constraint: c }),
+      );
+    }
+  }
+
+  // Altered constraints -> drop + add (or VALIDATE-only shortcut)
+  for (const [name, mainC] of mainByName) {
+    const branchC = branchByName.get(name);
+    if (!branchC) continue;
+
+    // Skip constraint clones on partitions - they are automatically updated when the parent constraint is updated
+    if (mainC.is_partition_clone || branchC.is_partition_clone) {
+      continue;
+    }
+
+    // Cheap scalar `===` checks first; only fall through to JSON.stringify
+    // on the array fields when every scalar has already matched.
+    const fieldsEqualExceptValidated =
+      mainC.constraint_type === branchC.constraint_type &&
+      mainC.deferrable === branchC.deferrable &&
+      mainC.initially_deferred === branchC.initially_deferred &&
+      mainC.is_local === branchC.is_local &&
+      mainC.no_inherit === branchC.no_inherit &&
+      mainC.is_temporal === branchC.is_temporal &&
+      mainC.foreign_key_table === branchC.foreign_key_table &&
+      mainC.foreign_key_schema === branchC.foreign_key_schema &&
+      mainC.on_update === branchC.on_update &&
+      mainC.on_delete === branchC.on_delete &&
+      mainC.match_type === branchC.match_type &&
+      mainC.check_expression === branchC.check_expression &&
+      JSON.stringify(mainC.key_columns) ===
+        JSON.stringify(branchC.key_columns) &&
+      JSON.stringify(mainC.foreign_key_columns) ===
+        JSON.stringify(branchC.foreign_key_columns);
+
+    // Safe-migration shortcut: when the only difference is `validated`
+    // flipping from false to true, emit a single `ALTER TABLE ... VALIDATE
+    // CONSTRAINT` instead of drop+add. VALIDATE CONSTRAINT only takes
+    // SHARE UPDATE EXCLUSIVE (concurrent reads/writes proceed), whereas
+    // dropping and re-adding takes ACCESS EXCLUSIVE for the entire scan.
+    // Postgres has no reverse command, so `true -> false` must still go
+    // through drop+add below.
+    if (
+      fieldsEqualExceptValidated &&
+      mainC.validated === false &&
+      branchC.validated === true
+    ) {
+      changes.push(
+        new AlterTableValidateConstraint({
+          table: branchTable,
+          constraint: branchC,
+        }),
+      );
+      // VALIDATE preserves the constraint OID, so its comment is preserved
+      // too. Only emit a comment change if it actually differs.
+      if (mainC.comment !== branchC.comment) {
+        if (branchC.comment === null) {
+          changes.push(
+            new DropCommentOnConstraint({
+              table: mainTable,
+              constraint: mainC,
+            }),
+          );
+        } else {
+          changes.push(
+            new CreateCommentOnConstraint({
+              table: branchTable,
+              constraint: branchC,
+            }),
+          );
+        }
+      }
+      continue;
+    }
+
+    const changed =
+      mainC.validated !== branchC.validated || !fieldsEqualExceptValidated;
+    if (changed) {
+      changes.push(
+        new AlterTableDropConstraint({
+          table: mainTable,
+          constraint: mainC,
+        }),
+      );
+      changes.push(
+        new AlterTableAddConstraint({
+          table: branchTable,
+          constraint: branchC,
+        }),
+      );
+      // Ensure constraint comment is applied after re-creation
+      if (branchC.comment !== null) {
+        changes.push(
+          new CreateCommentOnConstraint({
+            table: branchTable,
+            constraint: branchC,
+          }),
+        );
+      }
+    } else {
+      // Comment-only change on constraint
+      if (mainC.comment !== branchC.comment) {
+        if (branchC.comment === null) {
+          changes.push(
+            new DropCommentOnConstraint({
+              table: mainTable,
+              constraint: mainC,
+            }),
+          );
+        } else {
+          changes.push(
+            new CreateCommentOnConstraint({
+              table: branchTable,
+              constraint: branchC,
+            }),
+          );
+        }
+      }
+    }
+  }
+
+  return changes;
+}
+
+/**
+ * Diff two sets of tables from main and branch catalogs.
+ *
+ * @param ctx - Context containing version, currentUser, and defaultPrivilegeState
+ * @param main - The tables in the main catalog.
+ * @param branch - The tables in the branch catalog.
+ * @returns A list of changes to apply to main to make it match branch.
+ */
+export function diffTables(
+  ctx: Pick<
+    ObjectDiffContext,
+    "version" | "currentUser" | "defaultPrivilegeState"
+  >,
+  main: Record<string, Table>,
+  branch: Record<string, Table>,
+): TableChange[] {
+  const { created, dropped, altered } = diffObjects(main, branch);
+
+  const changes: TableChange[] = [];
+
+  for (const tableId of created) {
+    changes.push(new CreateTable({ table: branch[tableId] }));
+    const branchTable = branch[tableId];
+
+    // OWNER: If the table should be owned by someone other than the current user,
+    // emit ALTER TABLE ... OWNER TO after creation
+    if (branchTable.owner !== ctx.currentUser) {
+      changes.push(
+        new AlterTableChangeOwner({
+          table: branchTable,
+          owner: branchTable.owner,
+        }),
+      );
+    }
+
+    // ROW LEVEL SECURITY: If RLS should be enabled, emit ALTER TABLE ... ENABLE ROW LEVEL SECURITY
+    if (branchTable.row_security) {
+      changes.push(
+        new AlterTableEnableRowLevelSecurity({ table: branchTable }),
+      );
+    }
+
+    // FORCE ROW LEVEL SECURITY: If force RLS should be enabled, emit ALTER TABLE ... FORCE ROW LEVEL SECURITY
+    if (branchTable.force_row_security) {
+      changes.push(new AlterTableForceRowLevelSecurity({ table: branchTable }));
+    }
+
+    // REPLICA IDENTITY: If non-default, emit ALTER TABLE ... REPLICA IDENTITY
+    if (branchTable.replica_identity !== "d") {
+      changes.push(
+        new AlterTableSetReplicaIdentity({
+          table: branchTable,
+          mode: branchTable.replica_identity,
+          indexName: branchTable.replica_identity_index,
+        }),
+      );
+    }
+
+    changes.push(
+      ...createAlterConstraintChange(
+        // Create a dummy table with no constraints do diff constraints against
+        new Table({
+          // oxlint-disable-next-line typescript/no-misused-spread
+          ...branchTable,
+          constraints: [],
+        }),
+        branchTable,
+      ),
+    );
+
+    // Table comment on creation
+    if (branchTable.comment !== null && branchTable.comment !== undefined) {
+      changes.push(new CreateCommentOnTable({ table: branchTable }));
+    }
+
+    // Column comments on creation
+    for (const col of branchTable.columns) {
+      if (col.comment !== null && col.comment !== undefined) {
+        changes.push(
+          new CreateCommentOnColumn({ table: branchTable, column: col }),
+        );
+      }
+    }
+
+    // Table security labels on creation
+    for (const label of branchTable.security_labels) {
+      changes.push(
+        new CreateSecurityLabelOnTable({
+          table: branchTable,
+          securityLabel: label,
+        }),
+      );
+    }
+
+    // Column security labels on creation
+    for (const col of branchTable.columns) {
+      for (const label of col.security_labels ?? []) {
+        changes.push(
+          new CreateSecurityLabelOnColumn({
+            table: branchTable,
+            column: col,
+            securityLabel: label,
+          }),
+        );
+      }
+    }
+
+    // PRIVILEGES: For created objects, compare against default privileges state
+    // The migration script will run ALTER DEFAULT PRIVILEGES before CREATE (via constraint spec),
+    // so objects are created with the default privileges state in effect.
+    // We compare default privileges against desired privileges to generate REVOKE/GRANT statements
+    // needed to reach the final desired state.
+    const effectiveDefaults = ctx.defaultPrivilegeState.getEffectiveDefaults(
+      ctx.currentUser,
+      "table",
+      branchTable.schema ?? "",
+    );
+    const creatorFilteredDefaults =
+      branchTable.owner !== ctx.currentUser
+        ? effectiveDefaults.filter((p) => p.grantee !== ctx.currentUser)
+        : effectiveDefaults;
+    const desiredPrivileges = branchTable.privileges;
+    // Filter out owner privileges - owner always has ALL privileges implicitly
+    // and shouldn't be compared. Use the table owner as the reference.
+    const privilegeResults = diffPrivileges(
+      creatorFilteredDefaults,
+      desiredPrivileges,
+      branchTable.owner,
+    );
+
+    changes.push(
+      ...(emitColumnPrivilegeChanges(
+        privilegeResults,
+        branchTable,
+        branchTable,
+        "table",
+        {
+          Grant: GrantTablePrivileges,
+          Revoke: RevokeTablePrivileges,
+          RevokeGrantOption: RevokeGrantOptionTablePrivileges,
+        },
+        effectiveDefaults,
+        ctx.version,
+      ) as TableChange[]),
+    );
+  }
+
+  for (const tableId of dropped) {
+    changes.push(new DropTable({ table: main[tableId] }));
+  }
+
+  for (const tableId of altered) {
+    const mainTable = main[tableId];
+    const branchTable = branch[tableId];
+
+    // Dangerous operations (drop+create) are not performed by this tool.
+    // Only emit safe ALTER statements below.
+    // Only alterable properties changed - check each one
+
+    // PERSISTENCE (LOGGED/UNLOGGED)
+    if (mainTable.persistence !== branchTable.persistence) {
+      if (branchTable.persistence === "u" && mainTable.persistence === "p") {
+        changes.push(new AlterTableSetUnlogged({ table: mainTable }));
+      } else if (
+        branchTable.persistence === "p" &&
+        mainTable.persistence === "u"
+      ) {
+        changes.push(new AlterTableSetLogged({ table: mainTable }));
+      }
+    }
+
+    // ROW LEVEL SECURITY
+    if (mainTable.row_security !== branchTable.row_security) {
+      if (branchTable.row_security) {
+        changes.push(
+          new AlterTableEnableRowLevelSecurity({ table: mainTable }),
+        );
+      } else {
+        changes.push(
+          new AlterTableDisableRowLevelSecurity({ table: mainTable }),
+        );
+      }
+    }
+
+    // FORCE ROW LEVEL SECURITY
+    if (mainTable.force_row_security !== branchTable.force_row_security) {
+      if (branchTable.force_row_security) {
+        changes.push(new AlterTableForceRowLevelSecurity({ table: mainTable }));
+      } else {
+        changes.push(
+          new AlterTableNoForceRowLevelSecurity({ table: mainTable }),
+        );
+      }
+    }
+
+    // STORAGE PARAMS (WITH (...))
+    if (!deepEqual(mainTable.options, branchTable.options)) {
+      const mainOpts = mainTable.options ?? [];
+      const branchOpts = branchTable.options ?? [];
+
+      // Always set branch options when provided
+      if (branchOpts.length > 0) {
+        changes.push(
+          new AlterTableSetStorageParams({
+            table: mainTable,
+            options: branchOpts,
+          }),
+        );
+      }
+
+      // Reset any params that are present in main but absent in branch
+      if (mainOpts.length > 0) {
+        const mainNames = new Set(mainOpts.map((opt) => opt.split("=")[0]));
+        const branchNames = new Set(branchOpts.map((opt) => opt.split("=")[0]));
+        const removed: string[] = [];
+        for (const name of mainNames) {
+          if (!branchNames.has(name)) removed.push(name);
+        }
+        if (removed.length > 0) {
+          changes.push(
+            new AlterTableResetStorageParams({
+              table: mainTable,
+              params: removed,
+            }),
+          );
+        }
+      }
+    }
+
+    // REPLICA IDENTITY
+    // Re-emit when the mode changes, or when staying in 'i' mode but pointing
+    // at a different index. The index named on the branch must already exist
+    // before this ALTER runs; AlterTableSetReplicaIdentity declares that
+    // dependency in its `requires`.
+    const replicaIdentityChanged =
+      mainTable.replica_identity !== branchTable.replica_identity ||
+      (branchTable.replica_identity === "i" &&
+        mainTable.replica_identity_index !==
+          branchTable.replica_identity_index);
+    if (replicaIdentityChanged) {
+      changes.push(
+        new AlterTableSetReplicaIdentity({
+          table: mainTable,
+          mode: branchTable.replica_identity,
+          indexName: branchTable.replica_identity_index,
+        }),
+      );
+    }
+
+    // OWNER
+    if (mainTable.owner !== branchTable.owner) {
+      changes.push(
+        new AlterTableChangeOwner({
+          table: mainTable,
+          owner: branchTable.owner,
+        }),
+      );
+    }
+
+    // TABLE COMMENT (create/drop when comment changes)
+    if (mainTable.comment !== branchTable.comment) {
+      if (branchTable.comment === null) {
+        changes.push(new DropCommentOnTable({ table: mainTable }));
+      } else {
+        changes.push(new CreateCommentOnTable({ table: branchTable }));
+      }
+    }
+
+    // TABLE SECURITY LABELS
+    changes.push(
+      ...diffSecurityLabels<
+        CreateSecurityLabelOnTable | DropSecurityLabelOnTable
+      >(
+        mainTable.security_labels,
+        branchTable.security_labels,
+        (securityLabel) =>
+          new CreateSecurityLabelOnTable({
+            table: branchTable,
+            securityLabel,
+          }),
+        (securityLabel) =>
+          new DropSecurityLabelOnTable({
+            table: mainTable,
+            securityLabel,
+          }),
+      ),
+    );
+
+    // PARTITION ATTACH/DETACH
+    const mainIsPartition = Boolean(
+      mainTable.parent_schema && mainTable.parent_name,
+    );
+    const branchIsPartition = Boolean(
+      branchTable.parent_schema && branchTable.parent_name,
+    );
+
+    // Helper to resolve parent table from catalogs
+    const resolveParent = (
+      catalog: Record<string, Table>,
+      schema: string,
+      name: string,
+    ): Table | undefined => catalog[`table:${schema}.${name}`];
+
+    if (!mainIsPartition && branchIsPartition) {
+      const table = resolveParent(
+        branch,
+        branchTable.parent_schema as string,
+        branchTable.parent_name as string,
+      );
+      if (table) {
+        changes.push(
+          new AlterTableAttachPartition({ table, partition: branchTable }),
+        );
+      }
+    } else if (mainIsPartition && !branchIsPartition) {
+      const table = resolveParent(
+        main,
+        mainTable.parent_schema as string,
+        mainTable.parent_name as string,
+      );
+      if (table) {
+        changes.push(
+          new AlterTableDetachPartition({ table, partition: mainTable }),
+        );
+      }
+    } else if (mainIsPartition && branchIsPartition) {
+      const parentChanged =
+        mainTable.parent_schema !== branchTable.parent_schema ||
+        mainTable.parent_name !== branchTable.parent_name;
+      const boundChanged =
+        mainTable.partition_bound !== branchTable.partition_bound;
+      if (parentChanged || boundChanged) {
+        const oldParent = resolveParent(
+          main,
+          mainTable.parent_schema as string,
+          mainTable.parent_name as string,
+        );
+        if (oldParent) {
+          changes.push(
+            new AlterTableDetachPartition({
+              table: oldParent,
+              partition: mainTable,
+            }),
+          );
+        }
+        const newParent = resolveParent(
+          branch,
+          branchTable.parent_schema as string,
+          branchTable.parent_name as string,
+        );
+        if (newParent) {
+          changes.push(
+            new AlterTableAttachPartition({
+              table: newParent,
+              partition: branchTable,
+            }),
+          );
+        }
+      }
+    }
+
+    changes.push(...createAlterConstraintChange(mainTable, branchTable));
+
+    // COLUMNS
+    const mainCols = new Map(mainTable.columns.map((c) => [c.name, c]));
+    const branchCols = new Map(branchTable.columns.map((c) => [c.name, c]));
+
+    // Helper to get parent tables if this is a partition
+    // PostgreSQL automatically propagates column changes from parent to partitions,
+    // so we should skip changes on partitions when the parent has the same change
+    const getParentTables = (): {
+      parentMain: Table | null;
+      parentBranch: Table | null;
+    } => {
+      if (
+        !branchIsPartition ||
+        !branchTable.parent_schema ||
+        !branchTable.parent_name
+      ) {
+        return { parentMain: null, parentBranch: null };
+      }
+
+      const parentBranch = resolveParent(
+        branch,
+        branchTable.parent_schema,
+        branchTable.parent_name,
+      );
+      const parentMain = resolveParent(
+        main,
+        branchTable.parent_schema,
+        branchTable.parent_name,
+      );
+
+      return {
+        parentMain: parentMain ?? null,
+        parentBranch: parentBranch ?? null,
+      };
+    };
+
+    // Helper to check if parent has the same column property change
+    const parentHasSameColumnPropertyChange = (
+      columnName: string,
+      property: "type" | "default" | "not_null" | "identity",
+    ): boolean => {
+      const { parentMain, parentBranch } = getParentTables();
+      if (!parentMain || !parentBranch) {
+        return false;
+      }
+
+      const parentMainCol = parentMain.columns.find(
+        (c) => c.name === columnName,
+      );
+      const parentBranchCol = parentBranch.columns.find(
+        (c) => c.name === columnName,
+      );
+      const branchCol = branchCols.get(columnName);
+      const mainCol = mainCols.get(columnName);
+
+      if (!parentMainCol || !parentBranchCol || !branchCol || !mainCol) {
+        return false;
+      }
+
+      switch (property) {
+        case "type": {
+          const parentTypeChanged =
+            parentMainCol.data_type_str !== parentBranchCol.data_type_str ||
+            parentMainCol.collation !== parentBranchCol.collation;
+          const partitionTypeChanged =
+            mainCol.data_type_str !== branchCol.data_type_str ||
+            mainCol.collation !== branchCol.collation;
+          return (
+            parentTypeChanged &&
+            partitionTypeChanged &&
+            parentBranchCol.data_type_str === branchCol.data_type_str &&
+            parentBranchCol.collation === branchCol.collation
+          );
+        }
+        case "default": {
+          const parentDefaultChanged =
+            parentMainCol.default !== parentBranchCol.default;
+          const partitionDefaultChanged = mainCol.default !== branchCol.default;
+          return (
+            parentDefaultChanged &&
+            partitionDefaultChanged &&
+            parentBranchCol.default === branchCol.default
+          );
+        }
+        case "not_null": {
+          const parentNotNullChanged =
+            parentMainCol.not_null !== parentBranchCol.not_null;
+          const partitionNotNullChanged =
+            mainCol.not_null !== branchCol.not_null;
+          return (
+            parentNotNullChanged &&
+            partitionNotNullChanged &&
+            parentBranchCol.not_null === branchCol.not_null
+          );
+        }
+        case "identity": {
+          const parentIdentityChanged =
+            parentMainCol.is_identity !== parentBranchCol.is_identity ||
+            parentMainCol.is_identity_always !==
+              parentBranchCol.is_identity_always;
+          const partitionIdentityChanged =
+            mainCol.is_identity !== branchCol.is_identity ||
+            mainCol.is_identity_always !== branchCol.is_identity_always;
+          return (
+            parentIdentityChanged &&
+            partitionIdentityChanged &&
+            parentBranchCol.is_identity === branchCol.is_identity &&
+            parentBranchCol.is_identity_always === branchCol.is_identity_always
+          );
+        }
+      }
+    };
+
+    // Helper to check if parent has the same column add/drop
+    const shouldSkipColumnAddDropOnPartition = (
+      columnName: string,
+      changeType: "add" | "drop",
+    ): boolean => {
+      const { parentMain, parentBranch } = getParentTables();
+      if (!parentMain || !parentBranch) {
+        return false;
+      }
+
+      const parentMainHasCol = parentMain.columns.some(
+        (c) => c.name === columnName,
+      );
+      const parentBranchHasCol = parentBranch.columns.some(
+        (c) => c.name === columnName,
+      );
+
+      if (changeType === "add") {
+        // Check if parent also has this column added and final states match
+        if (!parentMainHasCol && parentBranchHasCol) {
+          const parentBranchCol = parentBranch.columns.find(
+            (c) => c.name === columnName,
+          );
+          const branchCol = branchCols.get(columnName);
+          return (
+            parentBranchCol !== undefined &&
+            branchCol !== undefined &&
+            parentBranchCol.data_type_str === branchCol.data_type_str &&
+            parentBranchCol.collation === branchCol.collation &&
+            parentBranchCol.default === branchCol.default &&
+            parentBranchCol.not_null === branchCol.not_null
+          );
+        }
+      } else {
+        // changeType === "drop"
+        // If parent is dropping the column, skip on partition
+        return parentMainHasCol && !parentBranchHasCol;
+      }
+
+      return false;
+    };
+
+    // Added columns
+    for (const [name, col] of branchCols) {
+      if (!mainCols.has(name)) {
+        // Skip if this is a partition and parent has the same column added
+        if (shouldSkipColumnAddDropOnPartition(name, "add")) {
+          continue;
+        }
+        changes.push(
+          new AlterTableAddColumn({ table: branchTable, column: col }),
+        );
+        if (col.comment !== null && col.comment !== undefined) {
+          changes.push(
+            new CreateCommentOnColumn({ table: branchTable, column: col }),
+          );
+        }
+      }
+    }
+
+    // Dropped columns
+    for (const [name, col] of mainCols) {
+      if (!branchCols.has(name)) {
+        // Skip if this is a partition and parent has the same column dropped
+        if (shouldSkipColumnAddDropOnPartition(name, "drop")) {
+          continue;
+        }
+        changes.push(
+          new AlterTableDropColumn({ table: mainTable, column: col }),
+        );
+      }
+    }
+
+    // Altered columns
+    for (const [name, mainCol] of mainCols) {
+      const branchCol = branchCols.get(name);
+      if (!branchCol) continue;
+
+      const columnTypeChanged =
+        mainCol.data_type_str !== branchCol.data_type_str;
+      const columnCollationChanged = mainCol.collation !== branchCol.collation;
+      const needsDefaultSafeFlow =
+        columnTypeChanged && mainCol.default !== null;
+
+      // TYPE or COLLATION change
+      if (columnTypeChanged || columnCollationChanged) {
+        // Skip if parent has the same type/collation change
+        if (!parentHasSameColumnPropertyChange(name, "type")) {
+          if (needsDefaultSafeFlow) {
+            changes.push(
+              new AlterTableAlterColumnDropDefault({
+                table: branchTable,
+                column: branchCol,
+              }),
+            );
+          }
+          changes.push(
+            new AlterTableAlterColumnType({
+              table: branchTable,
+              column: branchCol,
+              previousColumn: mainCol,
+            }),
+          );
+          if (needsDefaultSafeFlow && branchCol.default !== null) {
+            changes.push(
+              new AlterTableAlterColumnSetDefault({
+                table: branchTable,
+                column: branchCol,
+              }),
+            );
+          }
+        }
+      }
+
+      // PostgreSQL rejects SET DEFAULT while the column still has identity metadata,
+      // so identity removal must lead the IDENTITY -> serial/default transition.
+      if (mainCol.is_identity && !branchCol.is_identity) {
+        if (!parentHasSameColumnPropertyChange(name, "identity")) {
+          changes.push(
+            new AlterTableAlterColumnDropIdentity({
+              table: branchTable,
+              column: branchCol,
+            }),
+          );
+        }
+      }
+
+      // DEFAULT change
+      if (mainCol.default !== branchCol.default) {
+        // Skip if parent has the same default change
+        if (!parentHasSameColumnPropertyChange(name, "default")) {
+          if (needsDefaultSafeFlow) {
+            // Defaults were already dropped/re-set in the type-change flow above.
+            continue;
+          }
+          if (branchCol.default === null) {
+            // Drop default value
+            changes.push(
+              new AlterTableAlterColumnDropDefault({
+                table: branchTable,
+                column: branchCol,
+              }),
+            );
+          } else {
+            // Set new default value
+            const isGeneratedColumn = branchCol.is_generated;
+            const isPostgresLowerThan17 = ctx.version < 170000;
+            const generatedStatusChanged =
+              mainCol.is_generated !== branchCol.is_generated;
+
+            if (
+              isGeneratedColumn &&
+              (isPostgresLowerThan17 || generatedStatusChanged)
+            ) {
+              // For generated columns in < PostgreSQL 17, we need to drop and recreate
+              // instead of using SET EXPRESSION AS for computed columns. We also
+              // need to recreate the column when switching between regular and
+              // generated states because SET EXPRESSION only applies to existing
+              // generated columns.
+              // cf: https://git.postgresql.org/gitweb/?p=postgresql.git;a=commitdiff;h=5d06e99a3
+              // cf: https://www.postgresql.org/docs/release/17.0/
+              // > Allow ALTER TABLE to change a column's generation expression
+              changes.push(
+                new AlterTableDropColumn({
+                  table: mainTable,
+                  column: mainCol,
+                }),
+              );
+              changes.push(
+                new AlterTableAddColumn({
+                  table: branchTable,
+                  column: branchCol,
+                }),
+              );
+            } else {
+              // Use standard SET DEFAULT or SET EXPRESSION AS for newer PostgreSQL versions
+              changes.push(
+                new AlterTableAlterColumnSetDefault({
+                  table: branchTable,
+                  column: branchCol,
+                }),
+              );
+            }
+          }
+        }
+      }
+
+      // Serial-like defaults have to be cleared before ADD GENERATED AS IDENTITY,
+      // while mode-only flips stay in-place on an existing identity column.
+      if (
+        (!mainCol.is_identity && branchCol.is_identity) ||
+        (mainCol.is_identity &&
+          branchCol.is_identity &&
+          mainCol.is_identity_always !== branchCol.is_identity_always)
+      ) {
+        // Skip if parent has the same identity change
+        if (!parentHasSameColumnPropertyChange(name, "identity")) {
+          if (!mainCol.is_identity && branchCol.is_identity) {
+            changes.push(
+              new AlterTableAlterColumnAddIdentity({
+                table: branchTable,
+                column: branchCol,
+              }),
+            );
+          } else if (
+            mainCol.is_identity &&
+            branchCol.is_identity &&
+            mainCol.is_identity_always !== branchCol.is_identity_always
+          ) {
+            changes.push(
+              new AlterTableAlterColumnSetGenerated({
+                table: branchTable,
+                column: branchCol,
+              }),
+            );
+          }
+        }
+      }
+
+      // NOT NULL change
+      if (mainCol.not_null !== branchCol.not_null) {
+        // Skip if parent has the same NOT NULL change
+        if (!parentHasSameColumnPropertyChange(name, "not_null")) {
+          if (branchCol.not_null) {
+            changes.push(
+              new AlterTableAlterColumnSetNotNull({
+                table: branchTable,
+                column: branchCol,
+              }),
+            );
+          } else {
+            changes.push(
+              new AlterTableAlterColumnDropNotNull({
+                table: branchTable,
+                column: branchCol,
+              }),
+            );
+          }
+        }
+      }
+
+      // COMMENT change on column
+      // Note: Comments are NOT automatically propagated from parent to partitions,
+      // so we should NOT skip comment changes even if parent has the same change
+      if (mainCol.comment !== branchCol.comment) {
+        if (branchCol.comment === null) {
+          changes.push(
+            new DropCommentOnColumn({ table: mainTable, column: mainCol }),
+          );
+        } else {
+          changes.push(
+            new CreateCommentOnColumn({
+              table: branchTable,
+              column: branchCol,
+            }),
+          );
+        }
+      }
+
+      // SECURITY LABELS on column
+      changes.push(
+        ...diffSecurityLabels<
+          CreateSecurityLabelOnColumn | DropSecurityLabelOnColumn
+        >(
+          mainCol.security_labels ?? [],
+          branchCol.security_labels ?? [],
+          (securityLabel) =>
+            new CreateSecurityLabelOnColumn({
+              table: branchTable,
+              column: branchCol,
+              securityLabel,
+            }),
+          (securityLabel) =>
+            new DropSecurityLabelOnColumn({
+              table: mainTable,
+              column: mainCol,
+              securityLabel,
+            }),
+        ),
+      );
+    }
+
+    // Added columns with security labels (for created columns on existing tables)
+    for (const [name, col] of branchCols) {
+      if (!mainCols.has(name)) {
+        for (const label of col.security_labels ?? []) {
+          changes.push(
+            new CreateSecurityLabelOnColumn({
+              table: branchTable,
+              column: col,
+              securityLabel: label,
+            }),
+          );
+        }
+      }
+    }
+
+    // PRIVILEGES (unified object and column privileges)
+    // Filter out owner privileges - owner always has ALL privileges implicitly
+    // and shouldn't be compared. Use branch owner as the reference.
+    const privilegeResults = diffPrivileges(
+      mainTable.privileges,
+      branchTable.privileges,
+      branchTable.owner,
+    );
+
+    changes.push(
+      ...(emitColumnPrivilegeChanges(
+        privilegeResults,
+        branchTable,
+        mainTable,
+        "table",
+        {
+          Grant: GrantTablePrivileges,
+          Revoke: RevokeTablePrivileges,
+          RevokeGrantOption: RevokeGrantOptionTablePrivileges,
+        },
+        mainTable.privileges,
+        ctx.version,
+      ) as TableChange[]),
+    );
+  }
+
+  return changes;
+}