@intentius/sql-yodeler 0.0.0-stage → 0.1.0

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":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAMzC,qDAAqD;AACrD,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,CAAC;AAgChC,2DAA2D;AAC3D,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,GAAW,EAAU,EAAE,CAAC,UAAU,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AAkDxH,gEAAgE;AAChE,MAAM,UAAU,WAAW,CAAC,IAA2B;IACrD,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;IACvD,MAAM,IAAI,GAAG,IAAI,GAAG,EAA2B,CAAC;IAChD,MAAM,KAAK,GAAsB,EAAE,CAAC;IACpC,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;QACjC,IAAI,CAAC,CAAC,EAAE,CAAC;YACP,CAAC,GAAG;gBACF,EAAE,EAAE,CAAC,CAAC,YAAY;gBAClB,MAAM,EAAE,CAAC,CAAC,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM;gBACzC,QAAQ,EAAE,CAAC,CAAC,QAAQ;gBACpB,MAAM,EAAE,SAAS;gBACjB,KAAK,EAAE,EAAE;gBACT,SAAS,EAAE,CAAC,CAAC,UAAU;gBACvB,UAAU,EAAE,CAAC,CAAC,WAAW;gBACzB,UAAU,EAAE,CAAC,CAAC,WAAW,IAAI,EAAE;gBAC/B,GAAG,EAAE,CAAC,CAAC,GAAG;gBACV,UAAU,EAAE,SAAS;gBACrB,OAAO,EAAE,EAAE;gBACX,UAAU,EAAE,IAAI,GAAG,EAAE;aACtB,CAAC;YACF,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC;YAC5B,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAChB,CAAC;QACD,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW,IAAI,CAAC,CAAC,MAAM,KAAK,WAAW,IAAI,CAAC,CAAC,MAAM,KAAK,WAAW,IAAI,CAAC,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YACjH,2GAA2G;YAC3G,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;YAC7C,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC;YACxB,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,WAAW,CAAC;YAC7B,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC;YACd,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,UAAU,EAAE,EAAE,EAAE,CAAC,CAAC,WAAW,IAAI,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;QAClH,CAAC;aAAM,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YAClC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;YAC7C,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC;YACxB,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;YACpB,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;YAClB,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,UAAU,CAAC;YAC3B,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,WAAW,CAAC;YAC7B,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,WAAW,IAAI,EAAE,CAAC;YACnC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC;YACd,IAAI,CAAC,CAAC,MAAM,KAAK,WAAW,IAAI,CAAC,CAAC,UAAU,KAAK,SAAS;gBAAE,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,GAAG,CAAC;QACnF,CAAC;aAAM,CAAC;YACN,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,eAAe,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,eAAe,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,aAAa,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;QACxI,CAAC;IACH,CAAC;IACD,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC7C,CAAC;AAED,yDAAyD;AACzD,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAA8B,EAAW,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,WAAW,CAAC;AAEhG,6HAA6H;AAC7H,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAA8B,EAAE,KAAa,EAAW,EAAE,CAAC,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,WAAW,CAAC"}

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 {};

package/dist/history/store.js

