@ultimat3/db 1.0.0

package/src/drift.ts

@@ -0,0 +1,148 @@
+// Single responsibility: prove the live schema and the migration ledger agree. Drift is the
+// failure an agent creates most often — it edits a table by hand, the next deploy diverges, and
+// nothing complains until production. The rendered `X_DB_DRIFT` output is byte-for-byte pinned
+// by the framework contract; `x verify` fails on it and `--json` carries every difference.
+
+import { baseClient, type DbClient } from './client';
+import { DbError } from './errors';
+import { findTable, introspect, type SchemaDescription, type TableDescription } from './introspect';
+import { type LedgerRow, type Migration, readLedger } from './migrate';
+
+export type DriftKind =
+  | 'unexpected-column'
+  | 'missing-column'
+  | 'unexpected-table'
+  | 'missing-table';
+
+export interface DriftDifference {
+  readonly kind: DriftKind;
+  readonly table: string;
+  readonly column: string | null;
+  readonly cause: string;
+  readonly fix: string;
+}
+
+export interface DriftReport {
+  readonly ok: boolean;
+  readonly differences: readonly DriftDifference[];
+}
+
+function unexpectedColumn(table: string, column: string): DriftDifference {
+  return {
+    kind: 'unexpected-column',
+    table,
+    column,
+    // Pinned by the contract. Do not reword without changing docs/errors/X_DB_DRIFT.
+    cause: `table "${table}" has column "${column}" not present in any migration`,
+    fix: `x db gen "add ${column}"`,
+  };
+}
+
+function missingColumn(table: string, column: string): DriftDifference {
+  return {
+    kind: 'missing-column',
+    table,
+    column,
+    cause: `table "${table}" is missing column "${column}" that migrations declare`,
+    fix: 'x db migrate',
+  };
+}
+
+function unexpectedTable(table: string): DriftDifference {
+  return {
+    kind: 'unexpected-table',
+    table,
+    column: null,
+    cause: `table "${table}" is not present in any migration`,
+    fix: `x db gen "add ${table}"`,
+  };
+}
+
+function missingTable(table: string): DriftDifference {
+  return {
+    kind: 'missing-table',
+    table,
+    column: null,
+    cause: `table "${table}" is declared by migrations but does not exist`,
+    fix: 'x db migrate',
+  };
+}
+
+function compareTable(live: TableDescription, expected: TableDescription): DriftDifference[] {
+  const differences: DriftDifference[] = [];
+  const expectedColumns = new Set(expected.columns.map((column) => column.name));
+  const liveColumns = new Set(live.columns.map((column) => column.name));
+  for (const column of live.columns) {
+    if (expectedColumns.has(column.name)) continue;
+    differences.push(unexpectedColumn(live.name, column.name));
+  }
+  for (const column of expected.columns) {
+    if (!liveColumns.has(column.name)) differences.push(missingColumn(live.name, column.name));
+  }
+  return differences;
+}
+
+/** Pure and total: the same inputs always produce the same ordered report. */
+export function diffSchema(live: SchemaDescription, expected: SchemaDescription): DriftReport {
+  const differences: DriftDifference[] = [];
+  for (const table of live.tables) {
+    const counterpart = findTable(expected, table.name);
+    if (counterpart === undefined) differences.push(unexpectedTable(table.name));
+    else differences.push(...compareTable(table, counterpart));
+  }
+  for (const table of expected.tables) {
+    if (findTable(live, table.name) === undefined) differences.push(missingTable(table.name));
+  }
+  differences.sort((a, b) => {
+    if (a.table !== b.table) return a.table < b.table ? -1 : 1;
+    if (a.kind !== b.kind) return a.kind < b.kind ? -1 : 1;
+    return (a.column ?? '') < (b.column ?? '') ? -1 : 1;
+  });
+  return { ok: differences.length === 0, differences };
+}
+
+export function driftError(difference: DriftDifference): DbError {
+  return new DbError({
+    code: 'X_DB_DRIFT',
+    cause: difference.cause,
+    fix: difference.fix,
+    meta: { kind: difference.kind, table: difference.table, column: difference.column },
+  });
+}
+
+/** Throws the first difference. `x verify` calls this; `x db drift --json` reads the report. */
+export function assertNoDrift(report: DriftReport): void {
+  const first = report.differences[0];
+  if (first !== undefined) throw driftError(first);
+}
+
+/**
+ * The schema migrations claim. Each generated migration carries the snapshot it leaves behind,
+ * so the newest applied one with a snapshot is the expectation — no SQL is re-parsed.
+ */
+export function expectedSchema(
+  migrations: readonly Migration[],
+  ledger: readonly LedgerRow[],
+): SchemaDescription {
+  const applied = new Set(ledger.map((row) => row.id));
+  const snapshots = [...migrations]
+    .filter((migration) => applied.has(migration.id) && migration.snapshot !== undefined)
+    .sort((a, b) => (a.id < b.id ? -1 : 1));
+  return snapshots[snapshots.length - 1]?.snapshot ?? { tables: [] };
+}
+
+export interface DriftOptions {
+  readonly migrations: readonly Migration[];
+  readonly client?: DbClient | undefined;
+  readonly schema?: string | undefined;
+}
+
+export async function checkDrift(options: DriftOptions): Promise<DriftReport> {
+  const client = options.client ?? baseClient();
+  const ledger = await readLedger(client);
+  const live = await introspect({
+    client,
+    ...(options.schema === undefined ? {} : { schema: options.schema }),
+  });
+  return diffSchema(live, expectedSchema(options.migrations, ledger));
+}

