@ultimat3/db 15.0.0 → 16.0.0

package/src/migration-errors.ts

@@ -0,0 +1,132 @@
+// Single responsibility: the refusals a MIGRATION earns — the lock it could not take, a ledger that
+// disagrees with this build, a plan that cannot be reversed, a plan that destroys rows without
+// saying so, a snapshot that was never written, and a view standing in a retype's way. Split out of
+// `errors.ts` only because that file reached the 500-line ceiling, exactly as `invariant-errors.ts`
+// was: every code below is still declared, titled and registered there, and `DbError` is still the
+// one class. One direction only — nothing here is imported back.
+
+import { DESTRUCTIVE_CAUSE, DESTRUCTIVE_MARKER, type DestructiveStatement } from './destructive';
+import { DbError } from './errors';
+
+/**
+ * The migration advisory lock was still held when the wait ran out. `pg_advisory_lock` blocks with
+ * no timeout, so a migrator wedged on a partition — or OOM-killed with its backend still alive —
+ * left `helm upgrade --wait` sitting inside one statement, printing nothing, with the job never
+ * failing so `backoffLimit` never fired. A bounded `pg_try_advisory_lock` poll turns that into an
+ * exit code.
+ */
+export const migrateConcurrent = (lockKey: number, waitedMs: number): DbError =>
+  new DbError({
+    code: 'X_MIGRATE_CONCURRENT',
+    cause:
+      `another session still holds pg_advisory_lock(${lockKey}) after waiting ${waitedMs}ms, ` +
+      'so this migrator refused rather than block a deploy forever',
+    fix:
+      'psql "$DATABASE_URL" -c "select pid, application_name, state from pg_stat_activity ' +
+      "join pg_locks using (pid) where locktype = 'advisory'\"" +
+      '   # pg_terminate_backend(pid) the wedged migrator, then: x db migrate',
+    meta: { lockKey, waitedMs },
+  });
+
+export const migrationConflict = (cause: string, fix: string): DbError =>
+  new DbError({ code: 'X_MIGRATION_CONFLICT', cause, fix });
+
+export const migrationIrreversible = (cause: string, fix: string): DbError =>
+  new DbError({ code: 'X_MIGRATION_IRREVERSIBLE', cause, fix });
+
+/**
+ * A view standing in the way of a retype, refused one statement before Postgres would have.
+ *
+ * `restore` is the caller's, the way `migrationIrreversible`'s `fix:` is: it is a pair of
+ * `psql "$DATABASE_URL" -c '…'` invocations — the shape `migrationConflict` above already writes —
+ * built out of live catalog values through `identifier()`. This file may not import `sql.ts`: that
+ * module imports `identifierUnsafe` from here, and an import cycle around the module whose
+ * evaluation REGISTERS every code is not a cycle worth having for one quoted name.
+ */
+export const migrationViewDepends = (
+  view: string,
+  table: string,
+  column: string,
+  restore: string,
+): DbError =>
+  new DbError({
+    code: 'X_MIGRATION_VIEW_DEPENDS',
+    cause:
+      `view "${view}" is compiled against "${table}"."${column}", which this migration retypes; ` +
+      'Postgres answers 0A000 and rolls the whole migration back',
+    fix: restore,
+    meta: { view, table, column },
+  });
+
+/**
+ * A rollback step count this build cannot honour. `steps` reaches `Array.prototype.slice`, where a
+ * negative count counts from the END: `steps: -1` selected every applied migration except the
+ * newest and reversed four of five, which is the one class of mistake a rollback cannot undo.
+ * Refused rather than coerced, exactly as `DATABASE_POOL_MAX` is — a number silently reinterpreted
+ * as a different one is the failure a validated argument exists to prevent.
+ */
+export const rollbackStepsInvalid = (received: number): DbError =>
+  new DbError({
+    code: 'X_INVARIANT',
+    cause: `rollback was asked to reverse ${String(received)} migrations, which is not a positive integer`,
+    fix: 'rollback({ migrations, steps: 1 })   # a whole number of migrations, newest first',
+    meta: { steps: received },
+  });
+
+/**
+ * `packages/db/migrations/0000_initial.snapshot.json` → `packages/db/migrations/0000_initial.*` —
+ * every file that one migration owns, as one `rm` argument. Derived from the path the caller passed
+ * rather than rebuilt from a directory this package does not know: `db` is tier 1 and where an app
+ * keeps its migrations is `@ultimat3/cli`'s answer, not this one's.
+ */
+const snapshotSiblings = (file: string): string => file.replace(/\.snapshot\.json$/, '.*');
+
+/**
+ * `20260817120000_add_posts` → `add_posts`, the argument `x db gen` takes. The name is free text
+ * and only ever labels a *new* id, so an id carrying no stamp answers with itself rather than with
+ * the empty string — a `fix:` ending in `x db gen ""` is a command that cannot be run.
+ */
+const migrationNameOf = (id: string): string => id.replace(/^\d+_/, '') || id;
+
+/**
+ * The sidecar every generated migration writes is what the *next* generation diffs against, so a
+ * newest migration without one leaves nothing to diff. Refused rather than defaulted to the empty
+ * schema, which would generate `create table` for every table the database already holds.
+ */
+export const migrationSnapshotMissing = (id: string, file: string): DbError =>
+  new DbError({
+    code: 'X_MIGRATION_SNAPSHOT_MISSING',
+    cause: `migration "${id}" records no schema snapshot (${file}), so there is nothing to diff against`,
+    // Two remedies, both commands, in the order they are safe to try. "restore from version
+    // control" alone was neither: on a scaffolded app the sidecar was never written, so there is
+    // nothing to restore — and the drift this refusal answers named `x db gen` as *its* fix, so
+    // the two errors pointed at each other and an app's first migration had no way out.
+    // `x db gen` is named only *after* the files it would trip over are gone.
+    fix:
+      `git checkout -- ${file}   # or, if it was never written: ` +
+      `rm ${snapshotSiblings(file)} && x db gen "${migrationNameOf(id)}"`,
+    meta: { id, file },
+  });
+
+/**
+ * One error per file, never one per statement: the marker declares the whole migration, so a
+ * second finding would repeat an instruction the first already gave. `file` is app-relative and
+ * arrives from the caller — `db` is tier 1 and does not know where an app keeps its migrations.
+ *
+ * Irreversible and destructive are two questions. `X_MIGRATION_IRREVERSIBLE` refuses to *generate*
+ * a plan whose `down` cannot restore the rows; this one refuses to *ship* a plan whose `up`
+ * destroys them without saying so — a retype is reversible in DDL and still rewrites every row.
+ */
+export const migrationDestructive = (
+  file: string,
+  first: DestructiveStatement,
+  more = 0,
+): DbError =>
+  new DbError({
+    code: 'X_MIGRATION_DESTRUCTIVE',
+    cause:
+      `${file} ${DESTRUCTIVE_CAUSE[first.kind]} and does not declare it` +
+      `${more === 0 ? '' : ` (and ${more} more destructive)`}: ${first.statement}`,
+    fix: `add the line "${DESTRUCTIVE_MARKER}" to ${file}, or regenerate it: x db gen "<name>" --allow-destructive`,
+    meta: { file, kind: first.kind, statements: more + 1 },
+  });

