@zmdb/migrations 1.0.0-beta.1

package/src/introspect/__fixtures__/mysql-8.4.11.json

@@ -0,0 +1,371 @@
+{
+  "provenance": {
+    "capturedOn": "2026-09-04",
+    "captureFormat": "mysql --batch --raw; every non-NULL catalog cell is retained as text",
+    "image": "docker.io/library/mysql:8.4",
+    "imageCreated": "2026-07-27T22:08:26.634911873Z",
+    "imageDigest": "sha256:1d6b6a8fcee8ff758ff151d017f5203cd06792a0e698f0a593c9dfcb14609cf0",
+    "imageId": "bced325a4ab7aec848f4688371c7433351dcb5dba26fbcc29c67727d898ae5cb",
+    "schema": "zmdb430",
+    "server": {
+      "version": "8.4.11",
+      "versionComment": "MySQL Community Server - GPL",
+      "versionCompileMachine": "x86_64",
+      "versionCompileOs": "Linux"
+    }
+  },
+  "ddl": [
+    "CREATE TABLE accounts (id BIGINT NOT NULL AUTO_INCREMENT, email VARCHAR(255) NOT NULL, active TINYINT(1) NOT NULL DEFAULT 1, balance DECIMAL(12,2) NULL, status ENUM('active','disabled') NOT NULL DEFAULT 'active', created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), nickname TEXT NULL, PRIMARY KEY (id), UNIQUE KEY accounts_email_uq (email)) ENGINE=InnoDB",
+    "CREATE TABLE memberships (tenant_id INT NOT NULL, user_id INT NOT NULL, label VARCHAR(50) NULL, PRIMARY KEY (user_id, tenant_id)) ENGINE=InnoDB",
+    "CREATE TABLE posts (id INT NOT NULL AUTO_INCREMENT, account_id BIGINT NOT NULL, slug VARCHAR(120) NOT NULL, body LONGTEXT NULL, PRIMARY KEY (id), KEY posts_account_idx (account_id), CONSTRAINT posts_account_fkey FOREIGN KEY (account_id) REFERENCES accounts (id) ON DELETE CASCADE ON UPDATE RESTRICT) ENGINE=InnoDB"
+  ],
+  "queries": {
+    "columns": "SELECT TABLE_NAME, ORDINAL_POSITION, COLUMN_NAME, IS_NULLABLE, DATA_TYPE, COLUMN_TYPE, CHARACTER_MAXIMUM_LENGTH, NUMERIC_PRECISION, NUMERIC_SCALE, COLUMN_DEFAULT, EXTRA, GENERATION_EXPRESSION FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = DATABASE() ORDER BY TABLE_NAME, ORDINAL_POSITION",
+    "keyColumnUsage": "SELECT TABLE_NAME, CONSTRAINT_NAME, ORDINAL_POSITION, POSITION_IN_UNIQUE_CONSTRAINT, COLUMN_NAME, REFERENCED_TABLE_NAME, REFERENCED_COLUMN_NAME FROM information_schema.KEY_COLUMN_USAGE WHERE TABLE_SCHEMA = DATABASE() ORDER BY TABLE_NAME, CONSTRAINT_NAME, ORDINAL_POSITION",
+    "referentialConstraints": "SELECT TABLE_NAME, CONSTRAINT_NAME, UNIQUE_CONSTRAINT_NAME, MATCH_OPTION, UPDATE_RULE, DELETE_RULE FROM information_schema.REFERENTIAL_CONSTRAINTS WHERE CONSTRAINT_SCHEMA = DATABASE() ORDER BY TABLE_NAME, CONSTRAINT_NAME",
+    "statistics": "SELECT TABLE_NAME, INDEX_NAME, NON_UNIQUE, SEQ_IN_INDEX, COLUMN_NAME, EXPRESSION, INDEX_TYPE FROM information_schema.STATISTICS WHERE TABLE_SCHEMA = DATABASE() ORDER BY TABLE_NAME, INDEX_NAME, SEQ_IN_INDEX",
+    "tables": "SELECT TABLE_SCHEMA, TABLE_NAME, TABLE_TYPE, ENGINE FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE() ORDER BY TABLE_NAME"
+  },
+  "rows": {
+    "tables": [
+      {
+        "TABLE_SCHEMA": "zmdb430",
+        "TABLE_NAME": "accounts",
+        "TABLE_TYPE": "BASE TABLE",
+        "ENGINE": "InnoDB"
+      },
+      {
+        "TABLE_SCHEMA": "zmdb430",
+        "TABLE_NAME": "memberships",
+        "TABLE_TYPE": "BASE TABLE",
+        "ENGINE": "InnoDB"
+      },
+      {
+        "TABLE_SCHEMA": "zmdb430",
+        "TABLE_NAME": "posts",
+        "TABLE_TYPE": "BASE TABLE",
+        "ENGINE": "InnoDB"
+      }
+    ],
+    "columns": [
+      {
+        "TABLE_NAME": "accounts",
+        "ORDINAL_POSITION": "1",
+        "COLUMN_NAME": "id",
+        "IS_NULLABLE": "NO",
+        "DATA_TYPE": "bigint",
+        "COLUMN_TYPE": "bigint",
+        "CHARACTER_MAXIMUM_LENGTH": null,
+        "NUMERIC_PRECISION": "19",
+        "NUMERIC_SCALE": "0",
+        "COLUMN_DEFAULT": null,
+        "EXTRA": "auto_increment",
+        "GENERATION_EXPRESSION": ""
+      },
+      {
+        "TABLE_NAME": "accounts",
+        "ORDINAL_POSITION": "2",
+        "COLUMN_NAME": "email",
+        "IS_NULLABLE": "NO",
+        "DATA_TYPE": "varchar",
+        "COLUMN_TYPE": "varchar(255)",
+        "CHARACTER_MAXIMUM_LENGTH": "255",
+        "NUMERIC_PRECISION": null,
+        "NUMERIC_SCALE": null,
+        "COLUMN_DEFAULT": null,
+        "EXTRA": "",
+        "GENERATION_EXPRESSION": ""
+      },
+      {
+        "TABLE_NAME": "accounts",
+        "ORDINAL_POSITION": "3",
+        "COLUMN_NAME": "active",
+        "IS_NULLABLE": "NO",
+        "DATA_TYPE": "tinyint",
+        "COLUMN_TYPE": "tinyint(1)",
+        "CHARACTER_MAXIMUM_LENGTH": null,
+        "NUMERIC_PRECISION": "3",
+        "NUMERIC_SCALE": "0",
+        "COLUMN_DEFAULT": "1",
+        "EXTRA": "",
+        "GENERATION_EXPRESSION": ""
+      },
+      {
+        "TABLE_NAME": "accounts",
+        "ORDINAL_POSITION": "4",
+        "COLUMN_NAME": "balance",
+        "IS_NULLABLE": "YES",
+        "DATA_TYPE": "decimal",
+        "COLUMN_TYPE": "decimal(12,2)",
+        "CHARACTER_MAXIMUM_LENGTH": null,
+        "NUMERIC_PRECISION": "12",
+        "NUMERIC_SCALE": "2",
+        "COLUMN_DEFAULT": null,
+        "EXTRA": "",
+        "GENERATION_EXPRESSION": ""
+      },
+      {
+        "TABLE_NAME": "accounts",
+        "ORDINAL_POSITION": "5",
+        "COLUMN_NAME": "status",
+        "IS_NULLABLE": "NO",
+        "DATA_TYPE": "enum",
+        "COLUMN_TYPE": "enum('active','disabled')",
+        "CHARACTER_MAXIMUM_LENGTH": "8",
+        "NUMERIC_PRECISION": null,
+        "NUMERIC_SCALE": null,
+        "COLUMN_DEFAULT": "active",
+        "EXTRA": "",
+        "GENERATION_EXPRESSION": ""
+      },
+      {
+        "TABLE_NAME": "accounts",
+        "ORDINAL_POSITION": "6",
+        "COLUMN_NAME": "created_at",
+        "IS_NULLABLE": "NO",
+        "DATA_TYPE": "datetime",
+        "COLUMN_TYPE": "datetime(3)",
+        "CHARACTER_MAXIMUM_LENGTH": null,
+        "NUMERIC_PRECISION": null,
+        "NUMERIC_SCALE": null,
+        "COLUMN_DEFAULT": "CURRENT_TIMESTAMP(3)",
+        "EXTRA": "DEFAULT_GENERATED",
+        "GENERATION_EXPRESSION": ""
+      },
+      {
+        "TABLE_NAME": "accounts",
+        "ORDINAL_POSITION": "7",
+        "COLUMN_NAME": "nickname",
+        "IS_NULLABLE": "YES",
+        "DATA_TYPE": "text",
+        "COLUMN_TYPE": "text",
+        "CHARACTER_MAXIMUM_LENGTH": "65535",
+        "NUMERIC_PRECISION": null,
+        "NUMERIC_SCALE": null,
+        "COLUMN_DEFAULT": null,
+        "EXTRA": "",
+        "GENERATION_EXPRESSION": ""
+      },
+      {
+        "TABLE_NAME": "memberships",
+        "ORDINAL_POSITION": "1",
+        "COLUMN_NAME": "tenant_id",
+        "IS_NULLABLE": "NO",
+        "DATA_TYPE": "int",
+        "COLUMN_TYPE": "int",
+        "CHARACTER_MAXIMUM_LENGTH": null,
+        "NUMERIC_PRECISION": "10",
+        "NUMERIC_SCALE": "0",
+        "COLUMN_DEFAULT": null,
+        "EXTRA": "",
+        "GENERATION_EXPRESSION": ""
+      },
+      {
+        "TABLE_NAME": "memberships",
+        "ORDINAL_POSITION": "2",
+        "COLUMN_NAME": "user_id",
+        "IS_NULLABLE": "NO",
+        "DATA_TYPE": "int",
+        "COLUMN_TYPE": "int",
+        "CHARACTER_MAXIMUM_LENGTH": null,
+        "NUMERIC_PRECISION": "10",
+        "NUMERIC_SCALE": "0",
+        "COLUMN_DEFAULT": null,
+        "EXTRA": "",
+        "GENERATION_EXPRESSION": ""
+      },
+      {
+        "TABLE_NAME": "memberships",
+        "ORDINAL_POSITION": "3",
+        "COLUMN_NAME": "label",
+        "IS_NULLABLE": "YES",
+        "DATA_TYPE": "varchar",
+        "COLUMN_TYPE": "varchar(50)",
+        "CHARACTER_MAXIMUM_LENGTH": "50",
+        "NUMERIC_PRECISION": null,
+        "NUMERIC_SCALE": null,
+        "COLUMN_DEFAULT": null,
+        "EXTRA": "",
+        "GENERATION_EXPRESSION": ""
+      },
+      {
+        "TABLE_NAME": "posts",
+        "ORDINAL_POSITION": "1",
+        "COLUMN_NAME": "id",
+        "IS_NULLABLE": "NO",
+        "DATA_TYPE": "int",
+        "COLUMN_TYPE": "int",
+        "CHARACTER_MAXIMUM_LENGTH": null,
+        "NUMERIC_PRECISION": "10",
+        "NUMERIC_SCALE": "0",
+        "COLUMN_DEFAULT": null,
+        "EXTRA": "auto_increment",
+        "GENERATION_EXPRESSION": ""
+      },
+      {
+        "TABLE_NAME": "posts",
+        "ORDINAL_POSITION": "2",
+        "COLUMN_NAME": "account_id",
+        "IS_NULLABLE": "NO",
+        "DATA_TYPE": "bigint",
+        "COLUMN_TYPE": "bigint",
+        "CHARACTER_MAXIMUM_LENGTH": null,
+        "NUMERIC_PRECISION": "19",
+        "NUMERIC_SCALE": "0",
+        "COLUMN_DEFAULT": null,
+        "EXTRA": "",
+        "GENERATION_EXPRESSION": ""
+      },
+      {
+        "TABLE_NAME": "posts",
+        "ORDINAL_POSITION": "3",
+        "COLUMN_NAME": "slug",
+        "IS_NULLABLE": "NO",
+        "DATA_TYPE": "varchar",
+        "COLUMN_TYPE": "varchar(120)",
+        "CHARACTER_MAXIMUM_LENGTH": "120",
+        "NUMERIC_PRECISION": null,
+        "NUMERIC_SCALE": null,
+        "COLUMN_DEFAULT": null,
+        "EXTRA": "",
+        "GENERATION_EXPRESSION": ""
+      },
+      {
+        "TABLE_NAME": "posts",
+        "ORDINAL_POSITION": "4",
+        "COLUMN_NAME": "body",
+        "IS_NULLABLE": "YES",
+        "DATA_TYPE": "longtext",
+        "COLUMN_TYPE": "longtext",
+        "CHARACTER_MAXIMUM_LENGTH": "4294967295",
+        "NUMERIC_PRECISION": null,
+        "NUMERIC_SCALE": null,
+        "COLUMN_DEFAULT": null,
+        "EXTRA": "",
+        "GENERATION_EXPRESSION": ""
+      }
+    ],
+    "statistics": [
+      {
+        "TABLE_NAME": "accounts",
+        "INDEX_NAME": "accounts_email_uq",
+        "NON_UNIQUE": "0",
+        "SEQ_IN_INDEX": "1",
+        "COLUMN_NAME": "email",
+        "EXPRESSION": null,
+        "INDEX_TYPE": "BTREE"
+      },
+      {
+        "TABLE_NAME": "accounts",
+        "INDEX_NAME": "PRIMARY",
+        "NON_UNIQUE": "0",
+        "SEQ_IN_INDEX": "1",
+        "COLUMN_NAME": "id",
+        "EXPRESSION": null,
+        "INDEX_TYPE": "BTREE"
+      },
+      {
+        "TABLE_NAME": "memberships",
+        "INDEX_NAME": "PRIMARY",
+        "NON_UNIQUE": "0",
+        "SEQ_IN_INDEX": "1",
+        "COLUMN_NAME": "user_id",
+        "EXPRESSION": null,
+        "INDEX_TYPE": "BTREE"
+      },
+      {
+        "TABLE_NAME": "memberships",
+        "INDEX_NAME": "PRIMARY",
+        "NON_UNIQUE": "0",
+        "SEQ_IN_INDEX": "2",
+        "COLUMN_NAME": "tenant_id",
+        "EXPRESSION": null,
+        "INDEX_TYPE": "BTREE"
+      },
+      {
+        "TABLE_NAME": "posts",
+        "INDEX_NAME": "posts_account_idx",
+        "NON_UNIQUE": "1",
+        "SEQ_IN_INDEX": "1",
+        "COLUMN_NAME": "account_id",
+        "EXPRESSION": null,
+        "INDEX_TYPE": "BTREE"
+      },
+      {
+        "TABLE_NAME": "posts",
+        "INDEX_NAME": "PRIMARY",
+        "NON_UNIQUE": "0",
+        "SEQ_IN_INDEX": "1",
+        "COLUMN_NAME": "id",
+        "EXPRESSION": null,
+        "INDEX_TYPE": "BTREE"
+      }
+    ],
+    "keyColumnUsage": [
+      {
+        "TABLE_NAME": "accounts",
+        "CONSTRAINT_NAME": "accounts_email_uq",
+        "ORDINAL_POSITION": "1",
+        "POSITION_IN_UNIQUE_CONSTRAINT": null,
+        "COLUMN_NAME": "email",
+        "REFERENCED_TABLE_NAME": null,
+        "REFERENCED_COLUMN_NAME": null
+      },
+      {
+        "TABLE_NAME": "accounts",
+        "CONSTRAINT_NAME": "PRIMARY",
+        "ORDINAL_POSITION": "1",
+        "POSITION_IN_UNIQUE_CONSTRAINT": null,
+        "COLUMN_NAME": "id",
+        "REFERENCED_TABLE_NAME": null,
+        "REFERENCED_COLUMN_NAME": null
+      },
+      {
+        "TABLE_NAME": "memberships",
+        "CONSTRAINT_NAME": "PRIMARY",
+        "ORDINAL_POSITION": "1",
+        "POSITION_IN_UNIQUE_CONSTRAINT": null,
+        "COLUMN_NAME": "user_id",
+        "REFERENCED_TABLE_NAME": null,
+        "REFERENCED_COLUMN_NAME": null
+      },
+      {
+        "TABLE_NAME": "memberships",
+        "CONSTRAINT_NAME": "PRIMARY",
+        "ORDINAL_POSITION": "2",
+        "POSITION_IN_UNIQUE_CONSTRAINT": null,
+        "COLUMN_NAME": "tenant_id",
+        "REFERENCED_TABLE_NAME": null,
+        "REFERENCED_COLUMN_NAME": null
+      },
+      {
+        "TABLE_NAME": "posts",
+        "CONSTRAINT_NAME": "posts_account_fkey",
+        "ORDINAL_POSITION": "1",
+        "POSITION_IN_UNIQUE_CONSTRAINT": "1",
+        "COLUMN_NAME": "account_id",
+        "REFERENCED_TABLE_NAME": "accounts",
+        "REFERENCED_COLUMN_NAME": "id"
+      },
+      {
+        "TABLE_NAME": "posts",
+        "CONSTRAINT_NAME": "PRIMARY",
+        "ORDINAL_POSITION": "1",
+        "POSITION_IN_UNIQUE_CONSTRAINT": null,
+        "COLUMN_NAME": "id",
+        "REFERENCED_TABLE_NAME": null,
+        "REFERENCED_COLUMN_NAME": null
+      }
+    ],
+    "referentialConstraints": [
+      {
+        "TABLE_NAME": "posts",
+        "CONSTRAINT_NAME": "posts_account_fkey",
+        "UNIQUE_CONSTRAINT_NAME": "PRIMARY",
+        "MATCH_OPTION": "NONE",
+        "UPDATE_RULE": "RESTRICT",
+        "DELETE_RULE": "CASCADE"
+      }
+    ]
+  }
+}

