@supabase/pg-delta 1.0.0-alpha.13 → 1.0.0-alpha.15

package/README.md

@@ -181,7 +181,13 @@ See [Integrations Documentation](./docs/integrations.md) for complete details.
 
 ## Contributing
 
-Contributions welcome! Feel free to submit issues and pull requests.
+Please follow the repository-level guide in [../../CONTRIBUTING.md](../../CONTRIBUTING.md).
+
+In particular:
+
+- Open an issue first.
+- Wait for maintainer triage via one of `✨ Feature`, `🐛 Bug`, `📘 Docs`, or `🛠️ Chore` before opening a pull request.
+- Use [../../ISSUES.md](../../ISSUES.md) when reporting `pg-delta` bugs so maintainers have what they need to reproduce them.
 
 ## License
 

package/dist/core/catalog.diff.js

@@ -1,5 +1,6 @@
 import debug from "debug";
 import { expandReplaceDependencies } from "./expand-replace-dependencies.js";
+import { normalizePostDiffCycles } from "./post-diff-cycle-breaking.js";
 const debugCatalog = debug("pg-delta:catalog");
 import { diffAggregates } from "./objects/aggregate/aggregate.diff.js";
 import { DefaultPrivilegeState } from "./objects/base.default-privileges.js";
@@ -153,11 +154,16 @@ export function diffCatalogs(main, branch, options) {
         }
         return true;
     });
