@ultimat3/db 29.4.0 → 30.1.0

package/src/generate-row-security.ts

@@ -0,0 +1,51 @@
+// Single responsibility: the row-security half of one `x db gen` — the flag and each tenant table's
+// physical column in, `row-security-plan.ts`'s input out, typed off the entity's own column. Kept
+// out of `generate.ts` so the diff loop reads one call, the way the append-only arm does.
+
+import type { EntityDescriptionLike } from './entity-shape';
+import type { SchemaDescription } from './introspect';
+import type { RowSecurityPlanInput, TenantTable } from './row-security-plan';
+import { sqlType } from './sql-type';
+
+/** One tenant table as `@ultimat3/entity`'s `describeTenancy()` names it: physical names only. */
+export interface TenantColumnLike {
+  readonly table: string;
+  readonly column: string;
+}
+
+/** `GenerateOptions.rowSecurity`: `database.rowSecurity`, and which column each tenant table is scoped by. */
+export interface RowSecurityOption {
+  readonly enabled: boolean;
+  readonly tenants: readonly TenantColumnLike[];
+}
+
+const OFF: RowSecurityOption = { enabled: false, tenants: [] };
+
+/**
+ * Tenant tables this migration still declares, typed by the SQL the generator itself gives the
+ * column — one spelling of the type for the column and the policy's cast. A recorded table this
+ * migration drops is left out of `recorded`: `drop table` takes its policy with it, and a
+ * `drop policy` after that would name a table that no longer exists.
+ */
+export function rowSecurityInput(
+  entities: readonly EntityDescriptionLike[],
+  current: SchemaDescription,
+  option: RowSecurityOption = OFF,
+): RowSecurityPlanInput {
+  // A view carries no policy of its own: Postgres reads its source table's (`generate-view.ts`).
+  const declared = new Map(
+    entities.filter((entity) => entity.view === undefined).map((entity) => [entity.table, entity]),
+  );
+  const tenantTables = option.tenants.flatMap((tenant): TenantTable[] => {
+    const column = declared.get(tenant.table)?.columns.find((c) => c.column === tenant.column);
+    return column === undefined
+      ? []
+      : [{ table: tenant.table, column: tenant.column, type: sqlType(column.kind) }];
+  });
+  const recorded = new Set(
+    current.tables
+      .filter((table) => table.rowSecurity === true && declared.has(table.name))
+      .map((table) => table.name),
+  );
+  return { enabled: option.enabled, tenantTables, recorded };
+}

package/src/generate-snapshot.ts

@@ -0,0 +1,82 @@
+// Single responsibility: the snapshot a migration records — what the entities declare, in the
+// vocabulary `introspect.ts` reads, plus the one-time facts a parameter decides (replica identity,
+// row security). Split from `generate.ts`, which diffs against it; re-exported there.
+
+import { declaredChecks } from './check-ddl';
+import { defaultExpression } from './column-default';
+import type { EntityDescriptionLike } from './entity-shape';
+import { foreignKeysOf } from './foreign-key-plan';
+import { splitViews, viewDescriptionOf } from './generate-view';
+import type { ColumnDescription, SchemaDescription, TableDescription } from './introspect';
+import { declaredIndexes } from './invariant-ddl';
+import { withSameTenantIndexes } from './same-tenant';
+import { sqlType } from './sql-type';
+
+/** No table named, which is what every caller outside `generateMigration` describes. */
+const NONE: ReadonlySet<string> = new Set();
+
+export function snapshotOf(
+  entities: readonly EntityDescriptionLike[],
+  replicaIdentityFull: ReadonlySet<string> = NONE,
+  rowSecurity: ReadonlySet<string> = NONE,
+): SchemaDescription {
+  // A view is recorded as its statements (`generate-view.ts`), never as a table it is not.
+  const split = splitViews(entities);
+  const tables = [...withSameTenantIndexes(split.tables)]
+    .sort((a, b) => (a.table < b.table ? -1 : 1))
+    .map((entity): TableDescription => {
+      const columns: ColumnDescription[] = [...entity.columns]
+        .sort((a, b) => (a.column < b.column ? -1 : 1))
+        .map((column, index) => ({
+          name: column.column,
+          dataType: sqlType(column.kind),
+          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,
+        columns,
+        primaryKey: [...entity.primaryKey],
+        // 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.
+        //
+        // `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,
+          primary: false,
+          where: index.where,
+          order: index.order,
+          // Only when one was declared. Writing `using: 'btree'` out for every index would rewrite
+          // every sidecar in every app on the next `x db gen` — a diff on every file for a fact
+          // that was already true, which `indexMethodOf` reads out of the absence anyway.
+          ...(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 }),
+        // The same rule once more: `true` or absent, never `false`. This is what makes the ALTER
+        // beside it a one-time statement rather than a line every `x db gen` writes again.
+        ...(replicaIdentityFull.has(entity.table) ? { replicaIdentityFull: true as const } : {}),
+        // `true` or absent once more — the record that makes the trigger a one-time statement.
+        ...(entity.appendOnly === true ? { appendOnly: true as const } : {}),
+        // And again: the record that makes the tenant policy a one-time statement.
+        ...(rowSecurity.has(entity.table) ? { rowSecurity: true as const } : {}),
+      };
+    });
+  // `views` absent when none is declared, so no snapshot written before views existed moves.
+  return split.views.length === 0
+    ? { tables }
+    : { tables, views: split.views.map(viewDescriptionOf) };
+}

package/src/generate-steps.ts

@@ -21,6 +21,8 @@ export interface DiffSteps {
   /** 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. */
@@ -74,9 +76,12 @@ export function assembleSteps(diff: DiffSteps): GeneratedMigration {
     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),
+      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 —

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 };
+}