@ultimat3/db 12.0.0 → 14.0.0

package/src/foreign-key-plan.ts

@@ -5,6 +5,7 @@
 import type { EntityDescriptionLike } from './entity-shape';
 import { addForeignKey, dropForeignKey, foreignKeyTarget, onDeleteRule } from './foreign-key';
 import type { ForeignKeyDescription, TableDescription } from './introspect';
+import { identifier } from './sql';
 
 /** The two directions of one migration, pushed in `up` order; `down` is reversed at assembly. */
 export interface Plan {
@@ -137,10 +138,17 @@ export interface ConstraintPlans {
   readonly doomed: ReadonlySet<string>;
 }
 
-/** A key whose target is being dropped: gone on the way up, a note on the way back. */
+/**
+ * A key whose target is being dropped: gone on the way up, a note on the way back.
+ *
+ * The note goes through `identifier` too. A `--` comment ends at the first newline, so a name
+ * holding one is a second command on the line after it — the same escape `columnClause` closed,
+ * one quoting rule short of the statement above it.
+ */
 function unrestorableDrop(table: string, constraint: string, target: string, preDrops: Plan): void {
   preDrops.up.push(dropForeignKey(table, constraint));
   preDrops.down.push(
-    `-- constraint "${constraint}" on "${table}" cannot be restored; "${target}" is gone`,
+    `-- constraint ${identifier(constraint).text} on ${identifier(table).text} ` +
+      `cannot be restored; ${identifier(target).text} is gone`,
   );
 }

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 {
@@ -13,6 +15,8 @@ import type {
 } from './entity-shape';
 import { migrationIrreversible } from './errors';
 import { type ConstraintPlans, foreignKeyPlan, foreignKeysOf, type Plan } from './foreign-key-plan';
+import type { Regeneration } from './generated-column';
+import { generatedClause, isGenerated, regenerate } from './generated-column';
 import { declaredMethod, indexMethodOf, indexMethodSql } from './index-method';
 import {
   type ColumnDescription,
@@ -21,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',
@@ -42,26 +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 {
-  const parts = [`"${column.column}"`, sqlType(column.kind)];
+  // 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.
+  //
+  // 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(' ');
 }
@@ -106,7 +114,11 @@ export function snapshotOf(entities: readonly EntityDescriptionLike[]): SchemaDe
           nullable: !column.notNull,
           default: defaultExpression(column),
           position: index + 1,
+          // Only when one was declared — absent stays absent, so no snapshot written before this
+          // 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,
@@ -115,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,
@@ -128,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 };
@@ -136,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));
   }