package/src/retype-keys.ts

@@ -0,0 +1,139 @@
+// Single responsibility: which columns this migration RETYPES, and which recorded FOREIGN KEYS
+// that breaks — the one answer to both, computed over the whole schema and above `diffTable`.
+//
+// **Why above `diffTable`, and not inside it like every other dependent.** Postgres re-checks a
+// key's two ends against each other on every `alter column … type` and cannot rebuild one whose
+// sides stopped matching: measured on 18.4, `42804 foreign key constraint "rk_posts_org_code_fkey"
+// cannot be implemented — Key columns "org_code" … and "code" … are of incompatible types: integer
+// and text`, thrown by the ALTER itself, inside `ROLE=migrate`, with the ledger recording nothing.
+// The constraint that breaks is recorded on the table that OWNS it, which for a retype of the
+// key's TARGET is a different entity's record — `diffTable(orgs)` is handed `orgs`'s row and can
+// never see `posts.foreignKeys`. So the retype set is derived once, from `entities` and `current`
+// together, and `retypeColumn` READS it rather than deciding again: two answers to "is this column
+// being retyped" is the axiom-1 split this package has spent the week closing.
+//
+// **Over-approximated on purpose, the rule `retype-dependents.ts` states.** Whether two types keep
+// an equality operator between them is operator resolution, which is exactly the knowledge a
+// generator with no database cannot have — `varchar(80)` and `text` share one, `integer` and
+// `text` do not. A key moved aside that did not need to be is one `add constraint` re-validating a
+// table the ALTER beside it is already rewriting under ACCESS EXCLUSIVE; a key missed is the
+// release phase failing with the server's words and none of the entity's.
+//
+// **What it cannot see.** A key the recorded schema does not hold — a hand-written migration's,
+// or one from a sidecar written before `foreignKeys` was recorded — is invisible here and still
+// `42804`, the same construction limit `x db gen` has against a hand-added expression index. And
+// re-adding the key is still the SERVER's judgement: an entity that retypes one end and not the
+// other declares a pairing Postgres has no operator for, and the `add constraint` at the end of
+// `up` is where that is said. Refusing it here would need the type knowledge two paragraphs up.
+
+import type { EntityDescriptionLike } from './entity-shape';
+import { addForeignKey, dropForeignKey, keyId, unrestorableNote } from './foreign-key';
+import type { Plan } from './foreign-key-plan';
+import { isGenerated } from './generated-column';
+import type { ForeignKeyDescription, SchemaDescription, TableDescription } from './introspect';
+import { findTable } from './introspect';
+import { sqlType } from './sql-type';
+
+/** Table name to the columns whose physical type this migration moves. Empty entries are omitted. */
+export type RetypedColumns = ReadonlyMap<string, ReadonlySet<string>>;
+
+/** The columns of one table this migration retypes — `retypeColumn`'s own read of the set above. */
+export function retypedIn(retyped: RetypedColumns, table: string): ReadonlySet<string> {
+  return retyped.get(table) ?? new Set<string>();
+}
+
+/**
+ * Every plain `alter column … type` this migration will emit, before any of them is written.
+ *
+ * A GENERATED column is deliberately absent: `generated-column.ts` owns every statement one of
+ * them produces, and its plain -> generated path is a `drop column` that takes the key with it
+ * rather than an ALTER that trips over it. That gap is real and is named in `generated-column.ts`.
+ */
+export function retypedColumns(
+  entities: readonly EntityDescriptionLike[],
+  current: SchemaDescription,
+): RetypedColumns {
+  const moved = new Map<string, ReadonlySet<string>>();
+  for (const entity of entities) {
+    const live = findTable(current, entity.table);
+    if (live === undefined) continue;
+    const recorded = new Map(live.columns.map((column) => [column.name, column]));
+    const columns = new Set<string>();
+    for (const column of entity.columns) {
+      const held = recorded.get(column.column);
+      if (held === undefined) continue;
+      if (isGenerated(column) || held.generated !== undefined) continue;
+      if (held.dataType !== sqlType(column.kind)) columns.add(column.column);
+    }
+    if (columns.size > 0) moved.set(entity.table, columns);
+  }
+  return moved;
+}
+
+/** Whether either end of `key` sits on a column this migration retypes. `owner` owns the key. */
+function breaksOn(key: ForeignKeyDescription, owner: string, retyped: RetypedColumns): boolean {
+  const own = retyped.get(owner);
+  if (own !== undefined && key.columns.some((column) => own.has(column))) return true;
+  const target = retyped.get(key.referencedTable);
+  return target !== undefined && key.referencedColumns.some((column) => target.has(column));
+}
+
+/**
+ * Drop every recorded key a retype breaks, restore it in `down`, and answer which names were moved.
+ *
+ * The two statements go in the plan's OWN buckets and not beside the ALTER, because the drop has
+ * to precede every alter in the migration and the restore has to follow every one of them — both
+ * ends of a key can move, in two different entities' diffs. `preAlters` is merged at the very top
+ * of `up` and at the very FRONT of `down`, which reversal turns into the very end: so the reversed
+ * script reads drop-the-new-key, retype both ends back, add the recorded key. Restoring it any
+ * earlier is `42804` in the other direction.
+ *
+ * What comes back in `up` is not written here at all: `foreignKeyPlan` reads the returned set,
+ * treats a moved key as one the schema does not record, and adds the DECLARED key in the
+ * `constraints` bucket that already runs after every table statement. That is what makes the three
+ * outcomes fall out of code that already exists — still declared (added back), no longer declared
+ * (gone, exactly as the removal arm would have left it), and declared with a new `on delete` rule
+ * (added back carrying it) — instead of three branches restating them here.
+ */
+export function moveKeysAside(
+  current: SchemaDescription,
+  retyped: RetypedColumns,
+  doomed: ReadonlySet<string>,
+  preAlters: Plan,
+): ReadonlySet<string> {
+  const moved = new Set<string>();
+  for (const table of current.tables) {
+    for (const key of table.foreignKeys) {
+      if (!breaksOn(key, table.name, retyped)) continue;
+      moved.add(keyId(table.name, key.name));
+      preAlters.up.push(dropForeignKey(table.name, key.name));
+      preAlters.down.push(restore(table, key, doomed));
+    }
+  }
+  return moved;
+}
+
+/**
+ * The `down` half. A key whose own table or whose target is being dropped has no `add constraint`
+ * that could run at all, so it gets the SAME note `unrestorableDrop` gives one — the text is
+ * `unrestorableNote`'s, in `foreign-key.ts`, and not a second spelling here. One failed rollback
+ * has one wording whichever module emitted it (axiom 2); these two had already drifted, this one
+ * naming no table at all while `foreign-key-plan.ts` named the target.
+ *
+ * The table it names is the key's OWN when that is the one going: a constraint whose table is
+ * gone is the more proximate reason there is nothing to add it back onto.
+ */
+function restore(
+  table: TableDescription,
+  key: ForeignKeyDescription,
+  doomed: ReadonlySet<string>,
+): string {
+  if (!doomed.has(table.name) && !doomed.has(key.referencedTable)) {
+    return addForeignKey(table.name, key);
+  }
+  return unrestorableNote(
+    table.name,
+    key.name,
+    doomed.has(table.name) ? table.name : key.referencedTable,
+  );
+}

