@ultimat3/db 29.3.2 → 30.0.0

package/src/drift-findings.ts

@@ -1,10 +1,11 @@
 // Single responsibility: what a schema difference is CALLED and what its `fix:` says — one
-// constructor per `DriftKind`, and nothing that compares anything (`drift.ts` decides whether two
-// schemas disagree). A `fix:` is ONE command a shell runs, and a difference names the declared
+// constructor per `DriftKind` (the missing-or-rebuilt ones in `drift-missing.ts`), and nothing that
+// compares anything (`drift.ts` decides whether two schemas disagree). A `fix:` is ONE command a shell runs, and a difference names the declared
 // side's spelling, never the catalog's — which is Postgres' rewriting.
 
 import { psqlCommand } from './dependent-view';
-import { addForeignKey, dropForeignKey, onDeleteRule } from './foreign-key';
+import { undeclaredColumnNext } from './drift-errors';
+import { addForeignKey, dropForeignKey, onDeleteRule, validateConstraint } from './foreign-key';
 import type { CheckDescription, ForeignKeyDescription } from './introspect';
 import type { Migration } from './migrate';
 import { addPrimaryKey, dropPrimaryKey } from './primary-key';
@@ -23,8 +24,17 @@ export type DriftKind =
   | 'missing-check'
   | 'missing-foreign-key'
   | 'changed-foreign-key'
+  // A declared constraint the catalog holds `NOT VALID`: the deferred step's validate never finished.
+  | 'not-valid-constraint'
   // Constructed in `drift-append-only.ts`: an `appendOnly` table whose refusing trigger is gone.
   | 'missing-append-only-trigger'
+  // Constructed in `drift-triggers.ts`: a history, guard or counter trigger gone, or a retain table
+  // the catalog holds partitioned.
+  | 'missing-lifecycle-trigger'
+  | 'retain-partitioned'
+  // Constructed in `drift-row-security.ts`: a tenant policy missing, or present unrecorded.
+  | 'missing-row-security'
+  | 'unexpected-row-security'
   // Constructed in `object-drift.ts`: a trigger, function, view, type or sequence in the live
   // database that replaying the migrations does not create.
   | 'unexpected-object';
@@ -42,10 +52,10 @@ export interface DriftReport {
   readonly differences: readonly DriftDifference[];
 }
 
-const RE_CHECK = 'then x db migrate, which re-checks';
+export const RE_CHECK = 'then x db migrate, which re-checks';
 
 /** `set not null` is refused by the server while a row still holds NULL, and says so here. */
-const NULLS_FIRST = `refused while a row holds NULL there, so backfill those first; ${RE_CHECK}`;
+export const NULLS_FIRST = `refused while a row holds NULL there, so backfill those first; ${RE_CHECK}`;
 
 const CARRIES =
   'a name in this difference carries a backtick, a dollar sign, a quote, a backslash or whitespace';
@@ -99,7 +109,7 @@ const qualified = (schema: string, table: string): string | null => {
 };
 
 /** Every name inert in a shell AND writable as an identifier — the one screen, asked of each. */
