@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/server/migrate/files.js

@@ -0,0 +1,141 @@
+/**
+ * A migrations directory in Flyway's format: what is in it, and what each
+ * file's history row must say.
+ *
+ * The format is Flyway's so a team already on Flyway keeps its files, and can
+ * switch either way: `V3__add_payoff_quote.sql` is version 3, "add payoff
+ * quote"; `R__views.sql` is repeatable, run again whenever it changes; the
+ * directory is read recursively and a file's script is its path under it.
+ * The checksum is Flyway's own: CRC32 over the file's lines as UTF-8, with the
+ * line breaks and a leading byte-order mark left out, as a signed 32-bit
+ * integer — checked against flyway-core 13.8 in test/migrate.test.ts, so
+ * `flyway validate` and `tablewalk migrate validate` agree about a file.
+ *
+ * A file may carry a Flyway script config beside it (`V4__index.sql.conf`)
+ * whose one understood line is `executeInTransaction=false`, for a statement
+ * PostgreSQL will not run in a transaction (`CREATE INDEX CONCURRENTLY`).
+ */
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { crc32 } from 'node:zlib';
+const VERSIONED = /^V(\d+(?:[._]\d+)*)__(.+)\.sql$/;
+const REPEATABLE = /^R__(.+)\.sql$/;
+/** Flyway's checksum of a script's text. */
+export function flywayChecksum(text) {
+    const body = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    const lines = body.split(/\r\n|\r|\n/);
+    // A final line break ends the last line; it does not start another (Java's readLine).
+    if (lines.length && lines[lines.length - 1] === '')
+        lines.pop();
+    let sum = 0;
+    for (const line of lines)
+        sum = crc32(Buffer.from(line, 'utf8'), sum);
+    return sum | 0;
+}
+/** Flyway's order of versions: dotted parts compared as numbers, a missing part as 0. */
+export function compareVersions(a, b) {
+    const left = a.split('.').map(BigInt);
+    const right = b.split('.').map(BigInt);
+    for (let i = 0; i < Math.max(left.length, right.length); i++) {
+        const x = left[i] ?? 0n;
+        const y = right[i] ?? 0n;
+        if (x !== y)
+            return x < y ? -1 : 1;
+    }
+    return 0;
+}
+function transactional(path) {
+    const conf = `${path}.conf`;
+    if (!existsSync(conf))
+        return true;
+    for (const raw of readFileSync(conf, 'utf8').split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const match = /^executeInTransaction\s*=\s*(true|false)$/.exec(line);
+        if (!match)
+            throw new Error(`${conf}: "${line}" is not understood; the one setting a script config takes here is executeInTransaction=false.`);
+        return match[1] === 'true';
+    }
+    return true;
+}
+/** Every migration under `dir`, versioned ones in version order, then the repeatables by description. */
+export function readMigrations(dir) {
+    if (!existsSync(dir) || !statSync(dir).isDirectory())
+        return { dir, files: [], ignored: [] };
+    const files = [];
+    const ignored = [];
+    for (const entry of readdirSync(dir, { recursive: true, withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith('.sql'))
+            continue;
+        const path = join(entry.parentPath, entry.name);
+        const script = relative(dir, path).split(sep).join('/');
+        const versioned = VERSIONED.exec(entry.name);
+        const repeatable = REPEATABLE.exec(entry.name);
+        if (!versioned && !repeatable) {
+            if (/^[VRUB]\d*_/i.test(entry.name))
+                ignored.push(script);
+            continue;
+        }
+        const sql = readFileSync(path, 'utf8');
+        files.push({
+            kind: versioned ? 'versioned' : 'repeatable',
+            ...(versioned ? { version: versioned[1].replace(/_/g, '.') } : {}),
+            description: (versioned ? versioned[2] : repeatable[1]).replace(/_/g, ' '),
+            script,
+            path,
+            sql,
+            checksum: flywayChecksum(sql),
+            transactional: transactional(path),
+        });
+    }
+    files.sort((a, b) => a.kind !== b.kind
+        ? a.kind === 'versioned'
+            ? -1
+            : 1
+        : a.version !== undefined && b.version !== undefined
+            ? compareVersions(a.version, b.version)
+            : a.description < b.description
+                ? -1
+                : a.description > b.description
+                    ? 1
+                    : 0);
+    return { dir, files, ignored };
+}
+/**
+ * Write the next migration's file, empty but for a line that says what the
+ * runner will do with it. The version is one past the highest the directory
+ * holds, in the directory's own style: a team that numbers by timestamp gets a
+ * timestamp. `body` is the file's text when something already wrote it
+ * (`migrate diff`).
+ */
+export function newMigration(dir, name, repeatable, now = new Date(), body) {
+    const slug = name
+        .trim()
+        .replace(/[^A-Za-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '');
+    if (!slug)
+        throw new Error(`"${name}" gives the file no name: use letters or digits, like add_payoff_quote.`);
+    mkdirSync(dir, { recursive: true });
+    const { files } = readMigrations(dir);
+    let file;
+    if (repeatable) {
+        file = `R__${slug}.sql`;
+    }
+    else {
+        const majors = files.filter((f) => f.version !== undefined).map((f) => BigInt(f.version.split('.')[0]));
+        const highest = majors.reduce((a, b) => (b > a ? b : a), 0n);
+        // Fourteen digits or more is a yyyyMMddHHmmss scheme: keep it.
+        const stamp = BigInt(now.toISOString().replace(/\D/g, '').slice(0, 14));
+        const next = highest >= 10000000000000n ? (stamp > highest ? stamp : highest + 1n) : highest + 1n;
+        file = `V${next}__${slug}.sql`;
+    }
+    const path = join(dir, file);
+    if (existsSync(path))
+        throw new Error(`${path} already exists.`);
+    writeFileSync(path, body ??
+        (repeatable
+            ? `-- Runs again, after the versioned migrations, whenever this file changes: views, functions, grants.\n`
+            : `-- Runs once, in version order. Forward only: a later migration undoes what this one does.\n`), { flag: 'wx' });
+    return path;
+}

package/dist/server/migrate/flyway.d.ts

@@ -0,0 +1,7 @@
+import { type Dialect } from './database.js';
+import type { MigrateTarget } from './runner.js';
+export declare const FLYWAY_COMMANDS: Readonly<Record<string, string>>;
+/** A connection URL as Flyway's JDBC settings. */
+export declare function flywaySettings(url: string, dialect: Dialect): Record<string, string>;
+/** Run `flyway <command>` with the target's settings; its output passes through. Resolves to its exit code. */
+export declare function runFlyway(command: string, target: MigrateTarget, dialect: Dialect, write: (line: string) => void): Promise<number>;

package/dist/server/migrate/flyway.js

@@ -0,0 +1,69 @@
+/**
+ * `--tool flyway`: the same commands run by an installed Flyway instead of
+ * tablewalk's runner, for a team that wants the real thing. The files and the
+ * history table are the same ones either way (the layout is Flyway's and the
+ * table is named to Flyway with `FLYWAY_TABLE`), so a team can switch tools
+ * in either direction between two deploys.
+ *
+ * Everything reaches Flyway through its environment variables, never its
+ * command line: a password on argv is readable by every user of the machine
+ * in the process list. What only tablewalk can do still happens around it —
+ * the schema recorded after `up` for drift, and the App checked.
+ */
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+import { sqlitePath } from './database.js';
+import { envName, product, productEnv } from '../product.js';
+export const FLYWAY_COMMANDS = {
+    up: 'migrate',
+    status: 'info',
+    validate: 'validate',
+    baseline: 'baseline',
+    repair: 'repair',
+};
+/** A connection URL as Flyway's JDBC settings. */
+export function flywaySettings(url, dialect) {
+    if (dialect === 'sqlite')
+        return { FLYWAY_URL: `jdbc:sqlite:${resolve(sqlitePath(url))}` };
+    const parsed = new URL(url);
+    return {
+        FLYWAY_URL: `jdbc:postgresql://${parsed.host}${parsed.pathname}${parsed.search}`,
+        ...(parsed.username ? { FLYWAY_USER: decodeURIComponent(parsed.username) } : {}),
+        ...(parsed.password ? { FLYWAY_PASSWORD: decodeURIComponent(parsed.password) } : {}),
+    };
+}
+/** Run `flyway <command>` with the target's settings; its output passes through. Resolves to its exit code. */
+export function runFlyway(command, target, dialect, write) {
+    const env = {
+        ...process.env,
+        ...flywaySettings(target.url, dialect),
+        FLYWAY_LOCATIONS: `filesystem:${target.dir}`,
+        FLYWAY_TABLE: target.table,
+        FLYWAY_BASELINE_VERSION: '0',
+        ...(target.schemas.length ? { FLYWAY_SCHEMAS: target.schemas.join(',') } : {}),
+    };
+    return new Promise((done) => {
+        const child = spawn(productEnv('FLYWAY') ?? 'flyway', [FLYWAY_COMMANDS[command]], { env, stdio: ['ignore', 'pipe', 'pipe'] });
+        let pending = '';
+        const forward = (chunk) => {
+            pending += String(chunk);
+            const lines = pending.split('\n');
+            pending = lines.pop() ?? '';
+            for (const line of lines)
+                write(`  flyway: ${line}`);
+        };
+        child.stdout.on('data', forward);
+        child.stderr.on('data', forward);
+        child.once('error', (error) => {
+            write(error.code === 'ENOENT'
+                ? `Flyway is not installed where this can find it: put flyway on the PATH (or set ${envName('FLYWAY')} to its path), or drop --tool flyway to use ${product()}'s own runner.`
+                : `Flyway could not be started: ${error.message}`);
+            done(127);
+        });
+        child.once('close', (code) => {
+            if (pending)
+                write(`  flyway: ${pending}`);
+            done(code ?? 1);
+        });
+    });
+}

package/dist/server/migrate/history.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The history table: Flyway's layout, column for column and engine by engine,
+ * so Flyway reads what tablewalk wrote and tablewalk reads what Flyway wrote.
+ * Only the name is tablewalk's: `__mistri_schema_history` by default, a
+ * reserved runtime table (shared/runtimeTables.ts), so an App never lists it,
+ * a tenant App's database may hold it, and it is never another team's
+ * `flyway_schema_history`. Naming theirs is how a team moves over from Flyway,
+ * and it is said, never assumed.
+ */
+import { type MigrationDb } from './database.js';
+import { type MigrationFile } from './files.js';
+export declare const DEFAULT_HISTORY_TABLE = "__mistri_schema_history";
+interface HistoryRow {
+    readonly installed_rank: number;
+    readonly version: string | null;
+    readonly description: string;
+    readonly type: string;
+    readonly script: string;
+    readonly checksum: number | null;
+    readonly installed_by: string;
+    readonly installed_on: string;
+    readonly execution_time: number;
+    readonly success: boolean;
+}
+export declare const BASELINE_DESCRIPTION = "<< Flyway Baseline >>";
+export declare function qualified(db: MigrationDb, table: string): string;
+/** The DDL Flyway itself runs for this table (its createMetaDataTable.sql per engine). */
+export declare function historyDdl(db: MigrationDb, table: string): string[];
+export declare function historyExists(db: MigrationDb, table: string): Promise<boolean>;
+/** Every row, in the order they were installed. A table in another layout is refused, never written. */
+export declare function readHistory(db: MigrationDb, table: string): Promise<HistoryRow[]>;
+export declare function insertHistory(db: MigrationDb, table: string, row: {
+    version: string | null;
+    description: string;
+    type: string;
+    script: string;
+    checksum: number | null;
+    executionTime: number;
+    success: boolean;
+}): Promise<void>;
+/** What the rows say, as Flyway reads them: a later DELETE row cancels the one it names. */
+export interface History {
+    readonly rows: readonly HistoryRow[];
+    readonly baseline?: HistoryRow;
+    /** Each versioned migration in force, by version. */
+    readonly versioned: ReadonlyMap<string, HistoryRow>;
+    /** Each repeatable's latest run in force, by description. */
+    readonly repeatable: ReadonlyMap<string, HistoryRow>;
+    readonly failed: readonly HistoryRow[];
+    readonly lastRank: number;
+}
+export declare function readRows(rows: readonly HistoryRow[]): History;
+export interface Plan {
+    readonly history: History;
+    readonly pending: readonly MigrationFile[];
+    /** What stops a run: said per file, with what to do. */
+    readonly problems: readonly string[];
+    /** Said, never a failure: an applied version newer than every file (Flyway's "future"). */
+    readonly notes: readonly string[];
+}
+/**
+ * Files against history, with Flyway's rules: an applied file must still be
+ * there with the same checksum and description; a failed row stops everything
+ * until it is repaired; a new version below the newest applied one is out of
+ * order and refused, since running it would apply a change out of the order
+ * the others were tested in; a repeatable is pending when it is new or has
+ * changed. A version at or below the baseline is the baseline's.
+ */
+export declare function plan(files: readonly MigrationFile[], history: History): Plan;
+export {};

package/dist/server/migrate/history.js

@@ -0,0 +1,211 @@
+/**
+ * The history table: Flyway's layout, column for column and engine by engine,
+ * so Flyway reads what tablewalk wrote and tablewalk reads what Flyway wrote.
+ * Only the name is tablewalk's: `__mistri_schema_history` by default, a
+ * reserved runtime table (shared/runtimeTables.ts), so an App never lists it,
+ * a tenant App's database may hold it, and it is never another team's
+ * `flyway_schema_history`. Naming theirs is how a team moves over from Flyway,
+ * and it is said, never assumed.
+ */
+import { quoteIdent } from './database.js';
+import { compareVersions } from './files.js';
+import { product } from '../product.js';
+export const DEFAULT_HISTORY_TABLE = '__mistri_schema_history';
+export const BASELINE_DESCRIPTION = '<< Flyway Baseline >>';
+export function qualified(db, table) {
+    return db.home === undefined ? quoteIdent(db.dialect, table) : `${quoteIdent(db.dialect, db.home)}.${quoteIdent(db.dialect, table)}`;
+}
+/** The DDL Flyway itself runs for this table (its createMetaDataTable.sql per engine). */
+export function historyDdl(db, table) {
+    const name = qualified(db, table);
+    const index = quoteIdent(db.dialect, `${table}_s_idx`);
+    if (db.dialect === 'sqlite') {
+        return [
+            `CREATE TABLE ${name} (
+    "installed_rank" INT NOT NULL PRIMARY KEY,
+    "version" VARCHAR(50),
+    "description" VARCHAR(200) NOT NULL,
+    "type" VARCHAR(20) NOT NULL,
+    "script" VARCHAR(1000) NOT NULL,
+    "checksum" INT,
+    "installed_by" VARCHAR(100) NOT NULL,
+    "installed_on" TEXT NOT NULL DEFAULT (strftime('%Y-%m-%d %H:%M:%f','now')),
+    "execution_time" INT NOT NULL,
+    "success" BOOLEAN NOT NULL
+)`,
+            `CREATE INDEX ${index} ON ${name} ("success")`,
+        ];
+    }
+    return [
+        `CREATE TABLE ${name} (
+    "installed_rank" INT NOT NULL,
+    "version" VARCHAR(50),
+    "description" VARCHAR(200) NOT NULL,
+    "type" VARCHAR(20) NOT NULL,
+    "script" VARCHAR(1000) NOT NULL,
+    "checksum" INTEGER,
+    "installed_by" VARCHAR(100) NOT NULL,
+    "installed_on" TIMESTAMP NOT NULL DEFAULT now(),
+    "execution_time" INTEGER NOT NULL,
+    "success" BOOLEAN NOT NULL
+)`,
+        `ALTER TABLE ${name} ADD CONSTRAINT ${quoteIdent('postgres', `${table}_pk`)} PRIMARY KEY ("installed_rank")`,
+        `CREATE INDEX ${index} ON ${name} ("success")`,
+    ];
+}
+export async function historyExists(db, table) {
+    const rows = db.dialect === 'sqlite'
+        ? await db.all("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?", [table])
+        : db.dialect === 'postgres'
+            ? await db.all('SELECT 1 FROM pg_catalog.pg_tables WHERE schemaname = ? AND tablename = ?', [db.home, table])
+            : [];
+    return rows.length > 0;
+}
+/** Every row, in the order they were installed. A table in another layout is refused, never written. */
+export async function readHistory(db, table) {
+    if (!(await historyExists(db, table)))
+        return [];
+    let rows;
+    try {
+        // The time as text to the second, as each engine keeps it: a Date would be read in this machine's zone.
+        const on = db.dialect === 'postgres' ? "to_char(installed_on, 'YYYY-MM-DD HH24:MI:SS')" : 'substr(installed_on, 1, 19)';
+        rows =
+            await db.all(`SELECT installed_rank, version, description, type, script, checksum, installed_by, ${on} AS installed_on, execution_time, success
+      FROM ${qualified(db, table)} ORDER BY installed_rank`);
+    }
+    catch {
+        throw new Error(`${table} is not a Flyway-layout history table; name another with --history-table.`);
+    }
+    return rows.map((row) => ({
+        installed_rank: Number(row.installed_rank),
+        version: row.version === null ? null : String(row.version),
+        description: String(row.description),
+        type: String(row.type),
+        script: String(row.script),
+        checksum: row.checksum === null || row.checksum === undefined ? null : Number(row.checksum),
+        installed_by: String(row.installed_by ?? ''),
+        installed_on: String(row.installed_on),
+        execution_time: Number(row.execution_time),
+        success: row.success === true || row.success === 1 || row.success === '1' || row.success === 't',
+    }));
+}
+export async function insertHistory(db, table, row) {
+    const name = qualified(db, table);
+    const [{ next }] = await db.all(`SELECT COALESCE(MAX(installed_rank), 0) + 1 AS next FROM ${name}`);
+    await db.run(`INSERT INTO ${name} (installed_rank, version, description, type, script, checksum, installed_by, execution_time, success)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+        Number(next),
+        row.version,
+        row.description,
+        row.type,
+        row.script,
+        row.checksum,
+        db.user,
+        row.executionTime,
+        db.dialect === 'postgres' ? row.success : row.success ? 1 : 0,
+    ]);
+}
+export function readRows(rows) {
+    let baseline;
+    const versioned = new Map();
+    const repeatable = new Map();
+    const failed = [];
+    for (const row of rows) {
+        if (row.type === 'BASELINE') {
+            baseline = row;
+            continue;
+        }
+        if (row.type === 'SCHEMA')
+            continue;
+        const map = row.version === null ? repeatable : versioned;
+        const key = row.version ?? row.description;
+        if (row.type === 'DELETE') {
+            map.delete(key);
+            continue;
+        }
+        if (!row.success) {
+            failed.push(row);
+            continue;
+        }
+        if (row.version !== null) {
+            // A version applied twice is Flyway's to have refused; the first stands.
+            if (!versioned.has(key))
+                versioned.set(key, row);
+        }
+        else
+            repeatable.set(key, row);
+    }
+    return { rows, baseline, versioned, repeatable, failed, lastRank: rows.reduce((max, row) => Math.max(max, row.installed_rank), 0) };
+}
+/**
+ * Files against history, with Flyway's rules: an applied file must still be
+ * there with the same checksum and description; a failed row stops everything
+ * until it is repaired; a new version below the newest applied one is out of
+ * order and refused, since running it would apply a change out of the order
+ * the others were tested in; a repeatable is pending when it is new or has
+ * changed. A version at or below the baseline is the baseline's.
+ */
+export function plan(files, history) {
+    const problems = [];
+    const notes = [];
+    const baseline = history.baseline?.version ?? undefined;
+    const above = (version) => baseline === undefined || compareVersions(version, baseline) > 0;
+    const seen = new Map();
+    for (const file of files) {
+        if (file.version === undefined)
+            continue;
+        const twin = [...seen.values()].find((other) => compareVersions(other.version, file.version) === 0);
+        if (twin)
+            problems.push(`${file.script} and ${twin.script} are both version ${file.version}: give one of them the next free version.`);
+        seen.set(file.version, file);
+    }
+    for (const row of history.failed) {
+        problems.push(`${row.script} failed on ${row.installed_on}. What it did before it failed may still be there: undo or finish it by hand, then \`${product()} migrate repair\` removes the failed entry.`);
+    }
+    const byVersion = (version) => files.find((file) => file.version !== undefined && compareVersions(file.version, version) === 0);
+    const highestFile = files.reduce((max, file) => (file.version !== undefined && (max === undefined || compareVersions(file.version, max) > 0) ? file.version : max), undefined);
+    let highestApplied;
+    for (const [version, row] of history.versioned) {
+        if (highestApplied === undefined || compareVersions(version, highestApplied) > 0)
+            highestApplied = version;
+        const file = byVersion(version);
+        if (!file) {
+            if (highestFile !== undefined && compareVersions(version, highestFile) > 0)
+                notes.push(`version ${version} (${row.script}) is applied but has no file here: a newer checkout applied it.`);
+            else
+                problems.push(`${row.script} was applied on ${row.installed_on} and is not in the directory any more. Put it back, or \`${product()} migrate repair\` marks it deleted.`);
+            continue;
+        }
+        if (row.checksum !== file.checksum) {
+            problems.push(`${file.script} changed after it was applied (checksum ${row.checksum} applied, ${file.checksum} now). Put it back as it was and write the change as a new migration, or \`${product()} migrate repair\` accepts the file as it is now.`);
+        }
+        else if (row.description !== file.description) {
+            problems.push(`${file.script} was applied as "${row.description}"; its name now says "${file.description}". Rename it back, or \`${product()} migrate repair\`.`);
+        }
+    }
+    for (const [description, row] of history.repeatable) {
+        if (!files.some((file) => file.kind === 'repeatable' && file.description === description)) {
+            problems.push(`${row.script} was applied and is not in the directory any more. Put it back, or \`${product()} migrate repair\` marks it deleted.`);
+        }
+    }
+    const pending = [];
+    for (const file of files) {
+        if (file.kind === 'versioned') {
+            if (history.versioned.has(file.version) || [...history.versioned.keys()].some((v) => compareVersions(v, file.version) === 0))
+                continue;
+            if (!above(file.version))
+                continue;
+            if (highestApplied !== undefined && compareVersions(file.version, highestApplied) < 0) {
+                problems.push(`${file.script} is new, but version ${highestApplied} is already applied: give it a version after ${highestApplied}.`);
+                continue;
+            }
+            pending.push(file);
+        }
+        else {
+            const applied = history.repeatable.get(file.description);
+            if (!applied || applied.checksum !== file.checksum)
+                pending.push(file);
+        }
+    }
+    return { history, pending, problems, notes };
+}

package/dist/server/migrate/runner.d.ts

@@ -0,0 +1,100 @@
+import { type Dialect } from './database.js';
+import { type MigrationDirectory, type MigrationFile } from './files.js';
+import { type Plan } from './history.js';
+import { type Change, type Objects, type StoredSnapshot } from './snapshot.js';
+export interface MigrateTarget {
+    /** The resolved URL or SQLite path: secrets expanded, never printed. */
+    readonly url: string;
+    /** The schemas the run owns: PostgreSQL's first is where the history lives. */
+    readonly schemas: readonly string[];
+    readonly dir: string;
+    readonly table: string;
+}
+export interface Status {
+    readonly dialect: Dialect;
+    readonly home: string | undefined;
+    readonly directory: MigrationDirectory;
+    readonly plan: Plan;
+    readonly started: boolean;
+    /** Changes made outside migrations since the last run recorded the schema. */
+    readonly drift?: readonly Change[];
+    readonly snapshot?: StoredSnapshot;
+    /** History rows written after the recorded schema: another runner's, whose changes read as drift. */
+    readonly behind: number;
+    /** With no history yet: the tables and views already there, which want a baseline before anything runs. */
+    readonly holds: number;
+}
+export declare function migrationStatus(target: MigrateTarget): Promise<Status>;
+interface UpResult {
+    readonly status: Status;
+    readonly applied: ReadonlyArray<{
+        readonly file: MigrationFile;
+        readonly ms: number;
+    }>;
+    /** Set when a file failed: the run stopped there. */
+    readonly failure?: {
+        readonly file: MigrationFile;
+        readonly message: string;
+        readonly recorded: boolean;
+    };
+    /** Set when the database was refused before anything ran. */
+    readonly refused?: string;
+    /** With dryRun: what would run, in order. */
+    readonly wouldRun?: readonly MigrationFile[];
+}
+/**
+ * Apply every pending migration. Under the run's lock the plan is read again
+ * before each file, so a second deploy that waited finds the first's work
+ * done and applies nothing twice.
+ */
+export declare function migrateUp(target: MigrateTarget, options?: {
+    dryRun?: boolean;
+    waiting?: () => void;
+}): Promise<UpResult>;
+export interface Validation {
+    readonly status: Status;
+    readonly valid: boolean;
+}
+/**
+ * Flyway's validate — every applied file unchanged and present, nothing
+ * pending, nothing failed — and one thing Flyway cannot see: the database
+ * is still what its migrations made it.
+ */
+export declare function migrateValidate(target: MigrateTarget): Promise<Validation>;
+interface BaselineResult {
+    readonly already?: string;
+    readonly refused?: string;
+    readonly objects: Objects;
+    /** The snapshot file, and whether this run wrote it. */
+    readonly file: string;
+    readonly wrote: boolean;
+}
+/**
+ * Record the database as it is as version 0: nothing that exists is touched,
+ * and history starts here. The schema as read is written beside the
+ * migrations, read-only, and kept as the one migrations start from.
+ */
+export declare function migrateBaseline(target: MigrateTarget, options?: {
+    dryRun?: boolean;
+}): Promise<BaselineResult>;
+interface RepairResult {
+    readonly actions: readonly string[];
+}
+/**
+ * Make the history agree with the files again, as Flyway's repair does:
+ * failed entries removed, an applied file's checksum and description taken
+ * from the file as it is now, a file that is gone marked deleted. And the
+ * recorded schema retaken when another runner applied migrations after it,
+ * since their changes cannot be told from drift; drift itself is never
+ * repaired away.
+ */
+export declare function migrateRepair(target: MigrateTarget, options?: {
+    dryRun?: boolean;
+}): Promise<RepairResult>;
+/**
+ * Around a run another tool makes (`--tool flyway`): the schema read before
+ * it, and recorded after it as tablewalk's own runs record it, so drift stays
+ * measured whichever tool applied the files.
+ */
+export declare function recordAround(target: MigrateTarget, run: () => Promise<number>): Promise<number>;
+export {};