@ultimat3/db 13.0.0 → 14.0.0

package/src/foreign-key.ts

@@ -4,6 +4,7 @@
 
 import { assert } from '@ultimat3/core';
 import type { ForeignKeyDescription } from './introspect';
+import { identifier } from './sql';
 
 /**
  * `pg_constraint.confdeltype`. The catalog's vocabulary; a description holds the rule's name.
@@ -51,7 +52,16 @@ export function foreignKeyTarget(key: ForeignKeyDescription): string {
   return JSON.stringify([[...key.columns], key.referencedTable, [...key.referencedColumns]]);
 }
 
-const quoted = (names: readonly string[]): string => names.map((name) => `"${name}"`).join(', ');
+/**
+ * Through `identifier`, never `"${…}"` — the package's one rule, which every name this file writes
+ * now goes through. A name that closes its own quote produced a real `drop table` through
+ * `generateMigration` once already, out of `columnClause`, and every name below arrives the same
+ * way: from a projection this package cannot typecheck, or from a `.snapshot.json` on disk that
+ * anything may edit. Being unreachable with a hostile name today is a property of the CALLERS, not
+ * of this file, and it survives exactly until the next refactor.
+ */
+const quoted = (names: readonly string[]): string =>
+  names.map((name) => identifier(name).text).join(', ');
 
 /**
  * A statement of its own, never a clause inside `create table`. Inline, the constraint is created
@@ -76,14 +86,48 @@ export function addForeignKey(table: string, key: ForeignKeyDescription): string
     `references(() => target.id, { onDelete: 'cascade' })   # cascade | restrict | set null`,
   );
   return (
-    `alter table "${table}" add constraint "${key.name}" ` +
+    `alter table ${identifier(table).text} add constraint ${identifier(key.name).text} ` +
     `foreign key (${quoted(key.columns)}) ` +
-    `references "${key.referencedTable}" (${quoted(key.referencedColumns)})` +
+    `references ${identifier(key.referencedTable).text} (${quoted(key.referencedColumns)})` +
     `${rule === null ? '' : ` on delete ${rule}`};`
   );
 }
 
 /** The reverse. Dropping a constraint loses nothing the database cannot rebuild. */
 export function dropForeignKey(table: string, constraint: string): string {
-  return `alter table "${table}" drop constraint "${constraint}";`;
+  return `alter table ${identifier(table).text} drop constraint ${identifier(constraint).text};`;
+}
+
+/**
+ * The drop/add pair that moves a key's `on delete` rule — a rebuild, because Postgres has no
+ * `alter constraint` for it — for a `fix:` line an author pastes into a new migration.
+ *
+ * It lives here, beside the two writers, because it is the one caller reading values neither of
+ * them may assume: `held` is the **live catalog's** and `declared` is a `.snapshot.json`'s. Both
+ * writers refuse rather than guess — `identifier()` on a name holding a quote, a space or a
+ * backslash (all three legal inside a quoted Postgres name), and `addForeignKey` on an `on delete`
+ * rule Postgres does not have. That is exactly right for DDL this package SENDS and wrong for a
+ * `fix:` line: `diffSchema` is documented pure and total, so a pair it cannot write is a sentence,
+ * never a throw — a drift check that raises in place of its report hands the caller an exception
+ * where a verdict was asked for. The constraint is still named, because it is the only thing
+ * identifying which one, quoted by `JSON.stringify`, which escapes rather than refuses; nothing
+ * runs this string either way.
+ */
+export function rebuildForeignKey(
+  table: string,
+  declared: ForeignKeyDescription,
+  held: ForeignKeyDescription,
+): string {
+  // The writers are ASKED whether they can write the pair — never a second copy of their rules
+  // beside them, which is the copy that drifts. A refusal is the answer, and nothing here reads
+  // the thrown value.
+  try {
+    return `${dropForeignKey(table, held.name)} ${addForeignKey(table, declared)}`;
+  } catch {
+    return (
+      `drop constraint ${JSON.stringify(held.name)} on table ${JSON.stringify(table)} and add ` +
+      'it back with the on delete rule the migrations declare — by hand: x db gen cannot ' +
+      'write this pair'
+    );
+  }
 }

package/src/generate.ts

