migrane 0.3.0

package/dist/drivers/pg.js

@@ -0,0 +1,138 @@
+import { Pool } from 'pg';
+/**
+ * The reference driver, and the shortest statement of what a driver is: three
+ * methods over `node-postgres`, and the host they reach.
+ *
+ * `pg` is an optional peer dependency — importing `migrane` does not reach
+ * it, only importing this file does. A consumer on another client writes sixty
+ * lines like these instead of adopting ours.
+ */
+/**
+ * The simple query protocol answers a multi-statement request with one result
+ * per statement. Rows come from the last of them, which is what a caller
+ * reading `SELECT 1` at the end of a script expects.
+ */
+const rowsOf = (result) => (Array.isArray(result) ? (result.at(-1)?.rows ?? []) : result.rows);
+const queryable = (client) => ({
+    async query(text, values) {
+        // Passing no array at all rather than an empty one: `pg` switches to the
+        // extended protocol the moment values are present, and that protocol
+        // permits exactly one statement per request.
+        const result = values?.length
+            ? await client.query(text, [...values])
+            : await client.query(text);
+        return rowsOf(result);
+    },
+});
+const sessionOver = (client) => ({
+    ...queryable(client),
+    /**
+     * PostgreSQL's spelling of the lock `withLock` asks for. Blocking rather than
+     * `pg_try_advisory_lock`, per the contract on {@link Session.lock}; why it is
+     * session-level is `lock.ts`'s business.
+     */
+    async lock(key, run) {
+        await client.query('SELECT pg_advisory_lock($1)', [key]);
+        try {
+            return await run();
+        }
+        finally {
+            await client.query('SELECT pg_advisory_unlock($1)', [key]);
+        }
+    },
+    async transaction(run) {
+        await client.query('BEGIN');
+        try {
+            const result = await run(queryable(client));
+            await client.query('COMMIT');
+            return result;
+        }
+        catch (error) {
+            // A rollback that itself fails must not replace the error that caused it
+            // — that one is the answer to what went wrong.
+            await client.query('ROLLBACK').catch(() => { });
+            throw error;
+        }
+    },
+});
+/**
+ * Where these coordinates point, read the way `pg` itself reads them.
+ *
+ * It is worth the twenty lines because `Driver.host` is what a guard matches
+ * on: a host this cannot make out must never come back looking like one a
+ * guard allows. So every branch either produces the real host or produces
+ * something plainly no guard names — including the last one, which declines to
+ * guess. It also never returns the string it was given, because a connection
+ * string carries a password and this value is printed.
+ */
+const hostOf = (config) => {
+    if (typeof config !== 'string') {
+        return config.connectionString
+            ? hostOf(config.connectionString)
+            : // `pg`'s own precedence, so the guard and the pool cannot disagree: an
+                // omitted host means PGHOST, and then the local socket.
+                (config.host ?? process.env.PGHOST ?? '');
+    }
+    try {
+        // Brackets around an IPv6 address belong to the URL syntax, not to the
+        // address, and a guard has to be writable against what is printed.
+        return new URL(config).hostname.replace(/^\[|\]$/g, '');
+    }
+    catch {
+        // The libpq keyword form — `host=db.example.com port=5432 …`. Anything
+        // else is unreadable, and an unreadable host matches no guard.
+        return /(?:^|\s)host=(\S+)/.exec(config)?.[1] ?? 'unknown';
+    }
+};
+/**
+ * Which database these coordinates open, read with the same care as the host
+ * and for the same reason: a guard matching on the name must never be answered
+ * with a guess. `pg` itself falls back to the *user name* when nothing names a
+ * database; that branch deliberately answers `'unknown'` instead, because a
+ * wrong "unknown" refuses where a wrong guess would drop — the failure that is
+ * an inconvenience rather than a loss.
+ */
+const databaseOf = (config) => {
+    if (typeof config !== 'string') {
+        return config.connectionString
+            ? databaseOf(config.connectionString)
+            : (config.database ?? process.env.PGDATABASE ?? 'unknown');
+    }
+    try {
+        const name = new URL(config).pathname.replace(/^\//, '');
+        // Percent-decoded because the URL syntax owns the escapes, not the name —
+        // a guard compares against what `CREATE DATABASE` was told.
+        return name
+            ? decodeURIComponent(name)
+            : (process.env.PGDATABASE ?? 'unknown');
+    }
+    catch {
+        return (/(?:^|\s)dbname=(\S+)/.exec(config)?.[1] ??
+            process.env.PGDATABASE ??
+            'unknown');
+    }
+};
+/**
+ * A driver over a `pg` pool.
+ *
+ * Takes a connection string or a `PoolConfig`, so `pgDriver(process.env.DATABASE_URL)`
+ * is the whole setup for most consumers.
+ */
+export const pgDriver = (config) => {
+    const pool = new Pool(typeof config === 'string' ? { connectionString: config } : config);
+    return {
+        ...queryable(pool),
+        host: hostOf(config),
+        database: databaseOf(config),
+        async session(run) {
+            const client = await pool.connect();
+            try {
+                return await run(sessionOver(client));
+            }
+            finally {
+                client.release();
+            }
+        },
+        close: () => pool.end(),
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A migration runner that knows nothing about your application.
+ *
+ * Handed a {@link Driver} and a list of directories, and that is all it knows:
+ * no ORM, no container, no module registry, no dependency it makes you adopt.
+ * Drivers live behind their own import path, so reaching for one is a choice.
+ *
+ * Three entry points, cut by audience. This one is for **authoring**: what a
+ * config file, a migration, or an integration imports. `migrane/ship` holds
+ * the runtime for container entries — every job that does not touch a
+ * filesystem — and the `migrane` executable owns every job that does. Nothing
+ * here reads a disk, so a config that imports from this file bundles for any
+ * target.
+ *
+ * ```ts
+ * // database/config.ts
+ * import { defineConfig } from 'migrane';
+ * import { pgDriver } from 'migrane/drivers/pg';
+ *
+ * export default defineConfig({
+ *   dirs: ['./migrations'],
+ *   seeds: './seeders',
+ *   driver: () => pgDriver(process.env.DATABASE_URL!),
+ * });
+ * ```
+ */
+import type { Config } from './types.js';
+/** Identity, but it types the object literal at the point it is written. */
+export declare const defineConfig: (config: Config) => Config;
+export { compose } from './load.js';
+export { refuse } from './safety.js';
+export { createSql } from './sql.js';
+export type { Config, Context, Driver, Fragment, Guard, Hook, Migration, Module, Part, Queryable, Row, Session, Sql, Transacted, } from './types.js';

package/dist/index.js

@@ -0,0 +1,31 @@
+/**
+ * A migration runner that knows nothing about your application.
+ *
+ * Handed a {@link Driver} and a list of directories, and that is all it knows:
+ * no ORM, no container, no module registry, no dependency it makes you adopt.
+ * Drivers live behind their own import path, so reaching for one is a choice.
+ *
+ * Three entry points, cut by audience. This one is for **authoring**: what a
+ * config file, a migration, or an integration imports. `migrane/ship` holds
+ * the runtime for container entries — every job that does not touch a
+ * filesystem — and the `migrane` executable owns every job that does. Nothing
+ * here reads a disk, so a config that imports from this file bundles for any
+ * target.
+ *
+ * ```ts
+ * // database/config.ts
+ * import { defineConfig } from 'migrane';
+ * import { pgDriver } from 'migrane/drivers/pg';
+ *
+ * export default defineConfig({
+ *   dirs: ['./migrations'],
+ *   seeds: './seeders',
+ *   driver: () => pgDriver(process.env.DATABASE_URL!),
+ * });
+ * ```
+ */
+/** Identity, but it types the object literal at the point it is written. */
+export const defineConfig = (config) => config;
+export { compose } from './load.js';
+export { refuse } from './safety.js';
+export { createSql } from './sql.js';

package/dist/load.d.ts

@@ -0,0 +1,54 @@
+import type { Migration, Module } from './types.js';
+/**
+ * A `.sql` migration: two sections, marked by comments.
+ *
+ * The whole section is sent as one statement with no bind parameters, so
+ * PostgreSQL's simple query protocol runs every statement in it. Splitting on
+ * `;` ourselves would be wrong the first time a function body or a quoted
+ * string contained one.
+ */
+export declare const parseSql: (text: string, label: string) => Module;
+/**
+ * Runs parts in declaration order and reverses them for `down`.
+ *
+ * The transaction opt-out is taken by the whole migration if any single part
+ * asks for it. A part needing `CREATE INDEX CONCURRENTLY` cannot be wrapped,
+ * and wrapping the others while leaving that one bare would mean a failure
+ * rolling back some of a migration and not the rest — worse than being honest
+ * that this one is not atomic.
+ */
+export declare const compose: (parts: readonly Module[]) => Module;
+/**
+ * One part of a shipped unit: a module the manifest imported, or SQL text it
+ * carried inline because an image has no file to read.
+ */
+export type ManifestPart = Module | {
+    sql: string;
+};
+/** One migration or seed unit, as the generated manifest names it. */
+export interface ManifestEntry {
+    name: string;
+    sequence: number;
+    checksum: string;
+    parts: readonly ManifestPart[];
+}
+/**
+ * What `migrane manifest` generates, named here so a consumer's entry never
+ * has to hand-declare the shape of a file this package wrote. The two arrays
+ * are always both present — a project with no seeds gets an empty one, so an
+ * entry that destructures both need not know which this project has.
+ */
+export interface Manifest {
+    migrations: readonly ManifestEntry[];
+    seeds: readonly ManifestEntry[];
+}
+/**
+ * Turns a manifest's arrays into units the runner takes — loading for a
+ * machine with no source tree.
+ *
+ * The same composition rule applies, because it is the same rule: one part runs
+ * as itself, several compose in order with `down` reversed. Parsing the inline
+ * SQL happens here rather than in the generated file, which is what lets that
+ * file import nothing from this package.
+ */
+export declare const fromManifest: (entries: readonly ManifestEntry[]) => Migration[];

package/dist/load.js

@@ -0,0 +1,89 @@
+/**
+ * Turning migration text and manifest entries into something runnable —
+ * deliberately without touching a filesystem, so all of it ships into an
+ * image. Reading files is `discover.ts`'s business; this file only ever takes
+ * what a caller already holds.
+ *
+ * A directory migration's parts are composed here rather than by an `index.ts`
+ * the author writes: `up` in path order, `down` in reverse, so foreign keys
+ * hold in both directions. That is the whole reason the numbers on the files
+ * are load-bearing — they are the dependency order, and there is no second
+ * place stating it.
+ */
+/** `-- migrate:up`, optionally `-- migrate:up transaction:false`. */
+const SECTION = /^\s*--\s*migrate:(up|down)\b(.*)$/;
+/**
+ * A `.sql` migration: two sections, marked by comments.
+ *
+ * The whole section is sent as one statement with no bind parameters, so
+ * PostgreSQL's simple query protocol runs every statement in it. Splitting on
+ * `;` ourselves would be wrong the first time a function body or a quoted
+ * string contained one.
+ */
+export const parseSql = (text, label) => {
+    const sections = {};
+    let current;
+    let transacted = true;
+    for (const line of text.split('\n')) {
+        const marker = SECTION.exec(line);
+        if (marker) {
+            if (/\btransaction:\s*false\b/.test(marker[2] ?? ''))
+                transacted = false;
+            current = sections[marker[1]] ??= [];
+            continue;
+        }
+        current?.push(line);
+    }
+    if (!sections.up) {
+        throw new Error(`${label} has no "-- migrate:up" section, so there is nothing to run.`);
+    }
+    const body = (key) => sections[key]?.join('\n').trim();
+    const up = body('up');
+    const down = body('down');
+    return {
+        transaction: transacted,
+        up: async ({ db }) => {
+            if (up)
+                await db.query(up);
+        },
+        down: down ? async ({ db }) => void (await db.query(down)) : undefined,
+    };
+};
+/**
+ * Runs parts in declaration order and reverses them for `down`.
+ *
+ * The transaction opt-out is taken by the whole migration if any single part
+ * asks for it. A part needing `CREATE INDEX CONCURRENTLY` cannot be wrapped,
+ * and wrapping the others while leaving that one bare would mean a failure
+ * rolling back some of a migration and not the rest — worse than being honest
+ * that this one is not atomic.
+ */
+export const compose = (parts) => ({
+    transaction: parts.every((part) => part.transaction !== false),
+    up: async (context) => {
+        for (const part of parts)
+            await part.up(context);
+    },
+    down: parts.some((part) => part.down)
+        ? async (context) => {
+            for (const part of [...parts].reverse())
+                await part.down?.(context);
+        }
+        : undefined,
+});
+const moduleOf = (part, label) => 'sql' in part ? parseSql(part.sql, label) : part;
+/**
+ * Turns a manifest's arrays into units the runner takes — loading for a
+ * machine with no source tree.
+ *
+ * The same composition rule applies, because it is the same rule: one part runs
+ * as itself, several compose in order with `down` reversed. Parsing the inline
+ * SQL happens here rather than in the generated file, which is what lets that
+ * file import nothing from this package.
+ */
+export const fromManifest = (entries) => entries.map(({ parts, ...rest }) => ({
+    ...rest,
+    module: parts.length === 1
+        ? moduleOf(parts[0], rest.name)
+        : compose(parts.map((part) => moduleOf(part, rest.name))),
+}));

package/dist/lock.d.ts

@@ -0,0 +1,30 @@
+import type { Session } from './types.js';
+/**
+ * A session-level advisory lock held for the length of a run.
+ *
+ * Two containers starting at once is the ordinary case, not the exotic one.
+ * Without this both read the same empty bookkeeping table and both run the same
+ * `CREATE TABLE`, and the loser fails a deploy over a schema that was in fact
+ * applied correctly.
+ *
+ * Session-level rather than transaction-level because each migration commits in
+ * a transaction of its own, and a lock scoped to one would be released between
+ * migrations — exactly when the other process slips in.
+ */
+/**
+ * A stable key from the table name, so two applications sharing a database
+ * usually do not block each other.
+ *
+ * *Usually*: two names can collide into one key, and thirty-two bits makes that
+ * unlikely rather than impossible. A collision costs waiting, never
+ * correctness, so a wider key would buy a guarantee against a harmless outcome.
+ *
+ * Kept inside a signed 32-bit range because PostgreSQL wants a bigint and any
+ * int is one, well clear of what a JS number could no longer represent exactly.
+ */
+export declare const lockKey: (table: string) => number;
+/**
+ * Choosing the key is this file's business; knowing how a lock is spelled is
+ * the driver's, in a package whose opening line says it names no database.
+ */
+export declare const withLock: <T>(session: Session, table: string, run: () => Promise<T>) => Promise<T>;

package/dist/lock.js

@@ -0,0 +1,35 @@
+/**
+ * A session-level advisory lock held for the length of a run.
+ *
+ * Two containers starting at once is the ordinary case, not the exotic one.
+ * Without this both read the same empty bookkeeping table and both run the same
+ * `CREATE TABLE`, and the loser fails a deploy over a schema that was in fact
+ * applied correctly.
+ *
+ * Session-level rather than transaction-level because each migration commits in
+ * a transaction of its own, and a lock scoped to one would be released between
+ * migrations — exactly when the other process slips in.
+ */
+/**
+ * A stable key from the table name, so two applications sharing a database
+ * usually do not block each other.
+ *
+ * *Usually*: two names can collide into one key, and thirty-two bits makes that
+ * unlikely rather than impossible. A collision costs waiting, never
+ * correctness, so a wider key would buy a guarantee against a harmless outcome.
+ *
+ * Kept inside a signed 32-bit range because PostgreSQL wants a bigint and any
+ * int is one, well clear of what a JS number could no longer represent exactly.
+ */
+export const lockKey = (table) => {
+    let hash = 5381;
+    for (const character of table) {
+        hash = (Math.imul(hash, 33) ^ character.charCodeAt(0)) | 0;
+    }
+    return hash;
+};
+/**
+ * Choosing the key is this file's business; knowing how a lock is spelled is
+ * the driver's, in a package whose opening line says it names no database.
+ */
+export const withLock = (session, table, run) => session.lock(lockKey(table), run);

package/dist/reset.d.ts

@@ -0,0 +1,23 @@
+import { type Progress } from './runner.js';
+import type { Config, Driver, Guard } from './types.js';
+/**
+ * Drops every object in a schema.
+ *
+ * This exists so new DDL can be folded back into an unreleased migration
+ * instead of accumulating one-line migrations nobody has run — which is the
+ * normal way to work before a first release, and impossible without it, since
+ * an applied migration cannot be edited.
+ *
+ * It is also the only command that leaves a database with *nothing* in it:
+ * `up` runs the `before` hooks, so `fresh` always ends with whatever they
+ * install, and this does not.
+ */
+export interface ResetPlan {
+    schema: string;
+    /** Consulted before anything is dropped. Defaults to `refuse`. */
+    guard?: Guard;
+}
+/** A reset plan from a config, defaulting the schema from the same constant. */
+export declare const resetPlanFrom: (config: Config) => ResetPlan;
+/** The guard runs before the schema name is even quoted. See `safety.ts`. */
+export declare const reset: (driver: Driver, plan: ResetPlan, reporter?: Progress) => Promise<void>;

package/dist/reset.js

@@ -0,0 +1,16 @@
+import { DEFAULTS } from './defaults.js';
+import { toConsole } from './runner.js';
+import { refuse } from './safety.js';
+import { quoteIdent } from './sql.js';
+/** A reset plan from a config, defaulting the schema from the same constant. */
+export const resetPlanFrom = (config) => ({
+    schema: config.schema ?? DEFAULTS.schema,
+    guard: config.guard,
+});
+/** The guard runs before the schema name is even quoted. See `safety.ts`. */
+export const reset = async (driver, plan, reporter = toConsole) => {
+    await (plan.guard ?? refuse)(driver, 'reset drops every table');
+    await driver.query(`DROP SCHEMA IF EXISTS ${quoteIdent(plan.schema)} CASCADE`);
+    await driver.query(`CREATE SCHEMA ${quoteIdent(plan.schema)}`);
+    reporter.line('schema dropped');
+};

package/dist/runner.d.ts

@@ -0,0 +1,65 @@
+import type { Config, Driver, Guard, Hook, Migration } from './types.js';
+/**
+ * Applying and reverting — the same way on a developer machine and in a
+ * container, which is what makes a migration's result reproducible.
+ */
+/**
+ * Where progress output goes — one line per event, and that is the whole
+ * interface, because it is progress rather than a logger. Injected so a test
+ * can read it back; every verb defaults it to the console.
+ */
+export interface Progress {
+    line: (text: string) => void;
+}
+export declare const toConsole: Progress;
+export interface Plan {
+    migrations: readonly Migration[];
+    table: string;
+    before?: readonly Hook[];
+    /** Consulted by `down`, the one destructive verb here. Defaults to `refuse`. */
+    guard?: Guard;
+}
+/**
+ * A plan from a config and migrations already loaded — the shape an entrypoint
+ * built from a manifest is in, where there is nothing to read off a disk.
+ *
+ * The table default is settled here from the same constant `loadConfig` uses,
+ * deliberately: two spellings of one default is how an image ends up recording
+ * migrations in a table the CLI does not look in.
+ */
+export declare const planFrom: (config: Config, migrations: readonly Migration[]) => Plan;
+/**
+ * Each migration commits in a transaction of its own together with the row that
+ * records it, so a failure can never leave the DDL applied and the bookkeeping
+ * unwritten.
+ */
+export declare const up: (driver: Driver, plan: Plan, reporter?: Progress) => Promise<Migration[]>;
+/**
+ * Revert the most recently applied migration.
+ *
+ * Only one, and only the last: reverting is a decision taken a step at a time,
+ * and a command unwinding an unbounded number of them empties a database by
+ * typo.
+ *
+ * Guarded like `reset`. "No `down` against production" has to sit on the
+ * function to mean anything — a verb withheld from one entrypoint's command
+ * table says nothing about the same function imported directly.
+ */
+export declare const down: (driver: Driver, plan: Plan, reporter?: Progress) => Promise<Migration | undefined>;
+export interface Status {
+    name: string;
+    applied: boolean;
+    /** Applied, and the file has changed since — what `up` will refuse on. */
+    changed: boolean;
+}
+/**
+ * What is applied and what is pending, in the order they would run.
+ *
+ * Writes nothing beyond the `CREATE TABLE IF NOT EXISTS` that reading requires:
+ * asking a database what it holds should not change what it holds.
+ *
+ * **And it never refuses.** An edited migration is the likeliest reason someone
+ * is running this, so it reports `changed` and finishes the report rather than
+ * answering with a stack trace and no lines. `up` and `down` still refuse.
+ */
+export declare const status: (driver: Driver, plan: Plan, reporter?: Progress) => Promise<Status[]>;

package/dist/runner.js

@@ -0,0 +1,150 @@
+import { DEFAULTS } from './defaults.js';
+import { withLock } from './lock.js';
+import { refuse } from './safety.js';
+import { createSql } from './sql.js';
+import { applied, forget, record, verify } from './storage.js';
+export const toConsole = { line: (text) => console.log(text) };
+/**
+ * A plan from a config and migrations already loaded — the shape an entrypoint
+ * built from a manifest is in, where there is nothing to read off a disk.
+ *
+ * The table default is settled here from the same constant `loadConfig` uses,
+ * deliberately: two spellings of one default is how an image ends up recording
+ * migrations in a table the CLI does not look in.
+ */
+export const planFrom = (config, migrations) => ({
+    migrations,
+    table: config.table ?? DEFAULTS.table,
+    before: config.before,
+    guard: config.guard,
+});
+const contextOver = (db) => ({ sql: createSql(db), db });
+/**
+ * Everything a run needs held at once: one pinned connection, the advisory
+ * lock on it, and the bookkeeping read inside that lock.
+ *
+ * Reading `applied` *inside* the lock is the point. Read it outside and two
+ * processes can both see the same empty table before either takes the lock,
+ * which is the race the lock exists to close.
+ */
+const inRun = async (driver, plan, run) => driver.session((session) => withLock(session, plan.table, async () => {
+    const rows = await applied(session, plan.table);
+    verify(rows, plan.migrations);
+    return run(session, new Set(rows.map((row) => row.name)));
+}));
+/**
+ * Each migration commits in a transaction of its own together with the row that
+ * records it, so a failure can never leave the DDL applied and the bookkeeping
+ * unwritten.
+ */
+export const up = async (driver, plan, reporter = toConsole) => inRun(driver, plan, async (session, done) => {
+    // Before the pending check, not after: a hook syncs things a migration may
+    // reference, and whether it needs syncing has nothing to do with whether a
+    // *new* migration was added. Registering something that contributes a type
+    // has to take effect on the next `migrate`, with no migration written.
+    for (const hook of plan.before ?? [])
+        await hook(contextOver(session));
+    const pending = plan.migrations.filter(({ name }) => !done.has(name));
+    if (!pending.length) {
+        reporter.line('nothing to do');
+        return [];
+    }
+    for (const migration of pending) {
+        const { name, checksum, module } = migration;
+        reporter.line(`  migrating  ${name}`);
+        const started = Date.now();
+        const apply = async (db) => {
+            await module.up(contextOver(db));
+            await record(db, plan.table, {
+                name,
+                checksum,
+                duration: Math.round(Date.now() - started),
+            });
+        };
+        // The opt-out is not a detail to hide: an untransacted migration that
+        // fails half way leaves the schema changed and unrecorded, and the
+        // operator needs to know which one that was.
+        if (module.transaction === false) {
+            reporter.line(`  (untransacted)`);
+            await apply(session);
+        }
+        else {
+            await session.transaction(apply);
+        }
+        reporter.line(`  migrated   ${name}  ${Math.round(Date.now() - started)}ms`);
+    }
+    reporter.line(`applied ${pending.length}`);
+    return pending;
+});
+/**
+ * Revert the most recently applied migration.
+ *
+ * Only one, and only the last: reverting is a decision taken a step at a time,
+ * and a command unwinding an unbounded number of them empties a database by
+ * typo.
+ *
+ * Guarded like `reset`. "No `down` against production" has to sit on the
+ * function to mean anything — a verb withheld from one entrypoint's command
+ * table says nothing about the same function imported directly.
+ */
+export const down = async (driver, plan, reporter = toConsole) => {
+    await (plan.guard ?? refuse)(driver, 'down reverts a migration');
+    return inRun(driver, plan, async (session, done) => {
+        const last = [...plan.migrations]
+            .reverse()
+            .find(({ name }) => done.has(name));
+        if (!last) {
+            reporter.line('nothing to do');
+            return undefined;
+        }
+        if (!last.module.down) {
+            throw new Error(`"${last.name}" has no "down", so it cannot be reverted.`);
+        }
+        reporter.line(`  reverting  ${last.name}`);
+        const started = Date.now();
+        const revert = async (db) => {
+            await last.module.down?.(contextOver(db));
+            await forget(db, plan.table, last.name);
+        };
+        if (last.module.transaction === false)
+            await revert(session);
+        else
+            await session.transaction(revert);
+        reporter.line(`  reverted   ${last.name}  ${Math.round(Date.now() - started)}ms`);
+        return last;
+    });
+};
+/**
+ * What is applied and what is pending, in the order they would run.
+ *
+ * Writes nothing beyond the `CREATE TABLE IF NOT EXISTS` that reading requires:
+ * asking a database what it holds should not change what it holds.
+ *
+ * **And it never refuses.** An edited migration is the likeliest reason someone
+ * is running this, so it reports `changed` and finishes the report rather than
+ * answering with a stack trace and no lines. `up` and `down` still refuse.
+ */
+export const status = async (driver, plan, reporter = toConsole) => {
+    const rows = await applied(driver, plan.table);
+    const done = new Map(rows.map((row) => [row.name, row.checksum]));
+    const lines = plan.migrations.map(({ name, checksum }) => ({
+        name,
+        applied: done.has(name),
+        changed: done.has(name) && done.get(name) !== checksum,
+    }));
+    for (const { name, applied: isApplied, changed } of lines) {
+        reporter.line(changed
+            ? `  changed  ${name}  (edited after it was applied)`
+            : `  ${isApplied ? 'up     ' : 'pending'}  ${name}`);
+    }
+    if (!lines.length)
+        reporter.line('  no migrations');
+    // A name in the table with no file behind it is what a squash looks like from
+    // the database's side, and saying so is more useful than staying quiet.
+    for (const row of rows) {
+        if (!plan.migrations.some(({ name }) => name === row.name)) {
+            reporter.line(`  orphan   ${row.name}  (recorded, not on disk)`);
+        }
+    }
+    return lines;
+};