package/src/errors.ts

@@ -0,0 +1,150 @@
+// The database layer's stable error codes. Every factory produces the exact command that
+// fixes the situation — `X_DB_DRIFT` is the flagship and its rendering is byte-for-byte
+// pinned by the framework contract, so change its strings only with the contract.
+
+import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+
+/**
+ * Codes this package declares and owns. `X_DB_DRIFT` is db's: it is a statement about migrations
+ * against a schema, and `@ultimat3/entity` — which imports db — only throws it.
+ */
+export const DB_OWNED_ERROR_CODES = [
+  'X_DB_UNAVAILABLE',
+  'X_DB_DRIFT',
+  'X_MIGRATION_CONFLICT',
+  'X_MIGRATION_IRREVERSIBLE',
+  'X_SQL_UNSAFE',
+  'X_BRANCH_EXISTS',
+  'X_READONLY_VIOLATION',
+] as const;
+
+/** `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s. Never titled here, never registered here. */
+export const DB_BORROWED_ERROR_CODES = ['X_NOT_IMPLEMENTED'] as const;
+
+/** Every code db can throw: the ones it owns plus the ones it borrows. */
+export const DB_ERROR_CODES = [...DB_OWNED_ERROR_CODES, ...DB_BORROWED_ERROR_CODES] as const;
+
+export type DbOwnedErrorCode = (typeof DB_OWNED_ERROR_CODES)[number];
+export type DbErrorCode = (typeof DB_ERROR_CODES)[number];
+
+export const DB_ERROR_TITLES: Readonly<Record<DbOwnedErrorCode, string>> = {
+  X_DB_UNAVAILABLE: 'cannot reach the database',
+  X_DB_DRIFT: 'schema differs from migrations',
+  X_MIGRATION_CONFLICT: 'the migration ledger disagrees with this build',
+  X_MIGRATION_IRREVERSIBLE: 'this migration cannot be reversed without data loss',
+  X_SQL_UNSAFE: 'SQL was built by string interpolation',
+  X_BRANCH_EXISTS: 'that branch database already exists',
+  X_READONLY_VIOLATION: 'a mutating statement reached a read-only client',
+};
+
+// Registered unconditionally, in one call, so a second package claiming one of db's codes fails
+// loudly as X_ERROR_CODE_DUPLICATE at import instead of silently losing to whoever loaded first.
+registerErrorCodes(
+  Object.fromEntries(Object.entries(DB_ERROR_TITLES).map(([code, title]) => [code, { title }])),
+);
+
+export interface DbErrorInit {
+  readonly code: DbErrorCode;
+  readonly cause: string;
+  readonly fix: string;
+  readonly meta?: Readonly<Record<string, unknown>> | undefined;
+  readonly sourceError?: unknown;
+}
+
+export class DbError extends UltimateError {
+  override readonly name = 'DbError';
+  /**
+   * `code` is deliberately NOT re-declared here. `declare` cannot combine with `override`,
+   * and a plain re-declaration would shadow the property `UltimateError`'s constructor
+   * already assigned — under `useDefineForClassFields` that resets it to `undefined` at
+   * runtime. Callers get the narrow type from `DbErrorInit` at the construction site,
+   * which is where it matters.
+   */
+
+  constructor(init: DbErrorInit) {
+    super({
+      code: init.code,
+      cause: init.cause,
+      fix: init.fix,
+      docs: `https://ultimate.dev/errors/${init.code}`,
+      meta: init.meta,
+      sourceError: init.sourceError,
+    });
+  }
+}
+
+export const dbUnavailable = (detail: string, sourceError?: unknown): DbError =>
+  new DbError({
+    code: 'X_DB_UNAVAILABLE',
+    cause: detail,
+    fix: 'set DATABASE_URL to a reachable Postgres url, or run `x dev` to use the embedded PGlite',
+    sourceError,
+  });
+
+/** The contract's pinned wording. Mirror of `@ultimat3/entity`'s `dbDrift()` — keep in sync. */
+export const dbDrift = (tableName: string, columnName: string): DbError =>
+  new DbError({
+    code: 'X_DB_DRIFT',
+    cause: `table "${tableName}" has column "${columnName}" not present in any migration`,
+    fix: `x db gen "add ${columnName}"`,
+    meta: { table: tableName, column: columnName },
+  });
+
+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 });
+
+export const sqlUnsafe = (received: string, position: number): DbError =>
+  new DbError({
+    code: 'X_SQL_UNSAFE',
+    cause:
+      `interpolation #${position} in a sql\`\` template is ${received}, ` +
+      'which cannot be bound as a parameter',
+    fix: 'pass a scalar (it becomes $n), a nested sql`` fragment, or wrap audited SQL in raw()',
+    meta: { position, received },
+  });
+
+export const identifierUnsafe = (name: string): DbError =>
+  new DbError({
+    code: 'X_SQL_UNSAFE',
+    cause: `${JSON.stringify(name)} is not usable as a Postgres identifier`,
+    fix: 'pass a plain table/column name — identifiers cannot be bound as parameters',
+    meta: { name },
+  });
+
+export const branchExists = (branch: string): DbError =>
+  new DbError({
+    code: 'X_BRANCH_EXISTS',
+    cause: `database "${branch}" already exists`,
+    fix: `x db branch drop ${branch}   # then re-create, or pick another name`,
+    meta: { branch },
+  });
+
+/**
+ * An unvalidated branch name is spliced into `CREATE DATABASE "<name>"`, so a bad name is an
+ * injection vector, not a typo — hence `X_SQL_UNSAFE` rather than a validation code.
+ */
+export const branchNameInvalid = (branch: string): DbError =>
+  new DbError({
+    code: 'X_SQL_UNSAFE',
+    cause: `branch name "${branch}" is not [a-z0-9_-]+`,
+    fix: 'x db branch create <name>   # lowercase letters, digits, underscore and dash only',
+    meta: { branch },
+  });
+
+export const readonlyViolation = (statement: string, keyword: string): DbError =>
+  new DbError({
+    code: 'X_READONLY_VIOLATION',
+    cause: `a read-only client received a ${keyword.toUpperCase()} statement: ${statement}`,
+    fix: 'use db() instead of readOnly(db()), or rewrite the statement as a SELECT',
+    meta: { keyword },
+  });
+
+export const dbNotImplemented = (feature: string, fix: string): DbError =>
+  new DbError({
+    code: 'X_NOT_IMPLEMENTED',
+    cause: `${feature} is not implemented by this driver`,
+    fix,
+  });