@@ -4,6 +4,8 @@
 // field. Every generated migration must be reversible; a drop that loses data refuses instead.
 
 import { assert, systemClock } from '@ultimat3/core';
+import { checkClauses, checkPlan, declaredChecks } from './check-ddl';
+import { defaultExpression } from './column-default';
 import { isDestructive } from './destructive';
 import { dropOrder } from './drop-order';
 import type {
@@ -23,6 +25,9 @@ import {
   type SchemaDescription,
   type TableDescription,
 } from './introspect';
+import { declaredIndexes } from './invariant-ddl';
+import { identifier } from './sql';
+import { type UnrenderedDeclaration, unrenderedComment, unrenderedOf } from './unrendered';
 
 const SQL_TYPES: Readonly<Record<string, string>> = {
   uuid: 'uuid',
@@ -44,29 +49,27 @@ function sqlType(kind: string): string {
   return SQL_TYPES[kind] ?? kind;
 }
 
-/**
- * Entity descriptions carry `hasDefault` but not the expression, so the two generated defaults
- * are inferred from the blessed column helpers. Anything else is left to a follow-up migration.
- */
-function defaultExpression(column: ColumnDescriptionLike): string | null {
-  if (!column.hasDefault) return null;
-  if (column.kind === 'uuid' && column.primaryKey) return 'gen_random_uuid()';
-  if (column.kind === 'timestamptz') return 'now()';
-  return null;
-}
-
 function columnClause(column: ColumnDescriptionLike): string {
   // The generation clause sits directly after the type, and `generatedClause` refuses the pairs
   // Postgres has no column for. Every other part below is unchanged and unreachable for a
   // generated column: it may carry no default, and `hasDefault` is what the refusal reads.
-  const parts = [`"${column.column}"`, `${sqlType(column.kind)}${generatedClause(column)}`];
+  //
+  // Through `identifier`, never `"${…}"`: the name arrives from a projection this package cannot
+  // typecheck and a name that closes its own quote produced a real `drop table` through
+  // `generateMigration` once already. It is also what makes an unrendered report safe to write
+  // into a `--` comment, since generation refuses the dangerous name before the comment exists.
+  const parts = [
+    identifier(column.column).text,
+    `${sqlType(column.kind)}${generatedClause(column)}`,
+  ];
   const expression = defaultExpression(column);
   if (expression !== null) parts.push(`default ${expression}`);
   if (column.notNull) parts.push('not null');
   if (column.unique && !column.primaryKey) parts.push('unique');
-  if (column.check !== null) parts.push(`check (${column.check})`);
-  // No `references` clause. A foreign key is `alter table … add constraint`, emitted after every
-  // table exists (`foreignKeyPlan`) — inline it must point at a table that already exists, and
+  // No `check` clause — written here it was ANONYMOUS and reached `create table` alone, so
+  // regenerating dropped the value set `enumerated()` declares; `check-ddl.ts` owns every CHECK now.
+  // No `references` clause either: a foreign key is `alter table … add constraint`, emitted after
+  // every table exists (`foreignKeyPlan`) — inline it must point at a table that already exists, and
   // entity registration order is the app's import order, which says nothing about that.
   return parts.join(' ');
 }
@@ -115,6 +118,7 @@ export function snapshotOf(entities: readonly EntityDescriptionLike[]): SchemaDe
           // field existed gains a key and no app's sidecar regenerates over a fact already true.
           ...(column.generated === undefined ? {} : { generated: column.generated }),
         }));
