Merge pull request #1584 from constructive-io/feat/pgpm-constraint-folding

feat(transform): constraint-placement-invariant semantic diff (planning #1341)

Author: pyramation

pgpm/transform/__tests__/constraint-names.test.ts

@@ -0,0 +1,53 @@
+import { loadModule, parseSync } from 'plpgsql-parser';
+
+import { ConstraintNode, defaultConstraintName, firstColumnRef } from '../src/constraint-names';
+
+beforeAll(async () => {
+  await loadModule();
+});
+
+/** The Constraint nodes of a one-statement `ALTER TABLE` script. */
+const constraintOf = (sql: string): ConstraintNode => {
+  const stmt = parseSync(sql).sql.stmts[0].stmt as {
+    AlterTableStmt: { cmds: { AlterTableCmd: { def: { Constraint: ConstraintNode } } }[] };
+  };
+  return stmt.AlterTableStmt.cmds[0].AlterTableCmd.def.Constraint;
+};
+
+describe('defaultConstraintName', () => {
+  it('derives Postgres default names for unnamed table-level constraints', () => {
+    expect(defaultConstraintName('users', constraintOf('ALTER TABLE users ADD PRIMARY KEY (id);')))
+      .toBe('users_pkey');
+    expect(defaultConstraintName('users', constraintOf('ALTER TABLE users ADD UNIQUE (email);')))
+      .toBe('users_email_key');
+    expect(defaultConstraintName('users', constraintOf('ALTER TABLE users ADD UNIQUE (a, b);')))
+      .toBe('users_a_b_key');
+    expect(defaultConstraintName('posts', constraintOf('ALTER TABLE posts ADD FOREIGN KEY (user_id) REFERENCES users (id);')))
+      .toBe('posts_user_id_fkey');
+    expect(defaultConstraintName('users', constraintOf('ALTER TABLE users ADD CHECK (age > 0);')))
+      .toBe('users_age_check');
+  });
+
+  it('uses the owning column for column-attached constraints', () => {
+    expect(defaultConstraintName('users', { contype: 'CONSTR_UNIQUE' }, 'email')).toBe('users_email_key');
+    expect(defaultConstraintName('posts', { contype: 'CONSTR_FOREIGN' }, 'user_id')).toBe('posts_user_id_fkey');
+    expect(defaultConstraintName('users', { contype: 'CONSTR_CHECK' }, 'age')).toBe('users_age_check');
+  });
+
+  it('returns null when no stable name derives', () => {
+    expect(defaultConstraintName('users', { contype: 'CONSTR_UNIQUE' })).toBeNull();
+    expect(defaultConstraintName('users', { contype: 'CONSTR_EXCLUSION' })).toBeNull();
+  });
+});
+
+describe('firstColumnRef', () => {
+  it('finds the first referenced column in an expression tree', () => {
+    const check = constraintOf('ALTER TABLE t ADD CHECK (price > 0 AND qty > 0);');
+    expect(firstColumnRef(check.raw_expr)).toBe('price');
+  });
+
+  it('returns null for column-free expressions', () => {
+    const check = constraintOf('ALTER TABLE t ADD CHECK (1 = 1);');
+    expect(firstColumnRef(check.raw_expr)).toBeNull();
+  });
+});

pgpm/transform/__tests__/semantic-diff-driver.test.ts

@@ -138,6 +138,62 @@ describe('diffSchemas', () => {
     expect(result.warnings.some(w => w.includes('column "note" changed beyond its type'))).toBe(true);
   });
 
+  it('is constraint-placement-invariant: inline, table-elt, and standalone ADD CONSTRAINT unify', () => {
+    const consolidated = [
+      'CREATE SCHEMA app;',
+      'CREATE TABLE app.users (id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY, email text NOT NULL UNIQUE, age int CHECK (age > 0));',
+      'CREATE TABLE app.posts (id bigint PRIMARY KEY, user_id bigint NOT NULL REFERENCES app.users (id));'
+    ].join('\n');
+    const standalone = [
+      'CREATE SCHEMA app;',
+      'CREATE TABLE app.users (id bigint GENERATED ALWAYS AS IDENTITY NOT NULL, email text NOT NULL, age int);',
+      'ALTER TABLE app.users ADD CONSTRAINT users_pkey PRIMARY KEY (id);',
+      'ALTER TABLE app.users ADD CONSTRAINT users_email_key UNIQUE (email);',
+      'ALTER TABLE app.users ADD CONSTRAINT users_age_check CHECK (age > 0);',
+      'CREATE TABLE app.posts (id bigint NOT NULL, user_id bigint NOT NULL);',
+      'ALTER TABLE app.posts ADD CONSTRAINT posts_pkey PRIMARY KEY (id);',
+      'ALTER TABLE app.posts ADD CONSTRAINT posts_user_id_fkey FOREIGN KEY (user_id) REFERENCES app.users (id);'
+    ].join('\n');
+    const result = diffSchemas(consolidated, standalone);
+    expect(result.identical).toBe(true);
+    expect(result.changes).toEqual([]);
+  });
+
+  it('matches unnamed standalone constraints against their Postgres default names', () => {
+    const inline = 'CREATE TABLE app.users (id bigint PRIMARY KEY, email text UNIQUE);';
+    const unnamed = [
+      'CREATE TABLE app.users (id bigint NOT NULL, email text);',
+      'ALTER TABLE app.users ADD PRIMARY KEY (id);',
+      'ALTER TABLE app.users ADD UNIQUE (email);'
+    ].join('\n');
+    expect(diffSchemas(inline, unnamed).identical).toBe(true);
+  });
+
+  it('still surfaces a genuinely changed constraint, dropping it by its default name', () => {
+    const from = 'CREATE TABLE app.users (id bigint PRIMARY KEY, age int CHECK (age > 0));';
+    const to = 'CREATE TABLE app.users (id bigint PRIMARY KEY, age int CHECK (age > 1));';
+    const result = diffSchemas(from, to);
+    expect(result.identical).toBe(false);
+    const change = result.changes.find(c => c.name === 'schemas/app/tables/users/table/alter')!;
+    expect(change.deploy).toContain('DROP CONSTRAINT users_age_check');
+    expect(change.deploy).toContain('ADD CONSTRAINT users_age_check CHECK (age > 1)');
+  });
+
+  it('folds foreign keys into their table: fk placement never diffs', () => {
+    const inline = [
+      'CREATE TABLE app.users (id bigint PRIMARY KEY);',
+      'CREATE TABLE app.posts (id bigint PRIMARY KEY, user_id bigint REFERENCES app.users (id));'
+    ].join('\n');
+    const standalone = [
+      'CREATE TABLE app.users (id bigint PRIMARY KEY);',
+      'CREATE TABLE app.posts (id bigint PRIMARY KEY, user_id bigint);',
+      'ALTER TABLE app.posts ADD CONSTRAINT posts_user_id_fkey FOREIGN KEY (user_id) REFERENCES app.users (id);'
+    ].join('\n');
+    const result = diffSchemas(inline, standalone);
+    expect(result.identical).toBe(true);
+    expect(result.objects).toEqual([]);
+  });
+
   it('drops removed objects in reverse topological order', () => {
     const result = diffSchemas(BASE, 'CREATE SCHEMA app;\nCREATE TABLE app.users (id uuid PRIMARY KEY, name text);');
 

pgpm/transform/src/constraint-names.ts

@@ -0,0 +1,84 @@
+/**
+ * Postgres default constraint names.
+ *
+ * When a constraint is authored without a name, Postgres derives one at
+ * deploy time (`ChooseConstraintName` in the server): `{table}_pkey` for
+ * primary keys, `{table}_{cols}_key` for unique constraints,
+ * `{table}_{col}_fkey` for foreign keys, `{table}_{col}_check` (first
+ * referenced column) or `{table}_check` for check constraints. Synthesizing
+ * the same names makes unnamed authorship comparable to (and revertible as)
+ * what the catalog will actually contain.
+ */
+
+/** A parsed `Constraint` node (structural — the fields this module reads). */
+export interface ConstraintNode {
+  contype?: string;
+  conname?: string;
+  keys?: { String?: { sval?: string } }[];
+  fk_attrs?: { String?: { sval?: string } }[];
+  raw_expr?: unknown;
+}
+
+const svals = (items?: { String?: { sval?: string } }[]): string[] =>
+  (items ?? []).map(k => k.String?.sval).filter((s): s is string => typeof s === 'string');
+
+/** First `ColumnRef` column name reached in an expression tree, DFS order. */
+export function firstColumnRef(node: unknown): string | null {
+  if (Array.isArray(node)) {
+    for (const item of node) {
+      const found = firstColumnRef(item);
+      if (found) return found;
+    }
+    return null;
+  }
+  if (node && typeof node === 'object') {
+    const record = node as Record<string, unknown>;
+    const ref = record.ColumnRef as { fields?: unknown[] } | undefined;
+    if (ref?.fields) {
+      const names = svals(ref.fields as { String?: { sval?: string } }[]);
+      if (names.length > 0) return names[names.length - 1];
+    }
+    for (const value of Object.values(record)) {
+      const found = firstColumnRef(value);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+/**
+ * The name Postgres would assign to an unnamed constraint on `table`, given
+ * the constraint node and (for column-attached constraints) the owning
+ * column. Returns `null` for kinds without a stable derivation (exclusion
+ * constraints and anything unrecognized).
+ */
+export function defaultConstraintName(
+  table: string,
+  constraint: ConstraintNode,
+  column?: string
+): string | null {
+  const cols = (): string[] => {
+    const keyed = svals(constraint.keys);
+    if (keyed.length > 0) return keyed;
+    return column ? [column] : [];
+  };
+  switch (constraint.contype) {
+  case 'CONSTR_PRIMARY':
+    return `${table}_pkey`;
+  case 'CONSTR_UNIQUE': {
+    const names = cols();
+    return names.length > 0 ? `${table}_${names.join('_')}_key` : null;
+  }
+  case 'CONSTR_FOREIGN': {
+    const attrs = svals(constraint.fk_attrs);
+    const names = attrs.length > 0 ? attrs : column ? [column] : [];
+    return names.length > 0 ? `${table}_${names.join('_')}_fkey` : null;
+  }
+  case 'CONSTR_CHECK': {
+    const col = column ?? firstColumnRef(constraint.raw_expr);
+    return col ? `${table}_${col}_check` : `${table}_check`;
+  }
+  default:
+    return null;
+  }
+}

pgpm/transform/src/index.ts

@@ -23,6 +23,8 @@ export {
   categorizeChange,
   TIER_PROFILE,
 } from './categorize';
+export type { ConstraintNode } from './constraint-names';
+export { defaultConstraintName, firstColumnRef } from './constraint-names';
 export type {
   ClosureChange,
   ClosureInputChange,

pgpm/transform/src/semantic-diff-driver.ts

@@ -38,6 +38,7 @@ import {
 } from '@pgsql/transform';
 import { Deparser, parseSync } from 'plpgsql-parser';
 
+import { ConstraintNode, defaultConstraintName } from './constraint-names';
 import { GranularityChange, restructureChanges } from './granularity-driver';
 
 /** How one object differs between the two sides. */
@@ -165,7 +166,7 @@ function groupingIdentity(f: StatementFacts): ObjectIdentity | null {
   const identity = identityOf(f);
   if (!identity) return null;
   if (
-    (f.kind === 'table' || f.kind === 'constraint' || f.kind === 'rls_enable') &&
+    (f.kind === 'table' || f.kind === 'constraint' || f.kind === 'fk_constraint' || f.kind === 'rls_enable') &&
     identity.kind !== 'table'
   ) {
     return { kind: 'table', schema: identity.schema, name: identity.table ?? identity.name };
@@ -191,22 +192,62 @@ interface TableShape {
   extras: Map<string, unknown>;
 }
 
+/** JSON with recursively sorted object keys — an insertion-order-proof fingerprint. */
+function stablePrint(node: unknown): string {
+  if (Array.isArray(node)) return `[${node.map(stablePrint).join(',')}]`;
+  if (node && typeof node === 'object') {
+    const entries = Object.entries(node as Record<string, unknown>)
+      .filter(([, v]) => v !== undefined)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([k, v]) => `${JSON.stringify(k)}:${stablePrint(v)}`);
+    return `{${entries.join(',')}}`;
+  }
+  return JSON.stringify(node);
+}
+
+/** Constraint kinds that can move between column, table-elt, and ALTER form. */
+const RELOCATABLE = new Set(['CONSTR_PRIMARY', 'CONSTR_UNIQUE', 'CONSTR_FOREIGN', 'CONSTR_CHECK']);
+
 /**
  * Fold a table unit's statements (CREATE TABLE plus any ALTER TABLE
  * ADD COLUMN / ADD CONSTRAINT) into an effective shape, so atomic and
  * consolidated authorships of the same table compare equal.
+ *
+ * Constraint placement is representation, not semantics: `id bigint PRIMARY
+ * KEY`, a `PRIMARY KEY (id)` table elt, and `ALTER TABLE .. ADD CONSTRAINT
+ * t_pkey PRIMARY KEY (id)` all catalog identically. Relocatable constraints
+ * (PK/UNIQUE/FK/CHECK) are therefore lifted out of columns and ALTER
+ * commands into one canonical table-level set — keyed with the Postgres
+ * default name when unnamed, columns filled in from the owning column when
+ * column-attached — and PK columns gain the NOT NULL the catalog implies.
  */
 function tableShape(unit: ObjectUnit): TableShape {
   const shape: TableShape = { relation: null, columns: new Map(), extras: new Map() };
+  const table = unit.identity.name;
+  const rawColumns: { colname: string; def: Record<string, unknown> }[] = [];
+  const constraints: { node: ConstraintNode & Record<string, unknown>; column?: string }[] = [];
+  const pkColumns = new Set<string>();
 
   const addColumn = (node: Record<string, unknown>): void => {
-    const def = node as { colname?: string };
-    const clean = cleanTree(node);
-    shape.columns.set(def.colname ?? '', { def: clean, print: JSON.stringify(clean) });
+    const colname = (node as { colname?: string }).colname ?? '';
+    const attached = (node.constraints as { Constraint?: Record<string, unknown> }[] | undefined) ?? [];
+    const residual: unknown[] = [];
+    for (const item of attached) {
+      const c = item.Constraint as (ConstraintNode & Record<string, unknown>) | undefined;
+      if (c && RELOCATABLE.has(c.contype ?? '')) {
+        constraints.push({ node: c, column: colname });
+      } else {
+        residual.push(item);
+      }
+    }
+    rawColumns.push({ colname, def: { ...node, constraints: residual } });
+  };
+  const addConstraint = (node: Record<string, unknown>, column?: string): void => {
+    constraints.push({ node: node as ConstraintNode & Record<string, unknown>, column });
   };
   const addExtra = (node: unknown): void => {
     const clean = cleanTree(node);
-    shape.extras.set(JSON.stringify(clean), clean);
+    shape.extras.set(stablePrint(clean), clean);
   };
 
   for (const text of unit.texts) {
@@ -217,7 +258,9 @@ function tableShape(unit: ObjectUnit): TableShape {
         const elts = (stmt.CreateStmt.tableElts as Record<string, unknown>[] | undefined) ?? [];
         for (const elt of elts) {
           if (elt.ColumnDef) addColumn(elt.ColumnDef as Record<string, unknown>);
-          else addExtra(elt);
+          else if (elt.Constraint && RELOCATABLE.has((elt.Constraint as ConstraintNode).contype ?? '')) {
+            addConstraint(elt.Constraint as Record<string, unknown>);
+          } else addExtra(elt);
         }
       } else if (stmt.AlterTableStmt) {
         shape.relation ??= stmt.AlterTableStmt.relation;
@@ -228,6 +271,12 @@ function tableShape(unit: ObjectUnit): TableShape {
           const def = at.def as Record<string, unknown> | undefined;
           if (at.subtype === 'AT_AddColumn' && def?.ColumnDef) {
             addColumn(def.ColumnDef as Record<string, unknown>);
+          } else if (
+            at.subtype === 'AT_AddConstraint' &&
+            def?.Constraint &&
+            RELOCATABLE.has((def.Constraint as ConstraintNode).contype ?? '')
+          ) {
+            addConstraint(def.Constraint as Record<string, unknown>);
           } else {
             addExtra({ AlterTableCmd: at });
           }
@@ -237,6 +286,46 @@ function tableShape(unit: ObjectUnit): TableShape {
       }
     }
   }
+
+  for (const { node, column } of constraints) {
+    const canonical: Record<string, unknown> = { ...node };
+    canonical.conname = node.conname ?? defaultConstraintName(table, node, column) ?? undefined;
+    if (column && (node.keys ?? []).length === 0 && node.contype !== 'CONSTR_FOREIGN' && node.contype !== 'CONSTR_CHECK') {
+      canonical.keys = [{ String: { sval: column } }];
+    }
+    if (column && node.contype === 'CONSTR_FOREIGN' && (node.fk_attrs ?? []).length === 0) {
+      canonical.fk_attrs = [{ String: { sval: column } }];
+    }
+    if (node.contype === 'CONSTR_PRIMARY') {
+      const keyed = (canonical.keys as { String?: { sval?: string } }[] | undefined) ?? [];
+      for (const k of keyed) if (k.String?.sval) pkColumns.add(k.String.sval);
+    }
+    addExtra({ Constraint: canonical });
+  }
+
+  for (const { colname, def } of rawColumns) {
+    const residual = ((def.constraints as unknown[] | undefined) ?? []).map(c => {
+      const constraint = (c as { Constraint?: ConstraintNode & { conname?: string } }).Constraint;
+      // NOT NULL parses with parser-version-dependent extras (is_enforced,
+      // initially_valid); reduce to its semantic core so an authored NOT NULL
+      // equals the one a primary key implies.
+      if (constraint?.contype === 'CONSTR_NOTNULL') {
+        return { Constraint: { contype: 'CONSTR_NOTNULL', conname: constraint.conname } };
+      }
+      return c;
+    });
+    const hasNotNull = residual.some(
+      c => (c as { Constraint?: ConstraintNode }).Constraint?.contype === 'CONSTR_NOTNULL'
+    );
+    if (pkColumns.has(colname) && !hasNotNull) {
+      residual.push({ Constraint: { contype: 'CONSTR_NOTNULL' } });
+    }
+    const sorted = residual
+      .map(c => cleanTree(c))
+      .sort((x, y) => stablePrint(x).localeCompare(stablePrint(y)));
+    const clean = cleanTree({ ...def, constraints: sorted });
+    shape.columns.set(colname, { def: clean, print: stablePrint(clean) });
+  }
   return shape;
 }