@telorun/sql 0.21.3 → 0.22.1

package/src/schema/normalize-table.ts

@@ -0,0 +1,224 @@
+import type {
+  DeclaredColumn,
+  DeclaredForeignKey,
+  DeclaredIndex,
+  DeclaredTable,
+} from "./declared-schema.js";
+
+/**
+ * The manifest shape a backend's `Table` kind declares, reduced to the
+ * normalized model.
+ *
+ * The STRUCTURE is shared — named columns, named indexes, named foreign keys —
+ * while the type vocabulary is not: `type` is carried through opaquely and
+ * every field the shared model does not name becomes a type parameter, so a
+ * backend adds `length`, `precision` or `collation` to its schema and nothing
+ * here changes. Types are structured rather than spelled into a scalar
+ * (`type: varchar` with `length: 64`, never `varchar(64)`), so nothing has to
+ * parse a type back apart.
+ */
+export interface RawColumn {
+  readonly type: string;
+  readonly nullable?: boolean;
+  readonly array?: boolean;
+  readonly primaryKey?: boolean;
+  readonly unique?: boolean;
+  readonly default?: unknown;
+  readonly defaultExpression?: string;
+  readonly identity?: string;
+  readonly renamedFrom?: string;
+  readonly [param: string]: unknown;
+}
+
+export interface RawIndex {
+  readonly columns: readonly string[];
+  readonly unique?: boolean;
+  readonly [option: string]: unknown;
+}
+
+export interface RawForeignKey {
+  readonly columns: readonly string[];
+  readonly references: { readonly table: unknown; readonly columns: readonly string[] };
+  readonly onDelete?: string;
+  readonly onUpdate?: string;
+}
+
+export interface RawTable {
+  readonly table: string;
+  readonly columns?: Record<string, RawColumn>;
+  readonly indexes?: Record<string, RawIndex>;
+  readonly foreignKeys?: Record<string, RawForeignKey>;
+}
+
+const COLUMN_KEYS = new Set([
+  "type",
+  "nullable",
+  "array",
+  "primaryKey",
+  "unique",
+  "default",
+  "defaultExpression",
+  "identity",
+  "renamedFrom",
+]);
+
+const INDEX_KEYS = new Set(["columns", "unique"]);
+
+function params(raw: Record<string, unknown>, known: ReadonlySet<string>): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(raw).filter(([key, value]) => !known.has(key) && value !== undefined),
+  );
+}
+
+function normalizeColumn(name: string, raw: RawColumn): DeclaredColumn {
+  if (raw.default !== undefined && raw.defaultExpression !== undefined) {
+    throw new Error(
+      `column '${name}' declares both 'default' and 'defaultExpression' — a typed literal and ` +
+        `a backend SQL expression are separate fields and exactly one may be set`,
+    );
+  }
+
+  // A primary key and an identity column cannot hold NULL, and the engine
+  // enforces that whether or not the declaration says so. Left at the `nullable`
+  // default of true, the column would read back NOT NULL on the next boot, the
+  // pass would see a difference it could "fix", and every boot from then on
+  // would try to DROP NOT NULL on a primary key and fail. So the implication is
+  // applied here, once, where both the DDL and the comparison read it — and a
+  // declaration that states the opposite is refused rather than quietly
+  // overruled.
+  const impliesNotNull = raw.primaryKey === true || raw.identity !== undefined;
+  if (impliesNotNull && raw.nullable === true) {
+    throw new Error(
+      `column '${name}' is declared nullable and ${raw.primaryKey ? "a primary key" : "an identity column"}, ` +
+        `which cannot hold NULL. Remove 'nullable: true'.`,
+    );
+  }
+
+  return {
+    name,
+    type: raw.type,
+    params: params(raw as Record<string, unknown>, COLUMN_KEYS),
+    nullable: impliesNotNull ? false : (raw.nullable ?? true),
+    array: raw.array ?? false,
+    primaryKey: raw.primaryKey ?? false,
+    unique: raw.unique ?? false,
+    default: raw.default,
+    defaultExpression: raw.defaultExpression,
+    identity: raw.identity,
+    renamedFrom: raw.renamedFrom,
+  };
+}
+
+/**
+ * Turns whatever sits at a `references.table` slot into the referenced table's
+ * physical name.
+ *
+ * REQUIRED rather than optional: a `!ref` is not resolved when a controller is
+ * constructed — Phase-5 injection runs after `create()` returns — so a caller
+ * that omitted one would read the sentinel and reproduce, silently, the exact
+ * defect this parameter exists to fix. `tableReferenceResolver` is the one every
+ * backend uses.
+ */
+export type TableReferenceResolver = (value: unknown, fk: string) => string;
+
+/**
+ * Structural checks over one declaration, at resource creation — before any
+ * connection is opened, let alone any DDL planned.
+ *
+ * Each of these would otherwise reach the engine as raw SQL and come back as a
+ * driver error naming a statement the author never wrote. They are decidable
+ * from the declaration alone, so they are decided here and reported against the
+ * field that is wrong.
+ */
+function validateTable(table: DeclaredTable): void {
+  const where = `${table.name}`;
+  if (table.columns.length === 0) {
+    throw new Error(`table '${where}' declares no columns — a table needs at least one.`);
+  }
+
+  const names = new Set(table.columns.map((c) => c.name));
+
+  const primaryKeys = table.columns.filter((c) => c.primaryKey).map((c) => c.name);
+  if (primaryKeys.length > 1) {
+    throw new Error(
+      `table '${where}' marks ${primaryKeys.map((n) => `'${n}'`).join(" and ")} as primaryKey. ` +
+        `A composite primary key is not expressible as a per-column flag — declare one column ` +
+        `as the key, or create the constraint in a 'migrations:' entry.`,
+    );
+  }
+
+  for (const column of table.columns) {
+    if (!column.renamedFrom) continue;
+    if (column.renamedFrom === column.name) {
+      throw new Error(
+        `column '${where}.${column.name}' declares renamedFrom itself, which describes no rename.`,
+      );
+    }
+    if (names.has(column.renamedFrom)) {
+      throw new Error(
+        `column '${where}.${column.name}' renames from '${column.renamedFrom}', which this table ` +
+          `also declares. A rename's source is the column being retired, so declaring both would ` +
+          `copy one live column into another and retire neither.`,
+      );
+    }
+  }
+
+  // An index or foreign key over a column the table does not declare cannot be
+  // created, and the engine's complaint would name a generated statement.
+  for (const index of table.indexes) {
+    for (const column of index.columns) {
+      if (!names.has(column)) {
+        throw new Error(
+          `index '${where}.${index.name}' names column '${column}', which this table does not ` +
+            `declare.`,
+        );
+      }
+    }
+  }
+  for (const fk of table.foreignKeys) {
+    for (const column of fk.columns) {
+      if (!names.has(column)) {
+        throw new Error(
+          `foreign key '${where}.${fk.name}' names column '${column}', which this table does not ` +
+            `declare.`,
+        );
+      }
+    }
+    if (fk.references.columns.length !== fk.columns.length) {
+      throw new Error(
+        `foreign key '${where}.${fk.name}' has ${fk.columns.length} column(s) but references ` +
+          `${fk.references.columns.length} — a foreign key maps its columns one for one.`,
+      );
+    }
+  }
+}
+
+export function normalizeTable(
+  raw: RawTable,
+  resolveReference: TableReferenceResolver,
+): DeclaredTable {
+  const columns = Object.entries(raw.columns ?? {}).map(([name, column]) =>
+    normalizeColumn(name, column),
+  );
+  const indexes: DeclaredIndex[] = Object.entries(raw.indexes ?? {}).map(([name, index]) => ({
+    name,
+    columns: [...index.columns],
+    unique: index.unique ?? false,
+    options: params(index as Record<string, unknown>, INDEX_KEYS),
+  }));
+  const foreignKeys: DeclaredForeignKey[] = Object.entries(raw.foreignKeys ?? {}).map(
+    ([name, fk]) => ({
+      name,
+      columns: [...fk.columns],
+      references: {
+        table: resolveReference(fk.references.table, name),
+        columns: [...fk.references.columns],
+      },
+      onDelete: fk.onDelete,
+      onUpdate: fk.onUpdate,
+    }),
+  );
+  const table: DeclaredTable = { name: raw.table, columns, indexes, foreignKeys };
+  validateTable(table);
+  return table;
+}

