@intentius/sql-yodeler 0.0.0-stage → 0.1.0

package/dist/config/settings.d.ts

@@ -0,0 +1,40 @@
+/**
+ * One environment's settings, from `yodel.config.ts`, chant's profile and
+ * the process environment, first one set wins:
+ *
+ * | setting          | 1. yodel.config.ts                     | 2. chant.config.ts                | 3. env var              | default  |
+ * |------------------|----------------------------------------|-----------------------------------|-------------------------|----------|
+ * | topology         | `environments.<env>.topology`          | `sql.profiles.<env>.topology`     | `YODEL_TOPOLOGY`        | `single` |
+ * | history database | `environments.<env>.history.database`  |                                   | `YODEL_HISTORY_DATABASE`| `yodeler`|
+ * | lock TTL         | `environments.<env>.lockTtl` (seconds) |                                   | `YODEL_LOCK_TTL`        | 900      |
+ */
+import { type Topology } from "@intentius/chant-lexicon-sql/clickhouse/topology";
+import type { HistoryTopology } from "../history/topology.js";
+import { YodelError, type Project } from "../project.js";
+export interface EnvironmentSettings {
+    /** What every statement is rendered for when it is sent. */
+    topology: Topology;
+    /** Where {@link topology} came from, for messages: `yodel.config.ts`, `sql.profiles.<env>.topology`, `YODEL_TOPOLOGY` or `default`. */
+    topologySource: string;
+    /**
+     * The history's topology: {@link topology} without a cluster's Keeper
+     * path and replica name, which are for the migrations' tables. The
+     * history keeps its own path, one copy for the whole cluster.
+     */
+    historyTopology: HistoryTopology;
+    historyDatabase: string;
+    lockTtlMs: number;
+}
+/** The topology the history's DDL is written for. */
+export declare function historyTopologyOf(t: Topology): HistoryTopology;
+/** The settings of environment `name`; see the module comment for the order. */
+export declare function environmentSettings(project: Pick<Project, "config" | "yodel">, name: string, env?: NodeJS.ProcessEnv): EnvironmentSettings;
+/** `cluster:main (yodel.config.ts)`, for a report's header. */
+export declare const describeSettingsTopology: (s: Pick<EnvironmentSettings, "topology" | "topologySource">) => string;
+/**
+ * The declarative path (`yodel plan`, `yodel apply` without migrations) runs
+ * chant's planner and applier, which render for `sql.profiles.<env>.topology`
+ * and do not read `yodel.config.ts`. A topology set only in yodel.config.ts
+ * would be ignored there, so it is refused unless chant's profile says the same.
+ */
+export declare function declarativeTopologyRefusal(project: Pick<Project, "config" | "yodel">, name: string): YodelError | undefined;

package/dist/config/settings.js