@@ -0,0 +1,134 @@
+/**
+ * Reading and appending the history table. Nothing here updates or deletes
+ * a row.
+ */
+import { hostname, userInfo } from "node:os";
+import { randomUUID } from "node:crypto";
+import { HISTORY_COLUMNS, HISTORY_TABLE, historyDdl, ident, literal } from "./ddl.js";
+import { replicates } from "./topology.js";
+import { deriveState } from "./rows.js";
+/** Settings every history write carries: synchronous, and never deduplicated away on a Replicated engine. */
+const WRITE_SETTINGS = { async_insert: "0", insert_deduplicate: "0" };
+/** Who is applying: the CI actor or the user, at this host. */
+export function appliedBy(env = process.env) {
+    let user = env.GITHUB_ACTOR ?? env.GITLAB_USER_LOGIN ?? env.USER;
+    if (!user) {
+        try {
+            user = userInfo().username;
+        }
+        catch {
+            user = "unknown";
+        }
+    }
+    return `${user}@${hostname()}`;
+}
+const columnNames = HISTORY_COLUMNS.map(([name]) => name);
+/** A row as a server returns it (strings or numbers), as a {@link HistoryRow}. */
+export function fromRaw(r) {
+    const s = (k) => {
+        const v = r[k];
+        return typeof v === "string" ? v : typeof v === "number" || typeof v === "boolean" ? String(v) : "";
+    };
+    return {
+        seq: Number(r.seq),
+        run_id: s("run_id"),
+        kind: s("kind") === "statement" || s("kind") === "step" ? s("kind") : "migration",
+        migration_id: s("migration_id"),
+        parent: s("parent"),
+        checksum: s("checksum"),
+        statement_index: Number(r.statement_index),
+        statement_sha: s("statement_sha"),
+        status: (["started", "succeeded", "failed"].includes(s("status")) ? s("status") : "started"),
+        error: s("error"),
+        applied_by: s("applied_by"),
+        plan_digest: s("plan_digest"),
+        silences: s("silences") || "[]",
+        note: s("note"),
+        recorded_at: s("recorded_at"),
+    };
+}
+export class HistoryStore {
+    port;
+    location;
+    constructor(port, location) {
+        this.port = port;
+        this.location = location;
+    }
+    get table() {
+        return `${ident(this.location.database)}.${HISTORY_TABLE}`;
+    }
+    /** Whether the history table is there. A history that was never made has no rows. */
+    async exists() {
+        const rows = await this.port.query(`SELECT count() AS n FROM system.tables WHERE database = ${literal(this.location.database)} AND name = ${literal(HISTORY_TABLE)}`);
+        return Number(rows[0]?.n ?? 0) > 0;
+    }
+    /** Creates the database and table when they are not there. */
+    async ensure() {
+        for (const sql of historyDdl(this.location))
+            await this.port.query(sql);
+    }
+    /**
+     * 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.
+     */
+    async rows(options = {}) {
+        if (!(await this.exists()))
+            return [];
+        const { topology } = this.location;
+        if (options.sync !== false && replicates(topology))
+            await this.port.query(`SYSTEM SYNC REPLICA ${this.table}`);
+        const settings = topology.kind === "cloud" && options.sync !== false ? { settings: { select_sequential_consistency: "1" } } : {};
+        const select = columnNames.map((c) => (c === "recorded_at" ? "toString(recorded_at) AS recorded_at" : c)).join(", ");
+        const raw = await this.port.query(`SELECT ${select} FROM ${this.table} ORDER BY seq`, settings);
+        return raw.map(fromRaw);
+    }
+    async state(options = {}) {
+        return deriveState(await this.rows(options));
+    }
+    /** Appends rows, as written; `recorded_at` is the server's. */
+    async append(rows) {
+        if (rows.length === 0)
+            return;
+        const body = rows
+            .map((r) => JSON.stringify({ ...r, recorded_at: undefined }))
+            .join("\n");
+        await this.port.query(`INSERT INTO ${this.table} FORMAT JSONEachRow\n${body}`, { settings: WRITE_SETTINGS });
+    }
+}
+export const newRunContext = (planDigest, env = process.env) => ({
+    runId: randomUUID(),
+    appliedBy: appliedBy(env),
+    planDigest,
+});
+/**
+ * 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 class HistoryRecorder {
+    store;
+    run;
+    next;
+    constructor(store, run, maxSeq) {
+        this.store = store;
+        this.run = run;
+        this.next = maxSeq + 1;
+    }
+    async record(row) {
+        const full = {
+            error: "",
+            note: "",
+            silences: "[]",
+            ...row,
+            seq: this.next++,
+            run_id: this.run.runId,
+            applied_by: this.run.appliedBy,
+            plan_digest: this.run.planDigest,
+        };
+        await this.store.append([full]);
+        return full;
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/history/store.js.map

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

package/dist/history/topology.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Where the history table lives, as far as its DDL cares: a single node, a
+ * cluster (`ON CLUSTER`), a `Replicated` database, or ClickHouse Cloud.
+ *
+ * The same four kinds as chant's ClickHouse topology, with the same string
+ * form (`single`, `cluster:<name>`, `replicated`, `replicated:<cluster>`,
+ * `cloud`). Each environment names one in `yodel.config.ts` (#9, see
+ * `../config/settings.ts` for the fallbacks); the default is a single node.
+ */
+export type HistoryTopology = {
+    kind: "single";
+} | {
+    kind: "cluster";
+    /** The cluster's name in `remote_servers`, or a macro such as `{cluster}`. */
+    cluster: string;
+    /** The history table's Keeper path. Default {@link defaultReplicaPath}. */
+    replicaPath?: string;
+    /** Its replica name. Default {@link DEFAULT_HISTORY_REPLICA_NAME}. */
+    replicaName?: string;
+} | {
+    kind: "replicated";
+    /** A cluster to create the history's `Replicated` database on, when yodel creates it. */
+    cluster?: string;
+} | {
+    kind: "cloud";
+};
+export declare const SINGLE: HistoryTopology;
+/**
+ * A cluster's history table is one copy for the whole cluster, not one per
+ * shard: every runner, on any host, must read the same rows. So the Keeper
+ * path names no `{shard}`, and the replica name carries the shard as well as
+ * the replica, so replicas of different shards do not collide.
+ */
+export declare const defaultReplicaPath: (database: string, table: string) => string;
+export declare const DEFAULT_HISTORY_REPLICA_NAME = "{shard}-{replica}";
+/** A topology from its string form. */
+export declare function parseHistoryTopology(value: string): HistoryTopology;
+/** The string form of a topology, for messages. */
+export declare function describeTopology(t: HistoryTopology): string;
+/** Whether the history's tables replicate through Keeper, so a read on one host must first catch up with the others. */
+export declare const replicates: (t: HistoryTopology) => boolean;

