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

package/dist/core/post-diff-normalization.d.ts

@@ -0,0 +1,43 @@
+import type { Change } from "./change.types.ts";
+import type { Table } from "./objects/table/table.model.ts";
+/**
+ * Apply structural rewrites to the change list that are only obvious once
+ * every object diff has been collected. This pass does NOT prevent dependency
+ * cycles — that responsibility now lives in the sort phase, where
+ * `sortPhaseChanges` invokes `tryBreakCycleByChangeInjection` lazily on cycles
+ * that edge filtering can't break (FK SCC of dropped tables,
+ * AlterPublicationDropTables ↔ AlterTableDropColumn, …).
+ *
+ * Concretely, this pass:
+ *
+ * - Prunes `AlterTableDropColumn(T.*)` / `AlterTableDropConstraint(T.*)`
+ *   changes that are made redundant by an expansion-emitted
+ *   `DropTable(T) + CreateTable(T)` pair. Without this, the apply phase
+ *   would try to drop a column that no longer exists in the freshly
+ *   recreated table.
+ * - Prunes `DropSequence(S)` changes when `S` is `OWNED BY` a column on a
+ *   table promoted to `DropTable + CreateTable` by the expander. The
+ *   `DROP TABLE` cascade drops the sequence at apply time; emitting an
+ *   explicit `DROP SEQUENCE` in the same drop phase both duplicates the
+ *   cascade and forms an unbreakable `DropSequence ↔ DropTable` cycle on
+ *   the bidirectional pg_depend edges between the sequence and the
+ *   owning column.
+ * - Dedupes duplicate `AlterTableAddConstraint` /
+ *   `AlterTableValidateConstraint` / `CreateCommentOnConstraint` changes
+ *   produced when `diffTables()` and `expandReplaceDependencies()` both
+ *   emit the same constraint operation for a replaced table. Last write
+ *   wins so the expansion's emission survives.
+ * - Re-emits `ALTER TABLE ... REPLICA IDENTITY USING INDEX <idx>` after any
+ *   `DropIndex(idx) + CreateIndex(idx)` pair where `idx` is the replica
+ *   identity index of a branch table — Postgres silently clears the marker
+ *   when the underlying index is dropped, and `CREATE INDEX` cannot restore
+ *   it.
+ *
+ * Object-local PostgreSQL semantics (for example owned-sequence cascades)
+ * stay in the corresponding `diff*` function instead of this pass.
+ */
+export declare function normalizePostDiffChanges({ changes, replacedTableIds, branchTables, }: {
+    changes: Change[];
+    replacedTableIds?: ReadonlySet<string>;
+    branchTables?: Record<string, Table>;
+}): Change[];

package/dist/core/post-diff-normalization.js