@@ -0,0 +1,88 @@
+/**
+ * One environment's settings, from `yodel.config.ts`, chant's profile and
+ * the process environment, first one set wins:
+ *
+ * | setting          | 1. yodel.config.ts                     | 2. chant.config.ts                | 3. env var              | default  |
+ * |------------------|----------------------------------------|-----------------------------------|-------------------------|----------|
+ * | topology         | `environments.<env>.topology`          | `sql.profiles.<env>.topology`     | `YODEL_TOPOLOGY`        | `single` |
+ * | history database | `environments.<env>.history.database`  |                                   | `YODEL_HISTORY_DATABASE`| `yodeler`|
+ * | lock TTL         | `environments.<env>.lockTtl` (seconds) |                                   | `YODEL_LOCK_TTL`        | 900      |
+ */
+import { toTopology, topologyLabel } from "@intentius/chant-lexicon-sql/clickhouse/topology";
+import { DEFAULT_HISTORY_DATABASE } from "../history/ddl.js";
+import { DEFAULT_LOCK_TTL_MS } from "../history/lock.js";
+import { YodelError } from "../project.js";
+import { CONFIG_FILE } from "./load.js";
+function parse(value, where) {
+    try {
+        return toTopology(value);
+    }
+    catch (e) {
+        throw new YodelError(`${where}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+/** The topology the history's DDL is written for. */
+export function historyTopologyOf(t) {
+    return t.kind === "cluster" ? { kind: "cluster", cluster: t.cluster } : t;
+}
+/** The settings of environment `name`; see the module comment for the order. */
+export function environmentSettings(project, name, env = process.env) {
+    const own = project.yodel?.config.environments?.[name];
+    const profile = project.config.sql?.profiles?.[name];
+    let topology;
+    let topologySource;
+    if (own?.topology !== undefined) {
+        topology = parse(own.topology, `${CONFIG_FILE}: environments.${name}.topology`);
+        topologySource = CONFIG_FILE;
+    }
+    else if (profile?.topology !== undefined) {
+        topology = parse(profile.topology, `sql.profiles.${name}.topology`);
+        topologySource = `sql.profiles.${name}.topology`;
+    }
+    else if (env.YODEL_TOPOLOGY) {
+        topology = parse(env.YODEL_TOPOLOGY, "YODEL_TOPOLOGY");
+        topologySource = "YODEL_TOPOLOGY";
+    }
+    else {
+        topology = { kind: "single" };
+        topologySource = "default";
+    }
+    let lockTtlMs = DEFAULT_LOCK_TTL_MS;
+    if (own?.lockTtl !== undefined)
+        lockTtlMs = own.lockTtl * 1000;
+    else if (env.YODEL_LOCK_TTL) {
+        const ttl = Number(env.YODEL_LOCK_TTL);
+        if (!(Number.isFinite(ttl) && ttl > 0))
+            throw new YodelError(`YODEL_LOCK_TTL must be a number of seconds, got ${JSON.stringify(env.YODEL_LOCK_TTL)}`);
+        lockTtlMs = ttl * 1000;
+    }
+    return {
+        topology,
+        topologySource,
+        historyTopology: historyTopologyOf(topology),
+        historyDatabase: own?.history?.database ?? (env.YODEL_HISTORY_DATABASE || DEFAULT_HISTORY_DATABASE),
+        lockTtlMs,
+    };
+}
+/** `cluster:main (yodel.config.ts)`, for a report's header. */
+export const describeSettingsTopology = (s) => `${topologyLabel(s.topology)} (${s.topologySource})`;
+/**
+ * The declarative path (`yodel plan`, `yodel apply` without migrations) runs
+ * chant's planner and applier, which render for `sql.profiles.<env>.topology`
+ * and do not read `yodel.config.ts`. A topology set only in yodel.config.ts
+ * would be ignored there, so it is refused unless chant's profile says the same.
+ */
+export function declarativeTopologyRefusal(project, name) {
+    const own = project.yodel?.config.environments?.[name]?.topology;
+    if (own === undefined)
+        return undefined;
+    const profile = project.config.sql?.profiles?.[name]?.topology;
+    const ours = parse(own, `${CONFIG_FILE}: environments.${name}.topology`);
+    const chants = profile === undefined ? undefined : parse(profile, `sql.profiles.${name}.topology`);
+    if (chants && JSON.stringify(sorted(chants)) === JSON.stringify(sorted(ours)))
+        return undefined;
+    return new YodelError(`${CONFIG_FILE} sets environments.${name}.topology to ${topologyLabel(ours)}, but the declarative path plans and applies through chant, which reads sql.profiles.${name}.topology ` +
+        `(${chants ? topologyLabel(chants) : "unset"}). Set sql.profiles.${name}.topology to the same in chant.config.ts, or leave the topology to chant.config.ts.`);
+}
+const sorted = (t) => Object.entries(t).sort(([a], [b]) => a.localeCompare(b));
+//# sourceMappingURL=settings.js.map

package/dist/config/settings.js.map

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

package/dist/env-args.d.ts

@@ -0,0 +1,18 @@
+import type { Io } from "./command.js";
+/** The arguments `yodel <verb> <env>` takes: the environment, `--json`, `--dir`, and any extra string options. */
+export interface EnvArgs {
+    env: string;
+    json: boolean;
+    /** The project directory, or a directory inside it. Default: the working directory. */
+    dir: string;
+    options: Record<string, string | undefined>;
+}
+/** True when the arguments ask for the verb's help. */
+export declare const wantsHelp: (args: readonly string[]) => boolean;
+export declare function parseEnvArgs(verb: string, args: string[], extra?: readonly string[]): EnvArgs;
+export declare function usage(verb: string, extra?: readonly string[]): string;
+/**
+ * Runs a verb: prints `help` for `--help`, else runs `body`, turning a
+ * {@link YodelError} (or any error) into a message on stderr and its exit code.
+ */
+export declare function guarded(verb: string, io: Io, args: readonly string[], help: string, body: () => Promise<number>): Promise<number>;

package/dist/env-args.js

@@ -0,0 +1,62 @@
+import { parseArgs } from "node:util";
+import { YodelError } from "./project.js";
+/** True when the arguments ask for the verb's help. */
+export const wantsHelp = (args) => args.includes("--help") || args.includes("-h");
+export function parseEnvArgs(verb, args, extra = []) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args,
+            allowPositionals: true,
+            strict: true,
+            options: {
+                json: { type: "boolean" },
+                dir: { type: "string", short: "C" },
+                ...Object.fromEntries(extra.map((name) => [name, { type: "string" }])),
+            },
+        });
+    }
+    catch (e) {
+        throw new YodelError(`${e instanceof Error ? e.message : String(e)}\n${usage(verb, extra)}`);
+    }
+    const { values, positionals } = parsed;
+    const [env, ...rest] = positionals;
+    if (env === undefined || rest.length > 0)
+        throw new YodelError(usage(verb, extra));
+    const options = {};
+    for (const name of extra) {
+        const v = values[name];
+        options[name] = typeof v === "string" ? v : undefined;
+    }
+    return {
+        env,
+        json: values.json === true,
+        dir: typeof values.dir === "string" ? values.dir : process.cwd(),
+        options,
+    };
+}
+export function usage(verb, extra = []) {
+    return `usage: yodel ${verb} <env> [--json] [--dir <project>]${extra.map((e) => ` [--${e} <${e}>]`).join("")}`;
+}
+/**
+ * Runs a verb: prints `help` for `--help`, else runs `body`, turning a
+ * {@link YodelError} (or any error) into a message on stderr and its exit code.
+ */
+export async function guarded(verb, io, args, help, body) {
+    if (wantsHelp(args)) {
+        io.out(help);
+        return 0;
+    }
+    try {
+        return await body();
+    }
+    catch (e) {
+        if (e instanceof YodelError) {
+            io.err(`yodel ${verb}: ${e.message}\n`);
+            return e.exitCode;
+        }
+        io.err(`yodel ${verb}: ${e instanceof Error ? (e.stack ?? e.message) : String(e)}\n`);
+        return 1;
+    }
+}
+//# sourceMappingURL=env-args.js.map

package/dist/env-args.js.map

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

package/dist/history/client.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The one thing the history needs from a ClickHouse server: run a statement,
+ * get rows back. Over chant's own HTTP client in use; an in-memory fake in
+ * the unit tests.
+ */
+import type { ClickHouseEndpoint } from "@intentius/chant-lexicon-sql/clickhouse/http";
+export interface QueryOptions {
+    /** Server settings for this query alone. `database` sets the default database. */
+    settings?: Record<string, string>;
+}
+export interface ClickHousePort {
+    query<Row = Record<string, unknown>>(sql: string, options?: QueryOptions): Promise<Row[]>;
+}
+/** A port over chant's ClickHouse HTTP client. */
+export declare function httpPort(endpoint: ClickHouseEndpoint): Promise<ClickHousePort>;
+/** The server's message for an error from a port, first line. */
+export declare function serverMessage(e: unknown): string;

package/dist/history/client.js

@@ -0,0 +1,19 @@
+/**
+ * The one thing the history needs from a ClickHouse server: run a statement,
+ * get rows back. Over chant's own HTTP client in use; an in-memory fake in
+ * the unit tests.
+ */
+/** A port over chant's ClickHouse HTTP client. */
+export async function httpPort(endpoint) {
+    const { clickhouseQuery } = await import("@intentius/chant-lexicon-sql/clickhouse/http");
+    return {
+        query: (sql, options = {}) => clickhouseQuery(endpoint, sql, options.settings ? { settings: options.settings } : {}),
+    };
+}
+/** The server's message for an error from a port, first line. */
+export function serverMessage(e) {
+    if (e && typeof e === "object" && "serverMessage" in e && typeof e.serverMessage === "string")
+        return e.serverMessage.trim();
+    return e instanceof Error ? e.message : String(e);
+}
+//# sourceMappingURL=client.js.map

package/dist/history/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/history/client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAaH,kDAAkD;AAClD,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,QAA4B;IACzD,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,MAAM,CAAC,8CAA8C,CAAC,CAAC;IACzF,OAAO;QACL,KAAK,EAAE,CAAM,GAAW,EAAE,UAAwB,EAAE,EAAE,EAAE,CACtD,eAAe,CAAM,QAAQ,EAAE,GAAG,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9F,CAAC;AACJ,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,aAAa,CAAC,CAAU;IACtC,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,eAAe,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,aAAa,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC;IAC7H,OAAO,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AACpD,CAAC"}

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,100 @@
+/**
+ * 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;
+    constructor(holder: string, expiresAt: string, where: string, clear: string);
+}
+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>;