-    filteredChanges = expandReplaceDependencies({
+    const expandedDependencies = expandReplaceDependencies({
         changes: filteredChanges,
         mainCatalog: main,
         branchCatalog: branch,
     });
+    filteredChanges = normalizePostDiffCycles({
+        changes: expandedDependencies.changes,
+        mainCatalog: main,
+        replacedTableIds: expandedDependencies.replacedTableIds,
+    });
     debugCatalog("changes catalog diff: %O", stringifyWithBigInt(filteredChanges, 2));
     return filteredChanges;
 }

package/dist/core/connection-url.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Connection URL normalization for pg-delta.
+ *
+ * Auto-normalizes percent-encoded IPv6 hosts in PostgreSQL connection URLs.
+ * A URL like `postgresql://user:pass@2406%3Ada18%3A...%3Ab3c9:5432/db`
+ * becomes `postgresql://user:pass@[2406:da18:...:b3c9]:5432/db` before it
+ * reaches `pg-connection-string` / `pg.Pool`, so DNS resolution sees the
+ * address in its canonical bracketed form.
+ *
+ * Non-IPv6 hosts (IPv4, DNS names, already-bracketed IPv6, partial fragments
+ * that just happen to contain `%3A`) are returned verbatim.
+ */
+/**
+ * Return true if `value` is a valid IPv6 literal in any canonical form:
+ * full 8-group, `::` compression, or IPv4-mapped (`::ffff:1.2.3.4`).
+ * RFC 4007 zone identifiers (`fe80::1%eth0`) are accepted.
+ */
+export declare function isIPv6(value: string): boolean;
+/**
+ * Normalize a PostgreSQL connection URL so IPv6 hosts reach pg in the
+ * canonical bracketed form.
+ *
+ * If the URL's hostname contains a percent-encoded colon AND the decoded
+ * hostname is a valid IPv6 literal, the hostname is decoded and wrapped in
+ * `[...]`. All other fields (scheme, userinfo, port, path, query, fragment)
+ * are preserved byte-for-byte from the input.
+ *
+ * Any URL whose decoded hostname does not validate as IPv6 is returned
+ * verbatim, so a malformed input will surface its usual downstream error
+ * instead of being silently rewritten.
+ */
+export declare function normalizeConnectionUrl(url: string): string;

package/dist/core/connection-url.js

@@ -0,0 +1,77 @@
+/**
+ * Connection URL normalization for pg-delta.
+ *
+ * Auto-normalizes percent-encoded IPv6 hosts in PostgreSQL connection URLs.
+ * A URL like `postgresql://user:pass@2406%3Ada18%3A...%3Ab3c9:5432/db`
+ * becomes `postgresql://user:pass@[2406:da18:...:b3c9]:5432/db` before it
+ * reaches `pg-connection-string` / `pg.Pool`, so DNS resolution sees the
+ * address in its canonical bracketed form.
+ *
+ * Non-IPv6 hosts (IPv4, DNS names, already-bracketed IPv6, partial fragments
+ * that just happen to contain `%3A`) are returned verbatim.
+ */
+// IPv6 detection regex vendored from ip-regex (Sindre Sorhus, MIT).
+// https://github.com/sindresorhus/ip-regex
+const v4 = "(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]\\d|\\d)(?:\\.(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]\\d|\\d)){3}";
+const v6seg = "[a-fA-F\\d]{1,4}";
+const v6 = `
+(?:
+(?:${v6seg}:){7}(?:${v6seg}|:)|
+(?:${v6seg}:){6}(?:${v4}|:${v6seg}|:)|
+(?:${v6seg}:){5}(?::${v4}|(?::${v6seg}){1,2}|:)|
+(?:${v6seg}:){4}(?:(?::${v6seg}){0,1}:${v4}|(?::${v6seg}){1,3}|:)|
+(?:${v6seg}:){3}(?:(?::${v6seg}){0,2}:${v4}|(?::${v6seg}){1,4}|:)|
+(?:${v6seg}:){2}(?:(?::${v6seg}){0,3}:${v4}|(?::${v6seg}){1,5}|:)|
+(?:${v6seg}:){1}(?:(?::${v6seg}){0,4}:${v4}|(?::${v6seg}){1,6}|:)|
+(?::(?:(?::${v6seg}){0,5}:${v4}|(?::${v6seg}){1,7}|:))
+)(?:%[0-9a-zA-Z]{1,})?
+`
+    .replace(/\s*\/\/.*$/gm, "")
+    .replace(/\n/g, "")
+    .trim();
+const V6_EXACT = new RegExp(`^${v6}$`);
+/**
+ * Return true if `value` is a valid IPv6 literal in any canonical form:
+ * full 8-group, `::` compression, or IPv4-mapped (`::ffff:1.2.3.4`).
+ * RFC 4007 zone identifiers (`fe80::1%eth0`) are accepted.
+ */
+export function isIPv6(value) {
+    return typeof value === "string" && V6_EXACT.test(value);
+}
+/**
+ * Normalize a PostgreSQL connection URL so IPv6 hosts reach pg in the
+ * canonical bracketed form.
+ *
+ * If the URL's hostname contains a percent-encoded colon AND the decoded
+ * hostname is a valid IPv6 literal, the hostname is decoded and wrapped in
+ * `[...]`. All other fields (scheme, userinfo, port, path, query, fragment)
+ * are preserved byte-for-byte from the input.
+ *
+ * Any URL whose decoded hostname does not validate as IPv6 is returned
+ * verbatim, so a malformed input will surface its usual downstream error
+ * instead of being silently rewritten.
+ */
+export function normalizeConnectionUrl(url) {
+    const urlObj = new URL(url);
+    // Cheap pre-filter: only look closer if the hostname contains a
+    // percent-encoded colon. Anything else is left entirely untouched.
+    if (!/%3[aA]/.test(urlObj.hostname))
+        return url;
+    const decodedHost = decodeURIComponent(urlObj.hostname);
+    // Authoritative validation: only normalize when the decoded string is a
+    // real IPv6 literal. Rejects partial fragments, random hostnames that
+    // happen to contain `%3A`, and any malformed input.
+    if (!isIPv6(decodedHost))
+        return url;
+    // Preserve username/password/port/path/search/hash exactly as they appear
+    // in the WHATWG URL model (these are returned already percent-encoded).
+    const scheme = `${urlObj.protocol}//`;
+    const auth = urlObj.username
+        ? urlObj.password
+            ? `${urlObj.username}:${urlObj.password}@`
+            : `${urlObj.username}@`
+        : "";
+    const port = urlObj.port ? `:${urlObj.port}` : "";
+    const tail = `${urlObj.pathname}${urlObj.search}${urlObj.hash}`;
+    return `${scheme}${auth}[${decodedHost}]${port}${tail}`;
+}

package/dist/core/expand-replace-dependencies.d.ts

@@ -5,10 +5,16 @@ import type { Change } from "./change.types.ts";
  * replaced so that destructive drops succeed. Uses dependency edges from pg_depend
  * (already captured in Catalog.depends) plus change metadata (creates/drops/requires).
  *
- * New changes are appended; ordering is handled later by the sorter.
+ * New changes are appended; ordering and any multi-statement cycle normalization
+ * are handled later by post-diff helpers and the sorter.
  */
+interface ExpandReplaceDependenciesResult {
+    changes: Change[];
+    replacedTableIds: ReadonlySet<string>;
+}
 export declare function expandReplaceDependencies({ changes, mainCatalog, branchCatalog, }: {
     changes: Change[];
     mainCatalog: Catalog;
     branchCatalog: Catalog;
-}): Change[];
+}): ExpandReplaceDependenciesResult;
+export {};