package/src/schema/reclaim-policy.ts

@@ -0,0 +1,73 @@
+import { parseDurationMs } from "@telorun/sdk";
+import type { TombstoneRecord, VersionRecord } from "./schema-ledger.js";
+
+/**
+ * When a tombstone may be reclaimed. Eligibility is a CONJUNCTION: N released
+ * versions must have been observed since the object went missing, AND T must
+ * have elapsed. Version is the primary signal — it is what proves older code is
+ * no longer live — and time is the backstop, because N versions can land in an
+ * afternoon.
+ *
+ * Declaring no policy means nothing is ever dropped, so reclamation is opt-in
+ * by declaration rather than by invocation.
+ */
+export interface ReclaimPolicy {
+  readonly afterVersions: number;
+  readonly afterDuration: string;
+}
+
+export interface Eligibility {
+  readonly eligible: boolean;
+  /** Versions observed since the tombstone, and how many are still needed. */
+  readonly versionsObserved: number;
+  readonly versionsRemaining: number;
+  readonly msElapsed: number;
+  readonly msRemaining: number;
+}
+
+/**
+ * A rollback resets progress rather than merely pausing it.
+ *
+ * Going backwards proves older code is live, so a boot at a version that was
+ * already observed at or before the tombstone is not one more release past the
+ * removal — it is evidence the removal is not yet safe. Both counters restart
+ * from that observation: the version count, and the elapsed-time baseline. This
+ * is answerable only because the ledger records the observed *sequence* rather
+ * than a counter.
+ */
+export function assessTombstone(
+  tombstone: TombstoneRecord,
+  history: readonly VersionRecord[],
+  policy: ReclaimPolicy,
+  nowMs: number,
+): Eligibility {
+  const priorVersions = new Set(
+    history
+      .filter((entry) => entry.sequence <= tombstone.missingSinceSequence)
+      .map((entry) => entry.version),
+  );
+  let counted = new Set<string>();
+  let baselineAt = tombstone.missingSinceAt;
+  for (const entry of history) {
+    if (entry.sequence <= tombstone.missingSinceSequence) continue;
+    if (priorVersions.has(entry.version)) {
+      counted = new Set();
+      baselineAt = entry.firstSeenAt;
+      continue;
+    }
+    counted.add(entry.version);
+  }
+
+  const versionsObserved = counted.size;
+  const msElapsed = Math.max(0, nowMs - Date.parse(baselineAt));
+  const requiredMs = parseDurationMs(policy.afterDuration);
+  const versionsRemaining = Math.max(0, policy.afterVersions - versionsObserved);
+  const msRemaining = Math.max(0, requiredMs - msElapsed);
+  return {
+    eligible: versionsRemaining === 0 && msRemaining === 0,
+    versionsObserved,
+    versionsRemaining,
+    msElapsed,
+    msRemaining,
+  };
+}

