@ultimat3/db 29.3.2 → 30.0.0

package/src/generate-steps.ts

@@ -0,0 +1,99 @@
+// Single responsibility: turn one diff into the migration FILES it needs — one transactional step,
+// one non-transactional step, or the first followed by the second. Split from `generate.ts`, which
+// plans the statements; this file decides which step each list is and what each step records.
+
+import { NO_TRANSACTION_MARKER } from './concurrent-index';
+import { type ConcurrentPlan, intermediateSnapshot, stepStatements } from './concurrent-plan';
+import { isDestructiveMigration } from './destructive';
+import type { GeneratedMigration } from './generate';
+import type { SchemaDescription } from './introspect';
+import { type UnrenderedDeclaration, unrenderedComment } from './unrendered';
+
+export interface DiffSteps {
+  readonly id: string;
+  readonly name: string;
+  /** The transactional step's statements, in apply order. */
+  readonly up: readonly string[];
+  /** Its reversal, already in apply order. */
+  readonly down: readonly string[];
+  /** Everything that must run outside a transaction, after `up`. */
+  readonly concurrent: ConcurrentPlan;
+  /** The schema the whole diff leaves behind. */
+  readonly snapshot: SchemaDescription;
+  readonly unrendered: readonly UnrenderedDeclaration[];
+  /** `--rolling-unsafe` was asked for and this diff dropped a column that was never retired. */
+  readonly rollingUnsafe?: boolean | undefined;
+}
+
+/** One file's worth. `destructive` is read off `up` by the gate's own classifier, never assembled. */
+function migrationOf(
+  fields: Omit<GeneratedMigration, 'fileName' | 'destructive' | 'followUp'>,
+): GeneratedMigration {
+  return {
+    ...fields,
+    fileName: `migrations/${fields.id}.sql`,
+    destructive: isDestructiveMigration(fields.up),
+  };
+}
+
+/**
+ * The step files of one diff.
+ *
+ * The unrendered report sits at the TOP of the first step's `up` and never onto an empty one:
+ * `@ultimat3/cli`'s `generateAppMigration` reads an empty `up` as "nothing changed". In a
+ * non-transactional step the marker comes first — it is the header line the runner reads.
+ *
+ * Why TWO files and never one file in two halves: a migration is one ledger row. A file whose
+ * transactional half committed and whose concurrent half then failed is either recorded (and the
+ * index never built) or not (and the next run re-applies the committed half: `42P07`). Two files
+ * are two rows, and the second is idempotent by construction (`if not exists` / `if exists`, an
+ * INVALID leftover dropped first), so a failure in it is re-run, never repaired by hand.
+ */
+export function assembleSteps(diff: DiffSteps): GeneratedMigration {
+  const { id, name, snapshot, unrendered } = diff;
+  const body = diff.up.join('\n');
+  const step = stepStatements(diff.concurrent);
+  const later = step.up.join('\n');
+  const laterDown = step.down.join('\n');
+  const outside = (report: readonly UnrenderedDeclaration[]): string =>
+    `${NO_TRANSACTION_MARKER}\n${unrenderedComment(report)}${later}`;
+  if (body.length === 0 && later.length > 0) {
+    // Only index work: the non-transactional step IS the migration, under the plain id.
+    return migrationOf({
+      id,
+      name,
+      up: outside(unrendered),
+      down: laterDown,
+      snapshot,
+      unrendered,
+      transactional: false,
+    });
+  }
+  const first = migrationOf({
+    id,
+    name,
+    up: body.length === 0 ? body : unrenderedComment(unrendered) + body,
+    down: diff.down.join('\n'),
+    // What the transactional step alone leaves behind, when a second one follows it.
+    snapshot:
+      later.length === 0
+        ? snapshot
+        : intermediateSnapshot(snapshot, diff.concurrent.deferred, diff.concurrent.deferredKeys),
+    unrendered,
+    transactional: true,
+    ...(diff.rollingUnsafe === true ? { rollingUnsafe: true } : {}),
+  });
+  if (later.length === 0) return first;
+  // `_concurrently` sorts right after the plain id — as a ledger id, an `.sql` and every sidecar —
+  // so expand (the transaction) always lands before contract (the concurrent drops).
+  const followUp = migrationOf({
+    id: `${id}_concurrently`,
+    name: `${name} concurrently`,
+    up: outside([]),
+    down: laterDown,
+    snapshot,
+    unrendered: [],
+    transactional: false,
+  });
+  return { ...first, followUp };
+}

package/src/generate-triggers.ts