-const spellable = (names: readonly string[]): boolean =>
+export const spellable = (names: readonly string[]): boolean =>
   names.every((name) => shellInertIdentifier(name) !== null);
 
 /**
@@ -120,20 +130,8 @@ export function unexpectedColumn(table: string, column: string): DriftDifference
     cause: `table "${table}" has column "${column}" not present in any migration`,
     fix:
       shellInertIdentifier(column) === null
-        ? 'x db gen "add the undeclared column"   # the live column name carries a backtick, a ' +
-          'dollar sign, a quote, a backslash or whitespace, so it is in the cause and not in ' +
-          'this command'
-        : `x db gen "add ${column}"`,
-  };
-}
-
-export function missingColumn(table: string, column: string): DriftDifference {
-  return {
-    kind: 'missing-column',
-    table,
-    column,
-    cause: `table "${table}" is missing column "${column}" that migrations declare`,
-    fix: 'x db migrate',
+        ? `x db gen "add the undeclared column"   # the live column name carries shell syntax, so it is in the cause and not in this command; ${undeclaredColumnNext('it')}`
+        : `x db gen "add ${column}"   # ${undeclaredColumnNext(column)}`,
   };
 }
 
@@ -222,16 +220,6 @@ export function unexpectedTable(schema: string, table: string): DriftDifference
   };
 }
 
-export function missingTable(table: string): DriftDifference {
-  return {
-    kind: 'missing-table',
-    table,
-    column: null,
-    cause: `table "${table}" is declared by migrations but does not exist`,
-    fix: 'x db migrate',
-  };
-}
-
 /**
  * Not a difference between two schemas but the absence of one to compare against — reported
  * through the same channel so it reaches an operator, since a check that quietly answered "clean"
@@ -272,26 +260,6 @@ export function unknownSchema(migrations: readonly Migration[]): DriftDifference
   };
 }
 
-export function missingIndex(table: string, index: string): DriftDifference {
-  return {
-    kind: 'missing-index',
-    table,
-    column: null,
-    cause: `table "${table}" is missing index "${index}" that migrations declare`,
-    fix: 'x db migrate',
-  };
-}
-
-export function changedIndex(table: string, index: string, detail: string): DriftDifference {
-  return {
-    kind: 'changed-index',
-    table,
-    column: null,
-    cause: `index "${index}" on "${table}" ${detail}, not what migrations declare`,
-    fix: 'x db migrate',
-  };
-}
-
 /**
  * A CHECK a migration declares and the catalog does not hold.
  *
@@ -334,18 +302,6 @@ export function missingCheck(
   };
 }
 
-export function missingForeignKey(table: string, key: ForeignKeyDescription): DriftDifference {
-  return {
-    kind: 'missing-foreign-key',
-    table,
-    column: null,
-    cause:
-      `table "${table}" has no foreign key on (${key.columns.join(', ')}) to ` +
-      `"${key.referencedTable}" (${key.referencedColumns.join(', ')}) that migrations declare`,
-    fix: 'x db migrate',
-  };
-}
-
 /**
  * The key points where it was declared to point and one side's `on delete` rule is not the other's
  * — reported apart from `missing-foreign-key` because it is a different repair: the constraint is
@@ -405,6 +361,35 @@ export function changedForeignKey(
   };
 }
 
+/**
+ * The constraint is there and holds every new write; rows that predate it are unchecked. Left by a
+ * deferred step that stopped between its add and its validate, or by hand. The fix is the validate
+ * statement (`repair`), because a ledger that recorded the step will apply nothing on a re-run; a
+ * step still pending is re-run by `x db migrate`, whose validate is the same statement.
+ */
+export function notValidConstraint(
+  schema: string,
+  table: string,
+  constraint: string,
+): DriftDifference {
+  const path = pathTo(schema);
+  const steps = 'alter table … validate constraint … on the constraint this difference names';
+  return {
+    kind: 'not-valid-constraint',
+    table,
+    column: null,
+    cause: `constraint "${constraint}" on "${table}" is NOT VALID: rows older than it were never checked`,
+    fix:
+      path === null || !spellable([table, constraint])
+        ? byHand(steps)
+        : repair(
+            path,
+            validateConstraint(table, constraint),
+            'a row it finds is X_DB_FOREIGN_KEY_VIOLATION or a CHECK failure: repair that row, then run it again',
+          ),
+  };
+}
+
 const PRIMARY_KEY_BY_HAND = byHand(
   'drop the primary key this database holds, add the one migrations declare',
   `${CARRIES} or is too long, so no statement here can spell it`,

package/src/drift-missing.ts

@@ -0,0 +1,203 @@
+// Single responsibility: the findings for something a migration declares that the catalog lacks
+// or holds rebuilt — a table, a column, an index, a foreign key — each with the statement that puts
+// it back, built from the snapshot. Split from `drift-findings.ts`, whose helpers these share.
+
+import {
+  byHand,
+  type DriftDifference,
+  NULLS_FIRST,
+  pathTo,
+  RE_CHECK,
+  repair,
+  spellable,
+} from './drift-findings';
+import { addForeignKey } from './foreign-key';
+import { asDeclared, createIndex, mayBeConstraintBacked } from './index-ddl';
+import type { ColumnDescription, ForeignKeyDescription, IndexDescription } from './introspect';
+import { identifier } from './sql';
+
+/**
+ * Why none of these says `x db migrate`: `checkDrift` compares the catalog with the migrations the
+ * LEDGER holds, so the migration that declares the missing thing has already run and re-running the
+ * migrator applies nothing — the same finding comes back. The fix is the statement, against this
+ * database (`repair`), the rule `missingCheck` and `changedPrimaryKey` already follow.
+ */
+
+/**
+ * A snapshot column as a column definition. `dataType`, `default` and `generated` are the DECLARED
+ * side's own text, out of the author's migration — the trust `missingCheck` gives its predicate —
+ * and `psqlCommand` closes the shell layer around all of it. `notNull` is the caller's: an `add
+ * column … not null` with no value to fill existing rows with is refused on a table holding any.
+ */
+const columnClause = (column: ColumnDescription, notNull: boolean): string => {
+  const value =
+    column.generated !== undefined
+      ? ` generated always as (${column.generated}) stored`
+      : column.default === null
+        ? ''
+        : ` default ${column.default}`;
+  return `${identifier(column.name).text} ${column.dataType}${value}${notNull ? ' not null' : ''}`;
+};
+
+/** Every row an `add column` lands on gets a value, so `not null` can ride on the same statement. */
+const filled = (column: ColumnDescription): boolean =>
+  column.default !== null || column.generated !== undefined;
+
+const LATER_NOT_NULL = `then x db migrate, which re-checks and names the set not null — ${NULLS_FIRST}`;
+
+/** The statement, or `byHand` when a name in it is refused or a writer refuses the declaration. */
+const statementOr = (
+  schema: string,
+  names: readonly string[],
+  steps: string,
+  write: () => string,
+  note = RE_CHECK,
+): string => {
+  const path = pathTo(schema);
+  if (path === null || !spellable(names)) return byHand(steps);
+  try {
+    return repair(path, write(), note);
+  } catch {
+    return byHand(steps, 'migrations declare it in a form no statement here can write');
+  }
+};
+
+/**
+ * Added NULLABLE when nothing fills the rows already there — the strict form fails on a populated
+ * table — and the re-check then reports `changed-column`, whose fix is the `set not null`.
+ */
+export function missingColumn(
+  schema: string,
+  table: string,
+  column: ColumnDescription,
+): DriftDifference {
+  const strict = !column.nullable && filled(column);
+  return {
+    kind: 'missing-column',
+    table,
+    column: column.name,
+    cause: `table "${table}" is missing column "${column.name}" that migrations declare`,
+    fix: statementOr(
+      schema,
+      [table, column.name],
+      'add the column this difference names back, as the migration that declares it does',
+      () => `alter table ${identifier(table).text} add column ${columnClause(column, strict)};`,
+      strict || column.nullable ? RE_CHECK : LATER_NOT_NULL,
+    ),
+  };
+}
+
+/**
+ * The table and its primary key only. An index, a foreign key, a check or a trigger has a finding
+ * of its own with its own repair, which the re-check reports next — one statement per fact, so a
+ * key to a table that is also missing is never part of the statement that would fail on it.
+ */
+export function missingTable(
+  schema: string,
+  table: string,
+  columns: readonly ColumnDescription[],
+  primaryKey: readonly string[],
+): DriftDifference {
+  const create = (): string => {
+    const clauses = [...columns]
+      .sort((a, b) => a.position - b.position)
+      .map((column) => columnClause(column, !column.nullable));
+    if (primaryKey.length > 0) {
+      clauses.push(`primary key (${primaryKey.map((name) => identifier(name).text).join(', ')})`);
+    }
+    return `create table ${identifier(table).text} (${clauses.join(', ')});`;
+  };
+  return {
+    kind: 'missing-table',
+    table,
+    column: null,
+    cause: `table "${table}" is declared by migrations but does not exist`,
+    fix: statementOr(
+      schema,
+      [table, ...columns.map((column) => column.name), ...primaryKey],
+      'create the table this difference names, as the migration that declares it does',
+      create,
+      `${RE_CHECK} and names its indexes, keys, checks and triggers next`,
+    ),
+  };
+}
+
+const indexNames = (table: string, index: IndexDescription): readonly string[] => [
+  table,
+  index.name,
+  ...index.columns,
+];
+
+export function missingIndex(
+  schema: string,
+  table: string,
+  index: IndexDescription,
+): DriftDifference {
+  return {
+    kind: 'missing-index',
+    table,
+    column: null,
+    cause: `table "${table}" is missing index "${index.name}" that migrations declare`,
+    fix: statementOr(
+      schema,
+      indexNames(table, index),
+      'create the index this difference names, as the migration that declares it does',
+      () => createIndex(table, asDeclared(index)),
+    ),
+  };
+}
+
+/**
+ * Postgres has no `alter index` for any part drift compares, so the repair is a drop and the
+ * declared build, in one transaction. A live index a UNIQUE constraint may own refuses `drop index`
+ * (2BP01), so its constraint goes first — `if exists`, because it may be a plain index after all.
+ */
+export function changedIndex(
+  schema: string,
+  table: string,
+  declared: IndexDescription,
+  held: IndexDescription,
+  detail: string,
+): DriftDifference {
+  const rebuild = (): string => {
+    const name = identifier(declared.name).text;
+    const owner = mayBeConstraintBacked(held)
+      ? `alter table ${identifier(table).text} drop constraint if exists ${name}; `
+      : '';
+    return `${owner}drop index if exists ${name}; ${createIndex(table, asDeclared(declared))}`;
+  };
+  return {
+    kind: 'changed-index',
+    table,
+    column: null,
+    cause: `index "${declared.name}" on "${table}" ${detail}, not what migrations declare`,
+    fix: statementOr(
+      schema,
+      indexNames(table, declared),
+      'drop the index this difference names and create it as the migration that declares it does',
+      rebuild,
+    ),
+  };
+}
+
+export function missingForeignKey(
+  schema: string,
+  table: string,
+  key: ForeignKeyDescription,
+): DriftDifference {
+  return {
+    kind: 'missing-foreign-key',
+    table,
+    column: null,
+    cause:
+      `table "${table}" has no foreign key on (${key.columns.join(', ')}) to ` +
+      `"${key.referencedTable}" (${key.referencedColumns.join(', ')}) that migrations declare`,
+    fix: statementOr(
+      schema,
+      [table, key.name, key.referencedTable, ...key.columns, ...key.referencedColumns],
+      'add the foreign key this difference names back, as the migration that declares it does',
+      () => addForeignKey(table, key),
+      'a row it finds is X_DB_FOREIGN_KEY_VIOLATION: repair that row, run it again, then x db migrate, which re-checks',
+    ),
+  };
+}

package/src/drift-row-security.ts

@@ -0,0 +1,88 @@
+// Single responsibility: `X_DB_ROW_SECURITY_DRIFT` — a tenant table and `database.rowSecurity`
+// disagreeing about its policy, read two ways. Against the migrations (no database: the gate's
+// `drift` step) and against the live catalog (`checkDrift`, after `x db migrate`).
+
+import type { DriftDifference } from './drift-findings';
+import type { EntityDescriptionLike } from './entity-shape';
+import { DbError } from './errors';
+import { type RowSecurityOption, rowSecurityInput } from './generate-row-security';
+import type { SchemaDescription, TableDescription } from './introspect';
+import { ROW_SECURITY_POLICY } from './row-security';
+import { rowSecurityAfter } from './row-security-plan';
+import { shellInertIdentifier } from './sql';
+
+export const ROW_SECURITY_DRIFT_CODE = 'X_DB_ROW_SECURITY_DRIFT';
+
+/** `missing`: the flag wants a policy nothing put there. `stray`: one is there the flag does not want. */
+export interface RowSecurityDifference {
+  readonly table: string;
+  readonly direction: 'missing' | 'stray';
+}
+
+/**
+ * The flag and the tenant columns against what the newest snapshot recorded — the same input
+ * `x db gen` plans from, so the gate never expects a policy the generator would not write.
+ */
+export function rowSecurityDifferences(
+  entities: readonly EntityDescriptionLike[],
+  recorded: SchemaDescription,
+  option: RowSecurityOption,
+): readonly RowSecurityDifference[] {
+  const input = rowSecurityInput(entities, recorded, option);
+  const wanted = rowSecurityAfter(input);
+  return [
+    ...[...wanted]
+      .filter((table) => !input.recorded.has(table))
+      .map((table) => ({ table, direction: 'missing' as const })),
+    ...[...input.recorded]
+      .filter((table) => !wanted.has(table))
+      .map((table) => ({ table, direction: 'stray' as const })),
+  ].sort((a, b) => (a.table < b.table ? -1 : 1));
+}
+
+/** The migrations' reading as an error. The repair is the generation the flag is waiting on. */
+export const rowSecurityDrift = (difference: RowSecurityDifference): DbError =>
+  new DbError({
+    code: ROW_SECURITY_DRIFT_CODE,
+    cause:
+      difference.direction === 'missing'
+        ? `database.rowSecurity is on and no migration gave tenant table "${difference.table}" its policy: a raw sql read of it still sees every tenant's rows`
+        : `database.rowSecurity is off and a migration left tenant table "${difference.table}" its policy: every read without a tenant set sees no rows`,
+    fix: 'x db gen "row security"',
+    meta: { table: difference.table, direction: difference.direction },
+  });
+
+/** Where the statements are, as a command that prints them: the ledger already holds the migration. */
+const statementsOf = (table: string): string => {
+  const name = shellInertIdentifier(table);
+  const pattern = name === null ? ROW_SECURITY_POLICY : `on ${name}`;
+  return `grep -n '${pattern}' packages/db/migrations/*.sql`;
+};
+
+/**
+ * The catalog's reading, judged only where both halves were asked (`compareAppendOnly`'s rule):
+ * a snapshot that predates the field, or a description nobody introspected, says nothing.
+ * `policyNames` holds only an enabled AND forced table's policies, so a disabled or unforced
+ * table reads as missing — an owner or nobody would be bound by it.
+ */
+export function compareRowSecurity(
+  live: TableDescription,
+  expected: TableDescription,
+): DriftDifference[] {
+  if (live.policyNames === undefined) return [];
+  const present = live.policyNames.includes(ROW_SECURITY_POLICY);
+  const wanted = expected.rowSecurity === true;
+  if (present === wanted) return [];
+  const table = live.name;
+  return [
+    {
+      kind: wanted ? 'missing-row-security' : 'unexpected-row-security',
+      table,
+      column: null,
+      cause: wanted
+        ? `table "${table}" should carry the forced tenant policy ${ROW_SECURITY_POLICY} and does not, or its row security is disabled or not forced: raw sql sees every tenant's rows`
+        : `table "${table}" carries the tenant policy ${ROW_SECURITY_POLICY} no migration recorded`,
+      fix: `${statementsOf(table)}   # run the row-security statements it prints against this database with psql "$DATABASE_URL", then x db migrate, which re-checks`,
+    },
+  ];
+}

package/src/drift-triggers.ts

@@ -0,0 +1,54 @@
+// Single responsibility: whether the lifecycle triggers a migration installed — history, its guard,
+// counters — are still enabled on the table, and whether a `retain` table became partitioned. The
+// repository never sees either, so only the catalog can say. `drift-append-only.ts` is the model.
+
+import { byHand, type DriftDifference, pathTo, repair } from './drift-findings';
+import type { TableDescription, TriggerRecord } from './introspect';
+import { shellInertIdentifier } from './sql';
+
+/** The codes `driftError` raises for these kinds, exported so the tests assert the one literal. */
+export const LIFECYCLE_DRIFT_CODE = 'X_LIFECYCLE_TRIGGER_MISSING';
+export const RETAIN_DRIFT_CODE = 'X_ENTITY_RETAIN_INVALID';
+
+/** The fix is the statements `x db gen` wrote, against THIS database: the ledger already holds them. */
+function missingTrigger(live: TableDescription, trigger: TriggerRecord): DriftDifference {
+  const path = pathTo(live.schema);
+  return {
+    kind: 'missing-lifecycle-trigger',
+    table: live.name,
+    column: null,
+    cause:
+      `table "${live.name}" was given trigger ${trigger.name} by a migration, and it is missing or ` +
+      'disabled — writes here no longer record history or keep a counter',
+    fix:
+      path === null || shellInertIdentifier(live.name) === null
+        ? byHand(`re-create trigger ${trigger.name} as the newest migration that names it does`)
+        : repair(path, trigger.install.join(' ')),
+  };
+}
+
+function partitionedRetain(live: TableDescription): DriftDifference {
+  return {
+    kind: 'retain-partitioned',
+    table: live.name,
+    column: null,
+    cause:
+      `table "${live.name}" declares retain and the catalog holds it partitioned: a partitioned ` +
+      "table's retention is detaching its old partitions, never a row-by-row sweep",
+    fix: `x db gen "drop retain"   # after removing retain from the entity on ${live.name}; detach old partitions in a task`,
+  };
+}
+
+/** Judged only where both halves were asked, exactly as `compareAppendOnly` reads its pair. */
+export function compareTriggers(
+  live: TableDescription,
+  expected: TableDescription,
+): DriftDifference[] {
+  const out: DriftDifference[] = [];
+  if (expected.retain === true && live.partitioned === true) out.push(partitionedRetain(live));
+  if (live.triggerNames === undefined) return out;
+  for (const trigger of expected.triggers ?? []) {
+    if (!live.triggerNames.includes(trigger.name)) out.push(missingTrigger(live, trigger));
+  }
+  return out;
+}