package/src/fake.ts

@@ -0,0 +1,79 @@
+// Single responsibility: a `DbClient` that records instead of connecting. Every test in this
+// package — and every app test that wants to assert "the action wrote one row" — runs against it
+// via `setDbClient()`. Recording the exact text and values is what makes migration, transaction
+// and drift behaviour assertable with no database and no Docker.
+
+import type { DbClient } from './client';
+import type { SqlFragment } from './sql';
+
+export interface RecordedStatement {
+  readonly text: string;
+  readonly values: readonly unknown[];
+}
+
+export interface StubResponse {
+  readonly rows?: readonly unknown[] | undefined;
+  readonly affected?: number | undefined;
+}
+
+export interface RecordingClient extends DbClient {
+  readonly statements: readonly RecordedStatement[];
+  /** Statement texts with runs of whitespace collapsed — what assertions actually match on. */
+  readonly texts: readonly string[];
+  /** Later registrations win, so a test can narrow a general stub. */
+  on(match: string | RegExp, response: StubResponse): RecordingClient;
+  reset(): void;
+}
+
+interface Stub {
+  readonly match: string | RegExp;
+  readonly response: StubResponse;
+}
+
+const squash = (text: string): string => text.replace(/\s+/g, ' ').trim();
+
+function matches(stub: Stub, text: string): boolean {
+  return typeof stub.match === 'string' ? text.includes(stub.match) : stub.match.test(text);
+}
+
+export function createRecordingClient(): RecordingClient {
+  const statements: RecordedStatement[] = [];
+  const stubs: Stub[] = [];
+
+  function respond(fragment: SqlFragment): StubResponse {
+    statements.push({ text: fragment.text, values: [...fragment.values] });
+    const text = squash(fragment.text);
+    for (let index = stubs.length - 1; index >= 0; index -= 1) {
+      const stub = stubs[index];
+      if (stub !== undefined && matches(stub, text)) return stub.response;
+    }
+    return {};
+  }
+
+  const client: RecordingClient = {
+    statements,
+    get texts(): readonly string[] {
+      return statements.map((statement) => squash(statement.text));
+    },
+    on(match: string | RegExp, response: StubResponse): RecordingClient {
+      stubs.push({ match, response });
+      return client;
+    },
+    reset(): void {
+      statements.length = 0;
+      stubs.length = 0;
+    },
+    async query<T>(fragment: SqlFragment): Promise<readonly T[]> {
+      return (respond(fragment).rows ?? []) as readonly T[];
+    },
+    async one<T>(fragment: SqlFragment): Promise<T | null> {
+      const rows = respond(fragment).rows ?? [];
+      return (rows[0] as T | undefined) ?? null;
+    },
+    async execute(fragment: SqlFragment): Promise<number> {
+      const response = respond(fragment);
+      return response.affected ?? response.rows?.length ?? 0;
+    },
+  };
+  return client;
+}