+      const checks = declaredChecks(entity);
       return {
         schema: 'public',
         name: entity.table,
@@ -123,7 +127,10 @@ export function snapshotOf(entities: readonly EntityDescriptionLike[]): SchemaDe
         // Whole, never partly: a snapshot that recorded the name and dropped the predicate made
         // the next generation blind to a `where` or an `order` changing, and a partial index
         // silently kept as a total one is a constraint the entity no longer declares.
-        indexes: entity.indexes.map((index) => ({
+        //
+        // `declaredIndexes`, so a `unique` invariant's index is recorded exactly like an entity's
+        // own — a statement emitted and not recorded is `42P07` on the very next `x db gen`.
+        indexes: declaredIndexes(entity).map((index) => ({
           name: index.name,
           columns: [...index.columns],
           unique: index.unique,
@@ -136,6 +143,10 @@ export function snapshotOf(entities: readonly EntityDescriptionLike[]): SchemaDe
           ...(index.using === undefined ? {} : { using: index.using }),
         })),
         foreignKeys: foreignKeysOf(entity),
+        // Absent, never `[]`, on a table declaring none: a sidecar that predates this field must
+        // read as "nothing recorded" so the next generation adds the constraints the database is
+        // genuinely missing — the rule `using` and `generated` already state one field up.
+        ...(checks.length === 0 ? {} : { checks }),
       };
     });
   return { tables };
@@ -144,12 +155,17 @@ export function snapshotOf(entities: readonly EntityDescriptionLike[]): SchemaDe
 function createTable(entity: EntityDescriptionLike): readonly string[] {
   const clauses = entity.columns.map(columnClause);
   if (entity.primaryKey.length > 0) {
-    clauses.push(`primary key (${entity.primaryKey.map((key) => `"${key}"`).join(', ')})`);
+    const key = entity.primaryKey.map((column) => identifier(column).text).join(', ');
+    clauses.push(`primary key (${key})`);
   }
-  const statements = [`create table "${entity.table}" (\n  ${clauses.join(',\n  ')}\n);`];
+  // After the key, so a table declaring no invariant emits the statement it always emitted.
+  clauses.push(...checkClauses(entity));
+  const statements = [
+    `create table ${identifier(entity.table).text} (\n  ${clauses.join(',\n  ')}\n);`,
+  ];
   // Every column of a new table carries its own clause, so every `unique` one brings its index.
   const added = new Set(entity.columns.map((column) => column.column));
-  for (const index of entity.indexes) {
+  for (const index of declaredIndexes(entity)) {
     if (impliedByColumnClause(entity, index, added)) continue;
     statements.push(createIndex(entity.table, index));
   }
@@ -185,12 +201,17 @@ function createIndex(table: string, index: IndexDescriptionLike): string {
   );
   const kind = index.unique ? 'create unique index' : 'create index';
   const direction = index.order === null ? '' : ` ${index.order}`;
-  const columns = index.columns.map((column) => `"${column}"${direction}`).join(', ');
+  const columns = index.columns
+    .map((column) => `${identifier(column).text}${direction}`)
+    .join(', ');
   const predicate = index.where === null ? '' : ` where (${index.where})`;
   // Re-derived from the closed set, never spliced: `indexMethodSql` answers `''` for a btree, so
   // an index that declared no method emits the statement this generator always emitted, byte for
   // byte, and one that declared a method Postgres does not have is refused instead of built.
-  return `${kind} "${index.name}" on "${table}"${indexMethodSql(method)} (${columns})${predicate};`;
+  return (
+    `${kind} ${identifier(index.name).text} on ${identifier(table).text}` +
+    `${indexMethodSql(method)} (${columns})${predicate};`
+  );
 }
 
 /**
@@ -214,8 +235,8 @@ function retypeColumn(
   }
   if (recorded.dataType === wanted) return 'unchanged';
   const alter = (type: string): string =>
-    `alter table "${table}" alter column "${column.column}" type ${type} ` +
-    `using "${column.column}"::${type};`;
+    `alter table ${identifier(table).text} alter column ${identifier(column.column).text} ` +
+    `type ${type} using ${identifier(column.column).text}::${type};`;
   plan.up.push(alter(wanted));
   plan.down.push(alter(recorded.dataType));
   return 'altered';
@@ -250,7 +271,7 @@ function redefineIndex(
   plan: Plan,
 ): void {
   if (indexShape(index) === indexShape(recorded)) return;
-  plan.up.push(`drop index "${index.name}";`, createIndex(table, index));
+  plan.up.push(`drop index ${identifier(index.name).text};`, createIndex(table, index));
   // `down` is reversed at assembly, so the pair is pushed forwards and read backwards: recreating
   // the recorded definition is what must land last, after the new one is dropped.
   plan.down.push(
@@ -265,7 +286,7 @@ function redefineIndex(
       // rebuilt as a btree — a `down` that recreates the wrong structure is worse than none.
       ...(recorded.using === undefined ? {} : { using: declaredMethod(recorded.using) }),
     }),
-    `drop index "${index.name}";`,
+    `drop index ${identifier(index.name).text};`,
   );
 }
 
@@ -293,18 +314,20 @@ function diffTable(entity: EntityDescriptionLike, live: TableDescription, plan:
     // step nobody can perform, since a generated column cannot be written to.
     const nullable = column.notNull && !isGenerated(column) && defaultExpression(column) === null;
     const clause = nullable ? columnClause({ ...column, notNull: false }) : columnClause(column);
-    plan.up.push(`alter table "${entity.table}" add column ${clause};`);
+    plan.up.push(`alter table ${identifier(entity.table).text} add column ${clause};`);
     if (nullable) {
       plan.up.push(
-        `-- backfill "${column.column}", then: ` +
-          `alter table "${entity.table}" alter column "${column.column}" set not null;`,
+        `-- backfill ${identifier(column.column).text}, then: alter table ` +
+          `${identifier(entity.table).text} alter column ${identifier(column.column).text} set not null;`,
       );
     }
-    plan.down.push(`alter table "${entity.table}" drop column "${column.column}";`);
+    plan.down.push(
+      `alter table ${identifier(entity.table).text} drop column ${identifier(column.column).text};`,
+    );
   }
 
   const indexed = new Map(live.indexes.map((index) => [index.name, index]));
-  for (const index of entity.indexes) {
+  for (const index of declaredIndexes(entity)) {
     const recorded = indexed.get(index.name);
     // A rebuilt column took its indexes down with it, so this one is CREATED rather than compared:
     // `redefineIndex` sees a definition that never moved and would emit nothing at all.
@@ -316,8 +339,13 @@ function diffTable(entity: EntityDescriptionLike, live: TableDescription, plan:
     // migration emits, so it still needs a statement of its own.
     if (impliedByColumnClause(entity, index, added)) continue;
     plan.up.push(createIndex(entity.table, index));
-    plan.down.push(`drop index "${index.name}";`);
+    plan.down.push(`drop index ${identifier(index.name).text};`);
   }
+
+  // Last: a CHECK may read a column this migration just added, and `add constraint` on a column
+  // that does not exist yet is `42703`. `check-ddl.ts` owns which of them move; `rebuilt` because a
+  // column dropped and re-added lost its constraint while the snapshot still records it.
+  checkPlan(entity, live, plan, rebuilt);
 }
 
 export interface GenerateOptions {
@@ -343,6 +371,13 @@ export interface GeneratedMigration {
    * cannot be written unmarked and then refused by `x verify` for lacking the mark.
    */
   readonly destructive: boolean;
+  /**
+   * Every declaration this generator could not write down. Empty on a migration that carries the
+   * whole schema, which is what makes it readable as a verdict rather than as noise — and the same
+   * list `unrenderedComment` writes into the top of `up`, so a caller that would rather refuse
+   * (`x db gen`) and a reviewer reading the committed file are looking at one answer.
+   */
+  readonly unrendered: readonly UnrenderedDeclaration[];
 }
 
 export function migrationStamp(now: Date): string {
@@ -376,7 +411,7 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
     foreignKeyPlan(entity, live, plans);
     if (live === undefined) {
       plan.up.push(...createTable(entity));
-      plan.down.push(`drop table "${entity.table}";`);
+      plan.down.push(`drop table ${identifier(entity.table).text};`);
       continue;
     }
     diffTable(entity, live, plan);
@@ -389,9 +424,12 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
           `x db gen "${options.name}" --allow-destructive   # or keep the column and deprecate it`,
         );
       }