@@ -0,0 +1,119 @@
+// Single responsibility: an entity's lifecycle triggers — history, its guard, counters — as one
+// list per table, planned in both directions against what the newest snapshot recorded, and written
+// onto the snapshot so each is a one-time statement. The SQL of each is its own file's.
+
+import type { EntityDescriptionLike } from './entity-shape';
+import type { Plan } from './foreign-key-plan';
+import { counterTrigger, recountSql } from './generate-counter';
+import { historyTriggers } from './generate-history';
+import type { SchemaDescription, TableDescription, TriggerRecord } from './introspect';
+import { findTable } from './introspect';
+import { CROSS_TENANT_SETTING } from './row-security';
+import { identifier } from './sql';
+
+/** Every declared lifecycle trigger, by the table it sits on, in declaration order. */
+export function declaredTriggers(
+  entities: readonly EntityDescriptionLike[],
+): ReadonlyMap<string, readonly TriggerRecord[]> {
+  const byTable = new Map<string, TriggerRecord[]>();
+  const add = (table: string, trigger: TriggerRecord): void => {
+    const list = byTable.get(table) ?? [];
+    list.push(trigger);
+    byTable.set(table, list);
+  };
+  for (const entity of entities) {
+    if (entity.history !== undefined) {
+      for (const [table, trigger] of historyTriggers(entity.table, entity.history)) {
+        add(table, trigger);
+      }
+    }
+    for (const counter of entity.counts ?? [])
+      add(counter.table, counterTrigger(entity.table, counter));
+  }
+  return byTable;
+}
+
+const dropSql = (table: string, name: string): string =>
+  `drop trigger if exists ${identifier(name).text} on ${identifier(table).text};`;
+
+const same = (left: TriggerRecord, right: TriggerRecord): boolean =>
+  left.install.join('\n') === right.install.join('\n');
+
+/**
+ * The recount a NEW counter starts with, so a table that already holds rows is true from the first
+ * write. Cross-tenant for the one statement: under forced row security an unset tenant matches no
+ * row, and the recount would update nothing in silence.
+ */
+function recounts(
+  entities: readonly EntityDescriptionLike[],
+  added: ReadonlySet<string>,
+): string[] {
+  const out: string[] = [];
+  for (const entity of entities) {
+    for (const counter of entity.counts ?? []) {
+      const trigger = counterTrigger(entity.table, counter);
+      if (!added.has(`${counter.table}.${trigger.name}`)) continue;
+      out.push(`select set_config('${CROSS_TENANT_SETTING}', 'on', true);`);
+      out.push(recountSql(entity.table, counter));
+    }
+  }
+  return out;
+}
+
+/**
+ * Both directions, after every table exists. Declared and not recorded (or recorded with other
+ * statements): install, and `down` drops it — or reinstalls what was recorded. Recorded and no
+ * longer declared: drop, and `down` reinstalls it. A table dropped outright needs nothing: its
+ * triggers go with it. Functions are never dropped: one with no trigger does nothing.
+ */
+export function triggerPlan(
+  plan: Plan,
+  entities: readonly EntityDescriptionLike[],
+  current: SchemaDescription,
+): void {
+  const declared = declaredTriggers(entities);
+  const tables = new Set(entities.map((entity) => entity.table));
+  const added = new Set<string>();
+  for (const [table, triggers] of declared) {
+    const recorded = findTable(current, table)?.triggers ?? [];
+    for (const trigger of triggers) {
+      const before = recorded.find((each) => each.name === trigger.name);
+      if (before !== undefined && same(before, trigger)) continue;
+      plan.up.push(...trigger.install);
+      // `down` is reversed whole: pushed in apply order, reversed back into it.
+      if (before === undefined) plan.down.push(dropSql(table, trigger.name));
+      else plan.down.push(...[...before.install].reverse());
+      added.add(`${table}.${trigger.name}`);
+    }
+  }
+  for (const table of current.tables) {
+    if (!tables.has(table.name)) continue;
+    const wanted = declared.get(table.name) ?? [];
+    for (const recorded of table.triggers ?? []) {
+      if (wanted.some((each) => each.name === recorded.name)) continue;
+      plan.up.push(dropSql(table.name, recorded.name));
+      plan.down.push(...[...recorded.install].reverse());
+    }
+  }
+  plan.up.push(...recounts(entities, added));
+}
+
+/** The snapshot, each table carrying the triggers declared on it — absent where there are none. */
+export function recordTriggers(
+  snapshot: SchemaDescription,
+  entities: readonly EntityDescriptionLike[],
+): SchemaDescription {
+  const declared = declaredTriggers(entities);
+  const retained = new Set(
+    entities.filter((entity) => entity.retain !== undefined).map((entity) => entity.table),
+  );
+  const tables = snapshot.tables.map((table): TableDescription => {
+    const triggers = declared.get(table.name);
+    return {
+      ...table,
+      ...(triggers === undefined ? {} : { triggers }),
+      ...(retained.has(table.name) ? { retain: true as const } : {}),
+    };
+  });
+  return { ...snapshot, tables };
+}