package/src/generate.ts

@@ -0,0 +1,310 @@
+// Single responsibility: turn an entity snapshot into a timestamped, reversible migration.
+// `db` is tier 2 and cannot import `@ultimat3/entity`, so the snapshot arrives as a parameter —
+// the CLI passes `describeEntities()` and the types below mirror `EntityDescription` field for
+// field. Every generated migration must be reversible; a drop that loses data refuses instead.
+
+import { migrationIrreversible } from './errors';
+import {
+  type ColumnDescription,
+  findTable,
+  type SchemaDescription,
+  type TableDescription,
+} from './introspect';
+
+/** Structurally assignment-compatible with `@ultimat3/entity`'s `ColumnDescription`. */
+export interface ColumnDescriptionLike {
+  readonly property: string;
+  readonly column: string;
+  readonly kind: string;
+  readonly notNull: boolean;
+  readonly primaryKey: boolean;
+  readonly unique: boolean;
+  readonly hasDefault: boolean;
+  readonly check: string | null;
+  readonly references: string | null;
+}
+
+/** Structurally assignment-compatible with `@ultimat3/entity`'s `EntityDescription`. */
+export interface EntityDescriptionLike {
+  readonly name: string;
+  readonly table: string;
+  readonly primaryKey: readonly string[];
+  readonly columns: readonly ColumnDescriptionLike[];
+  /** Index names only, following entity's `<table>_<column>_idx` / `_key` convention. */
+  readonly indexes: readonly string[];
+}
+
+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',
+};
+
+function sqlType(kind: string): string {
+  return SQL_TYPES[kind] ?? kind;
+}
+
+/**
+ * Entity descriptions carry `hasDefault` but not the expression, so the two generated defaults
+ * are inferred from the blessed column helpers. Anything else is left to a follow-up migration.
+ */
+function defaultExpression(column: ColumnDescriptionLike): string | null {
+  if (!column.hasDefault) return null;
+  if (column.kind === 'uuid' && column.primaryKey) return 'gen_random_uuid()';
+  if (column.kind === 'timestamptz') return 'now()';
+  return null;
+}
+
+function columnClause(column: ColumnDescriptionLike): string {
+  const parts = [`"${column.column}"`, sqlType(column.kind)];
+  const expression = defaultExpression(column);
+  if (expression !== null) parts.push(`default ${expression}`);
+  if (column.notNull) parts.push('not null');
+  if (column.unique && !column.primaryKey) parts.push('unique');
+  if (column.check !== null) parts.push(`check (${column.check})`);
+  if (column.references !== null) {
+    const [refTable = column.references, refColumn = 'id'] = column.references.split('.');
+    parts.push(`references "${refTable}" ("${refColumn}")`);
+  }
+  return parts.join(' ');
+}
+
+export interface ParsedIndex {
+  readonly name: string;
+  readonly columns: readonly string[];
+  readonly unique: boolean;
+}
+
+/**
+ * A `unique` column clause already creates an index, and Postgres names it exactly what the
+ * entity's own convention names it — `<table>_<column>_key`. Emitting `create unique index` for
+ * it too is the same index twice: `42P07`, and a migration that cannot be applied at all.
+ * Mirrors the rule `entity()` already applies to a foreign key indexing its own column.
+ */
+function impliedByColumnClause(
+  entity: EntityDescriptionLike,
+  index: ParsedIndex,
+  added: ReadonlySet<string>,
+): boolean {
+  const [only] = index.columns;
+  if (!index.unique || index.columns.length !== 1 || only === undefined) return false;
+  const column = entity.columns.find((each) => each.column === only);
+  // `columnClause` writes `unique` under exactly this condition — keep the two in step.
+  return column !== undefined && column.unique && !column.primaryKey && added.has(only);
+}
+
+/** Entity only records index names; the convention is what makes the columns recoverable. */
+export function parseIndexName(table: string, name: string): ParsedIndex {
+  const unique = name.endsWith('_key');
+  const prefix = `${table}_`;
+  const withoutTable = name.startsWith(prefix) ? name.slice(prefix.length) : name;
+  const middle = withoutTable.replace(/_(idx|key)$/, '');
+  return { name, columns: middle === '' ? [] : [middle], unique };
+}
+
+export function snapshotOf(entities: readonly EntityDescriptionLike[]): SchemaDescription {
+  const tables = [...entities]
+    .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,
+        }));
+      return {
+        schema: 'public',
+        name: entity.table,
+        columns,
+        primaryKey: [...entity.primaryKey],
+        indexes: entity.indexes.map((name) => ({
+          ...parseIndexName(entity.table, name),
+          primary: false,
+        })),
+        foreignKeys: [],
+      };
+    });
+  return { tables };
+}
+
+function createTable(entity: EntityDescriptionLike): readonly string[] {
+  const clauses = entity.columns.map(columnClause);
+  if (entity.primaryKey.length > 0) {
+    clauses.push(`primary key (${entity.primaryKey.map((key) => `"${key}"`).join(', ')})`);
+  }
+  const statements = [`create table "${entity.table}" (\n  ${clauses.join(',\n  ')}\n);`];
+  // Every column of a new table carries its own clause, so every `unique` one brings its index.
+  const added = new Set(entity.columns.map((column) => column.column));
+  for (const name of entity.indexes) {
+    const index = parseIndexName(entity.table, name);
+    if (index.columns.length === 0 || impliedByColumnClause(entity, index, added)) continue;
+    statements.push(createIndex(entity.table, index));
+  }
+  return statements;
+}
+
+function createIndex(table: string, index: ParsedIndex): string {
+  const kind = index.unique ? 'create unique index' : 'create index';
+  const columns = index.columns.map((column) => `"${column}"`).join(', ');
+  return `${kind} "${index.name}" on "${table}" (${columns});`;
+}
+
+interface Plan {
+  readonly up: string[];
+  readonly down: string[];
+}
+
+/**
+ * Skipping an existing column by name alone missed the type moving under it: a table created
+ * while money's currency was bare `char` keeps `char(1)` and rejects every ISO 4217 code, yet the
+ * snapshot this run records claims `char(3)` — two claims with no statement between them. Both
+ * sides are generated spellings (`current` is a previous migration's own snapshot), so any
+ * difference is a real kind change, not a catalog alias.
+ */
+function retypeColumn(
+  table: string,
+  column: ColumnDescriptionLike,
+  recorded: ColumnDescription,
+  plan: Plan,
+): void {
+  const wanted = sqlType(column.kind);
+  if (recorded.dataType === wanted) return;
+  const alter = (type: string): string =>
+    `alter table "${table}" alter column "${column.column}" type ${type} ` +
+    `using "${column.column}"::${type};`;
+  plan.up.push(alter(wanted));
+  plan.down.push(alter(recorded.dataType));
+}
+
+function diffTable(entity: EntityDescriptionLike, live: TableDescription, plan: Plan): void {
+  const existing = new Map(live.columns.map((column) => [column.name, column]));
+  const added = new Set<string>();
+  for (const column of entity.columns) {
+    const recorded = existing.get(column.column);
+    if (recorded !== undefined) {
+      retypeColumn(entity.table, column, recorded, plan);
+      continue;
+    }
+    added.add(column.column);
+    // A NOT NULL add with no default cannot succeed on a populated table; emit it nullable and
+    // leave the agent the exact follow-up rather than a migration that fails at 3am.
+    const nullable = column.notNull && defaultExpression(column) === null;
+    const clause = nullable ? columnClause({ ...column, notNull: false }) : columnClause(column);
+    plan.up.push(`alter table "${entity.table}" add column ${clause};`);
+    if (nullable) {
+      plan.up.push(
+        `-- backfill "${column.column}", then: ` +
+          `alter table "${entity.table}" alter column "${column.column}" set not null;`,
+      );
+    }
+    plan.down.push(`alter table "${entity.table}" drop column "${column.column}";`);
+  }
+
+  const indexed = new Set(live.indexes.map((index) => index.name));
+  for (const name of entity.indexes) {
+    if (indexed.has(name)) continue;
+    const index = parseIndexName(entity.table, name);
+    // `added` only: an index over a column that was already there is implied by no clause this
+    // migration emits, so it still needs a statement of its own.
+    if (index.columns.length === 0 || impliedByColumnClause(entity, index, added)) continue;
+    plan.up.push(createIndex(entity.table, index));
+    plan.down.push(`drop index "${name}";`);
+  }
+}
+
+export interface GenerateOptions {
+  readonly entities: readonly EntityDescriptionLike[];
+  /** The schema migrations already declare — `expectedSchema(migrations, ledger)`. */
+  readonly current?: SchemaDescription | undefined;
+  readonly name: string;
+  readonly now?: Date | undefined;
+  /** Allow a DROP COLUMN whose down cannot restore the data. `x db gen --allow-destructive`. */
+  readonly allowDestructive?: boolean | undefined;
+}
+
+export interface GeneratedMigration {
+  readonly id: string;
+  readonly name: string;
+  readonly fileName: string;
+  readonly up: string;
+  readonly down: string;
+  readonly snapshot: SchemaDescription;
+}
+
+export function migrationStamp(now: Date): string {
+  return now.toISOString().replace(/[-:T]/g, '').slice(0, 14);
+}
+
+export function slugify(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '');
+}
+
+export function generateMigration(options: GenerateOptions): GeneratedMigration {
+  const current = options.current ?? { tables: [] };
+  const plan: Plan = { up: [], down: [] };
+  const wanted = new Set(options.entities.map((entity) => entity.table));
+
+  for (const entity of options.entities) {
+    const live = findTable(current, entity.table);
+    if (live === undefined) {
+      plan.up.push(...createTable(entity));
+      plan.down.push(`drop table "${entity.table}";`);
+      continue;
+    }
+    diffTable(entity, live, plan);
+    const kept = new Set(entity.columns.map((column) => column.column));
+    for (const column of live.columns) {
+      if (kept.has(column.name)) continue;
+      if (options.allowDestructive !== true) {
+        throw migrationIrreversible(
+          `dropping "${entity.table}"."${column.name}" discards its rows and cannot be undone`,
+          `x db gen "${options.name}" --allow-destructive   # or keep the column and deprecate it`,
+        );
+      }
+      plan.up.push(`alter table "${entity.table}" drop column "${column.name}";`);
+      plan.down.push(
+        `alter table "${entity.table}" add column "${column.name}" ${column.dataType};` +
+          ' -- data is not restored',
+      );
+    }
+  }
+
+  for (const table of current.tables) {
+    if (wanted.has(table.name)) continue;
+    if (options.allowDestructive !== true) {
+      throw migrationIrreversible(
+        `dropping table "${table.name}" discards every row and cannot be undone`,
+        `x db gen "${options.name}" --allow-destructive   # or delete the entity in two releases`,
+      );
+    }
+    plan.up.push(`drop table "${table.name}";`);
+    plan.down.push(`-- "${table.name}" cannot be restored; recover it from a backup`);
+  }
+
+  const id = `${migrationStamp(options.now ?? new Date())}_${slugify(options.name)}`;
+  return {
+    id,
+    name: options.name,
+    fileName: `migrations/${id}.sql`,
+    up: plan.up.join('\n'),
+    // Reverse order: the last thing created is the first thing dropped.
+    down: [...plan.down].reverse().join('\n'),
+    snapshot: snapshotOf(options.entities),
+  };
+}