@ultimat3/db 13.0.0 → 15.0.0

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,32 @@ 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;
+  /**
+   * The catalog's half of `checks`, and a **separate field rather than the same one** — names
+   * only, `conname` for `contype = 'c'`, never a definition.
+   *
+   * The two readings cannot share `checks` because they are not the same value. A catalog read
+   * carries Postgres' own rewriting of the predicate and a declaration carries this generator's
+   * spelling, so a `checks` filled from `pg_constraint` would put a rewritten expression on the
+   * field `checkPlan` diffs against a generated one — every regenerated migration would then drop
+   * and re-add every constraint in the app, forever, because the two strings can never be equal.
+   * Splitting them means the type says which reading a value came from, and `checkPlan` cannot be
+   * handed a catalog value by accident.
+   *
+   * `snapshotOf` never writes it and `parseSnapshot` never reads it, so a sidecar carries `checks`
+   * alone. `introspect()` always answers with it, `[]` included: absent therefore means "nobody
+   * asked the catalog", which is what keeps `compareChecks` silent on a description that never
+   * read one instead of reporting every declared constraint as missing.
+   */
+  readonly checkNames?: readonly string[] | undefined;
 }
 
 export interface SchemaDescription {
@@ -112,6 +153,12 @@ interface ForeignKeyRow {
   readonly on_delete: string | null;
 }
 
+/** A CHECK constraint's NAME. There is deliberately no column for its definition — see `checkNames`. */
+interface CheckRow {
+  readonly table_name: string;
+  readonly constraint_name: string;
+}
+
 const byName = (a: { name: string }, b: { name: string }): number => (a.name < b.name ? -1 : 1);
 
 export async function introspect(options: IntrospectOptions = {}): Promise<SchemaDescription> {
@@ -183,7 +230,21 @@ export async function introspect(options: IntrospectOptions = {}): Promise<Schem
     order by src.relname, c.conname
   `);
 
-  return buildSchema(schema, excluded, columns, indexes, foreignKeys);
+  // `conname` and nothing else. `pg_get_constraintdef(c.oid)` is one word further along this line
+  // and is the reason this query did not exist: it answers Postgres' rewriting of the predicate,
+  // which no generated spelling can ever equal, so reading it would make every drift check report
+  // a correct database as wrong. `contype = 'c'` is the CHECK constraints alone — Postgres 17
+  // onwards records a NOT NULL as `'n'`, and a domain's as `'c'` on the domain rather than here.
+  const checks = await client.query<CheckRow>(sql`
+    select src.relname as table_name, c.conname as constraint_name
+    from pg_constraint c
+    join pg_class src on src.oid = c.conrelid
+    join pg_namespace n on n.oid = src.relnamespace
+    where c.contype = 'c' and n.nspname = ${schema} and src.relkind = 'r'
+    order by src.relname, c.conname
+  `);
+
+  return buildSchema(schema, excluded, columns, indexes, foreignKeys, checks);
 }
 
 /** Pure, so the row -> description mapping is testable without a database. */
@@ -193,6 +254,7 @@ export function buildSchema(
   columns: readonly ColumnRow[],
   indexes: readonly IndexRow[],
   foreignKeys: readonly ForeignKeyRow[],
+  checks: readonly CheckRow[] = [],
 ): SchemaDescription {
   const names = [...new Set(columns.map((row) => row.table_name))]
     .filter((name) => !excluded.includes(name))
@@ -238,6 +300,12 @@ export function buildSchema(
           onDelete: row.on_delete,
         }))
         .sort(byName),
+      // Always written, `[]` included: this reading of a table HAS asked the catalog, and absence
+      // is reserved for a description that has not (`compareChecks` is silent on that one).
+      checkNames: checks
+        .filter((row) => row.table_name === name)
+        .map((row) => row.constraint_name)
+        .sort(),
     };
   });
 

package/src/invariant-ddl.ts

@@ -0,0 +1,193 @@
+// Single responsibility: the DDL an entity's INVARIANTS become — what a rule is called, the index a
+// `unique` becomes, and the CHECK list a caller merges. `check-ddl.ts` owns the plan those checks
+// join, because a column declares one of its own and the two are one list on the server.
+//
+// A `check` becomes a named CONSTRAINT, inline on a created table and `alter table … add
+// constraint` on an existing one. A `unique` becomes a unique INDEX — never a UNIQUE constraint —
+// because a soft-deleting entity stamps `deleted_at is null` onto it and Postgres has no partial
+// unique constraint, only a partial unique index. An `assert` becomes nothing: it is declared as a
+// rule only the app can judge (`sql: null`), which is what `hasJsOnlyInvariant` reads it as.
+
+import { assert } from '@ultimat3/core';
+import type {
+  EntityDescriptionLike,
+  IndexDescriptionLike,
+  InvariantDescriptionLike,
+} from './entity-shape';
+import { indexMethodOf } from './index-method';
+import type { CheckDescription } from './introspect';
+import { constraintNameUnsafe } from './invariant-errors';
+import { identifier } from './sql';
+
+/**
+ * `NAMEDATALEN - 1`. Postgres truncates a longer identifier and says nothing, so two constraints
+ * sharing their first 63 bytes are ONE constraint on the server while both names still differ in
+ * the snapshot — invisible to a drift check comparing declared names. `@ultimat3/entity` bounds
+ * the index names it mints for the same reason; this bound is Postgres', not a convention, so
+ * stating it on both sides of the tier seam is one fact written twice rather than two rules.
+ *
+ * Exported so `check-ddl.ts` bounds a column's constraint name against the same number: two copies
+ * of NAMEDATALEN in one package is two rules that can drift, which is the thing it exists against.
+ */
+export const MAX_IDENTIFIER_BYTES = 63;
+
+/**
+ * The convention alone, with nothing validated and nothing refused. One copy, so `constraintNameFor`
+ * and `namesConstraint` can never disagree about what a rule's constraint is called — the two
+ * questions "what do I emit" and "is this recorded constraint that rule's" are the same string.
+ */
+function spellConstraintName(table: string, invariant: InvariantDescriptionLike): string {
+  return `${table}_${invariant.name}_${invariant.kind === 'unique' ? 'key' : 'check'}`;
+}
+
+/**
+ * Whether a CHECK a migration RECORDED is this rule's own enforcement in the database. Two
+ * spellings, because two writers name it: this generator's `<table>_<name>_check`, and a
+ * hand-written migration that used the rule's own name — which is what `examples/dummy`'s
+ * `0001_init.sql` did for every one of its app-judged rules.
+ *
+ * Never throws, unlike `constraintNameFor`: its caller is a REPORTER (`unrendered.ts`), reached by
+ * `x verify`'s drift step, where a throw replaces a finding with a crash. The RECORDED name is
+ * required to be an identifier and the invariant's is not, because only the recorded one is written
+ * back out — into a `--` comment and into a `fix:` — and a sidecar is a hand-editable file.
+ */
+export function namesConstraint(
+  table: string,
+  invariant: InvariantDescriptionLike,
+  recorded: string,
+): boolean {
+  if (!isIdentifier(recorded)) return false;
+  return recorded === invariant.name || recorded === spellConstraintName(table, invariant);
+}
+
+/**
+ * The constraint an invariant becomes: `<table>_<name>_check` / `<table>_<name>_key`.
+ *
+ * The same string `@ultimat3/entity`'s `constraintName` builds, and it has to be re-derived here
+ * rather than read off the description because the projection carries the rule's own name and not
+ * the constraint's. Both spellings are pinned — entity's by `invariants.test.ts`, this one by
+ * `generate-invariant.test.ts` — and a divergence would show up as a constraint this generator
+ * adds twice under two names.
+ */
+export function constraintNameFor(table: string, invariant: InvariantDescriptionLike): string {
+  const name = spellConstraintName(table, invariant);
+  // Through the package's one identifier rule, never a second regex: an invariant name is
+  // validated by nobody at declaration, so this is where a name that closes the quote is stopped.
+  if (!isIdentifier(invariant.name) || !isIdentifier(table)) {
+    throw constraintNameUnsafe(table, invariant.name);
+  }
+  // Bytes and not characters: 63 is what the server counts, and `.length` stops seeing the
+  // truncation the moment a name is not ASCII.
+  const bytes = new TextEncoder().encode(name).length;
+  assert(
+    bytes <= MAX_IDENTIFIER_BYTES,
+    `constraint name "${name}" is ${bytes} bytes; Postgres truncates at ${MAX_IDENTIFIER_BYTES} and says nothing`,
+    `invariant('${invariant.name.slice(0, 20)}…', …)   # shorten the invariant name, then x db gen`,
+  );
+  return name;
+}
+
+/** Whether `identifier()` would accept this name — the package's one rule, asked rather than run. */
+export function isIdentifier(value: string): boolean {
+  try {
+    identifier(value);
+    return true;
+  } catch {
+    // `identifier` throws `X_SQL_UNSAFE` for exactly one reason and the caller re-throws its own,
+    // naming the invariant rather than the raw name — so nothing is swallowed here.
+    return false;
+  }
+}
+
+/**
+ * The physical columns a `unique` invariant names. `columns` when the description carries it;
+ * otherwise the `sql` field, which for a `unique` IS the comma-joined column list.
+ *
+ * The fallback is a re-read, not a name parsed back out of a convention: every part is validated
+ * as an identifier and a part that is not one is REFUSED, so the failure mode `parseIndexName` had
+ * — `posts_org_id_created_at_idx` silently becoming the column `"org_id_created_at"` — cannot
+ * happen, because a physical column name cannot contain a comma. It exists so this package can
+ * emit the constraint before `@ultimat3/entity` (tier 2, which this one may not import) projects
+ * `Invariant.columns`; the field it already holds is what makes the fallback deletable later.
+ */
+export function uniqueColumns(
+  table: string,
+  invariant: InvariantDescriptionLike,
+): readonly string[] {
+  const declared = invariant.columns ?? (invariant.sql ?? '').split(',').map((part) => part.trim());
+  assert(
+    declared.length > 0 && declared.every((column) => column.length > 0),
+    `unique invariant "${invariant.name}" on "${table}" names no columns`,
+    `invariant('${invariant.name}', c.unique(['<column>']))   # name the columns, then x db gen`,
+  );
+  for (const column of declared) {
+    if (!isIdentifier(column)) throw constraintNameUnsafe(table, column);
+  }
+  return declared;
+}
+
+/** A `unique` invariant as the index it is — so one list of indexes is created, diffed and recorded. */
+function uniqueIndexOf(
+  entity: EntityDescriptionLike,
+  invariant: InvariantDescriptionLike,
+): IndexDescriptionLike {
+  return {
+    name: constraintNameFor(entity.table, invariant),
+    columns: uniqueColumns(entity.table, invariant),
+    unique: true,
+    where: invariant.where,
+    order: null,
+  };
+}
+
+/** Every part of an index Postgres fixes at creation — the dedup key, and `redefineIndex`'s. */
+const shapeOf = (index: IndexDescriptionLike): string =>
+  JSON.stringify([
+    [...index.columns],
+    index.unique,
+    index.where,
+    index.order,
+    indexMethodOf(index),
+  ]);
+
+/**
+ * The indexes this entity declares: its own, plus one per `unique` invariant. ONE list, because
+ * `createTable`, `diffTable` and `snapshotOf` must agree about what exists — a unique index emitted
+ * but not recorded is `42P07` on the next `x db gen`, which is a worse failure than the silent drop
+ * this whole change is against.
+ *
+ * Deduped on the whole definition and never on the name, the rule `@ultimat3/entity` already
+ * applies. The case that bites: `invariant('slug', c.unique(['slug']))` on `members` derives
+ * `members_slug_key`, byte for byte what Postgres calls the index a `unique` column clause creates
+ * — so an entity declaring both pushes two `create unique index` statements under one name, which
+ * is `42P07` and a migration that cannot be applied at all. The entity's own index wins, because
+ * `impliedByColumnClause` is written against that name.
+ */
+export function declaredIndexes(entity: EntityDescriptionLike): readonly IndexDescriptionLike[] {
+  const invariants = entity.invariants ?? [];
+  if (invariants.length === 0) return entity.indexes;
+  const seen = new Set(entity.indexes.map(shapeOf));
+  const extra: IndexDescriptionLike[] = [];
+  for (const invariant of invariants) {
+    if (invariant.kind !== 'unique') continue;
+    const index = uniqueIndexOf(entity, invariant);
+    if (seen.has(shapeOf(index))) continue;
+    seen.add(shapeOf(index));
+    extra.push(index);
+  }
+  return [...entity.indexes, ...extra];
+}
+
+/**
+ * The CHECK constraints this entity's INVARIANTS declare, in declaration order. The predicate is
+ * handed on unvalidated: `check-ddl.ts` refuses a second command over the MERGED list, so one rule
+ * covers a rule's expression and a column's alike rather than one guard per producer.
+ */
+export function invariantChecks(entity: EntityDescriptionLike): readonly CheckDescription[] {
+  return (entity.invariants ?? [])
+    .filter((invariant) => invariant.kind === 'check' && invariant.sql !== null)
+    .map((invariant) => ({
+      name: constraintNameFor(entity.table, invariant),
+      expression: invariant.sql ?? '',
+    }));
+}

package/src/invariant-errors.ts

@@ -0,0 +1,47 @@
+// Single responsibility: the two refusals an entity INVARIANT earns before its DDL exists — a name
+// that cannot be an identifier, and a predicate holding a second command. Split out of `errors.ts`
+// only because that file reached the 500-line ceiling; both carry `X_SQL_UNSAFE`, which
+// `DB_OWNED_ERROR_CODES` there still declares and registers. No new code, and none is needed: an
+// invariant name reaching a statement text is the same hazard a branch name or an isolation level
+// is, and axiom 1 says one situation gets one code.
+
+import { describeValue } from '@ultimat3/core';
+import { DbError } from './errors';
+
+/**
+ * A name an invariant contributes to a statement — its own, or a column its `unique` list names —
+ * that cannot be an identifier. `X_SQL_UNSAFE` for the reason `branchNameInvalid` uses it:
+ * `create table` and `add constraint` take no parameters, so the name is SPLICED into the
+ * statement text, and NOTHING validates an invariant name at declaration, so
+ * `invariant('x" ); drop table t; --', …)` type-checks all the way to the generator. The identical
+ * hole `columnName` carried when it was `meta.name ?? snake(property)` with only the first branch
+ * checked, measured through `generateMigration` as a real `drop table`.
+ *
+ * Its own factory rather than `identifierUnsafe`, and that is the whole of its value — `identifier`
+ * refuses the same string one call later, at every site that emits it. What only this one carries
+ * is the REPAIR: `identifierUnsafe` says "pass a plain table/column name" to a caller holding a
+ * name, and an author holding a schema module needs the `invariant()` call named instead. Pinned
+ * on the `fix:` line, because a guard whose only value is its message is proven by nothing else.
+ */
+export const constraintNameUnsafe = (table: string, received: unknown): DbError =>
+  new DbError({
+    code: 'X_SQL_UNSAFE',
+    cause: `an invariant on "${table}" contributes ${describeValue(received)} to a statement, which cannot be a Postgres identifier`,
+    fix: "invariant('post_slug_unique', c.unique(['slug']))   # every name is [A-Za-z_][A-Za-z0-9_$]*, then x db gen",
+    meta: { table },
+  });
+
+/**
+ * A constraint predicate holding more than one command. Read through `statementsOf` — this
+ * package's one lexer, so a `;` inside a string literal is data and not a second statement — and
+ * refused before it is spliced into `check (…)`. The predicate arrives from `Expr.toSql()` at tier
+ * 2 or from a hand-built description, and an operand TypeScript never saw closing the parenthesis
+ * is an injection rather than a typo, which is what `X_SQL_UNSAFE` is for.
+ */
+export const constraintExpressionUnsafe = (constraint: string, count: number): DbError =>
+  new DbError({
+    code: 'X_SQL_UNSAFE',
+    cause: `the predicate of constraint "${constraint}" holds ${count} commands; a CHECK is one expression`,
+    fix: `invariant('${constraint}', c.column.atLeast(0))   # build the predicate with the column DSL, never as text`,
+    meta: { constraint, count },
+  });

package/src/retype-dependents.ts

@@ -0,0 +1,135 @@
+// Single responsibility: which RECORDED objects a retype of one column breaks, and the statements
+// that take them out of the way before the ALTER and put them back in the `down`.
+//
+// Postgres compiles a partial index's predicate and a CHECK's expression against the column's type
+// at creation and cannot recompile either: `alter table "posts" alter column "status" type text
+// using "status"::text` answers `42883 operator does not exist: text = post_status` and the
+// migration aborts mid-run — inside `ROLE=migrate`, with the ledger recording nothing. Measured on
+// Postgres 18.4 (`generate-retype.live.test.ts`), one dependent shape at a time:
+//
+// | recorded object                          | survives the ALTER |
+// |------------------------------------------|--------------------|
+// | btree on the column, plain or unique      | yes — Postgres rebuilds it itself |
+// | composite btree including the column      | yes |
+// | partial index whose predicate names it    | **no — 42883** |
+// | partial index naming another column       | yes |
+// | CHECK whose expression names it           | **no — 42883** |
+//
+// So only an expression that MENTIONS the column is dependent, and dropping the rest would be a
+// table scan per index for nothing.
+
+import { addCheck, dropCheck } from './check-ddl';
+import type { Plan } from './foreign-key-plan';
+import { asDeclared, createIndex, dropIndex } from './index-ddl';
+import type { CheckDescription, IndexDescription, TableDescription } from './introspect';
+import { IDENTIFIER_PART, noiseAt } from './sql-scan';
+
+/**
+ * Whether `expression` reads `column`, over-approximating on purpose.
+ *
+ * The two errors are not symmetrical. A dependent object missed is `42883` in the release phase;
+ * one reported that was not is a rebuild nobody asked for — so every ambiguous case answers `true`,
+ * and the folding is case-insensitive because Postgres folds an unquoted identifier to lower case
+ * and `"Status"` naming a different column is a rarity beside a predicate this must not miss.
+ *
+ * What it does NOT count is noise, through this package's one lexer (`sql-scan.ts`): the `status`
+ * in `where kind = 'status'` is data, not a reference, and the one in `-- status` is prose. A
+ * QUOTED identifier is counted — `"status"` is the reference the catalog stores for an author who
+ * quoted it, and skipping it as noise is exactly the miss that ends in `42883`.
+ */
+export function referencesColumn(expression: string, column: string): boolean {
+  const wanted = column.toLowerCase();
+  let at = 0;
+  while (at < expression.length) {
+    const noise = noiseAt(expression, at);
+    if (noise !== null) {
+      if (
+        noise.kind === 'identifier' &&
+        expression.slice(at + 1, noise.end - 1).toLowerCase() === wanted
+      ) {
+        return true;
+      }
+      at = noise.end;
+      continue;
+    }
+    if (!IDENTIFIER_PART.test(expression[at] ?? '')) {
+      at += 1;
+      continue;
+    }
+    let end = at;
+    while (end < expression.length && IDENTIFIER_PART.test(expression[end] ?? '')) end += 1;
+    if (expression.slice(at, end).toLowerCase() === wanted) return true;
+    at = end;
+  }
+  return false;
+}
+
+/** The recorded objects a retype of `column` cannot leave in place. */
+export interface RetypeDependents {
+  /**
+   * Partial indexes whose predicate reads the column. A `primary` one is structurally impossible —
+   * a primary key index has no predicate — which is what keeps `drop index` off the two indexes
+   * Postgres refuses it on: a primary key's and a unique constraint's.
+   */
+  readonly indexes: readonly IndexDescription[];
+  /** CHECK constraints whose expression reads the column. */
+  readonly checks: readonly CheckDescription[];
+}
+
+/**
+ * What a retype of `table`.`column` breaks, read off the RECORDED schema — never the catalog.
+ * `x db gen` runs with no database open, so a hand-added expression index over the same column is
+ * invisible here and still `42883`; what this can see is every object a migration wrote down.
+ */
+export function retypeDependents(column: string, live: TableDescription): RetypeDependents {
+  return {
+    indexes: live.indexes.filter(
+      (index) => !index.primary && index.where !== null && referencesColumn(index.where, column),
+    ),
+    checks: (live.checks ?? []).filter((check) => referencesColumn(check.expression, column)),
+  };
+}
+
+/**
+ * What this plan has already dropped ahead of a retype — names only, because that is all the two
+ * readers need. The ordinary diff runs AFTER the ALTER and must not act on an object that is no
+ * longer there: the index loop CREATES a name in `indexes` instead of comparing it (a `drop index`
+ * on a name already dropped is `42704`, and a definition that never moved would emit nothing at
+ * all, leaving the table with no index), and `checkPlan` neither drops nor re-adds a name in
+ * `checks` — the declared side is added back by its own arm, and a recorded constraint the entity
+ * no longer declares is simply gone, which is what `checkPlan` would have done to it anyway.
+ */
+export interface MovedAside {
+  readonly indexes: Set<string>;
+  readonly checks: Set<string>;
+}
+
+/**
+ * Drop every dependent in `up`, restore it in `down`, and record what was moved.
+ *
+ * `down` is reversed at assembly, so the restores are pushed FORWARDS here and the retype's own
+ * reversal is pushed after them — the reversed script therefore reads: retype back to the old
+ * type, then recreate the objects that were compiled against it. Restoring first would recreate a
+ * predicate against a type the column no longer has, which is `42883` in the other direction.
+ *
+ * What is restored is what the snapshot RECORDED, never what the entity declares: an object still
+ * declared is re-created by the ordinary diff, one statement later, in its current shape.
+ */
+export function moveDependentsAside(
+  live: TableDescription,
+  column: string,
+  plan: Plan,
+  moved: MovedAside,
+): void {
+  const dependents = retypeDependents(column, live);
+  for (const index of dependents.indexes) {
+    plan.up.push(dropIndex(index.name));
+    plan.down.push(createIndex(live.name, asDeclared(index)));
+    moved.indexes.add(index.name);
+  }
+  for (const check of dependents.checks) {
+    plan.up.push(dropCheck(live.name, check.name));
+    plan.down.push(addCheck(live.name, check));
+    moved.checks.add(check.name);
+  }
+}

package/src/snapshot-parse.ts

@@ -4,6 +4,7 @@
 // is a sidecar one of them accepts and the other cannot use.
 
 import type {
+  CheckDescription,
   ColumnDescription,
   ForeignKeyDescription,
   IndexDescription,
@@ -28,10 +29,30 @@ const order = (value: unknown): value is 'asc' | 'desc' | null =>
 
 function column(value: unknown): ColumnDescription | undefined {
   if (!isRow(value)) return undefined;
-  const { name, dataType, nullable, default: fallback, position } = value;
+  const { name, dataType, nullable, default: fallback, position, generated } = value;
   if (!str(name) || !str(dataType) || !bool(nullable) || !nullableStr(fallback)) return undefined;
   if (typeof position !== 'number') return undefined;
-  return { name, dataType, nullable, default: fallback, position };
+  // `generated` was recorded by `snapshotOf` and dropped HERE, silently, for as long as the field
+  // has existed: the sidecar carried the expression and the parse handed back a column without it,
+  // so `retypeColumn` read every generated column as newly generated and rebuilt it on every
+  // `x db gen`. Absent stays absent — an ordinary column must gain no key.
+  if (!(generated === undefined || str(generated))) return undefined;
+  return {
+    name,
+    dataType,
+    nullable,
+    default: fallback,
+    position,
+    ...(generated === undefined ? {} : { generated }),
+  };
+}
+
+/** The predicate is the snapshot's own spelling, so both halves are plain strings or nothing. */
+function check(value: unknown): CheckDescription | undefined {
+  if (!isRow(value)) return undefined;
+  const { name, expression } = value;
+  if (!str(name) || !str(expression)) return undefined;
+  return { name, expression };
 }
 
 function index(value: unknown): IndexDescription | undefined {
@@ -88,7 +109,14 @@ function tableOf(value: unknown): TableDescription | undefined {
   const indexes = all(value['indexes'], index);
   const foreignKeys = all(value['foreignKeys'], foreignKey);
   if (columns === undefined || indexes === undefined || foreignKeys === undefined) return undefined;
-  return { schema, name, columns, primaryKey, indexes, foreignKeys };
+  // Absent, never `[]`. A sidecar written before constraints were recorded says nothing about
+  // them, and reading that as "this table declares none" would drop every invariant an app has
+  // already generated instead of adding the ones its database is missing.
+  const raw = value['checks'];
+  if (raw === undefined) return { schema, name, columns, primaryKey, indexes, foreignKeys };
+  const checks = all(raw, check);
+  if (checks === undefined) return undefined;
+  return { schema, name, columns, primaryKey, indexes, foreignKeys, checks };
 }
 
 /**

package/src/statement-excerpt.ts

@@ -0,0 +1,18 @@
+// Single responsibility: one SQL statement as one capped line, for an error to print. Its own
+// module because two rails now report statements — `destructive.ts` and `ungeneratable.ts` — and a
+// second copy of "what does a reported statement look like" is two answers to one question.
+
+/**
+ * Only the comments *preceding* the statement come off, the ones `statementsOf` carries in from the
+ * file header or from the `-- backfill …` note above it; the SQL itself stays verbatim.
+ *
+ * Blanking is for **deciding**, never for reporting: `stripSqlNoise` empties quoted identifiers, so
+ * a report built from it says `drop table ""`, which names nothing an author can act on.
+ */
+export function statementExcerpt(statement: string): string {
+  const line = statement
+    .replace(/^(?:\s*(?:--[^\n]*|\/\*[\s\S]*?\*\/)\s*)+/, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return line.length > 120 ? `${line.slice(0, 117)}...` : line;
+}