package/src/sql-type.ts

@@ -0,0 +1,35 @@
+// Single responsibility: the physical Postgres type a declared column KIND becomes. One table, so
+// the statement that writes a column, the snapshot that records it and the pass that decides
+// whether a retype is happening at all cannot disagree about what `char` means.
+//
+// Split out of `generate.ts` for `retype-keys.ts`, which has to answer "does this column's type
+// move" ABOVE `diffTable` — a foreign key over a retyped column lives in another table's record.
+
+const SQL_TYPES: Readonly<Record<string, string>> = {
+  uuid: 'uuid',
+  text: 'text',
+  // Bare `char` is `char(1)` in Postgres, and the only column carrying this kind is money's
+  // currency — a three-letter ISO 4217 code whose CHECK the entity emits on the same line.
+  // Without the length no currency ever fits the constraint the same statement demands.
+  char: 'char(3)',
+  boolean: 'boolean',
+  integer: 'integer',
+  bigint: 'bigint',
+  numeric: 'numeric',
+  timestamptz: 'timestamptz',
+  date: 'date',
+  jsonb: 'jsonb',
+};
+
+/**
+ * A kind this table does not name passes through verbatim — an app's own domain, an enum type a
+ * hand-written migration created.
+ *
+ * `Object.hasOwn` and not a bare index: `kind` is DATA, so `SQL_TYPES['constructor']` answered the
+ * `Object` function and `type ${wanted}` spliced its source into a statement, while `'__proto__'`
+ * answered `[object Object]`. Guarded, both behave like every other unknown kind and pass through
+ * as themselves. Measured across the package's 766 tests: no other input's answer moves.
+ */
+export function sqlType(kind: string): string {
+  return Object.hasOwn(SQL_TYPES, kind) ? (SQL_TYPES[kind] ?? kind) : kind;
+}

