@ultimat3/db 14.0.0 → 16.0.0

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. */