-      plan.up.push(`alter table "${entity.table}" drop column "${column.name}";`);
+      plan.up.push(
+        `alter table ${identifier(entity.table).text} drop column ${identifier(column.name).text};`,
+      );
       plan.down.push(
-        `alter table "${entity.table}" add column "${column.name}" ${column.dataType};` +
+        `alter table ${identifier(entity.table).text} add column ` +
+          `${identifier(column.name).text} ${column.dataType};` +
           ' -- data is not restored',
       );
     }
@@ -409,15 +447,33 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
   plan.up.push(...preDrops.up, ...order.constraints);
   plan.down.push(...preDrops.down, ...order.constraints.map(() => '-- constraint not restored'));
   for (const table of order.tables) {
-    plan.up.push(`drop table "${table.name}";`);
-    plan.down.push(`-- "${table.name}" cannot be restored; recover it from a backup`);
+    plan.up.push(`drop table ${identifier(table.name).text};`);
+    // `identifier` in a comment too: a `--` ends at the first newline, so a name holding one
+    // would put a second command on the next line of `down`.
+    plan.down.push(
+      `-- ${identifier(table.name).text} cannot be restored; recover it from a backup`,
+    );
   }
 
   plan.up.push(...constraints.up);
   plan.down.push(...constraints.down);
 
   const id = `${migrationStamp(options.now ?? systemClock.now())}_${slugify(options.name)}`;