@@ -177,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};`
+  );
 }
 
 /**
@@ -197,14 +226,20 @@ function retypeColumn(
   column: ColumnDescriptionLike,
   recorded: ColumnDescription,
   plan: Plan,
-): void {
+): Regeneration {
   const wanted = sqlType(column.kind);
-  if (recorded.dataType === wanted) return;
+  // A generated column moves by its own rules — see `generated-column.ts`. Asked whenever EITHER
+  // side is one, because becoming generated and ceasing to be are both changes with a statement.
+  if (isGenerated(column) || recorded.generated !== undefined) {
+    return regenerate(table, column, wanted, recorded, plan);
+  }
+  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';
 }
 
 /** The parts of an index Postgres cannot alter in place — every one of them is a rebuild. */
@@ -236,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(
@@ -251,38 +286,52 @@ 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};`,
   );
 }
 
 function diffTable(entity: EntityDescriptionLike, live: TableDescription, plan: Plan): void {
   const existing = new Map(live.columns.map((column) => [column.name, column]));
   const added = new Set<string>();
+  // A column `regenerate` had to replace outright: `add column` implies no index, so every index
+  // over it has to be stated again even though its own definition never moved.
+  const rebuilt = new Set<string>();
   for (const column of entity.columns) {
     const recorded = existing.get(column.column);
     if (recorded !== undefined) {
-      retypeColumn(entity.table, column, recorded, plan);
+      if (retypeColumn(entity.table, column, recorded, plan) === 'rebuilt') {
+        rebuilt.add(column.column);
+      }
       continue;
     }
     added.add(column.column);
     // A NOT NULL add with no default cannot succeed on a populated table; emit it nullable and
     // leave the agent the exact follow-up rather than a migration that fails at 3am.
-    const nullable = column.notNull && defaultExpression(column) === null;
+    //
+    // A GENERATED column is the exception and not a special case of it: the database computes it
+    // for every existing row inside the same `add column`, so it lands NOT NULL and populated in
+    // one statement — measured. Emitting it nullable would leave a `-- backfill` comment naming a
+    // 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);
-    if (recorded !== undefined) {
+    // 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.
+    if (recorded !== undefined && !index.columns.some((column) => rebuilt.has(column))) {
       redefineIndex(entity.table, index, recorded, plan);
       continue;
     }
@@ -290,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 {
@@ -317,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 {
@@ -350,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);
@@ -363,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',
       );
     }
@@ -383,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,
@@ -401,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

@@ -0,0 +1,119 @@
+// Single responsibility: what a column the DATABASE computes contributes to DDL, and what changes
+// to one a migration may emit. Split from `generate.ts` because Postgres treats a generated column
+// as a different thing at every step — its clause, its retype, its NOT NULL add and the way its
+// expression moves are each a rule of their own, and none of them is the ordinary column's.
+
+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 ${identifier(table).text} alter column ${identifier(column).text}`;
+
+/**
+ * The `generated always as (…) stored` clause, or `''` for every ordinary column — so a description
+ * written before this field existed emits the statement it always emitted, byte for byte.
+ *
+ * The two rules Postgres has about the pair are refused HERE, where the entity is still named, for
+ * the reason `createIndex` refuses a unique GIN in the same file: an unguarded generator writes DDL
+ * whose first reader is `ROLE=migrate`, and the server's message carries none of the declaration's
+ * words. A column may not be both DEFAULTED and GENERATED (`42601` — a generated column's value IS
+ * its expression), and an empty expression is not one.
+ */
+export function generatedClause(column: ColumnDescriptionLike): string {
+  const expression = column.generated;
+  if (expression === undefined || expression === null) return '';
+  assert(
+    !column.hasDefault,
+    `column "${column.column}" is declared both generated and defaulted, and Postgres has neither`,
+    `drop the default from "${column.property}" — a generated column's value is its expression, computed on every write`,
+  );
+  assert(
+    expression.trim().length > 0,
+    `column "${column.column}" is generated by an empty expression`,
+    `give "${column.property}" an expression, or drop the generated declaration`,
+  );
+  return ` generated always as (${expression}) stored`;
+}
+
+export const isGenerated = (column: ColumnDescriptionLike): boolean =>
+  typeof column.generated === 'string';
+
+/**
+ * A generated column whose TYPE or whose EXPRESSION moved, brought into line without rebuilding it.
+ *
+ * `set expression as (…)` (Postgres 17) rewrites the table and recomputes every row, and the
+ * column's indexes survive — measured. Drop-and-recreate was the alternative and is worse in two
+ * ways that matter: dropping the column takes its indexes with it and nothing in this diff puts
+ * them back, and `alter table … drop column` is what `destructive.ts` reads as a data loss, so
+ * every expression change would have carried `-- destructive: true` on a migration that loses
+ * nothing. A marker on a migration that destroys nothing is a marker reviewers learn to ignore.
+ *
+ * The retype carries no `using`: Postgres refuses one on a generated column outright ("column … is
+ * a generated column"), which is exactly the statement `retypeColumn` emits for every other column
+ * — and there is nothing to convert, because the expression produces the new type itself.
+ *
+ * Two transitions this cannot express, and both are refused rather than half-emitted:
+ * plain → generated (there is no `set expression` for a column that has none) and a column whose
+ * recorded expression is unknown. `drop expression` is the one that HAS a statement, and it is the
+ * generated → plain direction, which keeps the values it computed.
+ */
+export function regenerate(
+  table: string,
+  column: ColumnDescriptionLike,
+  wantedType: string,
+  recorded: ColumnDescription,
+  plan: Plan,
+): Regeneration {
+  const wanted = column.generated ?? null;
+  const held = recorded.generated ?? null;
+  if (wanted === null && held === null) return 'unchanged';
+  // Generated -> plain: the column keeps every value it computed and simply stops being derived.
+  if (wanted === null) {
+    plan.up.push(`${alterColumn(table, column.column)} drop expression;`);
+    plan.down.push(`${alterColumn(table, column.column)} set expression as (${held ?? ''});`);
+    return 'altered';
+  }
+  // Plain -> generated: `set expression` needs a column that already has one, so this is the whole
+  // 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(
+      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 ${identifier(table).text} add column ${identifier(column.column).text} ` +
+        `${recorded.dataType};` +
+        ' -- was not a generated column',
+      dropColumn,
+    );
+    return 'rebuilt';
+  }
+  let moved = false;
+  if (recorded.dataType !== wantedType) {
+    plan.up.push(`${alterColumn(table, column.column)} type ${wantedType};`);
+    plan.down.push(`${alterColumn(table, column.column)} type ${recorded.dataType};`);
+    moved = true;
+  }
+  if (held !== wanted) {
+    plan.up.push(`${alterColumn(table, column.column)} set expression as (${wanted});`);
+    plan.down.push(`${alterColumn(table, column.column)} set expression as (${held});`);
+    moved = true;
+  }
+  return moved ? 'altered' : 'unchanged';
+}

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';