package/dist/history/topology.js

@@ -0,0 +1,54 @@
+/**
+ * Where the history table lives, as far as its DDL cares: a single node, a
+ * cluster (`ON CLUSTER`), a `Replicated` database, or ClickHouse Cloud.
+ *
+ * The same four kinds as chant's ClickHouse topology, with the same string
+ * form (`single`, `cluster:<name>`, `replicated`, `replicated:<cluster>`,
+ * `cloud`). Each environment names one in `yodel.config.ts` (#9, see
+ * `../config/settings.ts` for the fallbacks); the default is a single node.
+ */
+import { YodelError } from "../project.js";
+export const SINGLE = { kind: "single" };
+/**
+ * A cluster's history table is one copy for the whole cluster, not one per
+ * shard: every runner, on any host, must read the same rows. So the Keeper
+ * path names no `{shard}`, and the replica name carries the shard as well as
+ * the replica, so replicas of different shards do not collide.
+ */
+export const defaultReplicaPath = (database, table) => `/clickhouse/yodeler/${database}/${table}`;
+export const DEFAULT_HISTORY_REPLICA_NAME = "{shard}-{replica}";
+/** A topology from its string form. */
+export function parseHistoryTopology(value) {
+    const at = value.indexOf(":");
+    const kind = (at < 0 ? value : value.slice(0, at)).trim();
+    const arg = at < 0 ? undefined : value.slice(at + 1).trim();
+    switch (kind) {
+        case "single":
+        case "cloud":
+            if (arg !== undefined)
+                throw new YodelError(`topology ${kind} takes no argument: ${JSON.stringify(value)}`);
+            return { kind };
+        case "cluster":
+            if (!arg)
+                throw new YodelError(`topology cluster needs the cluster's name: cluster:<name>, got ${JSON.stringify(value)}`);
+            return { kind, cluster: arg };
+        case "replicated":
+            return arg ? { kind, cluster: arg } : { kind };
+        default:
+            throw new YodelError(`unknown topology ${JSON.stringify(value)}: expected single, cluster:<name>, replicated or cloud`);
+    }
+}
+/** The string form of a topology, for messages. */
+export function describeTopology(t) {
+    switch (t.kind) {
+        case "cluster":
+            return `cluster:${t.cluster}`;
+        case "replicated":
+            return t.cluster ? `replicated:${t.cluster}` : "replicated";
+        default:
+            return t.kind;
+    }
+}
+/** Whether the history's tables replicate through Keeper, so a read on one host must first catch up with the others. */
+export const replicates = (t) => t.kind === "cluster" || t.kind === "replicated";
+//# sourceMappingURL=topology.js.map

