@intentius/chant-lexicon-sql 0.0.0-stage → 0.112.1

package/src/op/activities/clickhouse-apply.e2e.test.ts

@@ -0,0 +1,150 @@
+/**
+ * The ClickHouse applier against the pinned server (#3208): create, then a
+ * column added, a TTL changed, a skip index added and a column type changed
+ * as a mutation; a sorting-key change refused as a rebuild; the same build
+ * applied twice; a prune that drops an owned table and spares one made by
+ * hand.
+ *
+ * Needs Docker; skips cleanly without it.
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { normalizeApply } from "@intentius/chant/apply";
+import { dockerAvailable, startScratchServer, type ScratchServer } from "../../clickhouse/container";
+import { clickhouseQuery } from "../../clickhouse/http";
+import { clickhouseImage } from "../../spec/pin";
+import { planAgainstServer } from "../../clickhouse/plan/commands";
+import { clickhouseApply, toApplyResult } from "./clickhouse-apply";
+
+const enabled = await dockerAvailable();
+let server: ScratchServer | undefined;
+const dir = mkdtempSync(join(tmpdir(), "chant-sql-apply-"));
+
+beforeAll(async () => {
+  if (!enabled) return;
+  server = await startScratchServer(clickhouseImage(), { namePrefix: "chant-sql-apply" });
+}, 600_000);
+
+afterAll(async () => {
+  await server?.stop();
+  rmSync(dir, { recursive: true, force: true });
+});
+
+interface Obj {
+  export: string;
+  type: string;
+  ddl: string;
+  dependsOn?: string[];
+}
+
+let builds = 0;
+function buildFile(objects: Obj[]): string {
+  const path = join(dir, `schema-${builds++}.json`);
+  writeFileSync(path, JSON.stringify({ dialect: "clickhouse", applyOrder: objects.map((o) => o.export), objects: objects.map((o) => ({ dependsOn: [], ...o })) }));
+  return path;
+}
+
+const DB: Obj = { export: "shop", type: "ClickHouse::Database", ddl: "CREATE DATABASE shop ENGINE = Atomic COMMENT 'The shop'" };
+const eventsV1: Obj = {
+  export: "events",
+  type: "ClickHouse::Table",
+  dependsOn: ["shop"],
+  ddl: `CREATE TABLE shop.events
+(
+  ts DateTime,
+  user_id UInt64,
+  kind String
+)
+ENGINE = MergeTree
+ORDER BY (ts, user_id)
+TTL ts + INTERVAL 180 DAY
+COMMENT 'Raw events'`,
+};
+const eventsV2: Obj = {
+  ...eventsV1,
+  ddl: `CREATE TABLE shop.events
+(
+  ts DateTime,
+  user_id UInt64,
+  region LowCardinality(String) DEFAULT 'eu',
+  kind LowCardinality(String),
+  INDEX kind_idx kind TYPE set(100) GRANULARITY 4
+)
+ENGINE = MergeTree
+ORDER BY (ts, user_id)
+TTL ts + INTERVAL 90 DAY
+COMMENT 'Raw events'`,
+};
+const OLD: Obj = { export: "old", type: "ClickHouse::Table", dependsOn: ["shop"], ddl: "CREATE TABLE shop.old_events (id UInt64) ENGINE = MergeTree ORDER BY id" };
+const BY_KIND: Obj = {
+  export: "byKind",
+  type: "ClickHouse::View",
+  dependsOn: ["events"],
+  ddl: "CREATE VIEW shop.by_kind AS SELECT kind, count() AS n FROM shop.events GROUP BY kind",
+};
+
+const deps = () => ({ config: { ownership: { stack: "e2e", env: "test" } }, env: { CLICKHOUSE_URL: server!.endpoint.url }, log: () => undefined });
+const apply = async (objects: Obj[], prune = false) => normalizeApply(toApplyResult(await clickhouseApply({ buildPath: buildFile(objects), environment: "e2e", prune }, undefined, deps())));
+const q = <T = Record<string, unknown>>(sql: string) => clickhouseQuery<T>(server!.endpoint, sql);
+const showCreate = async (name: string) => (await q<{ statement: string }>(`SHOW CREATE TABLE ${name}`))[0]!.statement;
+const actions = (r: ReturnType<typeof normalizeApply>) => Object.fromEntries(r.applied.map((a) => [a.name, a.action]));
+
+describe.skipIf(!enabled)("applying to a clickhouse-server", () => {
+  test("an empty server gets the declared objects, each marked", async () => {
+    const r = await apply([DB, eventsV1, OLD, BY_KIND]);
+    expect(actions(r)).toEqual({ shop: "created", "shop.events": "created", "shop.old_events": "created", "shop.by_kind": "created" });
+    expect(r.notAttempted).toEqual([]);
+    const comments = await q<{ name: string; comment: string }>("SELECT name, comment FROM system.tables WHERE database = 'shop' ORDER BY name");
+    expect(comments).toEqual([
+      { name: "by_kind", comment: "[chant managed-by=chant stack=e2e env=test]" },
+      { name: "events", comment: "Raw events [chant managed-by=chant stack=e2e env=test]" },
+      { name: "old_events", comment: "[chant managed-by=chant stack=e2e env=test]" },
+    ]);
+    await q("INSERT INTO shop.events SELECT now() - number, number, if(number % 2, 'click', 'view') FROM numbers(10000)");
+    // A table nobody declared, made by hand in the same database.
+    await q("CREATE TABLE shop.handmade (id UInt64) ENGINE = Log COMMENT 'made by hand'");
+  }, 120_000);
+
+  test("a column added, a TTL changed, a skip index added and a type changed as a mutation", async () => {
+    const r = await apply([DB, eventsV2, OLD, BY_KIND]);
+    expect(actions(r)).toEqual({ shop: "unchanged", "shop.events": "updated", "shop.old_events": "unchanged", "shop.by_kind": "unchanged" });
+    const ddl = await showCreate("shop.events");
+    expect(ddl).toContain("`region` LowCardinality(String) DEFAULT 'eu'");
+    expect(ddl).toContain("`kind` LowCardinality(String)");
+    expect(ddl).toContain("INDEX kind_idx kind TYPE set(100) GRANULARITY 4");
+    expect(ddl).toContain("TTL ts + toIntervalDay(90)");
+    const pending = await q("SELECT mutation_id FROM system.mutations WHERE database = 'shop' AND NOT is_done");
+    expect(pending).toEqual([]);
+    const mutations = await q<{ command: string }>("SELECT command FROM system.mutations WHERE database = 'shop' AND table = 'events'");
+    expect(mutations.some((m) => /MODIFY COLUMN `kind` LowCardinality\(String\)/.test(m.command))).toBe(true);
+    // The server now holds the declaration: a plan finds nothing to change but
+    // the table made by hand, which no build declares.
+    const plan = await planAgainstServer("e2e", buildFile([DB, eventsV2, OLD, BY_KIND]), { config: {}, env: { CLICKHOUSE_URL: server!.endpoint.url } });
+    expect(plan.changes.map((c) => [c.object, c.rule])).toEqual([["shop.handmade", "SQLCH250"]]);
+  }, 180_000);
+
+  test("a sorting-key change is refused as a rebuild and nothing is sent for it", async () => {
+    const before = await showCreate("shop.events");
+    const rebuilt = { ...eventsV2, ddl: eventsV2.ddl.replace("ORDER BY (ts, user_id)", "ORDER BY (user_id, ts)") };
+    const r = await apply([DB, rebuilt, OLD, BY_KIND]);
+    expect(r.notAttempted).toHaveLength(1);
+    expect(r.notAttempted[0]).toMatchObject({ kind: "ClickHouse::Table", name: "shop.events", reason: "unsupported-kind" });
+    expect(r.notAttempted[0]!.detail).toMatch(/SQLCH220.*clickhouse\.com\/docs.*ClickHouseRebuildOp\(\{ table: "shop\.events"/);
+    expect(await showCreate("shop.events")).toBe(before);
+  }, 120_000);
+
+  test("the same build applied a second time changes nothing", async () => {
+    const r = await apply([DB, eventsV2, OLD, BY_KIND]);
+    expect(Object.values(actions(r))).toEqual(["unchanged", "unchanged", "unchanged", "unchanged"]);
+  }, 120_000);
+
+  test("a prune drops the owned table the build no longer declares and spares the one made by hand", async () => {
+    const r = await apply([DB, eventsV2, BY_KIND], true);
+    expect(r.pruned.map((p) => p.name)).toEqual(["shop.old_events"]);
+    const names = (await q<{ name: string }>("SELECT name FROM system.tables WHERE database = 'shop' ORDER BY name")).map((t) => t.name);
+    expect(names).toEqual(["by_kind", "events", "handmade"]);
+  }, 120_000);
+});

package/src/op/activities/clickhouse-apply.test.ts

@@ -0,0 +1,265 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { describeApplyConformance } from "@intentius/chant-test-utils";
+import { normalizeApply } from "@intentius/chant/apply";
+import { clickhouseApply, resolveMarker, toApplyResult, type ClickHouseApplyDeps } from "./clickhouse-apply";
+import { writableClickHouse, type StoredObject, type WritableServer } from "../../clickhouse/testing/writable-server";
+import { ClickHouseApplyError } from "../../clickhouse/apply/apply";
+
+const dirs: string[] = [];
+const servers: WritableServer[] = [];
+afterAll(async () => {
+  for (const d of dirs) rmSync(d, { recursive: true, force: true });
+  for (const s of servers) await s.close();
+});
+
+interface Obj {
+  export: string;
+  type: string;
+  ddl: string;
+  dependsOn?: string[];
+}
+
+const DB: Obj = { export: "analytics", type: "ClickHouse::Database", ddl: "CREATE DATABASE analytics ENGINE = Atomic" };
+const EVENTS: Obj = {
+  export: "events",
+  type: "ClickHouse::Table",
+  ddl: "CREATE TABLE analytics.events (ts DateTime, user_id UInt64, kind String) ENGINE = MergeTree ORDER BY (ts, user_id) COMMENT 'Raw events'",
+  dependsOn: ["analytics"],
+};
+const BY_KIND: Obj = { export: "byKind", type: "ClickHouse::View", ddl: "CREATE VIEW analytics.by_kind AS SELECT kind, count() AS n FROM analytics.events GROUP BY kind", dependsOn: ["events"] };
+
+/** A build output the way `chant build -o dist/schema.json` writes it. */
+function buildOutput(objects: Obj[]): string {
+  const dir = mkdtempSync(join(tmpdir(), "chant-clickhouse-apply-"));
+  dirs.push(dir);
+  const path = join(dir, "schema.json");
+  writeFileSync(path, JSON.stringify({ dialect: "clickhouse", applyOrder: objects.map((o) => o.export), objects: objects.map((o) => ({ dependsOn: [], ...o })) }));
+  return path;
+}
+
+async function server(objects: StoredObject[] = []): Promise<WritableServer> {
+  const s = await writableClickHouse(objects);
+  servers.push(s);
+  return s;
+}
+
+const OURS = "[chant managed-by=chant stack=shop env=prod]";
+const deps = (s: WritableServer | undefined, extra: Partial<ClickHouseApplyDeps> = {}): ClickHouseApplyDeps => ({
+  config: { ownership: { stack: "shop", env: "prod" } },
+  env: s ? { CLICKHOUSE_URL: s.url } : {},
+  log: () => undefined,
+  ...extra,
+});
+
+const run = async (s: WritableServer | undefined, objects: Obj[], args: { prune?: boolean } = {}, extra: Partial<ClickHouseApplyDeps> = {}) =>
+  toApplyResult(await clickhouseApply({ buildPath: buildOutput(objects), environment: "test", ...args }, undefined, deps(s, extra)));
+
+/** A live object as `SHOW CREATE` prints it, marked or not. */
+function live(database: string | undefined, name: string, statement: string, comment?: string): StoredObject {
+  const engine = /^CREATE DATABASE/.test(statement) ? "Atomic" : /^CREATE VIEW/.test(statement) ? "View" : "MergeTree";
+  return { ...(database ? { database } : {}), name, engine, statement: comment ? `${statement}\nCOMMENT '${comment}'` : statement, ...(comment ? { comment } : {}) };
+}
+const liveDb = (comment = OURS) => live(undefined, "analytics", "CREATE DATABASE analytics\nENGINE = Atomic", comment);
+const liveEvents = (comment = `Raw events ${OURS}`) =>
+  live("analytics", "events", "CREATE TABLE analytics.events\n(\n    `ts` DateTime,\n    `user_id` UInt64,\n    `kind` String\n)\nENGINE = MergeTree\nORDER BY (ts, user_id)\nSETTINGS index_granularity = 8192", comment);
+
+describe("creating", () => {
+  test("an empty server gets every object, each created with chant's marker in its comment", async () => {
+    const s = await server();
+    const r = normalizeApply(await run(s, [DB, EVENTS, BY_KIND]));
+    expect(r.applied.map((a) => [a.name, a.action])).toEqual([
+      ["analytics", "created"],
+      ["analytics.events", "created"],
+      ["analytics.by_kind", "created"],
+    ]);
+    expect(s.writes[0]).toBe(`CREATE DATABASE analytics ENGINE = Atomic COMMENT '${OURS}'`);
+    expect(s.writes[1]).toContain(`COMMENT 'Raw events ${OURS}'`);
+    expect(s.writes[2]).toMatch(/GROUP BY kind COMMENT '\[chant managed-by=chant stack=shop env=prod\]'$/);
+  });
+
+  test("without an ownership stack the marker says managed-by alone", async () => {
+    const s = await server();
+    await run(s, [DB], {}, { config: {} });
+    expect(s.writes[0]).toBe("CREATE DATABASE analytics ENGINE = Atomic COMMENT '[chant managed-by=chant]'");
+  });
+});
+
+describe("updating", () => {
+  test("an added column goes in at its declared place", async () => {
+    const s = await server([liveDb(), liveEvents()]);
+    const withRegion = { ...EVENTS, ddl: EVENTS.ddl.replace("user_id UInt64,", "user_id UInt64, region LowCardinality(String) DEFAULT 'eu',") };
+    const r = normalizeApply(await run(s, [DB, withRegion]));
+    expect(r.applied.map((a) => [a.name, a.action])).toEqual([
+      ["analytics", "unchanged"],
+      ["analytics.events", "updated"],
+    ]);
+    expect(s.writes).toEqual(["ALTER TABLE `analytics`.`events` ADD COLUMN region LowCardinality(String) DEFAULT 'eu' AFTER `user_id`"]);
+  });
+
+  test("a column type change waits on its mutation", async () => {
+    const s = await server([liveDb(), liveEvents()]);
+    s.mutations.push({ database: "analytics", table: "events", mutation_id: "mutation_7.txt" });
+    setTimeout(() => (s.mutations.length = 0), 150);
+    const r = normalizeApply(await run(s, [DB, { ...EVENTS, ddl: EVENTS.ddl.replace("kind String", "kind LowCardinality(String)") }]));
+    expect(r.applied.find((a) => a.name === "analytics.events")?.action).toBe("updated");
+    expect(s.writes).toEqual(["ALTER TABLE `analytics`.`events` MODIFY COLUMN `kind` LowCardinality(String)"]);
+  });
+
+  test("a mutation still running at the timeout fails the apply, naming the mutation", async () => {
+    const s = await server([liveDb(), liveEvents()]);
+    s.mutations.push({ database: "analytics", table: "events", mutation_id: "mutation_9.txt" });
+    const err = await clickhouseApply(
+      { buildPath: buildOutput([DB, { ...EVENTS, ddl: EVENTS.ddl.replace("kind String", "kind LowCardinality(String)") }]), environment: "test", mutationTimeoutMs: 300 },
+      undefined,
+      deps(s),
+    ).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(ClickHouseApplyError);
+    expect((err as Error).message).toMatch(/mutation_9\.txt was still running/);
+    expect((err as ClickHouseApplyError).outcome.applied.map((a) => a.name)).toEqual(["analytics"]);
+  });
+
+  test("a refused rebuild is not attempted, with the restriction and the rebuild Op named", async () => {
+    const s = await server([liveDb(), liveEvents()]);
+    const r = normalizeApply(await run(s, [DB, { ...EVENTS, ddl: EVENTS.ddl.replace("ORDER BY (ts, user_id)", "ORDER BY (user_id, ts)") }]));
+    expect(r.notAttempted).toHaveLength(1);
+    expect(r.notAttempted[0]).toMatchObject({ kind: "ClickHouse::Table", name: "analytics.events", reason: "unsupported-kind" });
+    expect(r.notAttempted[0]!.detail).toMatch(/SQLCH220 Change the sorting key/);
+    expect(r.notAttempted[0]!.detail).toMatch(/clickhouse\.com\/docs/);
+    expect(r.notAttempted[0]!.detail).toContain('ClickHouseRebuildOp({ table: "analytics.events"');
+    expect(s.writes).toEqual([]);
+  });
+
+  test("a column drop is withheld unless the apply may delete", async () => {
+    const s = await server([liveDb(), liveEvents()]);
+    const without = { ...EVENTS, ddl: EVENTS.ddl.replace(", kind String", "") };
+    const withheld = normalizeApply(await run(s, [DB, without]));
+    expect(withheld.notAttempted[0]).toMatchObject({ name: "analytics.events", reason: "filtered" });
+    expect(s.writes).toEqual([]);
+    await run(s, [DB, without], { prune: true });
+    expect(s.writes).toEqual(["ALTER TABLE `analytics`.`events` DROP COLUMN `kind`"]);
+  });
+
+  test("an object whose comment lost the marker is stamped again, its own comment kept", async () => {
+    const s = await server([liveDb(), liveEvents("Raw events")]);
+    const r = normalizeApply(await run(s, [DB, EVENTS]));
+    expect(r.applied.find((a) => a.name === "analytics.events")?.action).toBe("updated");
+    expect(s.writes).toEqual([`ALTER TABLE \`analytics\`.\`events\` MODIFY COMMENT 'Raw events ${OURS}'`]);
+  });
+
+  test("a statement the server refuses fails the apply and the objects depending on it are not attempted", async () => {
+    const s = await server();
+    s.refuse = /CREATE TABLE/;
+    const err = (await clickhouseApply({ buildPath: buildOutput([DB, EVENTS, BY_KIND]), environment: "test" }, undefined, deps(s)).catch((e: unknown) => e)) as ClickHouseApplyError;
+    expect(err).toBeInstanceOf(ClickHouseApplyError);
+    expect(err.outcome.failed.map((f) => f.name)).toEqual(["analytics.events"]);
+    expect(err.outcome.notAttempted).toMatchObject([{ name: "analytics.by_kind", reason: "dependency-failed" }]);
+  });
+});
+
+describe("resolveMarker", () => {
+  test("the arguments win over the config, and a parameter-reference env needs ownershipEnv", () => {
+    expect(resolveMarker({ stack: "a" }, { ownership: { stack: "b", env: "prod" } })).toEqual({ stack: "a", env: "prod" });
+    expect(resolveMarker({}, { ownership: { stack: "b", enabled: false } })).toBeUndefined();
+    expect(() => resolveMarker({}, { ownership: { stack: "b", env: { param: "env" } } as never })).toThrow(/ownershipEnv/);
+  });
+});
+
+describeApplyConformance({
+  lexicon: "sql",
+  scenarios: [
+    {
+      name: "a database, a table and a view on an empty server",
+      plan: [
+        { kind: "ClickHouse::Database", name: "analytics" },
+        { kind: "ClickHouse::Table", name: "analytics.events" },
+        { kind: "ClickHouse::View", name: "analytics.by_kind" },
+      ],
+      run: async () => run(await server(), [DB, EVENTS, BY_KIND]),
+      expectApplied: ["ClickHouse::Database/analytics", "ClickHouse::Table/analytics.events", "ClickHouse::View/analytics.by_kind"],
+    },
+    {
+      name: "a sorting-key change refused as a rebuild beside an unchanged database",
+      plan: [
+        { kind: "ClickHouse::Database", name: "analytics" },
+        { kind: "ClickHouse::Table", name: "analytics.events" },
+      ],
+      run: async () => run(await server([liveDb(), liveEvents()]), [DB, { ...EVENTS, ddl: EVENTS.ddl.replace("ORDER BY (ts, user_id)", "ORDER BY ts") }]),
+      expectApplied: ["ClickHouse::Database/analytics"],
+      expectNotAttempted: ["ClickHouse::Table/analytics.events"],
+    },
+    {
+      name: "no server bound",
+      plan: [
+        { kind: "ClickHouse::Database", name: "analytics" },
+        { kind: "ClickHouse::Table", name: "analytics.events" },
+      ],
+      run: () => run(undefined, [DB, EVENTS]),
+      expectNotAttempted: ["ClickHouse::Database/analytics", "ClickHouse::Table/analytics.events"],
+    },
+    {
+      name: "prune without an ownership stack",
+      plan: [{ kind: "ClickHouse::Database", name: "analytics" }],
+      run: async () => run(await server([liveDb("[chant managed-by=chant]"), liveEvents("[chant managed-by=chant]")]), [DB], { prune: true }, { config: {} }),
+      expectApplied: ["ClickHouse::Database/analytics"],
+      expectNotAttempted: ["ClickHouse::Table/analytics.events"],
+    },
+  ],
+  pruneScenarios: [
+    {
+      name: "an owned orphan table beside one created by hand",
+      ownedOrphan: "analytics.events",
+      foreign: "analytics.handmade",
+      run: async () => {
+        const s = await server([liveDb(), liveEvents(), live("analytics", "handmade", "CREATE TABLE analytics.handmade\n(\n    `id` UInt64\n)\nENGINE = Log", "made by hand")]);
+        return { result: await run(s, [DB], { prune: true }), deletes: s.deletes };
+      },
+    },
+    {
+      name: "an owned orphan table beside another stack's",
+      ownedOrphan: "analytics.events",
+      foreign: "analytics.theirs",
+      run: async () => {
+        const s = await server([
+          liveDb(),
+          liveEvents(),
+          live("analytics", "theirs", "CREATE TABLE analytics.theirs\n(\n    `id` UInt64\n)\nENGINE = Log", "[chant managed-by=chant stack=other env=prod]"),
+        ]);
+        return { result: await run(s, [DB], { prune: true }), deletes: s.deletes };
+      },
+    },
+  ],
+  idempotenceScenarios: [
+    {
+      name: "the same build applied twice",
+      run: async () => {
+        const s = await server();
+        const first = await run(s, [DB, EVENTS, BY_KIND]);
+        const second = await run(s, [DB, EVENTS, BY_KIND]);
+        return { first, second };
+      },
+    },
+  ],
+});
+
+describe("idempotence", () => {
+  test("the second apply sends nothing and reports every object unchanged", async () => {
+    const s = await server();
+    await run(s, [DB, EVENTS, BY_KIND]);
+    const writes = s.writes.length;
+    const second = normalizeApply(await run(s, [DB, EVENTS, BY_KIND]));
+    expect(second.applied.map((a) => a.action)).toEqual(["unchanged", "unchanged", "unchanged"]);
+    expect(s.writes.length).toBe(writes);
+  });
+
+  test("prune keeps a database that still holds an object it does not drop", async () => {
+    const s = await server([liveDb(), live("analytics", "handmade", "CREATE TABLE analytics.handmade\n(\n    `id` UInt64\n)\nENGINE = Log")]);
+    // The build declares only a table in another database, so analytics itself is an owned orphan.
+    const other: Obj = { export: "o", type: "ClickHouse::Table", ddl: "CREATE TABLE analytics.other (id UInt64) ENGINE = Log" };
+    const r = normalizeApply(await run(s, [other], { prune: true }));
+    expect(r.notAttempted).toMatchObject([{ name: "analytics", reason: "not-prunable" }]);
+    expect(s.deletes).toEqual([]);
+  });
+});