package/dist/core/expand-replace-dependencies.js

@@ -17,13 +17,6 @@ import { DropRange } from "./objects/type/range/changes/range.drop.js";
 import { stableId } from "./objects/utils.js";
 import { CreateView } from "./objects/view/changes/view.create.js";
 import { DropView } from "./objects/view/changes/view.drop.js";
-/**
- * For objects we are replacing (drop + create), ensure that any dependents are also
- * replaced so that destructive drops succeed. Uses dependency edges from pg_depend
- * (already captured in Catalog.depends) plus change metadata (creates/drops/requires).
- *
- * New changes are appended; ordering is handled later by the sorter.
- */
 export function expandReplaceDependencies({ changes, mainCatalog, branchCatalog, }) {
     const createdIds = new Set();
     const droppedIds = new Set();
@@ -40,7 +33,10 @@ export function expandReplaceDependencies({ changes, mainCatalog, branchCatalog,
         }
     }
     if (replaceRoots.size === 0) {
-        return changes;
+        return {
+            changes,
+            replacedTableIds: new Set(),
+        };
     }
     // Build referenced -> dependents adjacency from main catalog dependencies.
     const dependentsByReferenced = new Map();
@@ -56,6 +52,12 @@ export function expandReplaceDependencies({ changes, mainCatalog, branchCatalog,
     const visitedTargets = new Set();
     const visitedRefs = new Set(replaceRoots);
     const queue = [...replaceRoots];
+    // Tables being replaced by an expansion-added DropTable+CreateTable pair.
+    // Any pre-existing targeted AlterTable*(T) object-scope change is superseded
+    // by the replacement and must be removed to avoid contradictions (e.g. an
+    // AlterTableDropColumn on a table that is about to be dropped) and the
+    // associated drop-phase cycle with the catalog constraint→column edge.
+    const tablesReplacedByExpansion = new Set();
     while (queue.length > 0) {
         const refId = queue.shift();
         const dependents = dependentsByReferenced.get(refId);
@@ -102,6 +104,12 @@ export function expandReplaceDependencies({ changes, mainCatalog, branchCatalog,
             if (!replacementChanges)
                 continue;
             additions.push(...replacementChanges);
+            // If we added a DropTable(T) for an existing table, mark T so any
+            // pre-existing object-scope AlterTable*(T) changes get dropped below —
+            // the DropTable+CreateTable pair supersedes all structural alterations.
+            if (resolved.kind === "table" && addDrop) {
+                tablesReplacedByExpansion.add(targetId);
+            }
             // Track new creates/drops so we don't duplicate work for downstream dependents.
             for (const change of replacementChanges) {
                 for (const id of change.creates ?? [])
@@ -112,9 +120,15 @@ export function expandReplaceDependencies({ changes, mainCatalog, branchCatalog,
         }
     }
     if (additions.length === 0) {
-        return changes;
+        return {
+            changes,
+            replacedTableIds: tablesReplacedByExpansion,
+        };
     }
-    return [...changes, ...additions];
+    return {
+        changes: [...changes, ...additions],
+        replacedTableIds: tablesReplacedByExpansion,
+    };
 }
 function isOwnedSequenceColumnDependency(referencedId, dependentId, mainCatalog, branchCatalog) {
     // When a sequence replace root is still OWNED BY the same column, the

package/dist/core/integrations/supabase.js

@@ -13,6 +13,7 @@ const SUPABASE_SYSTEM_SCHEMAS = [
     "_supavisor",
     "auth",
     "cron",
+    "etl",
     "extensions",
     "graphql",
     "graphql_public",

package/dist/core/objects/procedure/procedure.diff.js

@@ -99,6 +99,14 @@ export function diffProcedures(ctx, main, branch) {
         if (nonAlterablePropsChanged) {
             // Replace the entire procedure
             changes.push(new CreateProcedure({ procedure: branchProcedure, orReplace: true }));
+            if (mainProcedure.comment !== branchProcedure.comment) {
+                if (branchProcedure.comment === null) {
+                    changes.push(new DropCommentOnProcedure({ procedure: mainProcedure }));
+                }
+                else {
+                    changes.push(new CreateCommentOnProcedure({ procedure: branchProcedure }));
+                }
+            }
         }
         else {
             // Only alterable properties changed - check each one

package/dist/core/objects/sequence/sequence.diff.js

@@ -59,16 +59,24 @@ export function diffSequences(ctx, main, branch, branchTables = {}) {
     }
     for (const sequenceId of dropped) {
         const sequence = main[sequenceId];
-        // Skip generating DROP SEQUENCE if the sequence is owned by a table that's being dropped.
-        // PostgreSQL automatically drops sequences owned by tables when the table is dropped,
-        // so generating DROP SEQUENCE would cause an error (sequence doesn't exist).
+        // Skip generating DROP SEQUENCE if the sequence is owned by a table/column that's being dropped.
+        // PostgreSQL automatically cascades owned sequences when the owning table OR the owning
+        // column is dropped (via OWNED BY). Emitting DROP SEQUENCE in those cases would either
+        // fail at apply time (sequence already gone) or — in the column-drop case — create an
+        // unbreakable DropSequence ↔ AlterTableDropColumn cycle in the drop-phase sort graph.
         if (sequence.owned_by_schema &&
             sequence.owned_by_table &&
             sequence.owned_by_column) {
             const ownedByTableId = `table:${sequence.owned_by_schema}.${sequence.owned_by_table}`;
-            // If the owning table doesn't exist in branch catalog, it's being dropped
-            // and will auto-drop this sequence, so skip generating DROP SEQUENCE
-            if (!(ownedByTableId in branchTables)) {
+            const ownedByTable = branchTables[ownedByTableId];
+            // Owning table is dropped → PG auto-drops the owned sequence.
+            if (!ownedByTable) {
+                continue;
+            }
+            // Owning column is dropped (table survives) → PG still auto-drops the owned
+            // sequence as part of the column drop, so we must not emit DROP SEQUENCE.
+            const ownedByColumnExists = ownedByTable.columns?.some((col) => col.name === sequence.owned_by_column);
+            if (!ownedByColumnExists) {
                 continue;
             }
         }

package/dist/core/objects/table/changes/table.alter.js

@@ -462,13 +462,16 @@ export class AlterTableAlterColumnSetDefault extends AlterTableChange {
     }
     serialize(_options) {
         const set = this.column.is_generated ? "SET EXPRESSION AS" : "SET DEFAULT";
+        const value = this.column.is_generated
+            ? `(${this.column.default ?? "NULL"})`
+            : (this.column.default ?? "NULL");
         return [
             "ALTER TABLE",
             `${this.table.schema}.${this.table.name}`,
             "ALTER COLUMN",
             this.column.name,
             set,
-            this.column.default ?? "NULL",
+            value,
         ].join(" ");
     }
 }

package/dist/core/objects/table/changes/table.drop.d.ts

@@ -14,9 +14,21 @@ import { DropTableChange } from "./table.base.ts";
 export declare class DropTable extends DropTableChange {
     readonly table: Table;
     readonly scope: "object";
+    /**
+     * Names of constraints on this table that are dropped explicitly by a
+     * separate `AlterTableDropConstraint` change. Those constraints must not be
+     * claimed by `DropTable.drops` / `.requires`, otherwise catalog edges tied
+     * to the constraint stableId will attach to this DropTable node instead of
+     * the dedicated AlterTableDropConstraint node. When two tables with mutual
+     * FK references are dropped in the same phase, that misattribution
+     * produces an unbreakable cycle between the two DropTable changes.
+     */
+    readonly externallyDroppedConstraints: ReadonlySet<string>;
     constructor(props: {
         table: Table;
+        externallyDroppedConstraints?: ReadonlySet<string>;
     });
+    private get claimedConstraints();
     get drops(): (`column:${string}.${string}.${string}` | `constraint:${string}.${string}.${string}` | `table:${string}`)[];
     get requires(): (`column:${string}.${string}.${string}` | `constraint:${string}.${string}.${string}` | `table:${string}`)[];
     serialize(_options?: SerializeOptions): string;

package/dist/core/objects/table/changes/table.drop.js

@@ -13,17 +13,34 @@ import { DropTableChange } from "./table.base.js";
 export class DropTable extends DropTableChange {
     table;
     scope = "object";
+    /**
+     * Names of constraints on this table that are dropped explicitly by a
+     * separate `AlterTableDropConstraint` change. Those constraints must not be
+     * claimed by `DropTable.drops` / `.requires`, otherwise catalog edges tied
+     * to the constraint stableId will attach to this DropTable node instead of
+     * the dedicated AlterTableDropConstraint node. When two tables with mutual
+     * FK references are dropped in the same phase, that misattribution
+     * produces an unbreakable cycle between the two DropTable changes.
+     */
+    externallyDroppedConstraints;
     constructor(props) {
         super();
         this.table = props.table;
+        this.externallyDroppedConstraints =
+            props.externallyDroppedConstraints ?? new Set();
+    }
+    get claimedConstraints() {
+        return this.table.constraints.filter((constraint) => !this.externallyDroppedConstraints.has(constraint.name));
     }
     get drops() {
         return [
             this.table.stableId,
             ...this.table.columns.map((column) => stableId.column(this.table.schema, this.table.name, column.name)),
             // Include constraint stableIds so FK relationships that only exist at the
-            // constraint level still affect whole-table drop ordering.
-            ...this.table.constraints.map((constraint) => stableId.constraint(this.table.schema, this.table.name, constraint.name)),
+            // constraint level still affect whole-table drop ordering. Skip any
+            // constraint that the diff layer is dropping via a dedicated
+            // AlterTableDropConstraint change — that node owns the stableId.
+            ...this.claimedConstraints.map((constraint) => stableId.constraint(this.table.schema, this.table.name, constraint.name)),
         ];
     }
     get requires() {
@@ -32,7 +49,7 @@ export class DropTable extends DropTableChange {
             ...this.table.columns.map((col) => stableId.column(this.table.schema, this.table.name, col.name)),
             // Mirror the dropped constraint ids in requires so drop-phase graph
             // consumers can connect catalog FK edges back to this table drop.
-            ...this.table.constraints.map((constraint) => stableId.constraint(this.table.schema, this.table.name, constraint.name)),
+            ...this.claimedConstraints.map((constraint) => stableId.constraint(this.table.schema, this.table.name, constraint.name)),
         ];
     }
     serialize(_options) {

package/dist/core/objects/table/table.diff.js

@@ -486,9 +486,14 @@ export function diffTables(ctx, main, branch) {
                         // Set new default value
                         const isGeneratedColumn = branchCol.is_generated;
                         const isPostgresLowerThan17 = ctx.version < 170000;
-                        if (isGeneratedColumn && isPostgresLowerThan17) {
+                        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
+                            // 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

package/dist/core/post-diff-cycle-breaking.d.ts

@@ -0,0 +1,22 @@
+import type { Catalog } from "./catalog.model.ts";
+import type { Change } from "./change.types.ts";
+/**
+ * Normalize change-list cycles that only become apparent after all object
+ * diffs have been collected.
+ *
+ * This pass intentionally handles whole-plan interactions only:
+ * - If replace expansion added `DropTable(T)+CreateTable(T)`, targeted
+ *   `AlterTableDropColumn(T.*)` / `AlterTableDropConstraint(T.*)` changes are
+ *   redundant and create an unbreakable drop-phase cycle, so we elide them.
+ * - If two dropped tables reference each other via FK, we insert dedicated
+ *   `AlterTableDropConstraint` changes and teach the paired `DropTable`
+ *   changes not to claim those FK stable IDs.
+ *
+ * Object-local PostgreSQL semantics (for example owned-sequence cascades) stay
+ * in the corresponding `diff*` function instead of this pass.
+ */
+export declare function normalizePostDiffCycles({ changes, mainCatalog, replacedTableIds, }: {
+    changes: Change[];
+    mainCatalog: Catalog;
+    replacedTableIds?: ReadonlySet<string>;
+}): Change[];

package/dist/core/post-diff-cycle-breaking.js

@@ -0,0 +1,143 @@
+import { AlterTableDropColumn, AlterTableDropConstraint, } from "./objects/table/changes/table.alter.js";
+import { DropTable } from "./objects/table/changes/table.drop.js";
+import { stableId } from "./objects/utils.js";
+function constraintStableId(table, constraintName) {
+    return stableId.constraint(table.schema, table.name, constraintName);
+}
+/**
+ * Yield FK constraints on `table` whose referenced table is also dropped in the
+ * final plan. Self-references are left alone because the sort phase already
+ * handles the resulting self-loop correctly.
+ */
+function* iterCrossDropFkConstraints(table, droppedSet) {
+    for (const constraint of table.constraints) {
+        if (constraint.constraint_type !== "f")
+            continue;
+        if (constraint.is_partition_clone)
+            continue;
+        if (!constraint.foreign_key_schema || !constraint.foreign_key_table) {
+            continue;
+        }
+        const referencedId = stableId.table(constraint.foreign_key_schema, constraint.foreign_key_table);
+        if (referencedId === table.stableId)
+            continue;
+        if (!droppedSet.has(referencedId))
+            continue;
+        yield { constraint, referencedId };
+    }
+}
+function isSupersededByTableReplacement(change, replacedTableIds) {
+    if (!(change instanceof AlterTableDropColumn) &&
+        !(change instanceof AlterTableDropConstraint)) {
+        return false;
+    }
+    return replacedTableIds.has(change.table.stableId);
+}
+function collectExplicitConstraintDropIds(changes) {
+    const explicitConstraintDropIds = new Set();
+    for (const change of changes) {
+        if (!(change instanceof AlterTableDropConstraint))
+            continue;
+        explicitConstraintDropIds.add(constraintStableId(change.table, change.constraint.name));
+    }
+    return explicitConstraintDropIds;
+}
+function hasSameEntries(left, right) {
+    if (left.size !== right.size)
+        return false;
+    for (const value of left) {
+        if (!right.has(value))
+            return false;
+    }
+    return true;
+}
+/**
+ * Normalize change-list cycles that only become apparent after all object
+ * diffs have been collected.
+ *
+ * This pass intentionally handles whole-plan interactions only:
+ * - If replace expansion added `DropTable(T)+CreateTable(T)`, targeted
+ *   `AlterTableDropColumn(T.*)` / `AlterTableDropConstraint(T.*)` changes are
+ *   redundant and create an unbreakable drop-phase cycle, so we elide them.
+ * - If two dropped tables reference each other via FK, we insert dedicated
+ *   `AlterTableDropConstraint` changes and teach the paired `DropTable`
+ *   changes not to claim those FK stable IDs.
+ *
+ * Object-local PostgreSQL semantics (for example owned-sequence cascades) stay
+ * in the corresponding `diff*` function instead of this pass.
+ */
+export function normalizePostDiffCycles({ changes, mainCatalog, replacedTableIds = new Set(), }) {
+    const structurallyNormalizedChanges = replacedTableIds.size === 0
+        ? changes
+        : changes.filter((change) => !isSupersededByTableReplacement(change, replacedTableIds));
+    const dropTableChanges = structurallyNormalizedChanges.filter((change) => change instanceof DropTable);
+    if (dropTableChanges.length < 2) {
+        return structurallyNormalizedChanges;
+    }
+    const droppedSet = new Set(dropTableChanges.map((change) => change.table.stableId));
+    const droppedFkTargets = new Map();
+    for (const dropTableChange of dropTableChanges) {
+        const mainTable = mainCatalog.tables[dropTableChange.table.stableId] ??
+            dropTableChange.table;
+        const targets = new Set();
+        for (const { referencedId } of iterCrossDropFkConstraints(mainTable, droppedSet)) {
+            targets.add(referencedId);
+        }
+        droppedFkTargets.set(mainTable.stableId, targets);
+    }
+    const explicitConstraintDropIds = collectExplicitConstraintDropIds(structurallyNormalizedChanges);
+    const injectedConstraintDropsByTableId = new Map();
+    const externallyDroppedConstraintsByTableId = new Map();
+    let didMutate = structurallyNormalizedChanges !== changes;
+    for (const dropTableChange of dropTableChanges) {
+        const mainTable = mainCatalog.tables[dropTableChange.table.stableId] ??
+            dropTableChange.table;
+        const externallyDroppedConstraints = new Set(dropTableChange.externallyDroppedConstraints);
+        for (const { constraint, referencedId } of iterCrossDropFkConstraints(mainTable, droppedSet)) {
+            const isMutual = droppedFkTargets.get(referencedId)?.has(mainTable.stableId) === true;
+            if (!isMutual)
+                continue;
+            const droppedConstraintStableId = constraintStableId(mainTable, constraint.name);
+            externallyDroppedConstraints.add(constraint.name);
+            if (!explicitConstraintDropIds.has(droppedConstraintStableId)) {
+                const injectedDrop = new AlterTableDropConstraint({
+                    table: mainTable,
+                    constraint,
+                });
+                const existingDrops = injectedConstraintDropsByTableId.get(mainTable.stableId) ?? [];
+                existingDrops.push(injectedDrop);
+                injectedConstraintDropsByTableId.set(mainTable.stableId, existingDrops);
+                explicitConstraintDropIds.add(droppedConstraintStableId);
+                didMutate = true;
+            }
+        }
+        if (!hasSameEntries(dropTableChange.externallyDroppedConstraints, externallyDroppedConstraints)) {
+            externallyDroppedConstraintsByTableId.set(mainTable.stableId, externallyDroppedConstraints);
+            didMutate = true;
+        }
+    }
+    if (!didMutate) {
+        return changes;
+    }
+    const normalizedChanges = [];
+    for (const change of structurallyNormalizedChanges) {
+        if (!(change instanceof DropTable)) {
+            normalizedChanges.push(change);
+            continue;
+        }
+        const injectedConstraintDrops = injectedConstraintDropsByTableId.get(change.table.stableId) ?? [];
+        if (injectedConstraintDrops.length > 0) {
+            normalizedChanges.push(...injectedConstraintDrops);
+        }
+        const externallyDroppedConstraints = externallyDroppedConstraintsByTableId.get(change.table.stableId);
+        if (!externallyDroppedConstraints) {
+            normalizedChanges.push(change);
+            continue;
+        }
+        normalizedChanges.push(new DropTable({
+            table: change.table,
+            externallyDroppedConstraints,
+        }));
+    }
+    return normalizedChanges;
+}

package/dist/core/postgres-config.d.ts

@@ -3,6 +3,33 @@
  */
 import type { ClientBase, PoolClient, PoolConfig } from "pg";
 import { Pool } from "pg";
+/**
+ * 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 declare function isRetryableConnectError(err: unknown): boolean;
+/**
+ * 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 declare 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>;
 /**
  * Options for creating a Pool with event listeners.
  */