-  const up = plan.up.join('\n');
+  // At the TOP of `up`, so what is MISSING is the first thing read — and a line comment, so it is
+  // noise to every reader that matters: `statementsOf` drops a chunk of comments alone,
+  // `stripSqlNoise` blanks it before `isDestructive` looks for a verb, and the server ignores it.
+  //
+  // Never onto an EMPTY diff. `@ultimat3/cli`'s `generateAppMigration` reads `up.trim().length` as
+  // "nothing changed" and re-records the hash sidecar instead of writing a file; a comment there
+  // would make every `x db gen` on an app with an unrendered default write a migration holding no
+  // statement — a ledger row, a checksum and a place in the apply order for nothing. The list is
+  // still on `GeneratedMigration.unrendered`, which is where a caller with no file reads it.
+  //
+  // `current`, not the entities alone: an `assert` whose CHECK a previous migration recorded is a
+  // loss only because THIS plan drops it, and the recorded schema is the only thing that knows.
+  const unrendered = unrenderedOf(options.entities, current);
+  const body = plan.up.join('\n');
+  const up = body.length === 0 ? body : unrenderedComment(unrendered) + body;
   return {
     id,
     name: options.name,
@@ -427,5 +483,6 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
     down: [...plan.down].reverse().join('\n'),
     snapshot: snapshotOf(options.entities),
     destructive: isDestructive(up),
+    unrendered,
   };
 }

package/src/generated-column.ts

@@ -7,12 +7,19 @@ import { assert } from '@ultimat3/core';
 import type { ColumnDescriptionLike } from './entity-shape';
 import type { Plan } from './foreign-key-plan';
 import type { ColumnDescription } from './introspect';
+import { identifier } from './sql';
 
 /** How a column that moved was brought back into line — what the caller has to do next, if anything. */
 export type Regeneration = 'unchanged' | 'altered' | 'rebuilt';
 
+/**
+ * Through `identifier`, never `"${…}"`, for the reason `columnClause` states — and this path is
+ * the one `columnClause` does NOT cover: `regenerate` is reached from `retypeColumn` for a column
+ * that ALREADY exists, so nothing on the way here has looked at the name. Both operands arrive
+ * from a projection this package cannot typecheck and from a `.snapshot.json` anything may edit.
+ */
 const alterColumn = (table: string, column: string): string =>