package/src/generate-view.ts

@@ -0,0 +1,97 @@
+// Single responsibility: the views `x db gen` writes — `entity(name, { view: { sql } })` emitted
+// as `create [materialized] view`, recorded in the snapshot, and re-emitted whole when anything
+// they could depend on moves. Split from `generate.ts`, which hands every table to its own arms and
+// every view to this file, so no table arm (keys, row security, triggers) ever sees a view.
+
+import type { EntityDescriptionLike } from './entity-shape';
+import type { Plan } from './foreign-key-plan';
+import { createIndex } from './index-ddl';
+import type { SchemaDescription, ViewDescription } from './introspect';
+import { declaredIndexes } from './invariant-ddl';
+import { identifier } from './sql';
+
+/** Tables first, views second — the partition every arm of `generateMigration` reads. */
+export function splitViews(entities: readonly EntityDescriptionLike[]): {
+  readonly tables: readonly EntityDescriptionLike[];
+  readonly views: readonly EntityDescriptionLike[];
+} {
+  return {
+    tables: entities.filter((entity) => entity.view === undefined),
+    views: entities.filter((entity) => entity.view !== undefined),
+  };
+}
+
+/** The author's query as one statement body: no trailing `;`, no trailing whitespace. */
+const bodyOf = (sql: string): string => sql.trim().replace(/;\s*$/, '');
+
+/**
+ * What a declared view records: its statements, verbatim — the comparison `x db gen` makes next
+ * time is between two of these, so a changed query, a changed index or `materialized` flipping is
+ * a different list and a rebuild. Only a MATERIALIZED view carries indexes; Postgres has none for
+ * a plain one (`entity()` refuses the declaration first).
+ */
+export function viewDescriptionOf(entity: EntityDescriptionLike): ViewDescription {
+  const materialized = entity.view?.materialized === true;
+  const kind = materialized ? 'materialized view' : 'view';
+  const create = [
+    `create ${kind} ${identifier(entity.table).text} as ${bodyOf(entity.view?.sql ?? '')};`,
+    ...(materialized
+      ? declaredIndexes(entity).map((index) => createIndex(entity.table, index))
+      : []),
+  ];
+  return { name: entity.table, ...(materialized ? { materialized: true as const } : {}), create };
+}
+
+const drop = (view: ViewDescription): string =>
+  `drop ${view.materialized === true ? 'materialized view' : 'view'} if exists ${identifier(view.name).text};`;
+
+const same = (left: readonly ViewDescription[], right: readonly ViewDescription[]): boolean =>
+  left.length === right.length &&
+  left.every((view, at) => JSON.stringify(view) === JSON.stringify(right[at]));
+
+/**
+ * Whether the table statements of this migration can break a view compiled against them: a
+ * retype is `0A000` under a view and a dropped column or table is `2BP01`. The words are the ones
+ * `generate.ts` itself writes, so this reads its own output and never an author's SQL.
+ */
+export const touchesViewSources = (up: readonly string[]): boolean =>
+  up.some((statement) =>
+    /\balter column\b.*\btype\b|\bdrop column\b|^drop table\b/.test(statement),
+  );
+
+/** What a view rebuild contributes: drops ahead of every table statement, creates after them. */
+export interface ViewPlan {
+  readonly before: Plan;
+  readonly after: Plan;
+}
+
+/**
+ * Every recorded view is dropped (last declared first) and every declared one created (in
+ * declaration order — a view reading another view is declared after it) whenever the list moved
+ * or the tables under it did. Whole, never one view: which views read which is in their SQL, and
+ * a rebuild of the one that changed would leave its dependents compiled against the old one —
+ * `X_MIGRATION_VIEW_DEPENDS` is what that looks like at deploy. A materialized view comes back
+ * populated, so a rebuild costs one refresh, and nothing at all when nothing moved.
+ */
+export function viewPlan(
+  views: readonly EntityDescriptionLike[],
+  current: SchemaDescription,
+  tableUp: readonly string[],
+): ViewPlan {
+  const wanted = views.map(viewDescriptionOf);
+  const recorded = current.views ?? [];
+  const before: Plan = { up: [], down: [] };
+  const after: Plan = { up: [], down: [] };
+  if (same(wanted, recorded) && !(recorded.length > 0 && touchesViewSources(tableUp))) {
+    return { before, after };
+  }
+  for (const view of [...recorded].reverse()) before.up.push(drop(view));
+  // `down` is reversed whole by the caller, so it is written backwards here: what comes out is
+  // every recorded view recreated in its own order, after every table is back.
+  before.down.push(...recorded.flatMap((view) => view.create).reverse());
+  for (const view of wanted) {
+    after.up.push(...view.create);
+    after.down.push(drop(view));
+  }
+  return { before, after };
+}