@supabase/pg-delta 1.0.0-alpha.2 → 1.0.0-alpha.21

package/src/core/postgres-config.ts

@@ -0,0 +1,458 @@
+/**
+ * PostgreSQL connection configuration with custom type handlers.
+ */
+
+import type { ClientBase, PoolClient, PoolConfig } from "pg";
+import { escapeIdentifier, Pool, types } from "pg";
+import { normalizeConnectionUrl } from "./connection-url.ts";
+import { parseSslConfig } from "./plan/ssl-config.ts";
+
+// ============================================================================
+// Array Parser
+// ============================================================================
+
+/**
+ * Parse PostgreSQL array string into JavaScript array.
+ * Handles: {val1,val2}, {NULL,val}, {"quoted,val"}, nested arrays.
+ */
+function parseArray(
+  value: string,
+  parseElement: (val: string) => unknown = (v) => v,
+): unknown[] {
+  if (!value || value === "{}") return [];
+
+  // Remove outer braces
+  const inner = value.slice(1, -1);
+  if (inner === "") return [];
+
+  const result: unknown[] = [];
+  let current = "";
+  let inQuotes = false;
+  let depth = 0;
+
+  for (let i = 0; i < inner.length; i++) {
+    const char = inner[i];
+
+    if (char === '"' && inner[i - 1] !== "\\") {
+      inQuotes = !inQuotes;
+      current += char;
+    } else if (char === "{" && !inQuotes) {
+      depth++;
+      current += char;
+    } else if (char === "}" && !inQuotes) {
+      depth--;
+      current += char;
+    } else if (char === "," && !inQuotes && depth === 0) {
+      result.push(parseElement(current));
+      current = "";
+    } else {
+      current += char;
+    }
+  }
+
+  if (current !== "") {
+    result.push(parseElement(current));
+  }
+
+  return result;
+}
+
+/**
+ * Parse element, handling NULL, quoted strings, and unquoted values.
+ */
+function parseStringElement(val: string): string | null {
+  if (val === "NULL") return null;
+  if (val.startsWith('"') && val.endsWith('"')) {
+    // Unescape quoted string
+    return val.slice(1, -1).replace(/\\(.)/g, "$1");
+  }
+  return val;
+}
+
+function parseIntElement(val: string): number | null {
+  if (val === "NULL") return null;
+  return Number.parseInt(val, 10);
+}
+
+// ============================================================================
+// Type Parsers
+// ============================================================================
+
+// int2vector: "1 2 3" -> [1, 2, 3]
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(22, (val: string) => {
+  if (!val || val === "") return [];
+  return val
+    .split(" ")
+    .map(Number)
+    .filter((n: number) => !Number.isNaN(n));
+});
+
+// bigint: string -> BigInt
+types.setTypeParser(20, (val: string) => BigInt(val));
+
+// PostgreSQL array types
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(1002, (val: string) => parseArray(val, parseStringElement)); // "char"[]
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(1009, (val: string) => parseArray(val, parseStringElement)); // text[]
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(1015, (val: string) => parseArray(val, parseStringElement)); // varchar[]
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(1005, (val: string) => parseArray(val, parseIntElement)); // int2[]
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(1007, (val: string) => parseArray(val, parseIntElement)); // int4[]
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(1016, (val: string) => parseArray(val, parseIntElement)); // int8[]
+
+const DEFAULT_POOL_MAX = Number(process.env.PGDELTA_POOL_MAX) || 5;
+const DEFAULT_CONNECTION_TIMEOUT_MS =
+  Number(process.env.PGDELTA_CONNECTION_TIMEOUT_MS) || 3_000;
+const DEFAULT_CONNECT_TIMEOUT_MS =
+  Number(process.env.PGDELTA_CONNECT_TIMEOUT_MS) || 2_500;
+const DEFAULT_CONNECT_MAX_ATTEMPTS =
+  Number(process.env.PGDELTA_CONNECT_MAX_ATTEMPTS) || 3;
+const DEFAULT_CONNECT_BASE_BACKOFF_MS =
+  Number(process.env.PGDELTA_CONNECT_BASE_BACKOFF_MS) || 250;
+const DEFAULT_CONNECT_MAX_BACKOFF_MS =
+  Number(process.env.PGDELTA_CONNECT_MAX_BACKOFF_MS) || 1_000;
+
+// PostgreSQL auth-class SQLSTATE codes: not retryable.
+const NON_RETRYABLE_PG_CODES = new Set([
+  "28000", // invalid_authorization_specification
+  "28P01", // invalid_password
+  "28P02", // pgdelta: alias reserved here to future-proof against new auth codes
+]);
+
+// Non-retryable TLS/SSL markers. The `pg` driver surfaces TLS failures as
+// either plain Node `Error` instances with a code on `ERR_TLS_*` or error
+// messages that include well-known cert/TLS terminology; we match both
+// because node-pg normalises some of these.
+const TLS_MESSAGE_MARKERS = [
+  "self-signed certificate",
+  "self signed certificate",
+  "unable to verify the first certificate",
+  "certificate has expired",
+  "tls",
+  "ssl",
+];
+
+/**
+ * Return true when `err` represents a transient connect failure that makes
+ * sense to retry with backoff (e.g. refused connections, DNS blips, our own
+ * eager-connect timeout wrapper). Returns false for permanent failures such
+ * as authentication errors, TLS negotiation errors, and `ENOTFOUND`.
+ *
+ * Unknown errors are treated as retryable on purpose: transient-by-default
+ * is safer here because a duplicated retry is strictly cheaper than a spurious
+ * hard failure during catalog extraction.
+ */
+export function isRetryableConnectError(err: unknown): boolean {
+  if (!(err instanceof Error)) return true;
+  const code = (err as NodeJS.ErrnoException & { code?: string }).code;
+
+  if (code && NON_RETRYABLE_PG_CODES.has(code)) return false;
+  if (code === "ENOTFOUND") return false;
+  if (code && typeof code === "string" && code.startsWith("ERR_TLS")) {
+    return false;
+  }
+
+  const message = err.message?.toLowerCase() ?? "";
+  // Our own eager-connect timeout wrapper is retryable (flaky network).
+  if (message.includes("timed out after")) return true;
+  for (const marker of TLS_MESSAGE_MARKERS) {
+    if (message.includes(marker)) return false;
+  }
+  return true;
+}
+
+/**
+ * Retry an async `connect` operation with bounded exponential backoff.
+ * Stops immediately on a non-retryable error. On exhausted attempts, throws
+ * the last observed error.
+ *
+ * Exposed for testing — production call sites always go through
+ * {@link createManagedPool}.
+ */
+export async function connectWithRetry<T>(opts: {
+  connect: (attempt: number) => Promise<T>;
+  isRetryable?: (err: unknown) => boolean;
+  maxAttempts?: number;
+  baseBackoffMs?: number;
+  maxBackoffMs?: number;
+  sleep?: (ms: number) => Promise<void>;
+}): Promise<T> {
+  const maxAttempts = opts.maxAttempts ?? DEFAULT_CONNECT_MAX_ATTEMPTS;
+  const baseBackoffMs = opts.baseBackoffMs ?? DEFAULT_CONNECT_BASE_BACKOFF_MS;
+  const maxBackoffMs = opts.maxBackoffMs ?? DEFAULT_CONNECT_MAX_BACKOFF_MS;
+  const isRetryable = opts.isRetryable ?? isRetryableConnectError;
+  const sleep =
+    opts.sleep ?? ((ms: number) => new Promise((r) => setTimeout(r, ms)));
+
+  let lastError: unknown;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await opts.connect(attempt);
+    } catch (err) {
+      lastError = err;
+      if (attempt >= maxAttempts || !isRetryable(err)) {
+        throw err;
+      }
+      const backoff = Math.min(
+        baseBackoffMs * 2 ** (attempt - 1),
+        maxBackoffMs,
+      );
+      await sleep(backoff);
+    }
+  }
+  // Unreachable: loop either returns or throws.
+  throw lastError;
+}
+
+/**
+ * Options for creating a Pool with event listeners.
+ */
+interface CreatePoolOptions extends Partial<PoolConfig> {
+  /** Called when a new client connects to the pool */
+  onConnect?: (client: ClientBase) => void | Promise<void>;
+  /** Called when an idle client emits an error */
+  onError?: (err: Error, client: PoolClient) => void;
+  /** Called when a client is acquired from the pool */
+  onAcquire?: (client: PoolClient) => void;
+  /** Called when a client is removed from the pool */
+  onRemove?: (client: PoolClient) => void;
+}
+
+/**
+ * Create a Pool with custom type handlers and optional event listeners.
+ *
+ * `connectionString` may be `undefined` when the caller needs pg to rely on
+ * explicit `host`/`port`/`user`/... fields from `options` instead — notably
+ * the bracketed-IPv6 workaround in {@link poolConfigFromUrl}, where passing
+ * the connection string would cause `pg-connection-string` to re-inject the
+ * bracketed host that breaks `getaddrinfo`.
+ */
+export function createPool(
+  connectionString: string | undefined,
+  options?: CreatePoolOptions,
+): Pool {
+  const { onConnect, onError, onAcquire, onRemove, ...config } = options ?? {};
+  const pool = new Pool({
+    ...(connectionString ? { connectionString } : {}),
+    max: DEFAULT_POOL_MAX,
+    connectionTimeoutMillis: DEFAULT_CONNECTION_TIMEOUT_MS,
+    ...config,
+  });
+
+  if (onConnect) {
+    const pendingClientSetup = new WeakMap<PoolClient, Promise<void>>();
+    const waitForClientSetup = async (client: PoolClient) => {
+      const setup = pendingClientSetup.get(client);
+      if (setup) {
+        await setup;
+        return;
+      }
+      throw new Error(
+        "Internal error: pool client was acquired before async onConnect setup was registered. This indicates a bug in the pool wrapper logic; please report it with reproduction steps.",
+      );
+    };
+    const originalConnect = pool.connect.bind(pool);
+
+    pool.on("connect", (client) => {
+      pendingClientSetup.set(
+        client,
+        Promise.resolve().then(() => onConnect(client)),
+      );
+    });
+
+    pool.connect = ((
+      callback?: (
+        err: Error | undefined,
+        client: PoolClient | undefined,
+        release: (err?: Error | boolean) => void,
+      ) => void,
+    ) => {
+      if (!callback) {
+        return originalConnect().then(async (client) => {
+          try {
+            await waitForClientSetup(client);
+            return client;
+          } catch (setupError) {
+            (client as PoolClient).release?.(setupError as Error);
+            throw setupError;
+          }
+        });
+      }
+
+      return originalConnect(async (err, client, release) => {
+        if (err || !client) {
+          callback(err, client, release);
+          return;
+        }
+
+        try {
+          await waitForClientSetup(client);
+          callback(err, client, release);
+        } catch (setupError) {
+          release(setupError as Error);
+          callback(setupError as Error, undefined, () => {});
+        }
+      });
+    }) as Pool["connect"];
+  }
+  if (onError) pool.on("error", onError);
+  if (onAcquire) pool.on("acquire", onAcquire);
+  if (onRemove) pool.on("remove", onRemove);
+
+  return pool;
+}
+
+/**
+ * Build a pg {@link PoolConfig} from a cleaned connection URL.
+ *
+ * For most URLs this just returns `{ connectionString }` and pg does its
+ * normal parsing. But for URLs whose hostname is a bracketed IPv6 literal
+ * (e.g. `postgresql://user@[::1]:5432/db`, as produced by
+ * {@link normalizeConnectionUrl}), we expand the URL into explicit
+ * `host`/`port`/`user`/`password`/`database` fields with a **bare** IPv6
+ * host — no brackets.
+ *
+ * This works around a `pg-connection-string` quirk: its parser sets
+ * `config.host` to the WHATWG `URL.hostname`, which keeps the surrounding
+ * `[...]` for IPv6 literals. That bracketed value is then passed verbatim to
+ * `getaddrinfo`, which rejects it with `ENOTFOUND`. Since
+ * `pg`'s connection-parameters module does
+ * `Object.assign({}, config, parse(connectionString))`, any `host` we pass
+ * alongside `connectionString` gets clobbered — so we drop `connectionString`
+ * entirely on this path and hand pg the parsed fields directly.
+ *
+ * Remaining query parameters (e.g. `application_name`, `options`,
+ * `connect_timeout`) are forwarded as top-level config keys, mirroring how
+ * `pg-connection-string` would normally surface them.
+ */
+export function poolConfigFromUrl(cleanedUrl: string): PoolConfig {
+  const urlObj = new URL(cleanedUrl);
+  if (!urlObj.hostname.startsWith("[")) {
+    return { connectionString: cleanedUrl };
+  }
+
+  const config: Record<string, unknown> = {
+    host: urlObj.hostname.slice(1, -1),
+  };
+  if (urlObj.port) config.port = Number(urlObj.port);
+  if (urlObj.username) config.user = decodeURIComponent(urlObj.username);
+  if (urlObj.password) config.password = decodeURIComponent(urlObj.password);
+  if (urlObj.pathname.length > 1) {
+    config.database = decodeURIComponent(urlObj.pathname.slice(1));
+  }
+  for (const [key, value] of urlObj.searchParams) {
+    config[key] = value;
+  }
+  return config as PoolConfig;
+}
+
+/**
+ * End a pool and wait for all client sockets to fully close.
+ *
+ * pg-pool's `pool.end()` resolves once clients are removed from its
+ * internal bookkeeping, but the underlying `client.end()` calls (which
+ * close the TCP/TLS sockets) are fired asynchronously *after* that.
+ * If the server (e.g. a test container) is stopped right after
+ * `pool.end()` resolves, the still-open sockets receive an unexpected
+ * RST and emit unhandled "Connection terminated unexpectedly" errors.
+ *
+ * This helper waits for every `remove` event — which pg-pool emits
+ * inside each `client.end()` callback — ensuring all sockets are
+ * truly closed before it resolves.
+ */
+/**
+ * Create a pool from a connection URL with standard session setup:
+ * SSL parsing, search_path isolation, optional SET ROLE, and 57P01 suppression.
+ *
+ * Returns the pool and a `close` function that properly waits for all sockets
+ * to close (via {@link endPool}).
+ */
+export async function createManagedPool(
+  url: string,
+  options?: { role?: string; label?: "source" | "target" },
+): Promise<{ pool: Pool; close: () => Promise<void> }> {
+  // Normalize percent-encoded IPv6 hosts (e.g. `2406%3A...%3Ab3c9`) into the
+  // canonical bracketed form before the URL reaches `parseSslConfig` or pg.
+  // Non-IPv6 hosts are returned unchanged.
+  const normalizedUrl = normalizeConnectionUrl(url);
+  const sslConfig = await parseSslConfig(
+    normalizedUrl,
+    options?.label ?? "target",
+  );
+  // Expand bracketed-IPv6 URLs into explicit pg fields so the brackets never
+  // reach `getaddrinfo` — see `poolConfigFromUrl` for the full rationale.
+  const connectionConfig = poolConfigFromUrl(sslConfig.cleanedUrl);
+  const pool = createPool(connectionConfig.connectionString, {
+    ...connectionConfig,
+    ...(sslConfig.ssl !== undefined ? { ssl: sslConfig.ssl } : {}),
+    onError: (err: Error & { code?: string }) => {
+      if (err.code !== "57P01") {
+        console.error("Pool error:", err);
+      }
+    },
+    onConnect: async (client) => {
+      await client.query("SET search_path = ''");
+      if (options?.role) {
+        await client.query(`SET ROLE ${escapeIdentifier(options.role)}`);
+      }
+    },
+  });
+
+  // Eagerly validate connectivity so SSL/auth failures surface immediately
+  // instead of hanging on the first real query. node-pg's connectionTimeoutMillis
+  // is not reliably enforced under Bun when SSL negotiation hangs. Transient
+  // failures (refused connections, flaky DNS, our own timeout wrapper) are
+  // retried with bounded exponential backoff; auth/TLS/ENOTFOUND fail fast.
+  const label = options?.label ?? "target";
+  const timeoutMs = DEFAULT_CONNECT_TIMEOUT_MS;
+  try {
+    const client = await connectWithRetry({
+      connect: () =>
+        Promise.race([
+          pool.connect(),
+          new Promise<never>((_, reject) =>
+            setTimeout(
+              () =>
+                reject(
+                  new Error(
+                    `Connection to ${label} database timed out after ${timeoutMs}ms. ` +
+                      `The server may require SSL, use an invalid certificate, or be unreachable.`,
+                  ),
+                ),
+              timeoutMs,
+            ),
+          ),
+        ]),
+    });
+    client.release();
+  } catch (err) {
+    await pool.end().catch(() => {});
+    throw err;
+  }
+
+  return { pool, close: () => endPool(pool) };
+}
+
+export function endPool(pool: Pool): Promise<void> {
+  const clientCount = pool.totalCount;
+
+  if (clientCount === 0) {
+    return pool.end();
+  }
+
+  return new Promise<void>((resolve, reject) => {
+    let removed = 0;
+    pool.on("remove", function onRemove() {
+      if (++removed >= clientCount) {
+        pool.removeListener("remove", onRemove);
+        resolve();
+      }
+    });
+    pool.end().catch(reject);
+  });
+}