-  `alter table "${table}" alter column "${column}"`;
+  `alter table ${identifier(table).text} alter column ${identifier(column).text}`;
 
 /**
  * The `generated always as (…) stored` clause, or `''` for every ordinary column — so a description
@@ -82,16 +89,18 @@ export function regenerate(
   // column again. Reported as `rebuilt` so the caller can put the indexes back — an `add column`
   // implies none of them.
   if (held === null) {
+    const dropColumn = `alter table ${identifier(table).text} drop column ${identifier(column.column).text};`;
     plan.up.push(
-      `alter table "${table}" drop column "${column.column}";`,
-      `alter table "${table}" add column "${column.column}" ${wantedType}` +
-        `${generatedClause(column)}${column.notNull ? ' not null' : ''};`,
+      dropColumn,
+      `alter table ${identifier(table).text} add column ${identifier(column.column).text} ` +
+        `${wantedType}${generatedClause(column)}${column.notNull ? ' not null' : ''};`,
     );
     // Pushed forwards and read backwards — `down` is reversed at assembly.
     plan.down.push(
-      `alter table "${table}" add column "${column.column}" ${recorded.dataType};` +
+      `alter table ${identifier(table).text} add column ${identifier(column.column).text} ` +
+        `${recorded.dataType};` +
         ' -- was not a generated column',
-      `alter table "${table}" drop column "${column.column}";`,
+      dropColumn,
     );
     return 'rebuilt';
   }

package/src/index.ts

@@ -12,6 +12,14 @@ export {
   listBranches,
   reapBranches,
 } from './branch';
+export {
+  checkClauses,
+  checkPlan,
+  columnCheckName,
+  columnChecks,
+  columnNamesConstraint,
+  declaredChecks,
+} from './check-ddl';
 export type {
   DbClient,
   DbConnection,
@@ -32,6 +40,8 @@ export {
   poolProfileFor,
   setDbClient,
 } from './client';
+export type { ColumnDefaultLike } from './column-default';
+export { defaultExpression } from './column-default';
 export { defaultClient, REPLICA_URL_ENV } from './default-client';
 export type { DestructiveKind, DestructiveStatement } from './destructive';
 export {
@@ -56,6 +66,7 @@ export type {
   ColumnDescriptionLike,
   EntityDescriptionLike,
   IndexDescriptionLike,
+  InvariantDescriptionLike,
 } from './entity-shape';
 export type { DbErrorCode, DbErrorInit } from './errors';
 export {
@@ -96,6 +107,7 @@ export {
   isIndexMethod,
 } from './index-method';
 export type {
+  CheckDescription,
   ColumnDescription,
   ForeignKeyDescription,
   IndexDescription,
@@ -104,6 +116,13 @@ export type {
   TableDescription,
 } from './introspect';
 export { buildSchema, findTable, introspect } from './introspect';
+export {
+  constraintNameFor,
+  declaredIndexes,
+  invariantChecks,
+  uniqueColumns,
+} from './invariant-ddl';
+export { constraintExpressionUnsafe, constraintNameUnsafe } from './invariant-errors';
 export type {
   AppliedMigration,
   LedgerRow,
@@ -172,3 +191,7 @@ export { STATEMENT_ATTRIBUTE } from './statement-span';
 export { statementsOf } from './statement-split';
 export type { DbTx, IsolationLevel, TransactionOptions } from './transaction';
 export { beginStatement, currentTx, withTransaction } from './transaction';
+export type { GeneratableForm } from './ungeneratable';
+export { GENERATABLE_FORMS, ungeneratableStatements } from './ungeneratable';
+export type { UnrenderedDeclaration } from './unrendered';
+export { unrenderedComment, unrenderedOf } from './unrendered';

package/src/introspect.ts

@@ -57,6 +57,21 @@ export interface ForeignKeyDescription {
   readonly onDelete: string | null;
 }
 
+/**
+ * A named CHECK constraint, as the SNAPSHOT spells it — an entity invariant of kind `check`.
+ *
+ * Absent from every row this module reads out of the live catalog, deliberately and for the reason
+ * `ColumnDescription.generated` gives one field up: `pg_get_constraintdef` answers Postgres' own
+ * rewriting of the expression, so a catalog value could never compare equal to a generated one and
+ * drift would report a correct database forever. The diff that DOES read it is `x db gen`'s, where
+ * both sides are this generator's own spellings.
+ */
+export interface CheckDescription {
+  readonly name: string;
+  /** The predicate, exactly as the entity's invariant spells it. */
+  readonly expression: string;
+}
+
 export interface TableDescription {
   readonly schema: string;
   readonly name: string;
@@ -64,6 +79,14 @@ export interface TableDescription {
   readonly primaryKey: readonly string[];
   readonly indexes: readonly IndexDescription[];
   readonly foreignKeys: readonly ForeignKeyDescription[];
+  /**
+   * The CHECK constraints migrations declare. Absent — never `[]` — on a table that declares none
+   * and in every sidecar written before this field existed, matching `IndexDescription.using`: a
+   * snapshot that predates it must read as "nothing recorded" so the next `x db gen` emits the
+   * `add constraint` the database is genuinely missing, rather than as "recorded none", which
+   * would leave every already-generated app's invariants unenforced forever.
+   */
+  readonly checks?: readonly CheckDescription[] | undefined;
 }
 
 export interface SchemaDescription {