package/src/op/activities/clickhouse-apply.ts

@@ -0,0 +1,113 @@
+/**
+ * `clickhouseApply`, the Op activity for the ClickHouse applier (#3208), and
+ * `toApplyResult`, its projection onto core's apply envelope (#1446).
+ *
+ * It reads a build's output (`chant build -o dist/schema.json`), binds the
+ * environment's server the way observation and import do
+ * (`sql.profiles.<env>`, else `CLICKHOUSE_URL`; ../../clickhouse/live/bind.ts),
+ * and hands the declarations to `applyClickHouse`
+ * (../../clickhouse/apply/apply.ts), which holds the decisions.
+ *
+ * The ownership marker is the project's: `ownership.stack` and
+ * `ownership.env` from `chant.config.ts`, or `stack` / `ownershipEnv` passed
+ * in. Without a stack the apply still runs, stamping only the managed-by
+ * marker, and a prune declines (as `not-prunable`) rather than drop another
+ * project's tables.
+ */
+
+import { readFileSync } from "node:fs";
+import type { ChantConfig } from "@intentius/chant/config";
+import type { OwnershipMarker } from "@intentius/chant/ownership";
+import { notAttemptedOutcome, resolveOwnershipMarker } from "../../core/apply";
+import { bindClickHouse, ClickHouseBindingError, classifyClickHouseFailure } from "../../clickhouse/live/bind";
+import { applyClickHouse, declaredObjects, planRefs, type ClickHouseApplyOutcome } from "../../clickhouse/apply/apply";
+
+export type { ClickHouseApplyOutcome } from "../../clickhouse/apply/apply";
+export { toApplyResult } from "../../core/apply";
+
+export interface ClickHouseApplyArgs {
+  /** The build's primary output (`chant build src --lexicon sql -o dist/schema.json`), or a multi-lexicon output holding it under `sql`. */
+  buildPath: string;
+  /** The chant environment, which selects `sql.profiles.<environment>`. */
+  environment?: string;
+  /**
+   * Drop this project's objects the build no longer declares (only those
+   * whose comment carries its marker, stack and env), and allow column drops.
+   * Destructive, so off by default.
+   */
+  prune?: boolean;
+  /** Ownership stack. Default: `ownership.stack` in `chant.config.ts`. */
+  stack?: string;
+  /** Ownership env. Default: `ownership.env` in `chant.config.ts` (a literal; a `{ param }` reference needs this). */
+  ownershipEnv?: string;
+  /** How long to wait for one table's background rewrite. Default: ten minutes. */
+  mutationTimeoutMs?: number;
+  /** Project directory for `chant.config.ts`. Default: the working directory. */
+  cwd?: string;
+}
+
+/** What a test (or an embedding caller) may inject instead of the project's config and the process env. */
+export interface ClickHouseApplyDeps {
+  config?: Pick<ChantConfig, "sql" | "ownership">;
+  env?: Record<string, string | undefined>;
+  log?: (line: string) => void;
+}
+
+async function loadConfig(cwd: string): Promise<Pick<ChantConfig, "sql" | "ownership"> | undefined> {
+  try {
+    const { loadChantConfig } = await import("@intentius/chant/config");
+    return (await loadChantConfig(cwd)).config;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The marker to stamp and prune by: the arguments, else the project's `ownership` config. */
+export function resolveMarker(args: Pick<ClickHouseApplyArgs, "stack" | "ownershipEnv">, config: Pick<ChantConfig, "ownership"> | undefined): OwnershipMarker | undefined {
+  return resolveOwnershipMarker(args, config, "clickhouse apply");
+}
+
+/**
+ * Apply a sql build to the environment's ClickHouse server. A server that
+ * cannot be bound, or refuses the credentials on the first read, returns
+ * every declared object as not attempted, with the reason.
+ */
+export async function clickhouseApply(args: ClickHouseApplyArgs, signal?: AbortSignal, deps: ClickHouseApplyDeps = {}): Promise<ClickHouseApplyOutcome> {
+  const config = deps.config ?? (await loadConfig(args.cwd ?? process.cwd()));
+  const marker = resolveMarker(args, config);
+  const json = readFileSync(args.buildPath, "utf8");
+  const log = deps.log ?? ((line: string) => console.log(line));
+  let target;
+  try {
+    target = await bindClickHouse({ ...(args.environment !== undefined ? { environment: args.environment } : {}), config: config ?? {}, ...(deps.env ? { env: deps.env } : {}) });
+  } catch (err) {
+    if (!(err instanceof ClickHouseBindingError)) throw err;
+    return refused(declaredObjects(json), err.unresolved.reason, err.unresolved.detail);
+  }
+  const declared = declaredObjects(json, target.defaultDatabase);
+  let outcome: ClickHouseApplyOutcome;
+  try {
+    outcome = await applyClickHouse(target, declared, {
+      ...(marker ? { marker } : {}),
+      ...(args.prune ? { prune: true } : {}),
+      ...(args.mutationTimeoutMs !== undefined ? { mutationTimeoutMs: args.mutationTimeoutMs } : {}),
+      ...(signal ? { signal } : {}),
+      log,
+    });
+  } catch (err) {
+    // A server that never answered the first read was not written to at all.
+    const why = classifyClickHouseFailure(err);
+    if (why.reason === "no-credentials" && !(err instanceof Error && err.name === "ClickHouseApplyError")) {
+      return { ...refused(declared, "no-credentials", why.detail), target: target.endpoint.url, source: target.source };
+    }
+    throw err;
+  }
+  for (const a of outcome.applied) log(`${a.action}: ${a.kind}/${a.name}`);
+  for (const p of outcome.pruned) log(`pruned: ${p.kind}/${p.name}`);
+  for (const n of outcome.notAttempted) log(`not attempted: ${n.kind}/${n.name}: ${n.reason}${n.detail ? ` (${n.detail})` : ""}`);
+  return outcome;
+
+  function refused(objects: ReturnType<typeof declaredObjects>, reason: "no-binding" | "no-credentials", detail: string): ClickHouseApplyOutcome {
+    return notAttemptedOutcome(planRefs(objects), reason, detail);
+  }
+}

package/src/op/activities/clickhouse-emulator.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, test } from "vitest";
+import { emulatorLifecycle, emulatorsOf, endpointEnvVars } from "@intentius/chant/op";
+import { CLICKHOUSE_EMULATOR } from "./clickhouse-emulator";
+import { sqlPlugin } from "../../plugin";
+import { clickhouseImage } from "../../spec/pin";
+
+describe("the ClickHouse emulator capability (#3208)", () => {
+  test("is declared on the plugin, so chant emulator up boots it", () => {
+    expect(emulatorsOf(sqlPlugin.emulator)[0]).toEqual(CLICKHOUSE_EMULATOR);
+  });
+
+  test("runs the pinned image by digest, and names CLICKHOUSE_URL as its endpoint", () => {
+    expect(CLICKHOUSE_EMULATOR.spec.image).toBe(clickhouseImage());
+    expect(CLICKHOUSE_EMULATOR.spec.image).toMatch(/:26\.8\.15\.10@sha256:/);
+    expect(endpointEnvVars(CLICKHOUSE_EMULATOR)).toEqual(["CLICKHOUSE_URL"]);
+  });
+
+  test("starts the server reachable as the default user", () => {
+    expect(emulatorLifecycle(CLICKHOUSE_EMULATOR.spec).runCommand()).toBe(
+      `docker run -d --rm --name chant-clickhouse -p 8123:8123 -e CLICKHOUSE_SKIP_USER_SETUP=1 ${clickhouseImage()}`,
+    );
+  });
+});

package/src/op/activities/clickhouse-emulator.ts

@@ -0,0 +1,37 @@
+/**
+ * The sql lexicon's emulator capability (#3208): the pinned
+ * `clickhouse/clickhouse-server`, the same image and digest generation and
+ * the live tests run (../../spec/pin.ts), so `chant emulator up` boots a real
+ * server rather than a stand-in.
+ *
+ * `upstream` is left off on purpose. The freshness check compares the image
+ * tag against the repo's latest GitHub release, and ClickHouse's latest
+ * release is a monthly one, not the LTS line the pin follows; the lexicon's
+ * `upstreamPin` already tracks the LTS tags (`-lts`).
+ */
+
+import { emulatorLifecycle, type EmulatorCapability, type EmulatorSpec } from "@intentius/chant/op";
+import { clickhouseImage } from "../../spec/pin";
+
+export const CLICKHOUSE_EMULATOR_SPEC: EmulatorSpec = {
+  name: "chant-clickhouse",
+  image: clickhouseImage(),
+  containerPort: 8123,
+  healthPath: "/ping",
+  // The image disables network access for the passwordless default user
+  // unless this is set; a local server is reached as `default` with no password.
+  runArgs: ["-e", "CLICKHOUSE_SKIP_USER_SETUP=1"],
+};
+
+/** `CLICKHOUSE_URL` is the variable binding reads when no `sql.profiles.<env>` names a server. */
+export const CLICKHOUSE_EMULATOR: EmulatorCapability = {
+  spec: CLICKHOUSE_EMULATOR_SPEC,
+  env: (endpoint) => ({ CLICKHOUSE_URL: endpoint }),
+};
+
+const lifecycle = emulatorLifecycle(CLICKHOUSE_EMULATOR_SPEC);
+
+/** Boot the pinned ClickHouse server in Docker and return its endpoint. */
+export const clickhouseUp = (args: Parameters<typeof lifecycle.up>[0] = {}, signal?: AbortSignal) => lifecycle.up(args, signal);
+/** Stop and remove it (a no-op when it is gone). */
+export const clickhouseDown = (args: { name?: string } = {}, signal?: AbortSignal) => lifecycle.down(args, signal);