package/src/schema/schema-driver.ts

@@ -0,0 +1,207 @@
+import type { SqlConnection } from "../sql-connection.js";
+import type { LedgerTables } from "./schema-ledger.js";
+import type {
+  SchemaObjectId,
+  DeclaredColumn,
+  DeclaredForeignKey,
+  DeclaredIndex,
+  DeclaredTable,
+} from "./declared-schema.js";
+
+/** The live shape of one table, as the driver reads it back from the database. */
+export interface LiveColumn {
+  readonly name: string;
+  /**
+   * The driver's canonical rendering of the column's type, compared verbatim
+   * against what {@link SchemaDriver.typeSignature} produces for a declaration.
+   * Comparing signatures rather than parsed parts is what keeps every type rule
+   * inside the driver.
+   */
+  readonly typeSignature: string;
+  readonly nullable: boolean;
+  readonly hasDefault: boolean;
+  /** Whether the column is part of the table's primary key. */
+  readonly primaryKey: boolean;
+  /** Whether a single-column uniqueness constraint covers it. */
+  readonly unique: boolean;
+}
+
+/**
+ * An index as the database has it, not merely its name.
+ *
+ * Compared by name alone, changing which columns an index covers — or making it
+ * unique — emitted nothing and reported nothing, while the ledger recorded the
+ * new definition as owned. The declaration then asserted an index the database
+ * was not providing.
+ */
+export interface LiveIndex {
+  readonly name: string;
+  readonly columns: readonly string[];
+  readonly unique: boolean;
+}
+
+/** A foreign key as the database has it. Same reasoning as {@link LiveIndex}:
+ *  changing `onDelete` is a change to what the constraint DOES. */
+export interface LiveForeignKey {
+  readonly name: string;
+  readonly columns: readonly string[];
+  readonly references: { readonly table: string; readonly columns: readonly string[] };
+  readonly onDelete?: string;
+  readonly onUpdate?: string;
+}
+
+export interface LiveTable {
+  readonly name: string;
+  readonly columns: readonly LiveColumn[];
+  readonly indexes: readonly LiveIndex[];
+  readonly foreignKeys: readonly LiveForeignKey[];
+}
+
+/** How a declared change relates to the data already in the column. */
+export type ChangeSafety =
+  | { readonly safe: true }
+  | { readonly safe: false; readonly reason: string };
+
+/**
+ * Everything reconciliation needs that only the engine knows: how a type is
+ * spelled, how it is read back, what a lock is, and which alterations the
+ * engine can perform at all. The diff, the ledger, the tombstones and the
+ * ordering live in the shared library and are identical for every backend.
+ *
+ * Statement renderers return SQL text; the runner executes and logs it. They
+ * never touch the connection themselves, so a plan can be built, reported and
+ * refused without anything having run.
+ */
+export interface SchemaDriver {
+  readonly connection: SqlConnection;
+
+  /** Quote an identifier. */
+  quote(name: string): string;
+  /** Qualify a table with the namespace this schema resource owns. */
+  qualify(schema: string, table: string): string;
+
+  /**
+   * Hold the engine's cross-process schema lock for the duration of `body`.
+   * Every replica of an app boots the same pass, so this is what makes
+   * "reconcile once" true rather than hoped for.
+   */
+  withLock<T>(schema: string, body: () => Promise<T>): Promise<T>;
+
+  /** Create the namespace when absent. Purely additive. */
+  ensureNamespaceStatements(schema: string): string[];
+
+  /** The three ledger tables, `CREATE TABLE IF NOT EXISTS`. Named by the caller:
+   *  which ledger a schema resource writes to is its own declaration. */
+  ledgerStatements(schema: string, tables: LedgerTables): string[];
+
+  /**
+   * Run `statements` atomically where the engine allows DDL inside a
+   * transaction, and sequentially where it does not. Which of the two an engine
+   * offers is the driver's to know; the runner only needs the strongest
+   * grouping available, and relies on the pass being idempotent for the rest.
+   *
+   * A migration's ledger row is the LAST statement of its group, so on an engine
+   * with transactional DDL "applied" and "recorded as applied" are one commit.
+   * An implementation whose engine cannot do that MUST say so here, because the
+   * consequence is specific: a crash mid-group can re-run a migration that is
+   * not idempotent.
+   */
+  runAtomically(statements: readonly string[]): Promise<void>;
+
+  /**
+   * The current time, as ISO-8601 UTC text, **from the database**.
+   *
+   * Not the application's clock: the grace window gates an irreversible drop,
+   * and one replica with a skewed clock would satisfy `afterDuration`
+   * instantly. The ledger's history already treats the database as the
+   * authority; the clock measured against it has to come from there too, so
+   * every replica measures the same elapsed time.
+   */
+  now(): Promise<string>;
+
+  /** Read back the live shape of the named tables. Absent tables are omitted. */
+  introspect(schema: string, tables: readonly string[]): Promise<LiveTable[]>;
+
+  /** The canonical signature of a declared column's type, for comparison with {@link LiveColumn.typeSignature}. */
+  typeSignature(column: DeclaredColumn): string;
+
+  /**
+   * Whether altering a live column to the declared one can be applied without
+   * risking the data already in it. Type widening is safe, narrowing is not,
+   * and only the engine knows which is which.
+   */
+  classifyAlter(live: LiveColumn, declared: DeclaredColumn): ChangeSafety;
+
+  /**
+   * Whether the values in a live column can be COPIED into a newly added one —
+   * the expand-contract half of a rename.
+   *
+   * A different question from {@link classifyAlter}, which asks whether a column
+   * can be changed in place. Here the target is brand new, so its nullability
+   * and default are already what the declaration says and only the VALUES have
+   * to survive the move. An engine that can alter nothing in place can still
+   * copy freely between compatible types, and one that copies between anything
+   * may still lose data doing it.
+   */
+  classifyCopy(live: LiveColumn, target: DeclaredColumn): ChangeSafety;
+
+  /**
+   * Whether an index can be brought to its declaration in place. Most engines
+   * cannot alter one, so the honest answer is usually to drop and recreate —
+   * which this returns as statements, or refuses when the index is not this
+   * schema's to rebuild.
+   */
+  classifyIndexChange(live: LiveIndex, declared: DeclaredIndex): ChangeSafety;
+
+  /** Whether a foreign key can be brought to its declaration in place. */
+  classifyForeignKeyChange(live: LiveForeignKey, declared: DeclaredForeignKey): ChangeSafety;
+
+  /**
+   * Whether `createTable` already carries the table's foreign keys, so the
+   * reconciler must not also plan an `addForeignKey` for a table it just made.
+   *
+   * REQUIRED, like every other member here, because the wrong answer is silent:
+   * a driver that omitted it would get name matching by default, and if its
+   * engine also emits keys inside `CREATE TABLE` it would get exactly the
+   * unrestartable application this member exists to prevent — with no compile
+   * error and no failing test. Stating an answer is the point.
+   */
+  readonly foreignKeysInCreateTable: boolean;
+
+  /**
+   * Whether the engine reports a foreign key back under the name the
+   * declaration gave it.
+   *
+   * Separate from `foreignKeysInCreateTable` because they are separate facts and
+   * an engine can hold one without the other: MySQL emits keys inside `CREATE
+   * TABLE` and names them. Where this is false a declaration is matched to a
+   * live key by its columns, target and referential actions, since there is no
+   * name to match on and matching by one reads a table's own key as missing on
+   * every boot after the one that created it.
+   */
+  readonly namesForeignKeys: boolean;
+
+  createTable(schema: string, table: DeclaredTable): string[];
+  addColumn(schema: string, table: string, column: DeclaredColumn): string[];
+  alterColumn(schema: string, table: string, live: LiveColumn, column: DeclaredColumn): string[];
+  copyColumn(schema: string, table: string, from: string, to: string): string[];
+  createIndex(schema: string, table: string, index: DeclaredIndex): string[];
+  dropIndex(schema: string, table: string, index: string): string[];
+  addForeignKey(schema: string, table: string, fk: DeclaredForeignKey): string[];
+  dropForeignKey(schema: string, table: string, name: string): string[];
+
+  /**
+   * Whether this engine can reclaim an object of this kind at all.
+   *
+   * Asked BEFORE the drop is attempted, because a tombstone the engine cannot
+   * act on is otherwise permanent breakage rather than a one-off failure: it
+   * stays eligible, so every boot from then on fails in the same place, and the
+   * application never starts again. Reported instead, with the reason, and the
+   * tombstone is left standing.
+   */
+  canReclaim(id: SchemaObjectId): ChangeSafety;
+
+  /** Reclamation. Separated from the rest because these are the only destructive statements. */
+  dropColumn(schema: string, table: string, column: string): string[];
+  dropTable(schema: string, table: string): string[];
+}