@intentius/sql-yodeler 0.0.0-stage → 0.2.0

package/dist/history/postgres/ddl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ddl.js","sourceRoot":"","sources":["../../../src/history/postgres/ddl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE1C,4CAA4C;AAC5C,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC;AAEjF,sFAAsF;AACtF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC;AAErF,+FAA+F;AAC/F,MAAM,CAAC,MAAM,kBAAkB,GAAuD;IACpF,CAAC,KAAK,EAAE,6BAA6B,CAAC;IACtC,CAAC,QAAQ,EAAE,eAAe,CAAC;IAC3B,CAAC,MAAM,EAAE,kEAAkE,CAAC;IAC5E,CAAC,cAAc,EAAE,eAAe,CAAC;IACjC,CAAC,QAAQ,EAAE,0BAA0B,CAAC;IACtC,CAAC,UAAU,EAAE,0BAA0B,CAAC;IACxC,CAAC,iBAAiB,EAAE,kBAAkB,CAAC;IACvC,CAAC,eAAe,EAAE,0BAA0B,CAAC;IAC7C,CAAC,QAAQ,EAAE,oEAAoE,CAAC;IAChF,CAAC,OAAO,EAAE,0BAA0B,CAAC;IACrC,CAAC,YAAY,EAAE,0BAA0B,CAAC;IAC1C,CAAC,aAAa,EAAE,0BAA0B,CAAC;IAC3C,CAAC,UAAU,EAAE,4BAA4B,CAAC;IAC1C,CAAC,MAAM,EAAE,0BAA0B,CAAC;IACpC,CAAC,aAAa,EAAE,2DAA2D,CAAC;CAC7E,CAAC;AAEF,mFAAmF;AACnF,MAAM,CAAC,MAAM,kBAAkB,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,aAAa,CAAC,CAAC;AAE9G,kCAAkC;AAClC,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,MAAc,EAAU,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC;AAEzG,kGAAkG;AAClG,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,MAAM,OAAO,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,KAAK,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1F,OAAO;QACL,+BAA+B,OAAO,CAAC,MAAM,CAAC,EAAE;QAChD,8BAA8B,cAAc,CAAC,MAAM,CAAC,OAAO,OAAO,KAAK;QACvE,oBAAoB,cAAc,CAAC,MAAM,CAAC,6FAA6F;KACxI,CAAC;AACJ,CAAC"}