package/src/sql.ts

@@ -132,19 +132,37 @@ export function identifier(name: string): SqlFragment {
 }
 
 /**
- * A quoted string literal. Postgres utility statements (`CREATE DATABASE`, `COMMENT ON`) reject
- * bound parameters, so this is the only place a value may be inlined — and it escapes quotes.
- * Never reach for it in a query: `sql` binds parameters there.
+ * A quoted string literal Postgres reads IDENTICALLY under both settings of
+ * `standard_conforming_strings`. Utility and DDL statements (`CREATE DATABASE`, `COMMENT ON`,
+ * `create table … default …`) reject bound parameters, so this is the only place a value may be
+ * inlined. Never reach for it in a query: `sql` binds parameters there.
  *
- * The doubling is only an escape while `standard_conforming_strings` is `on`, which has been the
- * server default since 9.1: with it OFF, a backslash escapes the quote that follows and a value
- * ending in one closes the literal early. So this is safe for framework-supplied names — a
- * database, a schema, a comment this repo writes — and is NOT an escape for untrusted text under
- * an arbitrary server configuration. Nothing passes it caller input today; if something must,
- * bind a parameter instead, or send `E''`-style quoting from a statement that can take one.
+ * **It DOES receive caller input, and this comment said otherwise until 2026-08-25.**
+ * `column-default.ts:43` renders `ColumnDefaultLike` here, which is an app's own
+ * `.default('C:\\logs')` crossing the tier seam from `@ultimat3/entity` — nothing validates it and
+ * no `identifier()` guards it. (The package's two other callers are safe by CONSTRUCTION, not by
+ * input: `readonly-role.ts:71` sits in the same `sql` template as an `identifier(role)` that throws
+ * first, and `branch.ts:85` runs after an already-awaited `identifier(base)`.)
+ *
+ * Doubling the quote is not the whole rule. That GUC is settable per session, per database and per
+ * role and `SET` needs no privilege, and with it `off` a backslash escapes the character after it
+ * inside an ordinary `'…'`. Measured on 18.4 through `generateMigration`: `.default('C:\\logs')`
+ * emits `default 'C:\logs'`, which stores `C:\logs` with the GUC on and **`C:logs`** with it off —
+ * a column defaulting to a value nobody wrote, with no error anywhere. A value ENDING in a
+ * backslash is worse than wrong: the escaped quote leaves the literal unterminated and the text
+ * after it is string data until the next `'` puts the remainder back into code position.
+ *
+ * `E'…'` fixes the dialect in the text itself rather than trusting a setting, so both readings
+ * agree — **only** when the value actually carries a backslash. Without one there is no escape
+ * mechanism for the two settings to disagree about, so every migration already generated stays byte
+ * for byte what it was and nothing regenerates spuriously; both tracked apps have applied
+ * migrations on disk with hashes over this text. Same rule, same measurement, as
+ * `packages/entity/src/sql-literal.ts`, which is where it was first written and which adopts this
+ * one — tier 1 holds it, tier 2 imports down.
  */
 export function literal(value: string): SqlFragment {
-  return raw(`'${value.replaceAll("'", "''")}'`);
+  const quoted = value.replaceAll("'", "''");
+  return raw(value.includes('\\') ? `E'${quoted.replaceAll('\\', '\\\\')}'` : `'${quoted}'`);
 }
 
 /** `a, b, c` — the one blessed way to build an IN list or a column list. */