@@ -0,0 +1,231 @@
+import { CreateIndex } from "./objects/index/changes/index.create.js";
+import { DropIndex } from "./objects/index/changes/index.drop.js";
+import { DropSequence } from "./objects/sequence/changes/sequence.drop.js";
+import { AlterTableAddConstraint, AlterTableDropColumn, AlterTableDropConstraint, AlterTableSetReplicaIdentity, AlterTableValidateConstraint, } from "./objects/table/changes/table.alter.js";
+import { CreateCommentOnConstraint } from "./objects/table/changes/table.comment.js";
+import { stableId } from "./objects/utils.js";
+function constraintStableId(table, constraintName) {
+    return stableId.constraint(table.schema, table.name, constraintName);
+}
+function isSupersededByTableReplacement(change, replacedTableIds) {
+    if (change instanceof AlterTableDropColumn ||
+        change instanceof AlterTableDropConstraint) {
+        return replacedTableIds.has(change.table.stableId);
+    }
+    // `DropSequence(S)` is superseded when S is OWNED BY a column on a table
+    // that `expandReplaceDependencies` has promoted to `DropTable + CreateTable`
+    // in the same plan. PostgreSQL cascade-drops the OWNED BY sequence as part
+    // of the DROP TABLE, so the explicit DROP SEQUENCE is redundant and — more
+    // importantly — closes an unbreakable `DropSequence ↔ DropTable` cycle in
+    // the drop phase via the bidirectional pg_depend edges between the
+    // sequence and its owning column (`column → sequence` for the DEFAULT
+    // nextval reference, `sequence → column` for the OWNED BY auto-dependency).
+    // The alpha.15 short-circuit in `diffSequences.dropped` only suppresses
+    // `DropSequence` when the owning table itself is gone from `branchTables`;
+    // here the table survives in branch and the replacement is added later by
+    // the expander, so this whole-plan rewrite has to happen post-diff.
+    if (change instanceof DropSequence) {
+        if (!change.sequence.owned_by_schema ||
+            !change.sequence.owned_by_table ||
+            !change.sequence.owned_by_column) {
+            return false;
+        }
+        const ownedByTableId = stableId.table(change.sequence.owned_by_schema, change.sequence.owned_by_table);
+        return replacedTableIds.has(ownedByTableId);
+    }
+    return false;
+}
+/**
+ * Drop earlier duplicates of `AlterTableAddConstraint` /
+ * `AlterTableValidateConstraint` / `CreateCommentOnConstraint` targeting
+ * replaced tables, keeping only the last occurrence of each
+ * `(changeType, table.stableId, constraint.name)`.
+ *
+ * When `expandReplaceDependencies()` promotes a table to a full
+ * `DropTable + CreateTable` pair, it also emits one
+ * `AlterTableAddConstraint` (plus optional `VALIDATE CONSTRAINT` /
+ * `COMMENT ON CONSTRAINT`) per branch constraint. If `diffTables()` already
+ * emitted the same change for a shape flip or a new constraint on that
+ * table, the plan ends up with two identical `ALTER TABLE ... ADD
+ * CONSTRAINT ...` statements and PostgreSQL fails at apply time with
+ * `constraint "..." for relation "..." already exists`. Because
+ * `expandReplaceDependencies()` appends its additions after the original
+ * `diffTables()` output, the last occurrence is the expansion's emission —
+ * keeping it preserves correctness while removing the duplicate.
+ */
+function dropReplacedTableDuplicateConstraintChanges(changes, replacedTableIds) {
+    if (replacedTableIds.size === 0)
+        return changes;
+    const keyFor = (change) => {
+        if (!(change instanceof AlterTableAddConstraint) &&
+            !(change instanceof AlterTableValidateConstraint) &&
+            !(change instanceof CreateCommentOnConstraint)) {
+            return null;
+        }
+        if (!replacedTableIds.has(change.table.stableId))
+            return null;
+        const tag = change instanceof AlterTableAddConstraint
+            ? "add"
+            : change instanceof AlterTableValidateConstraint
+                ? "validate"
+                : "comment";
+        return `${tag}:${constraintStableId(change.table, change.constraint.name)}`;
+    };
+    const seen = new Set();
+    const reversedKept = [];
+    let mutated = false;
+    // Walk backwards: the first encounter of each key corresponds to its LAST
+    // occurrence in the original order. `expandReplaceDependencies()` appends
+    // additions after the original changes, so "last wins" keeps the
+    // expansion's emission and drops the earlier diffTables duplicate.
+    for (let i = changes.length - 1; i >= 0; i--) {
+        const change = changes[i];
+        const key = keyFor(change);
+        if (key !== null) {
+            if (seen.has(key)) {
+                mutated = true;
+                continue;
+            }
+            seen.add(key);
+        }
+        reversedKept.push(change);
+    }
+    return mutated ? reversedKept.reverse() : changes;
+}
+/**
+ * Re-emit `ALTER TABLE ... REPLICA IDENTITY USING INDEX <idx>` after any
+ * `DropIndex(idx) + CreateIndex(idx)` pair where `idx` is the replica-identity
+ * index of a branch table.
+ *
+ * Background: PostgreSQL silently flips a table's `relreplident` to `'d'`
+ * (DEFAULT) when the index it points to is dropped. `CREATE INDEX` cannot
+ * restore the marker — only `ALTER TABLE ... REPLICA IDENTITY USING INDEX`
+ * can. When both main and branch carry `replica_identity = 'i'` pointing at
+ * the same index name, `diffTables()` emits no replica-identity change of its
+ * own, so the marker would be lost on apply.
+ *
+ * This is a whole-plan interaction: `diffTables()` cannot detect it without
+ * also looking at index changes. Per the "whole-plan interactions belong in
+ * post-diff normalization" rule in the package CLAUDE.md, the restoration
+ * lives here.
+ *
+ * Insertion is idempotent: if `diffTables()` already emitted the same
+ * `AlterTableSetReplicaIdentity` for this table (e.g. when the user is also
+ * switching the replica-identity index name in the same migration), no
+ * duplicate is added.
+ */
+function restoreReplicaIdentityAfterIndexReplace(changes, branchTables) {
+    // Build the index-stable-id → owning-table map from branch state. Only
+    // tables in 'i' mode contribute, and only those whose configured index name
+    // is non-null (the extractor returns null for any other mode).
+    const replicaIdentityIndexToTable = new Map();
+    for (const table of Object.values(branchTables)) {
+        if (table.replica_identity !== "i" || !table.replica_identity_index) {
+            continue;
+        }
+        const indexId = stableId.index(table.schema, table.name, table.replica_identity_index);
+        replicaIdentityIndexToTable.set(indexId, table);
+    }
+    if (replicaIdentityIndexToTable.size === 0)
+        return changes;
+    // Find the indexes that are both dropped AND created in this plan. A pure
+    // drop or a pure create is handled by `diffTables()` directly (the table's
+    // replica_identity / replica_identity_index fields will have changed). The
+    // hole is specifically the drop+create pair that recreates the same name.
+    const droppedIndexIds = new Set();
+    const createdIndexIds = new Set();
+    for (const change of changes) {
+        if (change instanceof DropIndex) {
+            droppedIndexIds.add(change.index.stableId);
+        }
+        else if (change instanceof CreateIndex) {
+            createdIndexIds.add(change.index.stableId);
+        }
+    }
+    const replacedIndexIds = new Set();
+    for (const id of droppedIndexIds) {
+        if (createdIndexIds.has(id) && replicaIdentityIndexToTable.has(id)) {
+            replacedIndexIds.add(id);
+        }
+    }
+    if (replacedIndexIds.size === 0)
+        return changes;
+    // Skip tables for which `diffTables()` already emitted a replica-identity
+    // setter — re-emitting would produce a redundant ALTER TABLE (harmless on
+    // apply, but noisy in plan output).
+    const tablesWithExistingReplicaIdentitySetter = new Set();
+    for (const change of changes) {
+        if (change instanceof AlterTableSetReplicaIdentity) {
+            tablesWithExistingReplicaIdentitySetter.add(change.table.stableId);
+        }
+    }
+    // Insert one `AlterTableSetReplicaIdentity` per replaced index, immediately
+    // after the matching `CreateIndex`. The change's `requires` already names
+    // both the table and the recreated index, so the topo sort orders it
+    // correctly relative to the surrounding DDL.
+    const result = [];
+    for (const change of changes) {
+        result.push(change);
+        if (!(change instanceof CreateIndex) ||
+            !replacedIndexIds.has(change.index.stableId)) {
+            continue;
+        }
+        const table = replicaIdentityIndexToTable.get(change.index.stableId);
+        if (!table)
+            continue;
+        if (tablesWithExistingReplicaIdentitySetter.has(table.stableId))
+            continue;
+        result.push(new AlterTableSetReplicaIdentity({
+            table,
+            mode: "i",
+            indexName: table.replica_identity_index,
+        }));
+        // Mark as emitted so a second replaced index on the same table — if that
+        // ever arises — doesn't double-emit.
+        tablesWithExistingReplicaIdentitySetter.add(table.stableId);
+    }
+    return result;
+}
+/**
+ * Apply structural rewrites to the change list that are only obvious once
+ * every object diff has been collected. This pass does NOT prevent dependency
+ * cycles — that responsibility now lives in the sort phase, where
+ * `sortPhaseChanges` invokes `tryBreakCycleByChangeInjection` lazily on cycles
+ * that edge filtering can't break (FK SCC of dropped tables,
+ * AlterPublicationDropTables ↔ AlterTableDropColumn, …).
+ *
+ * Concretely, this pass:
+ *
+ * - Prunes `AlterTableDropColumn(T.*)` / `AlterTableDropConstraint(T.*)`
+ *   changes that are made redundant by an expansion-emitted
+ *   `DropTable(T) + CreateTable(T)` pair. Without this, the apply phase
+ *   would try to drop a column that no longer exists in the freshly
+ *   recreated table.
+ * - Prunes `DropSequence(S)` changes when `S` is `OWNED BY` a column on a
+ *   table promoted to `DropTable + CreateTable` by the expander. The
+ *   `DROP TABLE` cascade drops the sequence at apply time; emitting an
+ *   explicit `DROP SEQUENCE` in the same drop phase both duplicates the
+ *   cascade and forms an unbreakable `DropSequence ↔ DropTable` cycle on
+ *   the bidirectional pg_depend edges between the sequence and the
+ *   owning column.
+ * - Dedupes duplicate `AlterTableAddConstraint` /
+ *   `AlterTableValidateConstraint` / `CreateCommentOnConstraint` changes
+ *   produced when `diffTables()` and `expandReplaceDependencies()` both
+ *   emit the same constraint operation for a replaced table. Last write
+ *   wins so the expansion's emission survives.
+ * - Re-emits `ALTER TABLE ... REPLICA IDENTITY USING INDEX <idx>` after any
+ *   `DropIndex(idx) + CreateIndex(idx)` pair where `idx` is the replica
+ *   identity index of a branch table — Postgres silently clears the marker
+ *   when the underlying index is dropped, and `CREATE INDEX` cannot restore
+ *   it.
+ *
+ * Object-local PostgreSQL semantics (for example owned-sequence cascades)
+ * stay in the corresponding `diff*` function instead of this pass.
+ */
+export function normalizePostDiffChanges({ changes, replacedTableIds = new Set(), branchTables = {}, }) {
+    const restoredChanges = restoreReplicaIdentityAfterIndexReplace(changes, branchTables);
+    const dedupedChanges = dropReplacedTableDuplicateConstraintChanges(restoredChanges, replacedTableIds);
+    if (replacedTableIds.size === 0)
+        return dedupedChanges;
+    return dedupedChanges.filter((change) => !isSupersededByTableReplacement(change, replacedTableIds));
+}

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