package/dist/history/topology.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topology.js","sourceRoot":"","sources":["../../src/history/topology.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAoB3C,MAAM,CAAC,MAAM,MAAM,GAAoB,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,QAAgB,EAAE,KAAa,EAAU,EAAE,CAAC,uBAAuB,QAAQ,IAAI,KAAK,EAAE,CAAC;AAC1H,MAAM,CAAC,MAAM,4BAA4B,GAAG,mBAAmB,CAAC;AAEhE,uCAAuC;AACvC,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,MAAM,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC9B,MAAM,IAAI,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1D,MAAM,GAAG,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5D,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,QAAQ,CAAC;QACd,KAAK,OAAO;YACV,IAAI,GAAG,KAAK,SAAS;gBAAE,MAAM,IAAI,UAAU,CAAC,YAAY,IAAI,uBAAuB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAC5G,OAAO,EAAE,IAAI,EAAE,CAAC;QAClB,KAAK,SAAS;YACZ,IAAI,CAAC,GAAG;gBAAE,MAAM,IAAI,UAAU,CAAC,kEAAkE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAC1H,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;QAChC,KAAK,YAAY;YACf,OAAO,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;QACjD;YACE,MAAM,IAAI,UAAU,CAAC,oBAAoB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,wDAAwD,CAAC,CAAC;IAC5H,CAAC;AACH,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,gBAAgB,CAAC,CAAkB;IACjD,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;QACf,KAAK,SAAS;YACZ,OAAO,WAAW,CAAC,CAAC,OAAO,EAAE,CAAC;QAChC,KAAK,YAAY;YACf,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC;QAC9D;YACE,OAAO,CAAC,CAAC,IAAI,CAAC;IAClB,CAAC;AACH,CAAC;AAED,wHAAwH;AACxH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAkB,EAAW,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,IAAI,KAAK,YAAY,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The package root, for a project's `yodel.config.ts`:
+ *
+ * ```ts
+ * import { defineConfig } from "@intentius/sql-yodeler";
+ * export default defineConfig({ environments: { prod: { topology: "cluster:main" } } });
+ * ```
+ */
+export { defineConfig } from "./config/define.js";
+export type { EnvironmentConfig, Topology, TopologySetting, YodelConfig } from "./config/define.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * The package root, for a project's `yodel.config.ts`:
+ *
+ * ```ts
+ * import { defineConfig } from "@intentius/sql-yodeler";
+ * export default defineConfig({ environments: { prod: { topology: "cluster:main" } } });
+ * ```
+ */
+export { defineConfig } from "./config/define.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/init/adopt.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `yodel init --from <env>`: adopt a live database in one go.
+ *
+ *  1. Refuse, before anything is written, when the project already declares
+ *     a schema (unless `force`), already has migrations, or the
+ *     environment's history already records any; and when the environment
+ *     names no `databases` (ClickHouse) or `schemas` (Postgres), or names
+ *     the history's own.
+ *  2. Read the live database with chant's import (`chant import --from`'s
+ *     library functions) and write the declarations into the source
+ *     directory.
+ *  3. Build them and plan the build against the same database. The plan
+ *     must be empty: the declarations are the database. If it is not, the
+ *     import does not round-trip, and everything written is taken back.
+ *  4. Write the baseline migration: the first migration (parent `null`),
+ *     whose statements create everything, from an empty schema to the build.
+ *  5. Record it applied in the history without running it (`./baseline.ts`),
+ *     on ClickHouse in `<history database>.history`, on Postgres in
+ *     `<history schema>.history` (#13), under the apply lock.
+ *
+ * Any failure in 2 to 5 takes back every file written. The live database
+ * is only read; the one write to the server is the history row, and the
+ * history database (schema) and table when they were not there.
+ */
+import { type Environment, type Project } from "../project.js";
+import type { HistoryRow } from "../history/index.js";
+export interface AdoptOptions {
+    /** Overwrite declaration files the source directory already has. */
+    force?: boolean;
+    /** The baseline migration's name. Default {@link BASELINE_NAME}. */
+    name?: string;
+    now?: Date;
+    processEnv?: NodeJS.ProcessEnv;
+    log?: (line: string) => void;
+}
+export interface Adopted {
+    environment: string;
+    dialect: Project["dialect"];
+    /** The objects read, as `<kind> <name>`. */
+    objects: string[];
+    /** The declaration files written, relative to the project. */
+    schemaFiles: string[];
+    /** The baseline migration's directory, relative to the project. */
+    migrationPath: string;
+    baseline: {
+        id: string;
+        checksum: string;
+        statements: number;
+    };
+    /** The baseline's history row, recorded applied; init records it on both dialects. */
+    recorded: {
+        database: string;
+        row: HistoryRow;
+        lock: {
+            kind: string;
+            where: string;
+            notice?: string;
+        };
+    };
+    warnings: string[];
+}
+/** Where the declarations go: `sourceDir` when the config names one, else `src`. */
+export declare const schemaDir: (project: Project) => string;
+/** The refusals that need no server: a schema already declared, migrations already there, a ClickHouse scope that would take in the history. */
+export declare function preflight(project: Project, env: Environment, options?: {
+    force?: boolean;
+    processEnv?: NodeJS.ProcessEnv;
+}): void;
+/** Adopts `env`'s live database into the project; see the module comment. */
+export declare function adopt(project: Project, env: Environment, options?: AdoptOptions): Promise<Adopted>;