package/src/introspect/common.ts

@@ -0,0 +1,203 @@
+import { type CatalogSelection, type CatalogWarning, type CompiledQuery, type ReferentialAction } from '@zmdb/sql';
+
+export {
+  type CatalogColumnSnapshot,
+  type CatalogForeignKeySnapshot,
+  type CatalogIndexColumn,
+  type CatalogIndexSnapshot,
+  type CatalogSchemaSnapshot,
+  type CatalogSelection,
+  type CatalogTableSnapshot,
+  type CatalogWarning,
+  type IntrospectionDriver,
+  type Introspector,
+  type IntrospectOptions,
+  type ReferentialAction,
+} from '@zmdb/sql';
+export { normalizeDriftSnapshot } from './drift.js';
+
+export class CatalogRowError extends TypeError {
+  readonly catalog: string;
+  readonly row: number;
+  readonly field: string;
+  readonly expected: string;
+
+  constructor(catalog: string, row: number, field: string, expected: string, value: unknown) {
+    super(`${catalog} row ${String(row)} field "${field}" must be ${expected}; received ${describeValue(value)}`);
+    this.name = 'CatalogRowError';
+    this.catalog = catalog;
+    this.row = row;
+    this.field = field;
+    this.expected = expected;
+  }
+}
+
+function describeValue(value: unknown): string {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'an array';
+  return typeof value;
+}
+
+function valueAt(row: Readonly<Record<string, unknown>>, field: string): unknown {
+  return Reflect.get(row, field);
+}
+
+export function textField(
+  row: Readonly<Record<string, unknown>>,
+  field: string,
+  catalog: string,
+  index: number,
+): string {
+  const value = valueAt(row, field);
+  if (typeof value !== 'string') throw new CatalogRowError(catalog, index, field, 'a string', value);
+  return value;
+}
+
+export function nullableTextField(
+  row: Readonly<Record<string, unknown>>,
+  field: string,
+  catalog: string,
+  index: number,
+): string | null {
+  const value = valueAt(row, field);
+  if (value === null) return null;
+  if (typeof value !== 'string') {
+    throw new CatalogRowError(catalog, index, field, 'a string or null', value);
+  }
+  return value;
+}
+
+export function integerField(
+  row: Readonly<Record<string, unknown>>,
+  field: string,
+  catalog: string,
+  index: number,
+): number {
+  const value = valueAt(row, field);
+  if (typeof value === 'number' && Number.isSafeInteger(value)) return value;
+  if (typeof value === 'string' && /^-?\d+$/.test(value)) {
+    const parsed = Number(value);
+    if (Number.isSafeInteger(parsed)) return parsed;
+  }
+  throw new CatalogRowError(catalog, index, field, 'a safe integer or decimal integer string', value);
+}
+
+export function nullableIntegerField(
+  row: Readonly<Record<string, unknown>>,
+  field: string,
+  catalog: string,
+  index: number,
+): number | null {
+  const value = valueAt(row, field);
+  if (value === null) return null;
+  return integerField(row, field, catalog, index);
+}
+
+export function flagField(
+  row: Readonly<Record<string, unknown>>,
+  field: string,
+  catalog: string,
+  index: number,
+): boolean {
+  const value = integerField(row, field, catalog, index);
+  if (value === 0) return false;
+  if (value === 1) return true;
+  throw new CatalogRowError(catalog, index, field, '0 or 1', valueAt(row, field));
+}
+
+export function booleanField(
+  row: Readonly<Record<string, unknown>>,
+  field: string,
+  catalog: string,
+  index: number,
+): boolean {
+  const value = valueAt(row, field);
+  if (typeof value === 'boolean') return value;
+  throw new CatalogRowError(catalog, index, field, 'a boolean', value);
+}
+
+export function query(text: string, parameters: readonly unknown[] = []): CompiledQuery {
+  return { text, parameters };
+}
+
+function globExpression(glob: string): RegExp {
+  let source = '^';
+  for (const character of glob) {
+    if (character === '*') source += '.*';
+    else if (character === '?') source += '.';
+    else source += character.replace(/[\\^$.*+?()[\]{}|]/g, '\\$&');
+  }
+  return new RegExp(`${source}$`);
+}
+
+function matchesAny(name: string, globs: readonly string[]): boolean {
+  return globs.some(glob => globExpression(glob).test(name));
+}
+
+export function tableSelected(name: string, selection: CatalogSelection): boolean {
+  const include = selection.include;
+  if (include !== undefined && include.length > 0 && !matchesAny(name, include)) return false;
+  const exclude = selection.exclude ?? ['_zmdb_migrations'];
+  return !matchesAny(name, exclude);
+}
+
+export function action(value: string, catalog: string, row: number, field: string): ReferentialAction {
+  const normalized = value.toLowerCase().replaceAll('_', ' ');
+  switch (normalized) {
+    case 'no action':
+    case 'restrict':
+    case 'cascade':
+    case 'set null':
+    case 'set default':
+      return normalized;
+    default:
+      throw new CatalogRowError(catalog, row, field, 'a referential action', value);
+  }
+}
+
+export function deterministicForeignKeyName(table: string, columns: readonly string[]): string {
+  return `${table}_${columns.join('_')}_fkey`;
+}
+
+export function sortByName<T extends { readonly name: string }>(values: readonly T[]): readonly T[] {
+  return values.toSorted((left, right) => left.name.localeCompare(right.name));
+}
+
+export function sortWarnings(values: readonly CatalogWarning[]): readonly CatalogWarning[] {
+  return values.toSorted(
+    (left, right) =>
+      left.table.localeCompare(right.table) ||
+      (left.column ?? '').localeCompare(right.column ?? '') ||
+      left.reason.localeCompare(right.reason),
+  );
+}
+
+export function splitSqlList(value: string): readonly string[] {
+  const parts: string[] = [];
+  let start = 0;
+  let depth = 0;
+  let quote: "'" | '"' | '`' | undefined;
+
+  for (let index = 0; index < value.length; index += 1) {
+    const character = value[index];
+    if (quote !== undefined) {
+      if (character === quote) {
+        if (value[index + 1] === quote) index += 1;
+        else quote = undefined;
+      }
+      continue;
+    }
+    if (character === "'" || character === '"' || character === '`') {
+      quote = character;
+      continue;
+    }
+    if (character === '(') depth += 1;
+    else if (character === ')') depth -= 1;
+    else if (character === ',' && depth === 0) {
+      parts.push(value.slice(start, index).trim());
+      start = index + 1;
+    }
+  }
+  parts.push(value.slice(start).trim());
+  return parts;
+}