@intentius/sql-yodeler 0.0.0-stage → 0.2.0

package/dist/history/ddl.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The history's DDL, per topology. Written out here rather than rendered by
+ * chant's topology renderer, so the history does not wait on a chant release
+ * and the four forms are plain to read and test:
+ *
+ * | topology   | database                                   | history table                                   |
+ * |------------|--------------------------------------------|-------------------------------------------------|
+ * | single     | `CREATE DATABASE`                          | `MergeTree`                                     |
+ * | cluster    | `CREATE DATABASE ... ON CLUSTER c`         | `ReplicatedMergeTree('<path>', '<replica>')` `ON CLUSTER c` |
+ * | replicated | `ENGINE = Replicated(...)`, `ON CLUSTER` when the topology names one | `ReplicatedMergeTree` with no arguments (the database supplies them) |
+ * | cloud      | `CREATE DATABASE`                          | `MergeTree` (Cloud makes it `SharedMergeTree`)  |
+ *
+ * The lock table is a `KeeperMap` (see `./lock.ts`); on a cluster it is
+ * created `ON CLUSTER`, every host's table naming the same Keeper path, so
+ * there is one lock for the cluster.
+ */
+import { type HistoryTopology } from "./topology.js";
+/** The database the history lives in when the environment names none. */
+export declare const DEFAULT_HISTORY_DATABASE = "yodeler";
+export declare const HISTORY_TABLE = "history";
+export declare const LOCK_TABLE = "lock";
+/** A ClickHouse identifier, back-quoted. */
+export declare const ident: (name: string) => string;
+/** A ClickHouse string literal. */
+export declare const literal: (value: string) => string;
+/**
+ * The history table's columns. One row per event, never updated or deleted:
+ *
+ * - a migration row (`kind = 'migration'`, `statement_index = -1`) when a
+ *   migration starts, succeeds or fails;
+ * - a statement row (`kind = 'statement'`, `statement_index` its index in
+ *   the migration's `steps`) when a statement starts, succeeds or fails;
+ * - a step row (`kind = 'step'`, the same) when an Op step (a rebuild, a
+ *   backfill) starts, succeeds or fails, its `note` the step's summary as
+ *   JSON (the receipts it skipped and the work it ran).
+ *
+ * The state of a migration or a statement is its row with the highest
+ * `seq`. `seq` is taken under the lock, one more than the highest in the
+ * table, so it orders rows across runs without trusting anyone's clock;
+ * `recorded_at` is the server's time, for people.
+ */
+export declare const HISTORY_COLUMNS: readonly (readonly [name: string, type: string])[];
+export interface HistoryDdlOptions {
+    database: string;
+    topology: HistoryTopology;
+}
+/** `CREATE DATABASE IF NOT EXISTS` for the history's database. */
+export declare function databaseDdl({ database, topology }: HistoryDdlOptions): string;
+/** The history table's engine clause for a topology. */
+export declare function historyEngine({ database, topology }: HistoryDdlOptions): string;
+/** `CREATE TABLE IF NOT EXISTS <database>.history`. */
+export declare function historyTableDdl(options: HistoryDdlOptions): string;
+/** The Keeper path of an environment's lock, under the server's `keeper_map_path_prefix`. */
+export declare const lockKeeperPath: (database: string) => string;
+/** `CREATE TABLE IF NOT EXISTS <database>.lock`, a KeeperMap. */
+export declare function lockTableDdl(options: HistoryDdlOptions): string;
+/** Every statement that makes the history ready, in order: the database, then the table. */
+export declare const historyDdl: (options: HistoryDdlOptions) => string[];

package/dist/history/ddl.js

