@owlmeans/postgres-resource 0.1.18-rc.42 → 0.1.18-rc.43

package/build/utils/diff.js

@@ -1,386 +1,362 @@
 import { PgIndexMethod } from '../consts.js';
 import { PostgresPlaceholderError } from '../errors.js';
-import { qualify, quoteIdent } from './name.js';
+import { pgNameHelper } from './name.js';
 import { CAST } from './consts.local.js';
-const literal = (value) => {
-    if (value === null)
-        return 'NULL';
-    if (typeof value === 'number')
-        return `${value}`;
-    if (typeof value === 'boolean')
-        return value ? 'TRUE' : 'FALSE';
-    return `'${value.replace(/'/g, "''")}'`;
-};
-const defaultExpression = (column) => {
-    if (column.defaultRaw != null)
-        return column.defaultRaw;
-    if (column.defaultLiteral !== undefined)
-        return literal(column.defaultLiteral);
-    return undefined;
-};
-/**
- * Postgres echoes defaults back with explicit casts — a declared `'active'` comes back as
- * `'active'::text`. Compare without them, so an unchanged default doesn't look like drift on
- * every boot.
- */
-const normalizeDefault = (expression) => {
-    if (expression == null)
-        return null;
+export const createPgDiffHelper = () => {
+    const { qualify, quoteIdent } = pgNameHelper;
+    const literal = (value) => {
+        if (value === null)
+            return 'NULL';
+        if (typeof value === 'number')
+            return `${value}`;
+        if (typeof value === 'boolean')
+            return value ? 'TRUE' : 'FALSE';
+        return `'${value.replace(/'/g, "''")}'`;
+    };
+    const defaultExpression = (column) => {
+        if (column.defaultRaw != null)
+            return column.defaultRaw;
+        if (column.defaultLiteral !== undefined)
+            return literal(column.defaultLiteral);
+        return undefined;
+    };
     /**
-     * Casts anywhere (a `varchar` id's `gen_random_uuid()::text` is stored as
-     * `(gen_random_uuid())::character varying`) and the parentheses Postgres adds around them.
+     * Postgres echoes defaults back with explicit casts — a declared `'active'` comes back as
+     * `'active'::text`. Compare without them, so an unchanged default doesn't look like drift on
+     * every boot.
      */
-    return expression.toLowerCase().replace(CAST, '').replace(/[()]/g, '').replace(/\s+/g, ' ').trim();
-};
-/**
- * The form an index or constraint definition is compared in, so the statement this package emits
- * and the text Postgres reports for the object it created compare equal.
- *
- * Postgres deparses what it stores: it leaves an identifier unquoted when it can, casts every
- * literal (`''::text`), casts a `varchar` column inside an expression, wraps a partial predicate and
- * each of its operator expressions in parentheses, and rewrites `x IN (…)` as `x = ANY (ARRAY[…])`.
- * Comparing the raw texts made every boot drop and recreate every declared index and every enum
- * `CHECK`. So both sides lose case, quotes, casts, whitespace and parentheses, and `= ANY (ARRAY[…])`
- * reads as `IN (…)`. What that cannot tell apart — two definitions differing only in how their
- * operators group — is a change to make under a new name.
- */
-export const canonicalDefinition = (definition) => definition
-    .toLowerCase()
-    .replace(/"/g, '')
-    .replace(CAST, '')
-    .replace(/[\s()]/g, '')
-    .replace(/=anyarray\[([^\]]*)\]/g, 'in$1');
-const normalizeDefinition = canonicalDefinition;
-const columnList = (columns) => columns.map(quoteIdent).join(', ');
-const indexStatement = (spec, entry) => {
-    const target = entry.expression != null
-        ? `(${entry.expression})`
-        : `(${columnList(entry.columns)})`;
-    const where = entry.where != null ? ` WHERE ${entry.where}` : '';
-    return `CREATE ${entry.unique === true ? 'UNIQUE ' : ''}INDEX ${quoteIdent(entry.name)}`
-        + ` ON ${spec.qualified} USING ${entry.method ?? PgIndexMethod.BTree} ${target}${where}`;
-};
-const columnDefinition = (column) => {
-    const parts = [quoteIdent(column.column), column.sqlType];
-    if (column.notNull)
-        parts.push('NOT NULL');
-    const expression = defaultExpression(column);
-    if (expression != null)
-        parts.push(`DEFAULT ${expression}`);
-    return parts.join(' ');
-};
-/**
- * Foreign keys are planned separately from the rest of the table, and applied only once
- * every resource has initialized: a key points at a table another resource owns, and that
- * resource's own `init()` may not have run yet.
- *
- * @throws {PostgresPlaceholderError} when a target can't be resolved.
- */
-export const planForeignKeys = (spec, context) => spec.references.map(reference => {
-    const column = reference.property != null ? spec.byProperty[reference.property] : undefined;
-    if (column == null) {
-        throw new PostgresPlaceholderError(`fk-unknown-property:${reference.property}`);
-    }
-    let targetSchema = reference.schema ?? spec.schema;
-    let targetTable = reference.table;
-    if (reference.resource != null) {
-        if (context == null) {
-            throw new PostgresPlaceholderError(`fk-no-context:${reference.resource}`);
-        }
-        let target;
-        try {
-            target = context.resource(reference.resource);
-        }
-        catch {
-            throw new PostgresPlaceholderError(`fk-unknown-resource:${reference.resource}`);
-        }
-        if (target.table == null) {
-            throw new PostgresPlaceholderError(`fk-uninitialized:${reference.resource}`);
-        }
-        targetSchema = target.table.schema;
-        targetTable = target.table.table;
-    }
-    if (targetTable == null) {
-        throw new PostgresPlaceholderError(`fk-no-target:${reference.property}`);
-    }
-    const actions = [
-        reference.onDelete != null ? ` ON DELETE ${reference.onDelete}` : '',
-        reference.onUpdate != null ? ` ON UPDATE ${reference.onUpdate}` : ''
-    ].join('');
-    return {
-        kind: 'add-foreign-key',
-        target: reference.name,
-        sql: `ALTER TABLE ${spec.qualified} ADD CONSTRAINT ${quoteIdent(reference.name)}`
-            + ` FOREIGN KEY (${quoteIdent(column.column)})`
-            + ` REFERENCES ${qualify(targetSchema, targetTable)} (${quoteIdent(reference.column)})${actions}`
+    const normalizeDefault = (expression) => {
+        if (expression == null)
+            return null;
+        /**
+         * Casts anywhere (a `varchar` id's `gen_random_uuid()::text` is stored as
+         * `(gen_random_uuid())::character varying`) and the parentheses Postgres adds around them.
+         */
+        return expression.toLowerCase().replace(CAST, '').replace(/[()]/g, '').replace(/\s+/g, ' ').trim();
     };
-});
-/**
- * Compare the compiled specification against the live table and produce the ordered DDL
- * that converges one onto the other.
- *
- * Statement order is load bearing:
- *  - `DROP COLUMN` is last, because a `USING` cast or a backfill may legitimately read a
- *    column that is about to disappear.
- *  - A primary key constraint is never dropped: it cascades into every referencing key and
- *    can't be undone inside the same transaction once dependents exist.
- *
- * Foreign keys are not part of the plan at all — see {@link planForeignKeys}.
- */
-export const planSync = (spec, live, additive = false) => {
-    if (!live.exists) {
-        const constraints = [];
-        if (spec.primaryKey.length > 0) {
-            constraints.push(`CONSTRAINT ${quoteIdent(`${spec.table}_pkey`)} PRIMARY KEY (${columnList(spec.primaryKey)})`);
+    const canonicalDefinition = (definition) => definition
+        .toLowerCase()
+        .replace(/"/g, '')
+        .replace(CAST, '')
+        .replace(/[\s()]/g, '')
+        .replace(/=anyarray\[([^\]]*)\]/g, 'in$1');
+    const normalizeDefinition = canonicalDefinition;
+    const columnList = (columns) => columns.map(quoteIdent).join(', ');
+    const indexStatement = (spec, entry) => {
+        const target = entry.expression != null
+            ? `(${entry.expression})`
+            : `(${columnList(entry.columns)})`;
+        const where = entry.where != null ? ` WHERE ${entry.where}` : '';
+        return `CREATE ${entry.unique === true ? 'UNIQUE ' : ''}INDEX ${quoteIdent(entry.name)}`
+            + ` ON ${spec.qualified} USING ${entry.method ?? PgIndexMethod.BTree} ${target}${where}`;
+    };
+    const columnDefinition = (column) => {
+        const parts = [quoteIdent(column.column), column.sqlType];
+        if (column.notNull)
+            parts.push('NOT NULL');
+        const expression = defaultExpression(column);
+        if (expression != null)
+            parts.push(`DEFAULT ${expression}`);
+        return parts.join(' ');
+    };
+    const planForeignKeys = (spec, context) => spec.references.map(reference => {
+        const column = reference.property != null ? spec.byProperty[reference.property] : undefined;
+        if (column == null) {
+            throw new PostgresPlaceholderError(`fk-unknown-property:${reference.property}`);
         }
-        for (const unique of spec.uniques) {
-            constraints.push(`CONSTRAINT ${quoteIdent(unique.name)} UNIQUE (${columnList(unique.columns)})`);
+        let targetSchema = reference.schema ?? spec.schema;
+        let targetTable = reference.table;
+        if (reference.resource != null) {
+            if (context == null) {
+                throw new PostgresPlaceholderError(`fk-no-context:${reference.resource}`);
+            }
+            let target;
+            try {
+                target = context.resource(reference.resource);
+            }
+            catch {
+                throw new PostgresPlaceholderError(`fk-unknown-resource:${reference.resource}`);
+            }
+            if (target.table == null) {
+                throw new PostgresPlaceholderError(`fk-uninitialized:${reference.resource}`);
+            }
+            targetSchema = target.table.schema;
+            targetTable = target.table.table;
         }
-        for (const check of spec.checks) {
-            constraints.push(`CONSTRAINT ${quoteIdent(check.name)} CHECK (${check.expression})`);
+        if (targetTable == null) {
+            throw new PostgresPlaceholderError(`fk-no-target:${reference.property}`);
         }
-        const statements = [{
-                kind: 'create-table',
-                target: spec.table,
-                sql: `CREATE TABLE ${spec.qualified} (\n  `
-                    + [...spec.columns.map(columnDefinition), ...constraints].join(',\n  ')
-                    + '\n)'
-            }];
-        for (const entry of spec.indexes) {
-            statements.push({ kind: 'create-index', target: entry.name, sql: indexStatement(spec, entry) });
+        const actions = [
+            reference.onDelete != null ? ` ON DELETE ${reference.onDelete}` : '',
+            reference.onUpdate != null ? ` ON UPDATE ${reference.onUpdate}` : ''
+        ].join('');
+        return {
+            kind: 'add-foreign-key',
+            target: reference.name,
+            sql: `ALTER TABLE ${spec.qualified} ADD CONSTRAINT ${quoteIdent(reference.name)}`
+                + ` FOREIGN KEY (${quoteIdent(column.column)})`
+                + ` REFERENCES ${qualify(targetSchema, targetTable)} (${quoteIdent(reference.column)})${actions}`
+        };
+    });
+    const planSync = (spec, live, additive = false) => {
+        if (!live.exists) {
+            const constraints = [];
+            if (spec.primaryKey.length > 0) {
+                constraints.push(`CONSTRAINT ${quoteIdent(`${spec.table}_pkey`)} PRIMARY KEY (${columnList(spec.primaryKey)})`);
+            }
+            for (const unique of spec.uniques) {
+                constraints.push(`CONSTRAINT ${quoteIdent(unique.name)} UNIQUE (${columnList(unique.columns)})`);
+            }
+            for (const check of spec.checks) {
+                constraints.push(`CONSTRAINT ${quoteIdent(check.name)} CHECK (${check.expression})`);
+            }
+            const statements = [{
+                    kind: 'create-table',
+                    target: spec.table,
+                    sql: `CREATE TABLE ${spec.qualified} (\n  `
+                        + [...spec.columns.map(columnDefinition), ...constraints].join(',\n  ')
+                        + '\n)'
+                }];
+            for (const entry of spec.indexes) {
+                statements.push({ kind: 'create-index', target: entry.name, sql: indexStatement(spec, entry) });
+            }
+            return { fresh: true, statements };
         }
-        return { fresh: true, statements };
-    }
-    const statements = [];
-    const byName = {};
-    for (const column of live.columns) {
-        byName[column.name] = column;
-    }
-    const managed = spec.columns.filter(column => column.managed);
-    /** 1. Columns the table doesn't have yet — always added nullable so existing rows survive. */
-    for (const column of managed) {
-        if (byName[column.column] != null) {
-            continue;
+        const statements = [];
+        const byName = {};
+        for (const column of live.columns) {
+            byName[column.name] = column;
         }
-        const expression = defaultExpression(column);
-        statements.push({
-            kind: 'add-column',
-            target: column.column,
-            sql: `ALTER TABLE ${spec.qualified} ADD COLUMN ${quoteIdent(column.column)} ${column.sqlType}`
-                + (expression != null ? ` DEFAULT ${expression}` : '')
-        });
-        if (column.notNull) {
-            if (expression == null) {
-                statements.push({
-                    kind: 'backfill',
-                    target: column.column,
-                    sql: `UPDATE ${spec.qualified} SET ${quoteIdent(column.column)} = ${fallback(column)}`
-                        + ` WHERE ${quoteIdent(column.column)} IS NULL`
-                });
+        const managed = spec.columns.filter(column => column.managed);
+        /** 1. Columns the table doesn't have yet — always added nullable so existing rows survive. */
+        for (const column of managed) {
+            if (byName[column.column] != null) {
+                continue;
             }
+            const expression = defaultExpression(column);
             statements.push({
-                kind: 'set-not-null',
+                kind: 'add-column',
                 target: column.column,
-                sql: `ALTER TABLE ${spec.qualified} ALTER COLUMN ${quoteIdent(column.column)} SET NOT NULL`
+                sql: `ALTER TABLE ${spec.qualified} ADD COLUMN ${quoteIdent(column.column)} ${column.sqlType}`
+                    + (expression != null ? ` DEFAULT ${expression}` : '')
             });
-        }
-    }
-    /** 2-4. Type, nullability and default drift on columns that already exist. */
-    for (const column of managed) {
-        const existing = byName[column.column];
-        if (existing == null) {
-            continue;
-        }
-        /**
-         * A retype drops the column's default first.
-         *
-         * Postgres refuses `ALTER COLUMN … TYPE` outright when the column carries a DEFAULT it cannot
-         * cast to the new type — `42804 default for column "x" cannot be cast automatically` — and it
-         * refuses it before looking at a single row, so the `USING` clause never gets a chance to
-         * help. The whole plan runs in one transaction, so that refusal aborts the entire
-         * reconciliation: the table keeps its old shape and the resource fails every boot with an
-         * error about a column it is trying to fix. The standard remedy is to take the default out of
-         * the way, retype, and put it back — which is what the default-drift block below does, from
-         * the spec rather than from whatever the column happened to be carrying.
-         *
-         * The `id` column is the one that meets this in practice: it is created with a
-         * `gen_random_uuid()::text` default, so any change to its declared type hits this path.
-         */
-        let defaultDropped = false;
-        if (!additive && existing.type !== column.sqlType) {
-            if (existing.defaultExpr != null) {
+            if (column.notNull) {
+                if (expression == null) {
+                    statements.push({
+                        kind: 'backfill',
+                        target: column.column,
+                        sql: `UPDATE ${spec.qualified} SET ${quoteIdent(column.column)} = ${fallback(column)}`
+                            + ` WHERE ${quoteIdent(column.column)} IS NULL`
+                    });
+                }
                 statements.push({
-                    kind: 'set-default',
+                    kind: 'set-not-null',
                     target: column.column,
-                    sql: `ALTER TABLE ${spec.qualified} ALTER COLUMN ${quoteIdent(column.column)} DROP DEFAULT`
+                    sql: `ALTER TABLE ${spec.qualified} ALTER COLUMN ${quoteIdent(column.column)} SET NOT NULL`
                 });
-                defaultDropped = true;
             }
-            const using = column.using ?? `${quoteIdent(column.column)}::${column.sqlType}`;
-            statements.push({
-                kind: 'alter-type',
-                target: column.column,
-                sql: `ALTER TABLE ${spec.qualified} ALTER COLUMN ${quoteIdent(column.column)}`
-                    + ` TYPE ${column.sqlType} USING ${using}`
-            });
         }
-        const expression = defaultExpression(column);
-        // Once the retype has dropped it, the default has to be re-stated even when it matches what
-        // the column used to carry: the comparison is against the pre-plan introspection, which stops
-        // describing the column the moment the plan drops its default.
-        const defaultDrifted = defaultDropped
-            ? expression != null
-            : normalizeDefault(expression) !== normalizeDefault(existing.defaultExpr);
-        if (defaultDrifted) {
-            statements.push(expression != null
-                ? {
-                    kind: 'set-default',
-                    target: column.column,
-                    sql: `ALTER TABLE ${spec.qualified} ALTER COLUMN ${quoteIdent(column.column)}`
-                        + ` SET DEFAULT ${expression}`
+        /** 2-4. Type, nullability and default drift on columns that already exist. */
+        for (const column of managed) {
+            const existing = byName[column.column];
+            if (existing == null) {
+                continue;
+            }
+            /**
+             * A retype drops the column's default first.
+             *
+             * Postgres refuses `ALTER COLUMN … TYPE` outright when the column carries a DEFAULT it cannot
+             * cast to the new type — `42804 default for column "x" cannot be cast automatically` — and it
+             * refuses it before looking at a single row, so the `USING` clause never gets a chance to
+             * help. The whole plan runs in one transaction, so that refusal aborts the entire
+             * reconciliation: the table keeps its old shape and the resource fails every boot with an
+             * error about a column it is trying to fix. The standard remedy is to take the default out of
+             * the way, retype, and put it back — which is what the default-drift block below does, from
+             * the spec rather than from whatever the column happened to be carrying.
+             *
+             * The `id` column is the one that meets this in practice: it is created with a
+             * `gen_random_uuid()::text` default, so any change to its declared type hits this path.
+             */
+            let defaultDropped = false;
+            if (!additive && existing.type !== column.sqlType) {
+                if (existing.defaultExpr != null) {
+                    statements.push({
+                        kind: 'set-default',
+                        target: column.column,
+                        sql: `ALTER TABLE ${spec.qualified} ALTER COLUMN ${quoteIdent(column.column)} DROP DEFAULT`
+                    });
+                    defaultDropped = true;
                 }
-                : {
-                    kind: 'set-default',
+                const using = column.using ?? `${quoteIdent(column.column)}::${column.sqlType}`;
+                statements.push({
+                    kind: 'alter-type',
                     target: column.column,
-                    sql: `ALTER TABLE ${spec.qualified} ALTER COLUMN ${quoteIdent(column.column)} DROP DEFAULT`
+                    sql: `ALTER TABLE ${spec.qualified} ALTER COLUMN ${quoteIdent(column.column)}`
+                        + ` TYPE ${column.sqlType} USING ${using}`
                 });
-        }
-        if (column.notNull !== existing.notNull) {
-            if (column.notNull) {
+            }
+            const expression = defaultExpression(column);
+            // Once the retype has dropped it, the default has to be re-stated even when it matches what
+            // the column used to carry: the comparison is against the pre-plan introspection, which stops
+            // describing the column the moment the plan drops its default.
+            const defaultDrifted = defaultDropped
+                ? expression != null
+                : normalizeDefault(expression) !== normalizeDefault(existing.defaultExpr);
+            if (defaultDrifted) {
+                statements.push(expression != null
+                    ? {
+                        kind: 'set-default',
+                        target: column.column,
+                        sql: `ALTER TABLE ${spec.qualified} ALTER COLUMN ${quoteIdent(column.column)}`
+                            + ` SET DEFAULT ${expression}`
+                    }
+                    : {
+                        kind: 'set-default',
+                        target: column.column,
+                        sql: `ALTER TABLE ${spec.qualified} ALTER COLUMN ${quoteIdent(column.column)} DROP DEFAULT`
+                    });
+            }
+            if (column.notNull !== existing.notNull) {
+                if (column.notNull) {
+                    statements.push({
+                        kind: 'backfill',
+                        target: column.column,
+                        sql: `UPDATE ${spec.qualified} SET ${quoteIdent(column.column)}`
+                            + ` = ${expression ?? fallback(column)} WHERE ${quoteIdent(column.column)} IS NULL`
+                    });
+                }
                 statements.push({
-                    kind: 'backfill',
+                    kind: column.notNull ? 'set-not-null' : 'drop-not-null',
                     target: column.column,
-                    sql: `UPDATE ${spec.qualified} SET ${quoteIdent(column.column)}`
-                        + ` = ${expression ?? fallback(column)} WHERE ${quoteIdent(column.column)} IS NULL`
+                    sql: `ALTER TABLE ${spec.qualified} ALTER COLUMN ${quoteIdent(column.column)}`
+                        + ` ${column.notNull ? 'SET' : 'DROP'} NOT NULL`
                 });
             }
-            statements.push({
-                kind: column.notNull ? 'set-not-null' : 'drop-not-null',
-                target: column.column,
-                sql: `ALTER TABLE ${spec.qualified} ALTER COLUMN ${quoteIdent(column.column)}`
-                    + ` ${column.notNull ? 'SET' : 'DROP'} NOT NULL`
-            });
         }
-    }
-    /** 5. Unique and check constraints. Primary keys are deliberately excluded. */
-    const desiredConstraints = {};
-    for (const unique of spec.uniques) {
-        desiredConstraints[unique.name] = `UNIQUE (${columnList(unique.columns)})`;
-    }
-    for (const check of spec.checks) {
-        desiredConstraints[check.name] = `CHECK ((${check.expression}))`;
-    }
-    const liveConstraints = {};
-    for (const constraint of live.constraints) {
-        // Primary and foreign keys have their own paths. A NOT NULL (`n`) is a constraint row since
-        // Postgres 18 (`<table>_<column>_not_null`) and is owned by the column step above: dropping it by
-        // name is refused on a primary key column, and on any other it would undo a `required` property.
-        if (constraint.type === 'p' || constraint.type === 'f' || constraint.type === 'n') {
-            continue;
-        }
-        liveConstraints[constraint.name] = constraint.definition;
-    }
-    for (const [name, definition] of Object.entries(liveConstraints)) {
-        const desired = desiredConstraints[name];
-        if (desired != null && normalizeDefinition(desired) === normalizeDefinition(definition)) {
-            continue;
-        }
-        if (desired == null && additive) {
-            continue;
-        }
-        if (desired == null && !isGenerated(name, spec)) {
-            /** A constraint nobody declared was added by hand — leave it alone. */
-            continue;
-        }
-        statements.push({
-            kind: 'drop-constraint',
-            target: name,
-            sql: `ALTER TABLE ${spec.qualified} DROP CONSTRAINT ${quoteIdent(name)}`
-        });
-    }
-    for (const [name, definition] of Object.entries(desiredConstraints)) {
-        const existing = liveConstraints[name];
-        if (existing != null && normalizeDefinition(existing) === normalizeDefinition(definition)) {
-            continue;
-        }
-        if (existing != null && additive) {
-            continue;
+        /** 5. Unique and check constraints. Primary keys are deliberately excluded. */
+        const desiredConstraints = {};
+        for (const unique of spec.uniques) {
+            desiredConstraints[unique.name] = `UNIQUE (${columnList(unique.columns)})`;
         }
-        statements.push({
-            kind: 'add-constraint',
-            target: name,
-            sql: `ALTER TABLE ${spec.qualified} ADD CONSTRAINT ${quoteIdent(name)} ${definition}`
-        });
-    }
-    /** 6. Indexes. Constraint backed indexes are owned by their constraint, not by us. */
-    const constraintBacked = live.constraints.map(constraint => constraint.name);
-    const desiredIndexes = {};
-    for (const entry of spec.indexes) {
-        desiredIndexes[entry.name] = indexStatement(spec, entry);
-    }
-    for (const existing of live.indexes) {
-        if (constraintBacked.includes(existing.name)) {
-            continue;
+        for (const check of spec.checks) {
+            desiredConstraints[check.name] = `CHECK ((${check.expression}))`;
         }
-        const desired = desiredIndexes[existing.name];
-        if (desired != null && normalizeDefinition(desired) === normalizeDefinition(existing.definition)) {
-            continue;
+        const liveConstraints = {};
+        for (const constraint of live.constraints) {
+            // Primary and foreign keys have their own paths. A NOT NULL (`n`) is a constraint row since
+            // Postgres 18 (`<table>_<column>_not_null`) and is owned by the column step above: dropping it by
+            // name is refused on a primary key column, and on any other it would undo a `required` property.
+            if (constraint.type === 'p' || constraint.type === 'f' || constraint.type === 'n') {
+                continue;
+            }
+            liveConstraints[constraint.name] = constraint.definition;
         }
-        if (desired == null && (additive || !isGenerated(existing.name, spec))) {
-            continue;
+        for (const [name, definition] of Object.entries(liveConstraints)) {
+            const desired = desiredConstraints[name];
+            if (desired != null && normalizeDefinition(desired) === normalizeDefinition(definition)) {
+                continue;
+            }
+            if (desired == null && additive) {
+                continue;
+            }
+            if (desired == null && !isGenerated(name, spec)) {
+                /** A constraint nobody declared was added by hand — leave it alone. */
+                continue;
+            }
+            statements.push({
+                kind: 'drop-constraint',
+                target: name,
+                sql: `ALTER TABLE ${spec.qualified} DROP CONSTRAINT ${quoteIdent(name)}`
+            });
         }
-        statements.push({
-            kind: 'drop-index',
-            target: existing.name,
-            sql: `DROP INDEX ${qualify(spec.schema, existing.name)}`
-        });
-    }
-    for (const [name, statement] of Object.entries(desiredIndexes)) {
-        const existing = live.indexes.find(entry => entry.name === name);
-        if (existing != null && normalizeDefinition(existing.definition) === normalizeDefinition(statement)) {
-            continue;
+        for (const [name, definition] of Object.entries(desiredConstraints)) {
+            const existing = liveConstraints[name];
+            if (existing != null && normalizeDefinition(existing) === normalizeDefinition(definition)) {
+                continue;
+            }
+            if (existing != null && additive) {
+                continue;
+            }
+            statements.push({
+                kind: 'add-constraint',
+                target: name,
+                sql: `ALTER TABLE ${spec.qualified} ADD CONSTRAINT ${quoteIdent(name)} ${definition}`
+            });
         }
-        if (constraintBacked.includes(name)) {
-            continue;
+        /** 6. Indexes. Constraint backed indexes are owned by their constraint, not by us. */
+        const constraintBacked = live.constraints.map(constraint => constraint.name);
+        const desiredIndexes = {};
+        for (const entry of spec.indexes) {
+            desiredIndexes[entry.name] = indexStatement(spec, entry);
         }
-        statements.push({ kind: 'create-index', target: name, sql: statement });
-    }
-    /** 7. Drops, last and only in full mode. */
-    if (!additive) {
-        const keep = [...managed.map(column => column.column), ...spec.unmanaged];
-        for (const existing of live.columns) {
-            if (keep.includes(existing.name) || existing.generated !== '') {
+        for (const existing of live.indexes) {
+            if (constraintBacked.includes(existing.name)) {
+                continue;
+            }
+            const desired = desiredIndexes[existing.name];
+            if (desired != null && normalizeDefinition(desired) === normalizeDefinition(existing.definition)) {
+                continue;
+            }
+            if (desired == null && (additive || !isGenerated(existing.name, spec))) {
                 continue;
             }
             statements.push({
-                kind: 'drop-column',
+                kind: 'drop-index',
                 target: existing.name,
-                destructive: true,
-                sql: `ALTER TABLE ${spec.qualified} DROP COLUMN ${quoteIdent(existing.name)}`
+                sql: `DROP INDEX ${qualify(spec.schema, existing.name)}`
             });
         }
-    }
-    return { fresh: false, statements };
-};
-/** A name this package would have generated is a name this package may drop. */
-const isGenerated = (name, spec) => name.startsWith(`${spec.table}_`);
-/** Value used to fill an existing row before a column becomes `NOT NULL`. */
-const fallback = (column) => {
-    if (column.array)
-        return `'{}'::${column.sqlType}`;
-    if (column.jsonb)
-        return `'{}'::jsonb`;
-    switch (column.jsonType) {
-        case 'number':
-        case 'integer':
-        case 'bigint':
-            return '0';
-        case 'boolean':
-            return 'FALSE';
-        case 'date':
-            return 'now()';
-        default:
-            return `''::${column.sqlType}`;
-    }
+        for (const [name, statement] of Object.entries(desiredIndexes)) {
+            const existing = live.indexes.find(entry => entry.name === name);
+            if (existing != null && normalizeDefinition(existing.definition) === normalizeDefinition(statement)) {
+                continue;
+            }
+            if (constraintBacked.includes(name)) {
+                continue;
+            }
+            statements.push({ kind: 'create-index', target: name, sql: statement });
+        }
+        /** 7. Drops, last and only in full mode. */
+        if (!additive) {
+            const keep = [...managed.map(column => column.column), ...spec.unmanaged];
+            for (const existing of live.columns) {
+                if (keep.includes(existing.name) || existing.generated !== '') {
+                    continue;
+                }
+                statements.push({
+                    kind: 'drop-column',
+                    target: existing.name,
+                    destructive: true,
+                    sql: `ALTER TABLE ${spec.qualified} DROP COLUMN ${quoteIdent(existing.name)}`
+                });
+            }
+        }
+        return { fresh: false, statements };
+    };
+    /** A name this package would have generated is a name this package may drop. */
+    const isGenerated = (name, spec) => name.startsWith(`${spec.table}_`);
+    /** Value used to fill an existing row before a column becomes `NOT NULL`. */
+    const fallback = (column) => {
+        if (column.array)
+            return `'{}'::${column.sqlType}`;
+        if (column.jsonb)
+            return `'{}'::jsonb`;
+        switch (column.jsonType) {
+            case 'number':
+            case 'integer':
+            case 'bigint':
+                return '0';
+            case 'boolean':
+                return 'FALSE';
+            case 'date':
+                return 'now()';
+            default:
+                return `''::${column.sqlType}`;
+        }
+    };
+    return { canonicalDefinition, planForeignKeys, planSync };
 };
+export const pgDiffHelper = createPgDiffHelper();
+/** @deprecated compat:factory-refactor — use `pgDiffHelper.planSync(…)` */
+export const planSync = (spec, live, additive = false) => pgDiffHelper.planSync(spec, live, additive);
 //# sourceMappingURL=diff.js.map