package/src/core/sort/custom-constraints.ts

@@ -0,0 +1,235 @@
+import type { Change } from "../change.types.ts";
+import { getSchema } from "../change-utils.ts";
+import {
+  GrantRoleDefaultPrivileges,
+  RevokeRoleDefaultPrivileges,
+} from "../objects/role/changes/role.privilege.ts";
+import {
+  AlterTableAlterColumnAddIdentity,
+  AlterTableAlterColumnDropDefault,
+  AlterTableAlterColumnDropIdentity,
+  AlterTableAlterColumnSetDefault,
+} from "../objects/table/changes/table.alter.ts";
+import type { Constraint } from "./types.ts";
+
+/**
+ * Maps object type names to PostgreSQL default privilege objtype codes.
+ * This mirrors the mapping in base.default-privileges.ts.
+ */
+function objectTypeToObjtype(objectType: string): string | null {
+  switch (objectType) {
+    case "table":
+    case "view":
+    case "materialized_view":
+      return "r"; // Relations
+    case "sequence":
+      return "S"; // Sequences
+    case "procedure":
+    case "function":
+    case "aggregate":
+      return "f"; // Functions/routines
+    case "type":
+    case "domain":
+    case "enum":
+    case "range":
+    case "composite_type":
+      return "T"; // Types
+    case "schema":
+      return "n"; // Schemas
+    default:
+      return null;
+  }
+}
+
+/**
+ * A function that generates constraints for a list of changes.
+ * Should be optimized to avoid O(N²) complexity by using lookups/indexing.
+ */
+type ConstraintGenerator = (changes: Change[]) => Constraint[];
+
+/**
+ * Generate constraints to ensure ALTER DEFAULT PRIVILEGES comes before CREATE statements.
+ *
+ * Rules:
+ * - Only applies when the default privilege's schema matches the CREATE statement's schema
+ *   (or if the default privilege is global, applies to all schemas)
+ * - Only applies when the default privilege's objtype matches the CREATE statement's object type
+ * - Excludes CREATE ROLE and CREATE SCHEMA since they are dependencies
+ *   of ALTER DEFAULT PRIVILEGES and must come before it
+ *
+ * implementation: O(N) using schema/objtype indexing.
+ */
+function generateDefaultPrivilegeConstraints(changes: Change[]): Constraint[] {
+  const constraints: Constraint[] = [];
+  const defaultPrivilegeIndices: number[] = [];
+  // Map<objtype_code, Map<schema_name, index[]>>
+  const createsByObjTypeAndSchema = new Map<string, Map<string, number[]>>();
+
+  // Pass 1: Index changes
+  for (let i = 0; i < changes.length; i++) {
+    const change = changes[i];
+
+    // Identify default privilege changes
+    if (
+      change instanceof GrantRoleDefaultPrivileges ||
+      change instanceof RevokeRoleDefaultPrivileges
+    ) {
+      defaultPrivilegeIndices.push(i);
+      continue;
+    }
+
+    // Identify CREATE object changes (excluding role/schema)
+    if (
+      change.operation === "create" &&
+      change.scope === "object" &&
+      change.objectType !== "role" &&
+      change.objectType !== "schema"
+    ) {
+      const objTypeCode = objectTypeToObjtype(change.objectType);
+      if (!objTypeCode) continue;
+
+      const schema = getSchema(change);
+      // Default privileges only apply to schema-contained objects.
+      if (schema) {
+        let schemaMap = createsByObjTypeAndSchema.get(objTypeCode);
+        if (!schemaMap) {
+          schemaMap = new Map();
+          createsByObjTypeAndSchema.set(objTypeCode, schemaMap);
+        }
+
+        let indices = schemaMap.get(schema);
+        if (!indices) {
+          indices = [];
+          schemaMap.set(schema, indices);
+        }
+        indices.push(i);
+      }
+    }
+  }
+
+  // Pass 2: Generate constraints
+  for (const privIndex of defaultPrivilegeIndices) {
+    const privChange = changes[privIndex] as {
+      inSchema: string | null;
+      objtype: string;
+    };
+    const privSchema = privChange.inSchema;
+    const privObjType = privChange.objtype;
+
+    const schemaMap = createsByObjTypeAndSchema.get(privObjType);
+    if (!schemaMap) continue;
+
+    if (privSchema === null) {
+      // Global default privilege: applies to ALL schemas
+      for (const indices of schemaMap.values()) {
+        for (const createIndex of indices) {
+          // (No self-check needed as types differ)
+          constraints.push({
+            sourceChangeIndex: privIndex,
+            targetChangeIndex: createIndex,
+            source: "custom",
+          });
+        }
+      }
+    } else {
+      // Specific schema: applies only to that schema
+      const indices = schemaMap.get(privSchema);
+      if (indices) {
+        for (const createIndex of indices) {
+          constraints.push({
+            sourceChangeIndex: privIndex,
+            targetChangeIndex: createIndex,
+            source: "custom",
+          });
+        }
+      }
+    }
+  }
+
+  return constraints;
+}
+
+function generateIdentityTransitionConstraints(
+  changes: Change[],
+): Constraint[] {
+  const constraints: Constraint[] = [];
+  const dropDefaultByColumn = new Map<string, number[]>();
+  const dropIdentityByColumn = new Map<string, number[]>();
+  const addIdentityByColumn = new Map<string, number[]>();
+  const setDefaultByColumn = new Map<string, number[]>();
+
+  for (let i = 0; i < changes.length; i++) {
+    const change = changes[i];
+    const columnKey =
+      "table" in change && "column" in change
+        ? `${change.table.schema}.${change.table.name}.${change.column.name}`
+        : null;
+    if (!columnKey) continue;
+
+    if (change instanceof AlterTableAlterColumnDropDefault) {
+      const entries = dropDefaultByColumn.get(columnKey) ?? [];
+      entries.push(i);
+      dropDefaultByColumn.set(columnKey, entries);
+    } else if (change instanceof AlterTableAlterColumnAddIdentity) {
+      const entries = addIdentityByColumn.get(columnKey) ?? [];
+      entries.push(i);
+      addIdentityByColumn.set(columnKey, entries);
+    } else if (change instanceof AlterTableAlterColumnDropIdentity) {
+      const entries = dropIdentityByColumn.get(columnKey) ?? [];
+      entries.push(i);
+      dropIdentityByColumn.set(columnKey, entries);
+    } else if (change instanceof AlterTableAlterColumnSetDefault) {
+      const entries = setDefaultByColumn.get(columnKey) ?? [];
+      entries.push(i);
+      setDefaultByColumn.set(columnKey, entries);
+    }
+  }
+
+  // These rules only order same-column ALTERs inside the create/alter phase.
+  // Sequence drops are handled separately in the earlier drop phase.
+  for (const [columnKey, dropDefaultIndexes] of dropDefaultByColumn) {
+    const addIdentityIndexes = addIdentityByColumn.get(columnKey) ?? [];
+    for (const sourceIndex of dropDefaultIndexes) {
+      for (const targetIndex of addIdentityIndexes) {
+        constraints.push({
+          sourceChangeIndex: sourceIndex,
+          targetChangeIndex: targetIndex,
+          source: "custom",
+        });
+      }
+    }
+  }
+
+  for (const [columnKey, dropIdentityIndexes] of dropIdentityByColumn) {
+    const setDefaultIndexes = setDefaultByColumn.get(columnKey) ?? [];
+    for (const sourceIndex of dropIdentityIndexes) {
+      for (const targetIndex of setDefaultIndexes) {
+        constraints.push({
+          sourceChangeIndex: sourceIndex,
+          targetChangeIndex: targetIndex,
+          source: "custom",
+        });
+      }
+    }
+  }
+
+  return constraints;
+}
+
+/**
+ * All custom constraint generators.
+ */
+const customConstraintGenerators: ConstraintGenerator[] = [
+  generateDefaultPrivilegeConstraints,
+  generateIdentityTransitionConstraints,
+];
+
+/**
+ * Generate Constraints from custom constraint generators.
+ *
+ * Iterates through registered generators to produce constraints.
+ * Generators should be optimized (e.g. using indexing) to avoid O(N²) complexity.
+ */
+export function generateCustomConstraints(changes: Change[]): Constraint[] {
+  return customConstraintGenerators.flatMap((generate) => generate(changes));
+}