@intentius/sql-yodeler 0.0.0-stage → 0.2.0

package/dist/steps/rebuild.js

@@ -0,0 +1,155 @@
+/**
+ * A `ClickHouseRebuildOp` step: the change ClickHouse cannot make with
+ * `ALTER` (a sort key, an engine, a key column's type or name), run inside
+ * the migration as chant's rebuild Op.
+ *
+ * The Op is chant's own (`ClickHouseRebuildOp` from the sql lexicon), built
+ * from the step's options with the apply's environment, and run by chant's
+ * local executor with the lexicon's rebuild activities:
+ *
+ *   Plan, Create, Dual write (materialized-view mode), Backfill, Verify, Swap, Retain
+ *
+ * Three things differ from running the Op with `chant run`:
+ *
+ * - The declaration is the migration's recorded schema (`migration.json`'s
+ *   `schema`), written to a temporary build file, not a fresh `chant build`:
+ *   the table is rebuilt as this migration declares it, however far the
+ *   declared schema has moved on since.
+ * - It is built with `gates: "outer"`: the swap gate's approval is the
+ *   migration's (the step's options are in the migration's checksum, which
+ *   is in the plan digest the migrations Op's gate approved), so the Op has
+ *   no gate and no Drop phase. The verification still runs before the swap,
+ *   and a difference fails the step with nothing swapped. The old table is
+ *   kept, `<table>__chant_old`, until its retention date (7 days).
+ * - It is built with `onFailure: "keep"`, so a step that failed or was
+ *   killed part way keeps `<table>__chant_new` and `<table>__chant_dual` and
+ *   resumes from the backfill's receipts on the next `yodel apply`: every
+ *   partition with a receipt is skipped. To start the rebuild over instead,
+ *   drop those two tables (a refusal names them).
+ *
+ * The activities render their DDL for the topology chant resolves from
+ * `sql.profiles.<env>.topology`. When the environment's topology comes from
+ * elsewhere (`yodel.config.ts`, or `YODEL_TOPOLOGY`, #9), the step hands
+ * every rebuild activity chant's config with that topology set on the
+ * profile ({@link rebuildChantConfig}), so the rebuild renders for the same
+ * topology as the migration's statements. On a cluster of more than one
+ * shard the Op copies and verifies every shard; it needs the `{shard}` macro
+ * on each server, distinct per shard, and refuses the cluster without it.
+ */
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { environmentSettings } from "../config/settings.js";
+import { loadProject } from "../project.js";
+import { runOp, StepOpFailed } from "./run.js";
+/** The rebuild activities whose results the history's summary keeps. */
+const SUMMARIZED = ["clickhouseRebuildPlan", "clickhouseRebuildBackfill", "clickhouseRebuildVerify", "clickhouseRebuildSwap", "clickhouseRebuildRetain"];
+/** `config` with `sql.profiles.<environment>.topology` set to `topology`. Pure; `config` is not changed. */
+export function withProfileTopology(config, environment, topology) {
+    const profiles = config.sql?.profiles ?? {};
+    const profile = profiles[environment];
+    if (!profile)
+        return config;
+    return { ...config, sql: { ...config.sql, profiles: { ...profiles, [environment]: { ...profile, topology } } } };
+}
+/**
+ * The chant config a rebuild step's activities bind with: the project's,
+ * with the environment's resolved topology on its profile when chant would
+ * not find it there itself. `undefined` when chant's own resolution already
+ * gives the same topology (set in the profile, or no topology anywhere).
+ */
+export async function rebuildChantConfig(projectDir, environment, env = process.env) {
+    const project = await loadProject(projectDir);
+    const settings = environmentSettings(project, environment, env);
+    if (settings.topologySource === "default" || settings.topologySource === `sql.profiles.${environment}.topology`)
+        return undefined;
+    return withProfileTopology(project.config, environment, settings.topology);
+}
+/** The Op a rebuild step runs. `buildPath` is the recorded schema's file; `projectDir` holds chant.config.ts. */
+export async function rebuildOpConfig(options, ctx) {
+    const { ClickHouseRebuildOp } = await import("@intentius/chant-lexicon-sql/clickhouse/rebuild/op");
+    const { op } = ClickHouseRebuildOp({
+        name: options.name,
+        env: ctx.environment,
+        table: options.table,
+        dualWrite: options.dualWrite,
+        build: false,
+        output: ctx.buildPath,
+        path: ctx.projectDir,
+        gates: "outer",
+        onFailure: "keep",
+    });
+    return op.props;
+}
+const num = (v) => (typeof v === "number" ? v : undefined);
+const str = (v) => (typeof v === "string" ? v : undefined);
+/** Folds one rebuild activity's result into the summary. */
+export function summarize(summary, fn, result) {
+    const r = (typeof result === "object" && result !== null ? result : {});
+    const put = (k, v) => {
+        if (v !== undefined)
+            summary[k] = v;
+    };
+    if (fn === "clickhouseRebuildPlan")
+        put("state", str(r.state));
+    if (fn === "clickhouseRebuildBackfill") {
+        put("partitions", num(r.partitions));
+        put("copied", num(r.copied));
+        put("skipped", num(r.skipped));
+        put("cleared", num(r.cleared));
+        put("repaired", num(r.repaired));
+    }
+    if (fn === "clickhouseRebuildVerify")
+        put("verifiedRows", num(r.rows));
+    if (fn === "clickhouseRebuildSwap") {
+        put("swapped", typeof r.swapped === "boolean" ? r.swapped : undefined);
+        put("oldTable", str(r.oldTable));
+        put("retainUntil", str(r.retainUntil));
+    }
+    if (fn === "clickhouseRebuildRetain") {
+        put("oldTable", str(r.oldTable));
+        put("retainUntil", str(r.retainUntil));
+    }
+}
+/** Runs a rebuild step to the end. The summary is filled in as the activities return, so a failure still says how far it got. */
+export async function runRebuild(options, run, summary = { op: "ClickHouseRebuildOp", table: options.table }) {
+    const dir = mkdtempSync(join(tmpdir(), "yodel-rebuild-"));
+    try {
+        const buildPath = join(dir, "schema.json");
+        writeFileSync(buildPath, JSON.stringify(run.schema));
+        const config = await rebuildOpConfig(options, { environment: run.environment, projectDir: run.projectDir, buildPath });
+        const lexicon = run.activities ?? (await import("@intentius/chant-lexicon-sql/op/activities"));
+        const wrapped = {};
+        // A rebuild activity takes its config as a third argument (chant's ClickHouseRebuildDeps).
+        const deps = run.config ? { config: run.config } : undefined;
+        const summarized = SUMMARIZED;
+        for (const fn of Object.keys(lexicon).filter((f) => f.startsWith("clickhouseRebuild") && (deps !== undefined || summarized.includes(f)))) {
+            const inner = lexicon[fn];
+            if (!inner)
+                continue;
+            wrapped[fn] = async (args, signal) => {
+                const result = await (deps ? inner(args, signal, deps) : inner(args, signal));
+                if (summarized.includes(fn))
+                    summarize(summary, fn, result);
+                return result;
+            };
+        }
+        const records = await runOp(config, {
+            cwd: run.projectDir,
+            environment: run.environment,
+            activities: { ...(run.activities ?? {}), ...wrapped },
+            ...(run.base ? { base: run.base } : {}),
+            ...(run.signal ? { signal: run.signal } : {}),
+            ...(run.onRecord ? { onRecord: run.onRecord } : {}),
+        }).catch((e) => {
+            if (e instanceof StepOpFailed)
+                e.summary = summary;
+            throw e;
+        });
+        return { summary, records };
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=rebuild.js.map

package/dist/steps/rebuild.js.map

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

package/dist/steps/run.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Running an Op step's Op in this process, with chant's local executor
+ * (`runOpLocally`, the executor `chant run` uses), inside the versioned
+ * apply that holds the lock.
+ *
+ * The activities are the ones `chant run` loads for a sql project (core's,
+ * and the sql lexicon's, the rebuild's among them), plus what the step adds
+ * (a backfill's receipt store and its `yodelSql`). Nothing is written to the
+ * run ledger: the history table is the record of what ran.
+ *
+ * A step's Op has no gate of its own here. The migration it is part of was
+ * approved under the plan digest, which covers the step through the
+ * migration's checksum; a gate left in the Op is refused before it runs.
+ */
+import type { OpConfig } from "@intentius/chant/op/types";
+import type { ActivityFn } from "@intentius/chant/op/activity-registry";
+import type { StepRecord } from "@intentius/chant/op/local-executor";
+import { YodelError } from "../project.js";
+/** A step's Op stopped part way. The history records it failed; the next run resumes it. */
+export declare class StepOpFailed extends YodelError {
+    readonly op: string;
+    readonly detail: string;
+    readonly records: StepRecord[];
+    /** How far it got, for the history's note: set by the step that ran it. */
+    summary: unknown;
+    constructor(op: string, detail: string, records: StepRecord[]);
+}
+/** The gates in an Op, by name. */
+export declare const gatesOf: (config: Pick<OpConfig, "phases" | "onFailure">) => string[];
+/** The first failing record's error, for the message. */
+export declare function failureOf(records: readonly StepRecord[]): string;
+export interface RunOpOptions {
+    /** The project directory: chant's config is read from it. */
+    cwd: string;
+    /** The environment, handed to the activities through the run context. */
+    environment: string;
+    /** Activities added to (or replacing) the ones chant loads. */
+    activities?: Record<string, ActivityFn>;
+    /** The activities to use instead of loading chant's, for a test. */
+    base?: Map<string, ActivityFn>;
+    signal?: AbortSignal;
+    onRecord?: (record: StepRecord) => void;
+}
+/** Runs `config` to the end. Resolves with its records; throws {@link StepOpFailed} when it fails, or stops at a gate or a decision point. */
+export declare function runOp(config: OpConfig, options: RunOpOptions): Promise<StepRecord[]>;

package/dist/steps/run.js

@@ -0,0 +1,72 @@
+/**
+ * Running an Op step's Op in this process, with chant's local executor
+ * (`runOpLocally`, the executor `chant run` uses), inside the versioned
+ * apply that holds the lock.
+ *
+ * The activities are the ones `chant run` loads for a sql project (core's,
+ * and the sql lexicon's, the rebuild's among them), plus what the step adds
+ * (a backfill's receipt store and its `yodelSql`). Nothing is written to the
+ * run ledger: the history table is the record of what ran.
+ *
+ * A step's Op has no gate of its own here. The migration it is part of was
+ * approved under the plan digest, which covers the step through the
+ * migration's checksum; a gate left in the Op is refused before it runs.
+ */
+import { YodelError } from "../project.js";
+/** A step's Op stopped part way. The history records it failed; the next run resumes it. */
+export class StepOpFailed extends YodelError {
+    op;
+    detail;
+    records;
+    /** How far it got, for the history's note: set by the step that ran it. */
+    summary;
+    constructor(op, detail, records) {
+        super(`${op}: ${detail}`, 1);
+        this.op = op;
+        this.detail = detail;
+        this.records = records;
+        this.name = "StepOpFailed";
+    }
+}
+const allSteps = (config) => [...config.phases, ...(config.onFailure ?? [])].flatMap((p) => p.steps.flatMap((s) => (s.kind === "effect" ? [s, ...s.steps] : [s])));
+/** The gates in an Op, by name. */
+export const gatesOf = (config) => allSteps(config).flatMap((s) => (s.kind === "gate" ? [s.gate ?? "unnamed"] : []));
+/** The first failing record's error, for the message. */
+export function failureOf(records) {
+    const failed = records.find((r) => r.status === "fail");
+    return failed ? `${failed.phase} / ${failed.fn} failed: ${failed.error ?? "no error given"}` : "the Op failed";
+}
+/** Runs `config` to the end. Resolves with its records; throws {@link StepOpFailed} when it fails, or stops at a gate or a decision point. */
+export async function runOp(config, options) {
+    const gates = gatesOf(config);
+    if (gates.length > 0) {
+        throw new StepOpFailed(config.name, `it has a gate (${gates.join(", ")}); a step's Op runs behind the migration's own gate and may not have one of its own`, []);
+    }
+    const { loadActivities, loadProfiles } = await import("@intentius/chant/op/activity-registry");
+    const { runOpLocally, OpRunFailure } = await import("@intentius/chant/op/local-executor");
+    const activities = options.base ? new Map(options.base) : await loadActivities(["sql"]);
+    for (const [name, fn] of Object.entries(options.activities ?? {}))
+        activities.set(name, fn);
+    const profiles = await loadProfiles();
+    try {
+        const result = await runOpLocally(config, activities, profiles, options.signal, {
+            cwd: options.cwd,
+            env: options.environment,
+            ...(options.onRecord ? { onRecord: options.onRecord } : {}),
+        });
+        if (result.status !== "ok")
+            throw new StepOpFailed(config.name, `it stopped (${result.status}) instead of running to the end`, result.records);
+        return result.records;
+    }
+    catch (e) {
+        if (e instanceof StepOpFailed)
+            throw e;
+        if (e instanceof OpRunFailure) {
+            const cause = e.cause instanceof Error ? e.cause.message : typeof e.cause === "string" ? e.cause : undefined;
+            const failedStep = e.result.records.some((r) => r.status === "fail");
+            throw new StepOpFailed(config.name, failedStep ? failureOf(e.result.records) : (cause ?? "the Op failed"), e.result.records);
+        }
+        throw new StepOpFailed(config.name, e instanceof Error ? e.message : String(e), []);
+    }
+}
+//# sourceMappingURL=run.js.map

package/dist/steps/run.js.map

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

package/dist/topology/render.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A migration's statements as one environment runs them. The source is
+ * topology-neutral: `yodel new` writes each statement for a single node,
+ * and at apply time each is rendered for the environment's topology with
+ * chant's renderer (`ON CLUSTER` added or removed, the replicated engine
+ * written). Pure.
+ *
+ * The history records a statement by the neutral statement's sha, so a
+ * migration resumes the same way on every topology; the topology it was
+ * sent for goes in the row's note ({@link topologyNote}).
+ */
+import { type Topology } from "@intentius/chant-lexicon-sql/clickhouse/topology";
+export type { Topology };
+/** One neutral statement, as `topology` runs it. */
+export declare const renderForEnvironment: (sql: string, topology: Topology) => string;
+/** The `note` a statement row carries: the topology the statement was rendered for. */
+export declare const topologyNote: (topology: Topology) => string;

package/dist/topology/render.js

@@ -0,0 +1,17 @@
+/**
+ * A migration's statements as one environment runs them. The source is
+ * topology-neutral: `yodel new` writes each statement for a single node,
+ * and at apply time each is rendered for the environment's topology with
+ * chant's renderer (`ON CLUSTER` added or removed, the replicated engine
+ * written). Pure.
+ *
+ * The history records a statement by the neutral statement's sha, so a
+ * migration resumes the same way on every topology; the topology it was
+ * sent for goes in the row's note ({@link topologyNote}).
+ */
+import { renderStatement, topologyLabel } from "@intentius/chant-lexicon-sql/clickhouse/topology";
+/** One neutral statement, as `topology` runs it. */
+export const renderForEnvironment = (sql, topology) => renderStatement(sql, topology);
+/** The `note` a statement row carries: the topology the statement was rendered for. */
+export const topologyNote = (topology) => `topology=${topologyLabel(topology)}`;
+//# sourceMappingURL=render.js.map

package/dist/topology/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../src/topology/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,eAAe,EAAE,aAAa,EAAiB,MAAM,kDAAkD,CAAC;AAIjH,oDAAoD;AACpD,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,GAAW,EAAE,QAAkB,EAAU,EAAE,CAAC,eAAe,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;AAEhH,uFAAuF;AACvF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,QAAkB,EAAU,EAAE,CAAC,YAAY,aAAa,CAAC,QAAQ,CAAC,EAAE,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** The package version, read from package.json (one level above both src/ and dist/). */
+export declare function version(): string;

package/dist/version.js

@@ -0,0 +1,11 @@
+import { readFileSync } from "node:fs";
+/** The package version, read from package.json (one level above both src/ and dist/). */
+export function version() {
+    const url = new URL("../package.json", import.meta.url);
+    const pkg = JSON.parse(readFileSync(url, "utf8"));
+    if (typeof pkg.version !== "string") {
+        throw new Error(`no version in ${url.pathname}`);
+    }
+    return pkg.version;
+}
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,yFAAyF;AACzF,MAAM,UAAU,OAAO;IACrB,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACxD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAA0B,CAAC;IAC3E,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,iBAAiB,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,GAAG,CAAC,OAAO,CAAC;AACrB,CAAC"}

package/dist/versioned/approval.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The approval check `yodel apply <env> --execute` makes itself, against
+ * chant's gate ledger, before it sends anything.
+ *
+ * `YODEL_APPROVED_PLAN` is how the Op hands the digest to the Apply step, but
+ * it is never enough on its own: anyone can set an environment variable.
+ * `--execute` reads the ledger the gate step reads (the `chant/lifecycle`
+ * branch, through chant's `gitGateLedgerPort`) for the environment's
+ * migrations Op, and requires an approval of its gate for exactly the digest
+ * it computes under the lock, by the rule chant's gate applies
+ * (`evaluateGate`):
+ *
+ * - the resolution is for this gate and for this plan digest
+ *   (`latestResolutionForPlan`; one recorded before plan-bound gates never
+ *   counts);
+ * - it is newer than the newest pending fact for the gate, so an approval
+ *   from before the gate last asked does not answer it;
+ * - the workspace's approval rule for the gate (`identity.gates`), when one
+ *   applies, accepts it.
+ *
+ * A gate with a quorum or policy (`approval`) is refused here: counting a
+ * quorum is the gate step's, and `--execute` fails closed rather than
+ * approximate it.
+ */
+import type { GateLedgerPort } from "@intentius/chant/op/gate";
+import type { MigrateOpRef } from "./op.js";
+/** Exit code of a refusal for want of an approval: the same as a run stopped at the gate. */
+export declare const NOT_APPROVED = 3;
+/** Throws unless the ledger holds an approval of `op`'s gate for `digest`. Returns who approved it. */
+export declare function verifyApproval(port: GateLedgerPort, op: MigrateOpRef, digest: string): Promise<{
+    resolvedBy: string;
+    timestamp: string;
+}>;
+/** The ledger as the gate step reads it, in the project's checkout. */
+export declare function gitLedger(cwd: string): Promise<GateLedgerPort>;

package/dist/versioned/approval.js

@@ -0,0 +1,53 @@
+/**
+ * The approval check `yodel apply <env> --execute` makes itself, against
+ * chant's gate ledger, before it sends anything.
+ *
+ * `YODEL_APPROVED_PLAN` is how the Op hands the digest to the Apply step, but
+ * it is never enough on its own: anyone can set an environment variable.
+ * `--execute` reads the ledger the gate step reads (the `chant/lifecycle`
+ * branch, through chant's `gitGateLedgerPort`) for the environment's
+ * migrations Op, and requires an approval of its gate for exactly the digest
+ * it computes under the lock, by the rule chant's gate applies
+ * (`evaluateGate`):
+ *
+ * - the resolution is for this gate and for this plan digest
+ *   (`latestResolutionForPlan`; one recorded before plan-bound gates never
+ *   counts);
+ * - it is newer than the newest pending fact for the gate, so an approval
+ *   from before the gate last asked does not answer it;
+ * - the workspace's approval rule for the gate (`identity.gates`), when one
+ *   applies, accepts it.
+ *
+ * A gate with a quorum or policy (`approval`) is refused here: counting a
+ * quorum is the gate step's, and `--execute` fails closed rather than
+ * approximate it.
+ */
+import { YodelError } from "../project.js";
+const EPOCH = new Date(0).toISOString();
+/** Exit code of a refusal for want of an approval: the same as a run stopped at the gate. */
+export const NOT_APPROVED = 3;
+/** Throws unless the ledger holds an approval of `op`'s gate for `digest`. Returns who approved it. */
+export async function verifyApproval(port, op, digest) {
+    if (op.quorum) {
+        throw new YodelError(`--execute cannot check gate "${op.gate}" of ${op.name}: it declares an approval quorum or policy, which only the gate step counts; run yodel apply without --execute`, NOT_APPROVED);
+    }
+    const { latestPendingGate, latestResolutionForPlan } = await import("@intentius/chant/lifecycle/gate-ledger");
+    const ledger = await port.read(op.name);
+    const rule = (await port.approvalRule?.(op.gate)) ?? null;
+    const resolutions = ledger.resolutions.filter((r) => r.gate !== op.gate || rule === null || rule.refuses(r) === null);
+    const since = latestPendingGate(ledger.pending, op.gate)?.timestamp ?? EPOCH;
+    const found = latestResolutionForPlan(resolutions, op.gate, since, digest);
+    if (found.resolution)
+        return { resolvedBy: found.resolution.resolvedBy, timestamp: found.resolution.timestamp };
+    const other = found.mismatched
+        ? ` (the newest approval of that gate is for ${found.mismatched.planDigest ?? "no plan"}, by ${found.mismatched.resolvedBy} at ${found.mismatched.timestamp})`
+        : "";
+    throw new YodelError(`refused: chant's gate ledger holds no approval of ${op.name} / ${op.gate} for plan ${digest}${other}. Nothing was applied. ` +
+        `Run yodel apply without --execute; it stops at the gate and prints the chant approve command.`, NOT_APPROVED);
+}
+/** The ledger as the gate step reads it, in the project's checkout. */
+export async function gitLedger(cwd) {
+    const { gitGateLedgerPort } = await import("@intentius/chant/op/gate");
+    return gitGateLedgerPort({ cwd });
+}
+//# sourceMappingURL=approval.js.map

package/dist/versioned/approval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.js","sourceRoot":"","sources":["../../src/versioned/approval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAG3C,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;AAExC,6FAA6F;AAC7F,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC;AAE9B,uGAAuG;AACvG,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAoB,EAAE,EAAgB,EAAE,MAAc;IACzF,IAAI,EAAE,CAAC,MAAM,EAAE,CAAC;QACd,MAAM,IAAI,UAAU,CAAC,gCAAgC,EAAE,CAAC,IAAI,QAAQ,EAAE,CAAC,IAAI,gHAAgH,EAAE,YAAY,CAAC,CAAC;IAC7M,CAAC;IACD,MAAM,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,GAAG,MAAM,MAAM,CAAC,wCAAwC,CAAC,CAAC;IAC9G,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC;IAC1D,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;IACtH,MAAM,KAAK,GAAG,iBAAiB,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,SAAS,IAAI,KAAK,CAAC;IAC7E,MAAM,KAAK,GAAG,uBAAuB,CAAC,WAAW,EAAE,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IAC3E,IAAI,KAAK,CAAC,UAAU;QAAE,OAAO,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,CAAC,UAAU,EAAE,SAAS,EAAE,KAAK,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC;IAChH,MAAM,KAAK,GAAG,KAAK,CAAC,UAAU;QAC5B,CAAC,CAAC,6CAA6C,KAAK,CAAC,UAAU,CAAC,UAAU,IAAI,SAAS,QAAQ,KAAK,CAAC,UAAU,CAAC,UAAU,OAAO,KAAK,CAAC,UAAU,CAAC,SAAS,GAAG;QAC9J,CAAC,CAAC,EAAE,CAAC;IACP,MAAM,IAAI,UAAU,CAClB,qDAAqD,EAAE,CAAC,IAAI,MAAM,EAAE,CAAC,IAAI,aAAa,MAAM,GAAG,KAAK,yBAAyB;QAC3H,+FAA+F,EACjG,YAAY,CACb,CAAC;AACJ,CAAC;AAED,uEAAuE;AACvE,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,GAAW;IACzC,MAAM,EAAE,iBAAiB,EAAE,GAAG,MAAM,MAAM,CAAC,0BAA0B,CAAC,CAAC;IACvE,OAAO,iBAAiB,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;AACpC,CAAC"}

package/dist/versioned/checks.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Pre-migration checks (#52), run against an environment.
+ *
+ * A migration's `checks` (`../migrations/checks.ts`) are read-only queries.
+ * `yodel apply <env>` runs the first pending migration's before it runs the
+ * migrations Op, so a run that would be refused stops before anyone is
+ * asked to approve it; the Op's Apply step runs every migration's again
+ * under the lock, just before that migration's first statement, where the
+ * data is what the statements will meet. A check that fails, or whose query
+ * the server refuses, refuses the run with exit 4: nothing of that
+ * migration is sent. Under the lock the history records the outcome: the
+ * migration's `started` row carries the checks that passed in its `note`,
+ * and a refusal is a `failed` migration row naming the check.
+ *
+ * A migration resuming part way (a statement of it already succeeded) does
+ * not run its checks again: they held before its first statement.
+ */
+import { YodelError } from "../project.js";
+import { type CheckOutcome, type Migration } from "../migrations/index.js";
+import type { VersionedDriver } from "./driver.js";
+import type { PendingMigration } from "./state.js";
+/** Whether `p`'s checks run before it: it has some, and no statement of it has succeeded yet. */
+export declare const checksDue: (p: PendingMigration) => boolean;
+/** Runs each of `m`'s checks; a query the server refuses is a failed check. */
+export declare function runChecks(driver: VersionedDriver, m: Migration): Promise<CheckOutcome[]>;
+/** The checks that failed, one line each. */
+export declare function failedChecks(m: Migration, outcomes: readonly CheckOutcome[]): string[];
+/** The refusal when a check of `m` failed, or `undefined`. */
+export declare function checksRefusal(m: Migration, outcomes: readonly CheckOutcome[], when: string): YodelError | undefined;

package/dist/versioned/checks.js

@@ -0,0 +1,54 @@
+/**
+ * Pre-migration checks (#52), run against an environment.
+ *
+ * A migration's `checks` (`../migrations/checks.ts`) are read-only queries.
+ * `yodel apply <env>` runs the first pending migration's before it runs the
+ * migrations Op, so a run that would be refused stops before anyone is
+ * asked to approve it; the Op's Apply step runs every migration's again
+ * under the lock, just before that migration's first statement, where the
+ * data is what the statements will meet. A check that fails, or whose query
+ * the server refuses, refuses the run with exit 4: nothing of that
+ * migration is sent. Under the lock the history records the outcome: the
+ * migration's `started` row carries the checks that passed in its `note`,
+ * and a refusal is a `failed` migration row naming the check.
+ *
+ * A migration resuming part way (a statement of it already succeeded) does
+ * not run its checks again: they held before its first statement.
+ */
+import { YodelError } from "../project.js";
+import { EXIT_REFUSED } from "../exit.js";
+import { describeExpect, judgeCheck } from "../migrations/index.js";
+/** Whether `p`'s checks run before it: it has some, and no statement of it has succeeded yet. */
+export const checksDue = (p) => (p.migration.document.checks?.length ?? 0) > 0 && (p.partWay?.done.length ?? 0) === 0;
+/** Runs each of `m`'s checks; a query the server refuses is a failed check. */
+export async function runChecks(driver, m) {
+    const where = { defaultDatabase: m.document.defaultDatabase, defaultSchema: m.document.defaultSchema };
+    const out = [];
+    for (const check of m.document.checks ?? []) {
+        try {
+            out.push(judgeCheck(check, await driver.readCheck(check.sql, where)));
+        }
+        catch (e) {
+            out.push({ name: check.name, passed: false, detail: `the query failed: ${(e instanceof Error ? e.message : String(e)).split("\n")[0] ?? ""}` });
+        }
+    }
+    return out;
+}
+/** The checks that failed, one line each. */
+export function failedChecks(m, outcomes) {
+    return outcomes
+        .filter((o) => !o.passed)
+        .map((o) => {
+        const check = m.document.checks?.find((c) => c.name === o.name);
+        return `check ${o.name} failed: it must ${check ? describeExpect(check).replace(/^returns/, "return") : "pass"}, and returned ${o.detail}`;
+    });
+}
+/** The refusal when a check of `m` failed, or `undefined`. */
+export function checksRefusal(m, outcomes, when) {
+    const failed = failedChecks(m, outcomes);
+    if (failed.length === 0)
+        return undefined;
+    return new YodelError(`refused: a pre-migration check of ${m.id} failed ${when}. Nothing of ${m.id} was applied:\n${failed.map((f) => `  ${f}`).join("\n")}\n` +
+        `Fix the data, then run yodel apply again; if the check is wrong, edit it in migration.json and run yodel lint --update-checksum ${m.id} (the plan digest moves, so the plan is approved again).`, EXIT_REFUSED);
+}
+//# sourceMappingURL=checks.js.map

package/dist/versioned/checks.js.map

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

package/dist/versioned/clickhouse.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The versioned apply's ClickHouse driver: the Keeper (or local) lock
+ * (`../history/lock.ts`), the catalog fingerprint over `system.tables`
+ * (`./digest.ts`), and each statement rendered for the environment's
+ * topology (#9) and sent, then its `succeeded` row appended. ClickHouse DDL
+ * is not transactional, so the row follows the statement; a runner killed
+ * between the two leaves the statement's latest row `started`, and the next
+ * run sends it again.
+ */
+import type { ClickHouseEndpoint } from "@intentius/chant-lexicon-sql/clickhouse/http";
+import { type ClickHousePort, type HistoryLocation } from "../history/index.js";
+import { type Topology } from "../topology/render.js";
+import { type LiveScope } from "./digest.js";
+import type { VersionedDriver } from "./driver.js";
+export interface ClickHouseDriverInput {
+    port: ClickHousePort;
+    location: HistoryLocation;
+    scope: LiveScope;
+    serverKey: string;
+    lockTtlMs: number;
+    endpoint?: ClickHouseEndpoint | undefined;
+    topology?: Topology | undefined;
+}
+export declare function clickhouseDriver(input: ClickHouseDriverInput): VersionedDriver;

package/dist/versioned/clickhouse.js

@@ -0,0 +1,42 @@
+/**
+ * The versioned apply's ClickHouse driver: the Keeper (or local) lock
+ * (`../history/lock.ts`), the catalog fingerprint over `system.tables`
+ * (`./digest.ts`), and each statement rendered for the environment's
+ * topology (#9) and sent, then its `succeeded` row appended. ClickHouse DDL
+ * is not transactional, so the row follows the statement; a runner killed
+ * between the two leaves the statement's latest row `started`, and the next
+ * run sends it again.
+ */
+import { acquireLock, SINGLE, serverMessage } from "../history/index.js";
+import { renderForEnvironment, topologyNote } from "../topology/render.js";
+import { catalogFingerprint, readLiveCatalog } from "./digest.js";
+export function clickhouseDriver(input) {
+    const { port } = input;
+    const topology = input.topology ?? SINGLE;
+    return {
+        dialect: "clickhouse",
+        rowNote: topologyNote(topology),
+        acquireLock: (holder) => acquireLock(port, { database: input.location.database, topology: input.location.topology, holder, ttlMs: input.lockTtlMs, serverKey: input.serverKey }),
+        liveFingerprint: async () => catalogFingerprint(await readLiveCatalog(port, input.scope)),
+        async readCheck(sql, where) {
+            try {
+                return await port.query(sql.trim().replace(/;+$/, ""), { settings: { readonly: "2", ...(where.defaultDatabase ? { database: where.defaultDatabase } : {}) } });
+            }
+            catch (e) {
+                throw new Error(serverMessage(e), { cause: e });
+            }
+        },
+        async runStatement(step, run) {
+            try {
+                await port.query(renderForEnvironment(step.sql, topology), step.waitsForMutation ? { settings: { mutations_sync: "2" } } : {});
+            }
+            catch (e) {
+                throw new Error(serverMessage(e), { cause: e });
+            }
+            await run.succeeded("");
+        },
+        stepContext: () => ({ port, endpoint: input.endpoint }),
+        close: () => Promise.resolve(),
+    };
+}
+//# sourceMappingURL=clickhouse.js.map

package/dist/versioned/clickhouse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clickhouse.js","sourceRoot":"","sources":["../../src/versioned/clickhouse.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAA6C,MAAM,qBAAqB,CAAC;AACpH,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAiB,MAAM,uBAAuB,CAAC;AAC1F,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAkB,MAAM,aAAa,CAAC;AAalF,MAAM,UAAU,gBAAgB,CAAC,KAA4B;IAC3D,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC;IACvB,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,MAAM,CAAC;IAC1C,OAAO;QACL,OAAO,EAAE,YAAY;QACrB,OAAO,EAAE,YAAY,CAAC,QAAQ,CAAC;QAC/B,WAAW,EAAE,CAAC,MAAM,EAAE,EAAE,CACtB,WAAW,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC;QACzJ,eAAe,EAAE,KAAK,IAAI,EAAE,CAAC,kBAAkB,CAAC,MAAM,eAAe,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QACzF,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE,KAAK;YACxB,IAAI,CAAC;gBACH,OAAO,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,EAAE,QAAQ,EAAE,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;YACjK,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,MAAM,IAAI,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;YAClD,CAAC;QACH,CAAC;QACD,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,GAAG;YAC1B,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,KAAK,CAAC,oBAAoB,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,cAAc,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACjI,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,MAAM,IAAI,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;YAClD,CAAC;YACD,MAAM,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QAC1B,CAAC;QACD,WAAW,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;QACvD,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE;KAC/B,CAAC;AACJ,CAAC"}