package/dist/history/postgres/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The Postgres history (#13): `<schema>.history` (default `yodeler.history`),
+ * the same rows as ClickHouse's, and the session advisory lock.
+ *
+ *   pgHistoryDdl(schema)                     CREATE SCHEMA / TABLE
+ *   new PostgresHistoryStore(client, {schema}) exists(), ensure(), rows(), state(), append(rows)
+ *   acquireAdvisoryLock(conn, {schema, holder}) the apply lock, on a connection of its own
+ *   lockKeys(schema)                          the lock's two keys
+ */
+export * from "./ddl.js";
+export * from "./lock.js";
+export * from "./store.js";

package/dist/history/postgres/index.js

@@ -0,0 +1,13 @@
+/**
+ * The Postgres history (#13): `<schema>.history` (default `yodeler.history`),
+ * the same rows as ClickHouse's, and the session advisory lock.
+ *
+ *   pgHistoryDdl(schema)                     CREATE SCHEMA / TABLE
+ *   new PostgresHistoryStore(client, {schema}) exists(), ensure(), rows(), state(), append(rows)
+ *   acquireAdvisoryLock(conn, {schema, holder}) the apply lock, on a connection of its own
+ *   lockKeys(schema)                          the lock's two keys
+ */
+export * from "./ddl.js";
+export * from "./lock.js";
+export * from "./store.js";
+//# sourceMappingURL=index.js.map

package/dist/history/postgres/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/history/postgres/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC"}

package/dist/history/postgres/lock.d.ts

@@ -0,0 +1,48 @@
+/**
+ * One apply at a time per environment, on Postgres: a session advisory lock.
+ *
+ * `pg_try_advisory_lock(<yodel>, <history schema>)` on a connection of its
+ * own, opened for the lock and held for the whole apply. The two keys are
+ * fixed: the first is yodel's ({@link LOCK_CLASS}), the second a hash of the
+ * history schema's name ({@link lockKeys}), so every runner of the same
+ * environment asks for the same lock, and two environments with their own
+ * history schemas in one database do not share one. A session lock is
+ * Postgres's own: it is released when the session ends, however it ends
+ * (the runner exits, crashes, or its connection drops), so it needs no
+ * expiry, and a dead runner never leaves one behind.
+ *
+ * The statements run on another connection (the work connection), so the
+ * lock's connection is never inside a transaction a statement rolls back.
+ *
+ * A runner that finds the lock taken refuses with exit 5, as on ClickHouse,
+ * naming the session that holds it (its pid, its `application_name`, which
+ * says who, and since when). The heartbeat checks that the lock's session
+ * still holds it; a dropped connection stops the apply before its next
+ * statement.
+ *
+ * Clearing it by hand, when you know the holder is stuck: end that session,
+ * `SELECT pg_terminate_backend(<pid>)`.
+ */
+import { type Lock } from "../lock.js";
+import type { PgClient } from "./store.js";
+/** The first key of every yodel lock: "YODL" as an int4. */
+export declare const LOCK_CLASS = 1498367052;
+/** The lock's two int4 keys for a history schema. Both non-negative, so `pg_locks.objid` (an oid) reads them back as they are. */
+export declare function lockKeys(schema: string): [number, number];
+/** A connection the lock holds for itself. */
+export interface PgLockConnection extends PgClient {
+    end(): Promise<void>;
+}
+export interface PgLockOptions {
+    /** The history schema: the lock's second key. */
+    schema: string;
+    /** Who holds it, for the refusal another runner sees. */
+    holder: string;
+}
+/**
+ * Takes the advisory lock on `conn`, a connection opened for it, or throws
+ * {@link LockHeldError} (exit 5). On a refusal the connection is closed.
+ * The lock is released with the returned {@link Lock}'s `release`, which
+ * also closes the connection.
+ */
+export declare function acquireAdvisoryLock(conn: PgLockConnection, options: PgLockOptions): Promise<Lock>;

package/dist/history/postgres/lock.js

@@ -0,0 +1,95 @@
+/**
+ * One apply at a time per environment, on Postgres: a session advisory lock.
+ *
+ * `pg_try_advisory_lock(<yodel>, <history schema>)` on a connection of its
+ * own, opened for the lock and held for the whole apply. The two keys are
+ * fixed: the first is yodel's ({@link LOCK_CLASS}), the second a hash of the
+ * history schema's name ({@link lockKeys}), so every runner of the same
+ * environment asks for the same lock, and two environments with their own
+ * history schemas in one database do not share one. A session lock is
+ * Postgres's own: it is released when the session ends, however it ends
+ * (the runner exits, crashes, or its connection drops), so it needs no
+ * expiry, and a dead runner never leaves one behind.
+ *
+ * The statements run on another connection (the work connection), so the
+ * lock's connection is never inside a transaction a statement rolls back.
+ *
+ * A runner that finds the lock taken refuses with exit 5, as on ClickHouse,
+ * naming the session that holds it (its pid, its `application_name`, which
+ * says who, and since when). The heartbeat checks that the lock's session
+ * still holds it; a dropped connection stops the apply before its next
+ * statement.
+ *
+ * Clearing it by hand, when you know the holder is stuck: end that session,
+ * `SELECT pg_terminate_backend(<pid>)`.
+ */
+import { createHash } from "node:crypto";
+import { lockOwner, LockHeldError, LockLostError } from "../lock.js";
+/** The first key of every yodel lock: "YODL" as an int4. */
+export const LOCK_CLASS = 0x594f444c;
+/** The lock's two int4 keys for a history schema. Both non-negative, so `pg_locks.objid` (an oid) reads them back as they are. */
+export function lockKeys(schema) {
+    const digest = createHash("sha256").update(`yodel apply lock\n${schema}`, "utf8").digest();
+    return [LOCK_CLASS, digest.readUInt32BE(0) & 0x7fffffff];
+}
+/** `application_name` is 63 bytes at most; the lock's says it is yodel's and whose. */
+const applicationName = (owner) => `yodel apply ${owner}`.slice(0, 63);
+/**
+ * Takes the advisory lock on `conn`, a connection opened for it, or throws
+ * {@link LockHeldError} (exit 5). On a refusal the connection is closed.
+ * The lock is released with the returned {@link Lock}'s `release`, which
+ * also closes the connection.
+ */
+export async function acquireAdvisoryLock(conn, options) {
+    const [k1, k2] = lockKeys(options.schema);
+    const owner = lockOwner(options.holder);
+    const where = `Postgres advisory lock (${String(k1)}, ${String(k2)}) for history schema ${options.schema}`;
+    try {
+        await conn.query("SELECT pg_catalog.set_config('application_name', $1, false)", [applicationName(owner)]);
+        const [row] = await conn.query("SELECT pg_catalog.pg_try_advisory_lock($1::int4, $2::int4) AS ok", [k1, k2]);
+        if (row?.ok !== true) {
+            const [held] = await conn.query(`SELECT l.pid, a.application_name AS app, pg_catalog.to_char(a.backend_start AT TIME ZONE 'UTC', 'YYYY-MM-DD HH24:MI:SS') AS since
+           FROM pg_catalog.pg_locks l LEFT JOIN pg_catalog.pg_stat_activity a ON a.pid = l.pid
+          WHERE l.locktype = 'advisory' AND l.granted AND l.classid = $1::oid AND l.objid = $2::oid AND l.objsubid = 2
+          LIMIT 1`, [k1, k2]);
+            const who = held ? `${held.app || "(no application_name)"}, pid ${String(held.pid)}` : "(another session)";
+            throw new LockHeldError(who, held?.since ?? "(unknown)", where, held ? `SELECT pg_terminate_backend(${String(held.pid)})` : "end the session that holds it");
+        }
+    }
+    catch (e) {
+        await conn.end().catch(() => undefined);
+        throw e;
+    }
+    let released = false;
+    return {
+        kind: "advisory",
+        owner,
+        where,
+        async heartbeat() {
+            if (released)
+                throw new LockLostError(where);
+            let holds;
+            try {
+                const [row] = await conn.query("SELECT count(*) AS n FROM pg_catalog.pg_locks WHERE locktype = 'advisory' AND granted AND pid = pg_catalog.pg_backend_pid() AND classid = $1::oid AND objid = $2::oid AND objsubid = 2", [k1, k2]);
+                holds = Number(row?.n ?? 0) > 0;
+            }
+            catch {
+                holds = false;
+            }
+            if (!holds)
+                throw new LockLostError(where);
+        },
+        async release() {
+            if (released)
+                return;
+            released = true;
+            try {
+                await conn.query("SELECT pg_catalog.pg_advisory_unlock($1::int4, $2::int4)", [k1, k2]);
+            }
+            finally {
+                await conn.end().catch(() => undefined);
+            }
+        },
+    };
+}
+//# sourceMappingURL=lock.js.map

package/dist/history/postgres/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../../src/history/postgres/lock.ts"],"names":[],"mappings":"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"}

package/dist/history/postgres/store.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Reading and appending the Postgres history table. Nothing here updates or
+ * deletes a row.
+ *
+ * The store works on one connection, the apply's work connection, so a row
+ * appended while that connection has a transaction open commits or rolls
+ * back with it: that is how a statement and its `succeeded` row commit
+ * together (`../../versioned/postgres/executor.ts`).
+ */
+import { type HistoryRow, type HistoryState } from "../rows.js";
+import { type HistoryStoreLike } from "../store.js";
+/** What the history needs from a Postgres connection: chant's `PostgresClient`. */
+export interface PgClient {
+    query<T = Record<string, unknown>>(sql: string, params?: readonly unknown[]): Promise<T[]>;
+}
+export interface PgHistoryLocation {
+    /** The schema the history table lives in. */
+    schema: string;
+}
+export declare class PostgresHistoryStore implements HistoryStoreLike {
+    readonly client: PgClient;
+    readonly location: PgHistoryLocation;
+    constructor(client: PgClient, location: PgHistoryLocation);
+    get table(): string;
+    /** Whether the history table is there. A history that was never made has no rows. */
+    exists(): Promise<boolean>;
+    /** Creates the schema and table when they are not there. */
+    ensure(): Promise<void>;
+    /** Every row, in seq order. Postgres reads are consistent, so the `sync` option the ClickHouse store takes changes nothing here. */
+    rows(): Promise<HistoryRow[]>;
+    state(): Promise<HistoryState>;
+    /** Appends rows, as written; `recorded_at` is the server's. On the store's connection, so inside its open transaction, if any. */
+    append(rows: readonly HistoryRow[]): Promise<void>;
+}
+/** The parameterized `INSERT` of `rows`. */
+export declare function insertRows(schema: string, rows: readonly HistoryRow[]): {
+    sql: string;
+    params: unknown[];
+};

package/dist/history/postgres/store.js

@@ -0,0 +1,68 @@
+/**
+ * Reading and appending the Postgres history table. Nothing here updates or
+ * deletes a row.
+ *
+ * The store works on one connection, the apply's work connection, so a row
+ * appended while that connection has a transaction open commits or rolls
+ * back with it: that is how a statement and its `succeeded` row commit
+ * together (`../../versioned/postgres/executor.ts`).
+ */
+import { deriveState } from "../rows.js";
+import { fromRaw } from "../store.js";
+import { HISTORY_TABLE } from "../ddl.js";
+import { pgHistoryDdl, pgHistoryTable, PG_HISTORY_COLUMNS, PG_WRITTEN_COLUMNS } from "./ddl.js";
+/** The history's rows read back, `recorded_at` in the ClickHouse table's form (`YYYY-MM-DD hh:mm:ss.ffffff`, UTC). */
+const SELECT = PG_HISTORY_COLUMNS.map(([name]) => name === "recorded_at" ? `pg_catalog.to_char(recorded_at AT TIME ZONE 'UTC', 'YYYY-MM-DD HH24:MI:SS.US') AS recorded_at` : name === "seq" ? "seq::text AS seq" : name).join(", ");
+export class PostgresHistoryStore {
+    client;
+    location;
+    constructor(client, location) {
+        this.client = client;
+        this.location = location;
+    }
+    get table() {
+        return pgHistoryTable(this.location.schema);
+    }
+    /** Whether the history table is there. A history that was never made has no rows. */
+    async exists() {
+        const [row] = await this.client.query("SELECT EXISTS (SELECT 1 FROM pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace WHERE n.nspname = $1 AND c.relname = $2 AND c.relkind = 'r') AS present", [this.location.schema, HISTORY_TABLE]);
+        return row?.present === true;
+    }
+    /** Creates the schema and table when they are not there. */
+    async ensure() {
+        if (await this.exists())
+            return;
+        for (const sql of pgHistoryDdl(this.location.schema))
+            await this.client.query(sql);
+    }
+    /** Every row, in seq order. Postgres reads are consistent, so the `sync` option the ClickHouse store takes changes nothing here. */
+    async rows() {
+        if (!(await this.exists()))
+            return [];
+        const raw = await this.client.query(`SELECT ${SELECT} FROM ${this.table} ORDER BY seq`);
+        return raw.map(fromRaw);
+    }
+    async state() {
+        return deriveState(await this.rows());
+    }
+    /** Appends rows, as written; `recorded_at` is the server's. On the store's connection, so inside its open transaction, if any. */
+    async append(rows) {
+        if (rows.length === 0)
+            return;
+        const { sql, params } = insertRows(this.location.schema, rows);
+        await this.client.query(sql, params);
+    }
+}
+/** The parameterized `INSERT` of `rows`. */
+export function insertRows(schema, rows) {
+    const params = [];
+    const tuples = rows.map((r) => {
+        const values = PG_WRITTEN_COLUMNS.map((c) => {
+            params.push(c === "seq" ? String(r.seq) : r[c]);
+            return `$${String(params.length)}`;
+        });
+        return `(${values.join(", ")})`;
+    });
+    return { sql: `INSERT INTO ${pgHistoryTable(schema)} (${PG_WRITTEN_COLUMNS.join(", ")}) VALUES ${tuples.join(", ")}`, params };
+}
+//# sourceMappingURL=store.js.map

package/dist/history/postgres/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../src/history/postgres/store.ts"],"names":[],"mappings":"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"}

package/dist/history/rows.d.ts

@@ -0,0 +1,96 @@
+/**
+ * History rows and the state they add up to. Pure: rows in, state out.
+ *
+ * Rows are only ever appended. The state of a migration is its migration
+ * row with the highest `seq`; the state of one of its statements is that
+ * statement's row with the highest `seq`. A migration whose latest row is
+ * `succeeded` is applied. One whose latest row is `failed` (a statement
+ * failed) or `started` (the runner died) is part way: it resumes at the
+ * first statement whose latest row is not `succeeded`.
+ */
+export type HistoryStatus = "started" | "succeeded" | "failed";
+/** `step`: an Op step (#12), recorded as a statement is, its `note` the step's summary (receipts skipped and run). */
+export type HistoryKind = "migration" | "statement" | "step";
+/** The statement index of a migration's own rows. */
+export declare const MIGRATION_ROW = -1;
+/** One row of the history table, as written and as read back. */
+export interface HistoryRow {
+    seq: number;
+    /** The apply run that wrote it. */
+    run_id: string;
+    kind: HistoryKind;
+    migration_id: string;
+    /** The migration's parent id, `""` for the first. */
+    parent: string;
+    /** The migration's checksum when the row was written. */
+    checksum: string;
+    /** {@link MIGRATION_ROW} on a migration row; else the statement's (or Op step's) index in the migration's `steps`. */
+    statement_index: number;
+    /** `sha256:<hex>` of the statement's SQL; `""` on a migration row. */
+    statement_sha: string;
+    status: HistoryStatus;
+    /** The server's message, on a `failed` row. */
+    error: string;
+    /** Who ran it: the CI actor or the user, and the host. */
+    applied_by: string;
+    /** The plan digest the run was approved under. */
+    plan_digest: string;
+    /** The silences (`-- yodel:allow <RULE> <reason>`) in force, as JSON text; `"[]"` when none. */
+    silences: string;
+    /** Free text, e.g. a repair's reason (#15). */
+    note: string;
+    /** The server's time, `YYYY-MM-DD hh:mm:ss.ffffff` UTC; absent on a row not yet written. */
+    recorded_at?: string;
+}
+/** The hash a statement row records of the SQL it sent. */
+export declare const statementSha: (sql: string) => string;
+export interface StatementRecord {
+    index: number;
+    status: HistoryStatus;
+    sha: string;
+    error: string;
+    seq: number;
+}
+/** What the history says about one migration. */
+export interface MigrationRecord {
+    id: string;
+    parent: string | null;
+    /** The checksum on its latest migration row. */
+    checksum: string;
+    status: HistoryStatus;
+    error: string;
+    /** Who applied it; until it is applied, who wrote its latest migration row. A repair does not change it. */
+    appliedBy: string;
+    planDigest: string;
+    /** When it was applied (the row that first recorded it succeeded); until then, its latest migration row's time. A repair does not change it. */
+    recordedAt: string;
+    /** The repairs recorded since it was applied (`yodel repair`: a later succeeded migration row), oldest first. */
+    repairs: Repair[];
+    /** The seq of its latest migration row. */
+    seq: number;
+    /** The seq of the first row that recorded it `succeeded`; orders applied migrations by when they were applied. */
+    appliedSeq: number | undefined;
+    /** Each statement's latest row, by index. */
+    statements: Map<number, StatementRecord>;
+}
+/** A `yodel repair` of an applied migration: the new checksum, who recorded it, when and why. */
+export interface Repair {
+    checksum: string;
+    by: string;
+    at: string;
+    reason: string;
+    seq: number;
+}
+export interface HistoryState {
+    /** Every migration the history names, in the order each was first recorded. */
+    migrations: MigrationRecord[];
+    byId: Map<string, MigrationRecord>;
+    /** The highest seq in the history, 0 when it is empty. */
+    maxSeq: number;
+}
+/** The state the rows add up to. Rows may come in any order. */
+export declare function deriveState(rows: readonly HistoryRow[]): HistoryState;
+/** Whether the history records the migration applied. */
+export declare const isApplied: (m: MigrationRecord | undefined) => boolean;
+/** Whether the statement at `index` has already run: its latest row is `succeeded`. Such a statement is never sent again. */
+export declare const statementDone: (m: MigrationRecord | undefined, index: number) => boolean;

package/dist/history/rows.js

@@ -0,0 +1,73 @@
+/**
+ * History rows and the state they add up to. Pure: rows in, state out.
+ *
+ * Rows are only ever appended. The state of a migration is its migration
+ * row with the highest `seq`; the state of one of its statements is that
+ * statement's row with the highest `seq`. A migration whose latest row is
+ * `succeeded` is applied. One whose latest row is `failed` (a statement
+ * failed) or `started` (the runner died) is part way: it resumes at the
+ * first statement whose latest row is not `succeeded`.
+ */
+import { createHash } from "node:crypto";
+/** The statement index of a migration's own rows. */
+export const MIGRATION_ROW = -1;
+/** The hash a statement row records of the SQL it sent. */
+export const statementSha = (sql) => `sha256:${createHash("sha256").update(sql, "utf8").digest("hex")}`;
+/** The state the rows add up to. Rows may come in any order. */
+export function deriveState(rows) {
+    const sorted = [...rows].sort((a, b) => a.seq - b.seq);
+    const byId = new Map();
+    const order = [];
+    let maxSeq = 0;
+    for (const r of sorted) {
+        maxSeq = Math.max(maxSeq, r.seq);
+        let m = byId.get(r.migration_id);
+        if (!m) {
+            m = {
+                id: r.migration_id,
+                parent: r.parent === "" ? null : r.parent,
+                checksum: r.checksum,
+                status: "started",
+                error: "",
+                appliedBy: r.applied_by,
+                planDigest: r.plan_digest,
+                recordedAt: r.recorded_at ?? "",
+                seq: r.seq,
+                appliedSeq: undefined,
+                repairs: [],
+                statements: new Map(),
+            };
+            byId.set(r.migration_id, m);
+            order.push(m);
+        }
+        if (r.kind === "migration" && r.status === "succeeded" && m.status === "succeeded" && m.appliedSeq !== undefined) {
+            // Already applied: a repair. It records a new checksum; the migration was applied when and by whom it was.
+            m.parent = r.parent === "" ? null : r.parent;
+            m.checksum = r.checksum;
+            m.planDigest = r.plan_digest;
+            m.seq = r.seq;
+            m.repairs.push({ checksum: r.checksum, by: r.applied_by, at: r.recorded_at ?? "", reason: r.note, seq: r.seq });
+        }
+        else if (r.kind === "migration") {
+            m.parent = r.parent === "" ? null : r.parent;
+            m.checksum = r.checksum;
+            m.status = r.status;
+            m.error = r.error;
+            m.appliedBy = r.applied_by;
+            m.planDigest = r.plan_digest;
+            m.recordedAt = r.recorded_at ?? "";
+            m.seq = r.seq;
+            if (r.status === "succeeded" && m.appliedSeq === undefined)
+                m.appliedSeq = r.seq;
+        }
+        else {
+            m.statements.set(r.statement_index, { index: r.statement_index, status: r.status, sha: r.statement_sha, error: r.error, seq: r.seq });
+        }
+    }
+    return { migrations: order, byId, maxSeq };
+}
+/** Whether the history records the migration applied. */
+export const isApplied = (m) => m?.status === "succeeded";
+/** Whether the statement at `index` has already run: its latest row is `succeeded`. Such a statement is never sent again. */
+export const statementDone = (m, index) => m?.statements.get(index)?.status === "succeeded";
+//# sourceMappingURL=rows.js.map

package/dist/history/rows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rows.js","sourceRoot":"","sources":["../../src/history/rows.ts"],"names":[],"mappings":"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"}

package/dist/history/store.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Reading and appending the history table. Nothing here updates or deletes
+ * a row.
+ */
+import type { ClickHousePort } from "./client.js";
+import { type HistoryTopology } from "./topology.js";
+import { type HistoryRow, type HistoryState } from "./rows.js";
+export interface HistoryLocation {
+    database: string;
+    topology: HistoryTopology;
+}
+/** Who is applying: the CI actor or the user, at this host. */
+export declare function appliedBy(env?: NodeJS.ProcessEnv): string;
+type RawRow = Record<string, unknown>;
+/** A row as a server returns it (strings or numbers), as a {@link HistoryRow}. */
+export declare function fromRaw(r: RawRow): HistoryRow;
+/** What the versioned verbs need of a history, on either dialect: this ClickHouse store, or `./postgres/store.ts`. */
+export interface HistoryStoreLike {
+    exists(): Promise<boolean>;
+    ensure(): Promise<void>;
+    rows(options?: {
+        sync?: boolean;
+    }): Promise<HistoryRow[]>;
+    state(options?: {
+        sync?: boolean;
+    }): Promise<HistoryState>;
+    append(rows: readonly HistoryRow[]): Promise<void>;
+}
+export declare class HistoryStore implements HistoryStoreLike {
+    readonly port: ClickHousePort;
+    readonly location: HistoryLocation;
+    constructor(port: ClickHousePort, location: HistoryLocation);
+    get table(): string;
+    /** Whether the history table is there. A history that was never made has no rows. */
+    exists(): Promise<boolean>;
+    /** Creates the database and table when they are not there. */
+    ensure(): Promise<void>;
+    /**
+     * Every row. On a cluster or a Replicated database the replica first
+     * catches up with the others (`SYSTEM SYNC REPLICA`), so a run reads what
+     * a run on another host wrote; on Cloud the read is sequentially
+     * consistent. `sync: false` skips that, for a status read that need not
+     * wait.
+     */
+    rows(options?: {
+        sync?: boolean;
+    }): Promise<HistoryRow[]>;
+    state(options?: {
+        sync?: boolean;
+    }): Promise<HistoryState>;
+    /** Appends rows, as written; `recorded_at` is the server's. */
+    append(rows: readonly HistoryRow[]): Promise<void>;
+}
+/** The fields a run sets on every row it writes. */
+export interface RunContext {
+    runId: string;
+    appliedBy: string;
+    planDigest: string;
+}
+export declare const newRunContext: (planDigest: string, env?: NodeJS.ProcessEnv) => RunContext;
+/**
+ * Writes one run's rows, each with the next `seq`. Made under the lock from
+ * the history's highest seq, so seqs never collide across runs.
+ */
+export declare class HistoryRecorder {
+    readonly store: HistoryStoreLike;
+    readonly run: RunContext;
+    private next;
+    constructor(store: HistoryStoreLike, run: RunContext, maxSeq: number);
+    record(row: Omit<HistoryRow, "seq" | "run_id" | "applied_by" | "plan_digest" | "recorded_at" | "error" | "note" | "silences"> & Partial<Pick<HistoryRow, "error" | "note" | "silences">>): Promise<HistoryRow>;
+}
+export {};