@@ -1,14 +1,48 @@
 /**
  * PostgreSQL connection configuration with custom type handlers.
  */
-import type { PoolClient, PoolConfig } from "pg";
+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>;
+/**
+ * Race `connect()` against a `timeoutMs` rejection and clear the timer when
+ * either side wins. If the timer is left running after a fast connect, the
+ * pending `setTimeout` keeps the event loop alive and the process hangs for
+ * the rest of `timeoutMs`.
+ */
+export declare function connectWithTimeout<T>(connect: () => Promise<T>, timeoutMs: number, label: "source" | "target"): Promise<T>;
 /**
  * Options for creating a Pool with event listeners.
  */
 interface CreatePoolOptions extends Partial<PoolConfig> {
     /** Called when a new client connects to the pool */
-    onConnect?: (client: PoolClient) => void | Promise<void>;
+    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 */
@@ -18,6 +52,65 @@ interface CreatePoolOptions extends Partial<PoolConfig> {
 }
 /**
  * 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 declare function createPool(connectionString: string | undefined, options?: CreatePoolOptions): 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 declare function poolConfigFromUrl(cleanedUrl: string): 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 declare function createPool(connectionString: string, options?: CreatePoolOptions): Pool;
+export declare function createManagedPool(url: string, options?: {
+    role?: string;
+    label?: "source" | "target";
+}): Promise<{
+    pool: Pool;
+    close: () => Promise<void>;
+}>;
+export declare function endPool(pool: Pool): Promise<void>;
 export {};