@@ -0,0 +1,100 @@
+/**
+ * The history's DDL, per topology. Written out here rather than rendered by
+ * chant's topology renderer, so the history does not wait on a chant release
+ * and the four forms are plain to read and test:
+ *
+ * | topology   | database                                   | history table                                   |
+ * |------------|--------------------------------------------|-------------------------------------------------|
+ * | single     | `CREATE DATABASE`                          | `MergeTree`                                     |
+ * | cluster    | `CREATE DATABASE ... ON CLUSTER c`         | `ReplicatedMergeTree('<path>', '<replica>')` `ON CLUSTER c` |
+ * | replicated | `ENGINE = Replicated(...)`, `ON CLUSTER` when the topology names one | `ReplicatedMergeTree` with no arguments (the database supplies them) |
+ * | cloud      | `CREATE DATABASE`                          | `MergeTree` (Cloud makes it `SharedMergeTree`)  |
+ *
+ * The lock table is a `KeeperMap` (see `./lock.ts`); on a cluster it is
+ * created `ON CLUSTER`, every host's table naming the same Keeper path, so
+ * there is one lock for the cluster.
+ */
+import { defaultReplicaPath, DEFAULT_HISTORY_REPLICA_NAME } from "./topology.js";
+/** The database the history lives in when the environment names none. */
+export const DEFAULT_HISTORY_DATABASE = "yodeler";
+export const HISTORY_TABLE = "history";
+export const LOCK_TABLE = "lock";
+/** A ClickHouse identifier, back-quoted. */
+export const ident = (name) => `\`${name.replace(/\\/g, "\\\\").replace(/`/g, "\\`")}\``;
+/** A ClickHouse string literal. */
+export const literal = (value) => `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+const onCluster = (t) => (t.kind === "cluster" ? ` ON CLUSTER ${ident(t.cluster)}` : "");
+/**
+ * The history table's columns. One row per event, never updated or deleted:
+ *
+ * - a migration row (`kind = 'migration'`, `statement_index = -1`) when a
+ *   migration starts, succeeds or fails;
+ * - a statement row (`kind = 'statement'`, `statement_index` its index in
+ *   the migration's `steps`) when a statement starts, succeeds or fails;
+ * - a step row (`kind = 'step'`, the same) when an Op step (a rebuild, a
+ *   backfill) starts, succeeds or fails, its `note` the step's summary as
+ *   JSON (the receipts it skipped and the work it ran).
+ *
+ * The state of a migration or a statement is its row with the highest
+ * `seq`. `seq` is taken under the lock, one more than the highest in the
+ * table, so it orders rows across runs without trusting anyone's clock;
+ * `recorded_at` is the server's time, for people.
+ */
+export const HISTORY_COLUMNS = [
+    ["seq", "UInt64"],
+    ["run_id", "String"],
+    ["kind", "LowCardinality(String)"],
+    ["migration_id", "String"],
+    ["parent", "String"],
+    ["checksum", "String"],
+    ["statement_index", "Int32"],
+    ["statement_sha", "String"],
+    ["status", "LowCardinality(String)"],
+    ["error", "String"],
+    ["applied_by", "String"],
+    ["plan_digest", "String"],
+    ["silences", "String DEFAULT '[]'"],
+    ["note", "String"],
+    ["recorded_at", "DateTime64(6, 'UTC') DEFAULT now64(6)"],
+];
+/** `CREATE DATABASE IF NOT EXISTS` for the history's database. */
+export function databaseDdl({ database, topology }) {
+    if (topology.kind === "replicated") {
+        const cluster = topology.cluster ? ` ON CLUSTER ${ident(topology.cluster)}` : "";
+        return `CREATE DATABASE IF NOT EXISTS ${ident(database)}${cluster} ENGINE = Replicated(${literal(`/clickhouse/databases/${database}`)}, '{shard}', '{replica}')`;
+    }
+    return `CREATE DATABASE IF NOT EXISTS ${ident(database)}${onCluster(topology)}`;
+}
+/** The history table's engine clause for a topology. */
+export function historyEngine({ database, topology }) {
+    switch (topology.kind) {
+        case "cluster": {
+            const path = topology.replicaPath ?? defaultReplicaPath(database, HISTORY_TABLE);
+            const replica = topology.replicaName ?? DEFAULT_HISTORY_REPLICA_NAME;
+            return `ReplicatedMergeTree(${literal(path)}, ${literal(replica)})`;
+        }
+        case "replicated":
+            return "ReplicatedMergeTree";
+        case "single":
+        case "cloud":
+            return "MergeTree";
+    }
+}
+/** `CREATE TABLE IF NOT EXISTS <database>.history`. */
+export function historyTableDdl(options) {
+    const columns = HISTORY_COLUMNS.map(([name, type]) => `  ${name} ${type}`).join(",\n");
+    return (`CREATE TABLE IF NOT EXISTS ${ident(options.database)}.${HISTORY_TABLE}${onCluster(options.topology)}\n(\n${columns}\n)\n` +
+        `ENGINE = ${historyEngine(options)}\nORDER BY (migration_id, statement_index, seq)\n` +
+        `COMMENT 'yodel migration history: append-only, one row per migration and per statement event'`);
+}
+/** The Keeper path of an environment's lock, under the server's `keeper_map_path_prefix`. */
+export const lockKeeperPath = (database) => `/yodeler/${database}/lock`;
+/** `CREATE TABLE IF NOT EXISTS <database>.lock`, a KeeperMap. */
+export function lockTableDdl(options) {
+    return (`CREATE TABLE IF NOT EXISTS ${ident(options.database)}.${LOCK_TABLE}${onCluster(options.topology)}\n` +
+        `(\n  name String,\n  owner String,\n  acquired_at DateTime64(3, 'UTC'),\n  expires_at DateTime64(3, 'UTC')\n)\n` +
+        `ENGINE = KeeperMap(${literal(lockKeeperPath(options.database))})\nPRIMARY KEY name`);
+}
+/** Every statement that makes the history ready, in order: the database, then the table. */
+export const historyDdl = (options) => [databaseDdl(options), historyTableDdl(options)];
+//# sourceMappingURL=ddl.js.map

package/dist/history/ddl.js.map

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

package/dist/history/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The migration history (#8): an append-only ClickHouse table in the
+ * database the environment names (default `yodeler`), and the apply lock.
+ *
+ *   historyDdl({ database, topology })     CREATE DATABASE / TABLE for single, cluster, replicated, cloud
+ *   lockTableDdl({ database, topology })   the KeeperMap lock table
+ *   new HistoryStore(port, location)       exists(), ensure(), rows(), state(), append(rows)
+ *   new HistoryRecorder(store, run, maxSeq) record(row): appends with the next seq
+ *   deriveState(rows)                      the latest row per migration and per statement
+ *   isApplied(record), statementDone(record, i)
+ *   acquireLock(port, options), withLock(lock, ttl, body)
+ *   parseHistoryTopology("cluster:main")
+ *
+ * Rows are never updated or deleted; a state is always the row with the
+ * highest seq for its key. #10 (`init --from` records a baseline), #12 (Op
+ * steps record their receipts' progress), #13 (the Postgres twin), #15
+ * (`repair` appends a migration row with the new checksum and a `note`) and
+ * #16 (the digest) build on this.
+ */
+export * from "./client.js";
+export * from "./ddl.js";
+export * from "./lock.js";
+export * from "./rows.js";
+export * from "./store.js";
+export * from "./topology.js";

package/dist/history/index.js

@@ -0,0 +1,26 @@
+/**
+ * The migration history (#8): an append-only ClickHouse table in the
+ * database the environment names (default `yodeler`), and the apply lock.
+ *
+ *   historyDdl({ database, topology })     CREATE DATABASE / TABLE for single, cluster, replicated, cloud
+ *   lockTableDdl({ database, topology })   the KeeperMap lock table
+ *   new HistoryStore(port, location)       exists(), ensure(), rows(), state(), append(rows)
+ *   new HistoryRecorder(store, run, maxSeq) record(row): appends with the next seq
+ *   deriveState(rows)                      the latest row per migration and per statement
+ *   isApplied(record), statementDone(record, i)
+ *   acquireLock(port, options), withLock(lock, ttl, body)
+ *   parseHistoryTopology("cluster:main")
+ *
+ * Rows are never updated or deleted; a state is always the row with the
+ * highest seq for its key. #10 (`init --from` records a baseline), #12 (Op
+ * steps record their receipts' progress), #13 (the Postgres twin), #15
+ * (`repair` appends a migration row with the new checksum and a `note`) and
+ * #16 (the digest) build on this.
+ */
+export * from "./client.js";
+export * from "./ddl.js";
+export * from "./lock.js";
+export * from "./rows.js";
+export * from "./store.js";
+export * from "./topology.js";
+//# sourceMappingURL=index.js.map

package/dist/history/index.js.map

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

package/dist/history/lock.d.ts

@@ -0,0 +1,104 @@
+/**
+ * One apply at a time per environment.
+ *
+ * ## Keeper: a KeeperMap row
+ *
+ * The lock is a row in `<history database>.lock`, a `KeeperMap` table, so
+ * it lives in Keeper. Inserted with `keeper_map_strict_mode = 1`, an insert
+ * of a key that is there already fails ("Node exists") instead of
+ * overwriting it: create-if-absent, which is a lock. Every runner, on any
+ * host, sees the same row, because every host's `lock` table names the same
+ * Keeper path. It was picked over the other routes ClickHouse SQL offers:
+ *
+ * - an insert into a Replicated table that deduplicates: the losing insert is
+ *   dropped silently, inside a time window, so the loser cannot tell it lost
+ *   without reading back, and a later insert is not refused at all;
+ * - `INSERT INTO system.zookeeper`: no `DELETE`, so a lock could never be
+ *   released or expired from SQL.
+ *
+ * The row names its owner and an expiry. A runner that holds it extends the
+ * expiry while it works (a heartbeat every third of the TTL) and deletes the
+ * row when done. A runner that finds an expired row deletes that row (by its
+ * owner, so it never deletes a newer one) and inserts its own; two runners
+ * racing for an expired lock both delete, and only one insert succeeds. A
+ * heartbeat that finds the row gone or someone else's stops the apply
+ * before its next statement.
+ *
+ * KeeperMap needs Keeper and the server setting `keeper_map_path_prefix`.
+ *
+ * ## No Keeper: a local lock file
+ *
+ * A single node with no Keeper (or no `keeper_map_path_prefix`) gets a lock
+ * file under the system temp directory instead, created exclusively, with
+ * the same owner and expiry. It serializes applies from one machine only, and
+ * the run says so: cross-runner locking needs Keeper. A cluster, a
+ * Replicated database or Cloud never fall back: they refuse without the
+ * KeeperMap lock.
+ *
+ * ## Clearing a lock by hand
+ *
+ * A dead runner's lock expires after its TTL (`YODEL_LOCK_TTL`, seconds,
+ * default 900). To clear it sooner, when you know no apply is running:
+ *
+ *   Keeper: ALTER TABLE <history database>.lock DELETE WHERE name = 'apply'
+ *   local:  rm the lock file the refusal names
+ */
+import { YodelError } from "../project.js";
+import { type ClickHousePort } from "./client.js";
+import { type HistoryTopology } from "./topology.js";
+/** Exit code: another apply holds the lock. */
+export declare const LOCKED = 5;
+/** The lock row's key: one apply lock per history database. */
+export declare const LOCK_NAME = "apply";
+/** Default lock TTL. */
+export declare const DEFAULT_LOCK_TTL_MS: number;
+export interface Lock {
+    /** `advisory`: a Postgres session advisory lock (`./postgres/lock.ts`). */
+    kind: "keeper" | "local" | "advisory";
+    owner: string;
+    /** Where it is: the KeeperMap table, or the lock file. */
+    where: string;
+    /** Set when the lock is local: why, and that cross-runner locking needs Keeper. */
+    notice?: string;
+    /** Extends the expiry. Throws a {@link LockLostError} when the lock is no longer this owner's. */
+    heartbeat(): Promise<void>;
+    /** Deletes the lock, when it is still this owner's. */
+    release(): Promise<void>;
+}
+export declare class LockHeldError extends YodelError {
+    readonly holder: string;
+    readonly expiresAt: string;
+    readonly where: string;
+    readonly clear: string;
+    /** Set when the run waited for it (`--lock-wait`): how long, in words. */
+    readonly waited?: string | undefined;
+    constructor(holder: string, expiresAt: string, where: string, clear: string, 
+    /** Set when the run waited for it (`--lock-wait`): how long, in words. */
+    waited?: string | undefined);
+}
+export declare class LockLostError extends YodelError {
+    constructor(where: string);
+}
+export interface LockOptions {
+    database: string;
+    topology: HistoryTopology;
+    /** Who holds it, for the refusal another runner sees. */
+    holder: string;
+    ttlMs?: number;
+    /** Identifies the server, for the local lock file's name. */
+    serverKey: string;
+    /** Where local lock files go. Default: `<tmpdir>/yodel-locks`. */
+    localDir?: string;
+}
+/** A lock owner: who, plus a random part so two runs by the same user never share one. */
+export declare const lockOwner: (holder: string) => string;
+/** Acquires the environment's apply lock, or throws {@link LockHeldError}. */
+export declare function acquireLock(port: ClickHousePort, options: LockOptions): Promise<Lock>;
+/** The local lock's file for a server and history database. */
+export declare function localLockPath(options: Pick<LockOptions, "serverKey" | "database" | "localDir">): string;
+/**
+ * Runs `body` holding the lock: a heartbeat every third of the TTL while it
+ * runs, the lock released after, whatever happens. `beat` lets the body
+ * extend the lock (and learn it was lost) between statements.
+ */
+export declare function withLock<T>(lock: Lock, ttlMs: number, body: (beat: () => Promise<void>) => Promise<T>): Promise<T>;

package/dist/history/lock.js

@@ -0,0 +1,230 @@
+/**
+ * One apply at a time per environment.
+ *
+ * ## Keeper: a KeeperMap row
+ *
+ * The lock is a row in `<history database>.lock`, a `KeeperMap` table, so
+ * it lives in Keeper. Inserted with `keeper_map_strict_mode = 1`, an insert
+ * of a key that is there already fails ("Node exists") instead of
+ * overwriting it: create-if-absent, which is a lock. Every runner, on any
+ * host, sees the same row, because every host's `lock` table names the same
+ * Keeper path. It was picked over the other routes ClickHouse SQL offers:
+ *
+ * - an insert into a Replicated table that deduplicates: the losing insert is
+ *   dropped silently, inside a time window, so the loser cannot tell it lost
+ *   without reading back, and a later insert is not refused at all;
+ * - `INSERT INTO system.zookeeper`: no `DELETE`, so a lock could never be
+ *   released or expired from SQL.
+ *
+ * The row names its owner and an expiry. A runner that holds it extends the
+ * expiry while it works (a heartbeat every third of the TTL) and deletes the
+ * row when done. A runner that finds an expired row deletes that row (by its
+ * owner, so it never deletes a newer one) and inserts its own; two runners
+ * racing for an expired lock both delete, and only one insert succeeds. A
+ * heartbeat that finds the row gone or someone else's stops the apply
+ * before its next statement.
+ *
+ * KeeperMap needs Keeper and the server setting `keeper_map_path_prefix`.
+ *
+ * ## No Keeper: a local lock file
+ *
+ * A single node with no Keeper (or no `keeper_map_path_prefix`) gets a lock
+ * file under the system temp directory instead, created exclusively, with
+ * the same owner and expiry. It serializes applies from one machine only, and
+ * the run says so: cross-runner locking needs Keeper. A cluster, a
+ * Replicated database or Cloud never fall back: they refuse without the
+ * KeeperMap lock.
+ *
+ * ## Clearing a lock by hand
+ *
+ * A dead runner's lock expires after its TTL (`YODEL_LOCK_TTL`, seconds,
+ * default 900). To clear it sooner, when you know no apply is running:
+ *
+ *   Keeper: ALTER TABLE <history database>.lock DELETE WHERE name = 'apply'
+ *   local:  rm the lock file the refusal names
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { YodelError } from "../project.js";
+import { serverMessage } from "./client.js";
+import { databaseDdl, ident, literal, LOCK_TABLE, lockTableDdl } from "./ddl.js";
+import { describeTopology } from "./topology.js";
+/** Exit code: another apply holds the lock. */
+export const LOCKED = 5;
+/** The lock row's key: one apply lock per history database. */
+export const LOCK_NAME = "apply";
+/** Default lock TTL. */
+export const DEFAULT_LOCK_TTL_MS = 15 * 60 * 1000;
+export class LockHeldError extends YodelError {
+    holder;
+    expiresAt;
+    where;
+    clear;
+    waited;
+    constructor(holder, expiresAt, where, clear, 
+    /** Set when the run waited for it (`--lock-wait`): how long, in words. */
+    waited) {
+        super(`another apply holds the lock (${where}): owner ${holder}, ${where.startsWith("Postgres advisory lock") ? "since" : "until"} ${expiresAt} UTC. ` +
+            (waited ? `This run ${waited}. ` : "") +
+            `Wait for it, or once you know it is not running, clear it with: ${clear}`, LOCKED);
+        this.holder = holder;
+        this.expiresAt = expiresAt;
+        this.where = where;
+        this.clear = clear;
+        this.waited = waited;
+        this.name = "LockHeldError";
+    }
+}
+export class LockLostError extends YodelError {
+    constructor(where) {
+        super(`the apply lock (${where}) is no longer held by this run (it expired and another run took it); stopped before the next statement`, LOCKED);
+        this.name = "LockLostError";
+    }
+}
+/** A lock owner: who, plus a random part so two runs by the same user never share one. */
+export const lockOwner = (holder) => `${holder}#${String(process.pid)}-${randomUUID().slice(0, 8)}`;
+const isNodeExists = (e) => /Node exists|already exists/i.test(serverMessage(e));
+const keeperMapUnavailable = (e) => /keeper_map_path_prefix|ZooKeeper|Keeper is not|KEEPER_EXCEPTION.*(not configured|connection)|No such engine|UNKNOWN_STORAGE/i.test(serverMessage(e));
+const STRICT = { keeper_map_strict_mode: "1", async_insert: "0" };
+/** Acquires the environment's apply lock, or throws {@link LockHeldError}. */
+export async function acquireLock(port, options) {
+    const ttlMs = options.ttlMs ?? DEFAULT_LOCK_TTL_MS;
+    await port.query(databaseDdl(options));
+    try {
+        await port.query(lockTableDdl(options));
+    }
+    catch (e) {
+        if (!keeperMapUnavailable(e))
+            throw e;
+        const why = (serverMessage(e).split("\n")[0] ?? "").replace(/^Code: \d+\. DB::Exception: /, "").replace(/\s*\([A-Z_]+\)\s*\(version [^)]*\)\s*$/, "");
+        if (options.topology.kind !== "single") {
+            throw new YodelError(`topology ${describeTopology(options.topology)} needs the Keeper lock (a KeeperMap table), and the server cannot make one: ${why}. ` +
+                `Configure Keeper and keeper_map_path_prefix on the server.`);
+        }
+        return localLock(options, ttlMs, `no KeeperMap on this server (${why}); the lock is a file on this machine, so cross-runner locking needs Keeper (and keeper_map_path_prefix)`);
+    }
+    return keeperLock(port, options, ttlMs);
+}
+async function keeperLock(port, options, ttlMs) {
+    const table = `${ident(options.database)}.${LOCK_TABLE}`;
+    const owner = lockOwner(options.holder);
+    const where = `KeeperMap ${options.database}.${LOCK_TABLE}`;
+    const clear = `ALTER TABLE ${table} DELETE WHERE name = '${LOCK_NAME}'`;
+    const until = `now64(3) + toIntervalMillisecond(${String(ttlMs)})`;
+    const read = async () => (await port.query(
+    // Not aliased as expires_at: an alias shadows the column in ClickHouse, and the comparison would read the string.
+    `SELECT owner, toString(expires_at) AS until, expires_at < now64(3) AS expired FROM ${table} WHERE name = ${literal(LOCK_NAME)}`))[0];
+    for (let attempt = 0;; attempt++) {
+        try {
+            await port.query(`INSERT INTO ${table} (name, owner, acquired_at, expires_at) SELECT ${literal(LOCK_NAME)}, ${literal(owner)}, now64(3), ${until}`, { settings: STRICT });
+            break;
+        }
+        catch (e) {
+            if (!isNodeExists(e))
+                throw e;
+            const held = await read();
+            if (held && Number(held.expired) !== 1)
+                throw new LockHeldError(held.owner, held.until, where, clear);
+            if (attempt >= 3)
+                throw new LockHeldError(held?.owner ?? "(unknown)", held?.until ?? "(unknown)", where, clear);
+            // Expired (or released between the insert and the read): delete that owner's row, never a newer one, and try again.
+            if (held)
+                await port.query(`ALTER TABLE ${table} DELETE WHERE name = ${literal(LOCK_NAME)} AND owner = ${literal(held.owner)}`, { settings: STRICT });
+        }
+    }
+    return {
+        kind: "keeper",
+        owner,
+        where,
+        async heartbeat() {
+            await port.query(`ALTER TABLE ${table} UPDATE expires_at = ${until} WHERE name = ${literal(LOCK_NAME)} AND owner = ${literal(owner)}`, { settings: STRICT });
+            const held = await read();
+            if (held?.owner !== owner)
+                throw new LockLostError(where);
+        },
+        async release() {
+            await port.query(`ALTER TABLE ${table} DELETE WHERE name = ${literal(LOCK_NAME)} AND owner = ${literal(owner)}`, { settings: STRICT });
+        },
+    };
+}
+/** The local lock's file for a server and history database. */
+export function localLockPath(options) {
+    const key = createHash("sha256").update(`${options.serverKey}\n${options.database}`).digest("hex").slice(0, 16);
+    return join(options.localDir ?? join(tmpdir(), "yodel-locks"), `${options.database}-${key}.lock`);
+}
+function readLockFile(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function localLock(options, ttlMs, notice) {
+    const path = localLockPath(options);
+    mkdirSync(join(path, ".."), { recursive: true });
+    const owner = lockOwner(options.holder);
+    const where = `local lock file ${path}`;
+    const body = () => JSON.stringify({ owner, acquiredAt: new Date().toISOString(), expiresAt: new Date(Date.now() + ttlMs).toISOString() });
+    for (let attempt = 0;; attempt++) {
+        try {
+            writeFileSync(path, body(), { flag: "wx" });
+            break;
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e;
+            const held = readLockFile(path);
+            const expired = !held || Date.parse(held.expiresAt) < Date.now();
+            if (!expired || attempt >= 3)
+                throw new LockHeldError(held?.owner ?? "(unreadable)", held?.expiresAt ?? "(unknown)", where, `rm ${path}`);
+            rmSync(path, { force: true });
+        }
+    }
+    return {
+        kind: "local",
+        owner,
+        where,
+        notice,
+        heartbeat() {
+            if (readLockFile(path)?.owner !== owner)
+                return Promise.reject(new LockLostError(where));
+            writeFileSync(path, body());
+            return Promise.resolve();
+        },
+        release() {
+            if (readLockFile(path)?.owner === owner)
+                rmSync(path, { force: true });
+            return Promise.resolve();
+        },
+    };
+}
+/**
+ * Runs `body` holding the lock: a heartbeat every third of the TTL while it
+ * runs, the lock released after, whatever happens. `beat` lets the body
+ * extend the lock (and learn it was lost) between statements.
+ */
+export async function withLock(lock, ttlMs, body) {
+    let lost;
+    const timer = setInterval(() => {
+        lock.heartbeat().catch((e) => {
+            lost ??= e;
+        });
+    }, Math.max(1000, Math.floor(ttlMs / 3)));
+    timer.unref();
+    const beat = async () => {
+        if (lost !== undefined)
+            throw lost instanceof Error ? lost : new LockLostError(lock.where);
+        await lock.heartbeat();
+    };
+    try {
+        return await body(beat);
+    }
+    finally {
+        clearInterval(timer);
+        await lock.release().catch(() => undefined);
+    }
+}
+//# sourceMappingURL=lock.js.map

package/dist/history/lock.js.map

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

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

@@ -0,0 +1,22 @@
+/**
+ * The Postgres history's DDL: `<schema>.history` in a schema of its own
+ * (default `yodeler`, the environment's history database setting), the same
+ * columns as the ClickHouse table (`../ddl.ts`), so a row reads the same in
+ * both and `deriveState` adds them up the same way.
+ *
+ * `seq` is the primary key: two runs can never write the same one (a run
+ * takes it under the advisory lock, one more than the highest), and the key
+ * says so if one ever tried. Rows are only ever inserted.
+ */
+/** A Postgres identifier, double-quoted. */
+export declare const pgIdent: (name: string) => string;
+/** A Postgres string literal (standard_conforming_strings, the default since 9.1). */
+export declare const pgLiteral: (value: string) => string;
+/** The history table's columns, in the order {@link HISTORY_COLUMNS} (ClickHouse) has them. */
+export declare const PG_HISTORY_COLUMNS: readonly (readonly [name: string, type: string])[];
+/** The columns a row write names: all but `recorded_at`, which is the server's. */
+export declare const PG_WRITTEN_COLUMNS: string[];
+/** `<schema>.history`, quoted. */
+export declare const pgHistoryTable: (schema: string) => string;
+/** Every statement that makes the history ready, in order: the schema, the table, its comment. */
+export declare function pgHistoryDdl(schema: string): string[];

package/dist/history/postgres/ddl.js

@@ -0,0 +1,47 @@
+/**
+ * The Postgres history's DDL: `<schema>.history` in a schema of its own
+ * (default `yodeler`, the environment's history database setting), the same
+ * columns as the ClickHouse table (`../ddl.ts`), so a row reads the same in
+ * both and `deriveState` adds them up the same way.
+ *
+ * `seq` is the primary key: two runs can never write the same one (a run
+ * takes it under the advisory lock, one more than the highest), and the key
+ * says so if one ever tried. Rows are only ever inserted.
+ */
+import { HISTORY_TABLE } from "../ddl.js";
+/** A Postgres identifier, double-quoted. */
+export const pgIdent = (name) => `"${name.replace(/"/g, '""')}"`;
+/** A Postgres string literal (standard_conforming_strings, the default since 9.1). */
+export const pgLiteral = (value) => `'${value.replace(/'/g, "''")}'`;
+/** The history table's columns, in the order {@link HISTORY_COLUMNS} (ClickHouse) has them. */
+export const PG_HISTORY_COLUMNS = [
+    ["seq", "bigint NOT NULL PRIMARY KEY"],
+    ["run_id", "text NOT NULL"],
+    ["kind", "text NOT NULL CHECK (kind IN ('migration', 'statement', 'step'))"],
+    ["migration_id", "text NOT NULL"],
+    ["parent", "text NOT NULL DEFAULT ''"],
+    ["checksum", "text NOT NULL DEFAULT ''"],
+    ["statement_index", "integer NOT NULL"],
+    ["statement_sha", "text NOT NULL DEFAULT ''"],
+    ["status", "text NOT NULL CHECK (status IN ('started', 'succeeded', 'failed'))"],
+    ["error", "text NOT NULL DEFAULT ''"],
+    ["applied_by", "text NOT NULL DEFAULT ''"],
+    ["plan_digest", "text NOT NULL DEFAULT ''"],
+    ["silences", "text NOT NULL DEFAULT '[]'"],
+    ["note", "text NOT NULL DEFAULT ''"],
+    ["recorded_at", "timestamptz NOT NULL DEFAULT pg_catalog.clock_timestamp()"],
+];
+/** The columns a row write names: all but `recorded_at`, which is the server's. */
+export const PG_WRITTEN_COLUMNS = PG_HISTORY_COLUMNS.map(([name]) => name).filter((n) => n !== "recorded_at");
+/** `<schema>.history`, quoted. */
+export const pgHistoryTable = (schema) => `${pgIdent(schema)}.${pgIdent(HISTORY_TABLE)}`;
+/** Every statement that makes the history ready, in order: the schema, the table, its comment. */
+export function pgHistoryDdl(schema) {
+    const columns = PG_HISTORY_COLUMNS.map(([name, type]) => `  ${name} ${type}`).join(",\n");
+    return [
+        `CREATE SCHEMA IF NOT EXISTS ${pgIdent(schema)}`,
+        `CREATE TABLE IF NOT EXISTS ${pgHistoryTable(schema)} (\n${columns}\n)`,
+        `COMMENT ON TABLE ${pgHistoryTable(schema)} IS 'yodel migration history: append-only, one row per migration, statement and step event'`,
+    ];
+}
+//# sourceMappingURL=ddl.js.map