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

package/src/clickhouse/apply/statements.ts

@@ -0,0 +1,393 @@
+/**
+ * The statements that make one classified change (#3208): a `CREATE` with
+ * chant's marker in its comment, the `ALTER`s for the metadata and
+ * background-rewrite classes, and the `DROP` a prune issues.
+ *
+ * Each function here takes a declared object and the changes the classifier
+ * reported for it, and returns SQL; nothing is sent. The applier
+ * (`./apply.ts`) sends them, and the rebuild migration (#3198) builds its new
+ * table and swaps it in with the same pieces.
+ *
+ * The SQL is taken from the declaration's own text wherever it can be: a
+ * column's definition, an index's expression, a TTL, a setting's value are
+ * the spans the parser found in the declared `CREATE`, not the normalized
+ * forms the classifier compared. The normalized form is for comparing; what
+ * the server is sent is what the author wrote.
+ */
+
+import type { OwnershipMarker } from "@intentius/chant/ownership";
+import { isTrivia, tokenizeText, type Token } from "../tokens";
+import { parseCreate, type CreateNode, type Span, type TableNode, type ViewNode } from "../parser";
+import { canonicalObject, type CanonicalObject } from "../plan/normalize";
+import type { Change } from "../plan/diff";
+import { CLASSIFIER_RULES } from "../plan/rules";
+import { stampedComment } from "../ownership";
+import { CLICKHOUSE_ENTITY_TYPES, type ClickHouseEntityType } from "../entities";
+
+/** A backquoted identifier. */
+export const ident = (name: string): string => `\`${name.replace(/`/g, "``")}\``;
+
+/** `database.name` backquoted, or a database's bare name. */
+export const qualifiedIdent = (database: string | undefined, name: string): string =>
+  database !== undefined ? `${ident(database)}.${ident(name)}` : ident(name);
+
+/** A single-quoted string literal. */
+export const sqlString = (value: string): string => `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+
+/** `db.name` split at its first dot. */
+export function splitQualified(name: string): { database?: string; name: string } {
+  const at = name.indexOf(".");
+  return at < 0 ? { name } : { database: name.slice(0, at), name: name.slice(at + 1) };
+}
+
+/** One object as a build declares it, in the shape the applier works with. */
+export interface DeclaredObject {
+  /** The export name: the object's identity in chant. */
+  exportName: string;
+  type: ClickHouseEntityType;
+  /** `database.name` for a table or view, the name for a database: its identity on the server. */
+  key: string;
+  ddl: string;
+  canonical: CanonicalObject;
+  /** The export names this object references. */
+  dependsOn: string[];
+}
+
+/** One statement to send, and whether it starts a background rewrite to wait on. */
+export interface Step {
+  sql: string;
+  /** A mutation follows on the server; wait on `system.mutations` before the next step. */
+  rewrite: boolean;
+}
+
+interface Parsed {
+  tokens: Token[];
+  node: CreateNode;
+}
+
+const parsedCache = new WeakMap<DeclaredObject, Parsed>();
+
+function parsed(obj: DeclaredObject): Parsed {
+  let p = parsedCache.get(obj);
+  if (!p) {
+    const tokens = tokenizeText(obj.ddl, 0);
+    p = { tokens, node: parseCreate(tokens) };
+    parsedCache.set(obj, p);
+  }
+  return p;
+}
+
+const text = (tokens: Token[], span: Span | undefined): string | undefined =>
+  span && span.to > span.from
+    ? tokens
+        .slice(span.from, span.to)
+        .map((t) => t.text)
+        .join("")
+        .trim()
+    : undefined;
+
+/** The object's name on the server, quoted. */
+export const objectIdent = (obj: DeclaredObject): string => qualifiedIdent(obj.canonical.database, obj.canonical.name);
+
+/** The statement's end, past its significant tokens: trailing whitespace, comments and a `;` left out. */
+function statementBody(tokens: Token[]): string {
+  let end = tokens.length;
+  while (end > 0 && (isTrivia(tokens[end - 1]!) || tokens[end - 1]!.text === ";")) end--;
+  return tokens
+    .slice(0, end)
+    .map((t) => t.text)
+    .join("");
+}
+
+/**
+ * The declared `CREATE` with chant's ownership marker in its comment: the
+ * declared comment, if any, with the trailer after it, or a `COMMENT` clause
+ * added at the end. Set in the `CREATE` itself, so no object is ever created
+ * unmarked. `orReplace` turns `CREATE VIEW` into `CREATE OR REPLACE VIEW`;
+ * `trailer` adds pairs to the marker (the rebuild migration's working
+ * objects, `../rebuild/`).
+ */
+export function createStatement(
+  obj: DeclaredObject,
+  marker: OwnershipMarker | undefined,
+  opts: { orReplace?: boolean; trailer?: Readonly<Record<string, string>> } = {},
+): string {
+  const { tokens, node } = parsed(obj);
+  const literal = sqlString(stampedComment(obj.canonical.comment, marker, opts.trailer));
+  let sql: string;
+  if (node.comment) {
+    sql =
+      tokens
+        .slice(0, node.comment.from)
+        .map((t) => t.text)
+        .join("") +
+      literal +
+      statementBody(tokens.slice(node.comment.to));
+  } else {
+    sql = `${statementBody(tokens)} COMMENT ${literal}`;
+  }
+  if (opts.orReplace && node.statement === "view" && !node.orReplace) {
+    sql = sql.replace(/^(\s*(?:--[^\n]*\n\s*)*)CREATE\s+/i, "$1CREATE OR REPLACE ");
+  }
+  return sql;
+}
+
+/** Restamp the object's comment: the declared comment with this project's marker. */
+export function commentStatement(obj: DeclaredObject, marker: OwnershipMarker | undefined): string {
+  const literal = sqlString(stampedComment(obj.canonical.comment, marker));
+  return obj.type === CLICKHOUSE_ENTITY_TYPES.database
+    ? `ALTER DATABASE ${objectIdent(obj)} MODIFY COMMENT ${literal}`
+    : `ALTER TABLE ${objectIdent(obj)} MODIFY COMMENT ${literal}`;
+}
+
+/** The `DROP` for an object a prune removes. `SYNC` so the name is free when it returns. */
+export function dropStatement(type: string, database: string | undefined, name: string): string {
+  if (type === CLICKHOUSE_ENTITY_TYPES.database) return `DROP DATABASE ${ident(name)} SYNC`;
+  const what = type === CLICKHOUSE_ENTITY_TYPES.table ? "TABLE" : "VIEW";
+  return `DROP ${what} ${qualifiedIdent(database, name)} SYNC`;
+}
+
+/** Changes a plan refuses to make in place: they run as the rebuild migration (#3198). */
+export const isRebuild = (c: Change): boolean => c.class === "rebuild";
+
+/** Changes that remove data from an object the build still declares: withheld unless the apply may delete. */
+export const isDestructiveAlter = (c: Change): boolean => c.rule === "SQLCH202";
+
+/**
+ * A refused change in a sentence: the rule, the restriction, where it is
+ * stated, and where the change goes instead: the rebuild migration Op for
+ * the table (`key`, `database.name`), or for a view or database, which the
+ * Op does not rebuild, a drop and a create.
+ */
+export function refusalDetail(changes: readonly Change[], key?: string, type?: string): string {
+  const parts = changes.map((c) => {
+    const rule = CLASSIFIER_RULES[c.rule];
+    const values = c.before !== undefined || c.after !== undefined ? ` (${c.before ?? "none"} -> ${c.after ?? "none"})` : "";
+    return `${c.rule} ${rule.title} on ${c.field}${values}: ${rule.restriction} ${rule.cite}`;
+  });
+  const instead =
+    type === undefined || type === CLICKHOUSE_ENTITY_TYPES.table
+      ? `Run it as the rebuild migration Op: ClickHouseRebuildOp({ table: ${JSON.stringify(key ?? "<database.table>")}, ... }) from @intentius/chant-lexicon-sql/clickhouse`
+      : "The rebuild migration Op rebuilds tables only; drop and create this object instead";
+  return `needs a rebuild, which ALTER cannot make: ${parts.join("; ")}. ${instead}`;
+}
+
+/**
+ * The declaration under another name in the same database: the rebuild
+ * migration creates its new table from the declared `CREATE` this way.
+ */
+export function renamedDeclaration(obj: DeclaredObject, name: string, defaultDatabase = "default"): DeclaredObject {
+  const { tokens, node } = parsed(obj);
+  if (node.statement === "database") throw new Error(`${obj.key}: a database is not renamed this way`);
+  const ddl =
+    tokens
+      .slice(0, node.name.from)
+      .map((t) => t.text)
+      .join("") +
+    qualifiedIdent(obj.canonical.database ?? defaultDatabase, name) +
+    tokens
+      .slice(node.name.to)
+      .map((t) => t.text)
+      .join("");
+  const canonical = canonicalObject(ddl, defaultDatabase);
+  return { ...obj, ddl, canonical, key: `${canonical.database}.${canonical.name}` };
+}
+
+// ── tables ────────────────────────────────────────────────────────────
+
+/** A column's whole definition as declared: from its name to the comma or parenthesis that ends it. */
+function columnDefinition(tokens: Token[], node: TableNode, name: string): string {
+  const col = node.columns.find((c) => c.name === name);
+  if (!col) throw new Error(`no declared column ${name}`);
+  let depth = 0;
+  let i = col.nameSpan.from;
+  for (; i < tokens.length; i++) {
+    const t = tokens[i]!;
+    if (t.text === "(" || t.text === "[") depth++;
+    else if (t.text === ")" || t.text === "]") {
+      if (depth === 0) break;
+      depth--;
+    } else if (t.text === "," && depth === 0) break;
+  }
+  return tokens
+    .slice(col.nameSpan.from, i)
+    .filter((t) => t.kind !== "comment")
+    .map((t) => t.text)
+    .join("")
+    .trim();
+}
+
+function columnType(tokens: Token[], node: TableNode, name: string): string {
+  const col = node.columns.find((c) => c.name === name)!;
+  const type = text(tokens, col.type) ?? "";
+  return `${type}${col.nullable === true ? " NULL" : col.nullable === false ? " NOT NULL" : ""}`;
+}
+
+/** Where a column goes: after the declared column before it, or first. */
+function position(node: TableNode, name: string): string {
+  const i = node.columns.findIndex((c) => c.name === name);
+  return i <= 0 ? "FIRST" : `AFTER ${ident(node.columns[i - 1]!.name)}`;
+}
+
+/** `columns.<name>` or `columns.<name>.<part>`. */
+function columnField(field: string): { column: string; part?: string } | undefined {
+  const m = /^columns\.([^.]+)(?:\.(type|default|codec|ttl|comment))?$/.exec(field);
+  return m ? { column: m[1]!, ...(m[2] ? { part: m[2] } : {}) } : undefined;
+}
+
+/**
+ * The column order once the steps before it have run, and the moves that make
+ * it the declared order.
+ */
+function reorderSteps(t: string, tokens: Token[], node: TableNode, live: CanonicalObject | undefined, changes: readonly Change[]): Step[] {
+  if (!live) return [];
+  const renamed = new Map(changes.filter((c) => c.rule === "SQLCH212").map((c) => [c.before!, c.after!]));
+  const dropped = new Set(changes.filter((c) => c.rule === "SQLCH202").map((c) => columnField(c.field)!.column));
+  const declared = node.columns.map((c) => c.name);
+  const current = live.columns.map((c) => renamed.get(c.name) ?? c.name).filter((n) => !dropped.has(n));
+  // Added columns went in at their declared place.
+  for (const [i, name] of declared.entries()) {
+    if (current.includes(name)) continue;
+    const prev = i === 0 ? -1 : current.indexOf(declared[i - 1]!);
+    current.splice(prev + 1, 0, name);
+  }
+  const steps: Step[] = [];
+  for (const [i, name] of declared.entries()) {
+    const want = i === 0 ? undefined : declared[i - 1];
+    const at = current.indexOf(name);
+    const have = at <= 0 ? undefined : current[at - 1];
+    if (have === want) continue;
+    current.splice(at, 1);
+    current.splice(want === undefined ? 0 : current.indexOf(want) + 1, 0, name);
+    steps.push({ sql: `ALTER TABLE ${t} MODIFY COLUMN ${ident(name)} ${columnType(tokens, node, name)} ${want === undefined ? "FIRST" : `AFTER ${ident(want)}`}`, rewrite: false });
+  }
+  return steps;
+}
+
+function tableSteps(obj: DeclaredObject, changes: readonly Change[], live: CanonicalObject | undefined): Step[] {
+  const { tokens, node } = parsed(obj) as { tokens: Token[]; node: TableNode };
+  const t = objectIdent(obj);
+  const alter = (clause: string, rewrite = false): Step => ({ sql: `ALTER TABLE ${t} ${clause}`, rewrite });
+  const steps: Step[] = [];
+  const of = (rule: string) => changes.filter((c) => c.rule === rule);
+
+  for (const c of of("SQLCH212")) steps.push(alter(`RENAME COLUMN ${ident(c.before!)} TO ${ident(c.after!)}`));
+
+  // Added columns, in declared order, each at its declared place. Appending
+  // new columns to the sorting key has to happen in the same ALTER as adding
+  // them (SQLCH216), so then they go together.
+  const added = of("SQLCH201")
+    .map((c) => columnField(c.field)!.column)
+    .sort((a, b) => node.columns.findIndex((c) => c.name === a) - node.columns.findIndex((c) => c.name === b));
+  const adds = added.map((name) => `ADD COLUMN ${columnDefinition(tokens, node, name)} ${position(node, name)}`);
+  const sortKey = of("SQLCH216")[0];
+  if (sortKey) steps.push(alter([...adds, `MODIFY ORDER BY ${text(tokens, node.orderBy)}`].join(", ")));
+  else for (const a of adds) steps.push(alter(a));
+
+  for (const c of of("SQLCH202")) steps.push(alter(`DROP COLUMN ${ident(columnField(c.field)!.column)}`));
+
+  for (const c of changes) {
+    const f = columnField(c.field);
+    if (!f?.part) continue;
+    const col = node.columns.find((x) => x.name === f.column)!;
+    const name = ident(f.column);
+    switch (c.rule) {
+      case "SQLCH210":
+        steps.push(alter(`MODIFY COLUMN ${name} ${columnType(tokens, node, f.column)}`, true));
+        break;
+      case "SQLCH207":
+        if (col.default) steps.push(alter(`MODIFY COLUMN ${name} ${col.default.kind}${col.default.expr ? ` ${text(tokens, col.default.expr)}` : ""}`));
+        else steps.push(alter(`MODIFY COLUMN ${name} REMOVE ${(c.before ?? "DEFAULT").split(" ")[0]}`));
+        break;
+      case "SQLCH208":
+        steps.push(alter(col.codec ? `MODIFY COLUMN ${name} CODEC(${text(tokens, col.codec)})` : `MODIFY COLUMN ${name} REMOVE CODEC`));
+        break;
+      case "SQLCH205":
+        steps.push(alter(col.ttl ? `MODIFY COLUMN ${name} TTL ${text(tokens, col.ttl)}` : `MODIFY COLUMN ${name} REMOVE TTL`, true));
+        break;
+      case "SQLCH203":
+        steps.push(alter(`COMMENT COLUMN ${name} ${sqlString(obj.canonical.columns.find((x) => x.name === f.column)?.comment ?? "")}`));
+        break;
+    }
+  }
+
+  for (const c of of("SQLCH204")) {
+    const name = c.field.slice("indexes.".length);
+    if (c.before !== undefined) steps.push(alter(`DROP INDEX ${ident(name)}`));
+    const ix = node.indexes.find((x) => x.name === name);
+    if (ix) {
+      steps.push(
+        alter(`ADD INDEX ${ident(name)} ${text(tokens, ix.expr)} TYPE ${text(tokens, ix.type)}${ix.granularity ? ` GRANULARITY ${text(tokens, ix.granularity)}` : ""}`),
+      );
+    }
+  }
+  for (const c of of("SQLCH214")) {
+    const name = c.field.slice("projections.".length);
+    if (c.before !== undefined) steps.push(alter(`DROP PROJECTION ${ident(name)}`));
+    const p = node.projections.find((x) => x.name === name);
+    if (p) steps.push(alter(`ADD PROJECTION ${ident(name)} (${text(tokens, p.body)})`));
+  }
+  for (const c of of("SQLCH215")) {
+    const name = c.field.slice("constraints.".length);
+    if (c.before !== undefined) steps.push(alter(`DROP CONSTRAINT ${ident(name)}`));
+    const k = node.constraints.find((x) => x.name === name);
+    if (k) steps.push(alter(`ADD CONSTRAINT ${ident(name)} ${k.kind} ${text(tokens, k.expr)}`));
+  }
+
+  for (const c of of("SQLCH205").filter((x) => x.field === "ttl")) {
+    steps.push(alter(node.ttl ? `MODIFY TTL ${text(tokens, node.ttl)}` : "REMOVE TTL", true));
+  }
+  for (const c of of("SQLCH217")) {
+    void c;
+    steps.push(alter(node.sampleBy ? `MODIFY SAMPLE BY ${text(tokens, node.sampleBy)}` : "REMOVE SAMPLE BY"));
+  }
+  for (const c of of("SQLCH206")) {
+    const key = c.field.slice("settings.".length);
+    const s = node.settings?.find((x) => x.key === key);
+    // A setting declared at its default compares as absent: set it as written.
+    steps.push(alter(s ? `MODIFY SETTING ${key} = ${text(tokens, s.value)}` : `RESET SETTING ${key}`));
+  }
+
+  if (of("SQLCH209").length > 0) steps.push(...reorderSteps(t, tokens, node, live, changes));
+  return steps;
+}
+
+function viewSteps(obj: DeclaredObject, changes: readonly Change[], marker: OwnershipMarker | undefined): Step[] {
+  const { tokens, node } = parsed(obj) as { tokens: Token[]; node: ViewNode };
+  const t = objectIdent(obj);
+  const steps: Step[] = [];
+  if (!node.materialized) {
+    if (changes.some((c) => c.rule === "SQLCH240")) steps.push({ sql: createStatement(obj, marker, { orReplace: true }), rewrite: false });
+    return steps;
+  }
+  if (changes.some((c) => c.rule === "SQLCH241")) steps.push({ sql: `ALTER TABLE ${t} MODIFY QUERY ${text(tokens, node.select)}`, rewrite: false });
+  if (changes.some((c) => c.rule === "SQLCH244") && node.refresh) steps.push({ sql: `ALTER TABLE ${t} MODIFY REFRESH ${text(tokens, node.refresh)}`, rewrite: false });
+  return steps;
+}
+
+/**
+ * The statements that make an existing object match its declaration, for the
+ * metadata and background-rewrite changes the classifier reported for it.
+ * Rebuild-class changes are not handled here: the caller refuses them.
+ * `live` is the object's current definition, which a column reorder needs.
+ *
+ * The object's own comment, and chant's marker in it, are not set here
+ * (`commentStatement`), except where a plain view is replaced whole.
+ */
+export function alterSteps(obj: DeclaredObject, changes: readonly Change[], opts: { live?: CanonicalObject; marker?: OwnershipMarker } = {}): Step[] {
+  const steps: Step[] = [];
+  for (const c of changes.filter((x) => x.rule === "SQLCH231")) steps.push({ sql: `RENAME DATABASE ${ident(c.before!)} TO ${ident(c.after!)}`, rewrite: false });
+  for (const c of changes.filter((x) => x.rule === "SQLCH230")) {
+    const from = splitQualified(c.before!);
+    const to = splitQualified(c.after!);
+    steps.push({ sql: `RENAME TABLE ${qualifiedIdent(from.database, from.name)} TO ${qualifiedIdent(to.database, to.name)}`, rewrite: false });
+  }
+  if (obj.type === CLICKHOUSE_ENTITY_TYPES.table) steps.push(...tableSteps(obj, changes, opts.live));
+  else if (obj.type === CLICKHOUSE_ENTITY_TYPES.view || obj.type === CLICKHOUSE_ENTITY_TYPES.materializedView) steps.push(...viewSteps(obj, changes, opts.marker));
+  return steps;
+}
+
+/** Whether the steps for these changes already set the object's comment (a plain view replaced whole). */
+export function stepsSetComment(obj: DeclaredObject, changes: readonly Change[]): boolean {
+  return obj.type === CLICKHOUSE_ENTITY_TYPES.view && changes.some((c) => c.rule === "SQLCH240");
+}

package/src/clickhouse/catalog-types.ts

@@ -0,0 +1,84 @@
+/**
+ * The shapes of the generated ClickHouse catalog tables
+ * (`src/generated/clickhouse.ts`). The data is generated; these types are
+ * not, so the generated module stays data and a reader of it has one place to
+ * look for what a field means.
+ */
+
+import type { ArgumentKind, ArgumentOverlay } from "./overlays/kinds";
+import type { CodecOverlay } from "./overlays/codecs";
+import type { EngineCapabilities } from "../spec/catalog";
+
+export type { ArgumentKind, ArgumentOverlay, EngineCapabilities };
+
+/** One engine or skip-index argument: its place in the syntax line, and its kind where the overlay knows it. */
+export interface ArgumentSpec {
+  name: string;
+  position: number;
+  optional: boolean;
+  repeated: boolean;
+  /** Written `name = value`. */
+  named: boolean;
+  /** `"unknown"` for an argument no overlay types; a quoted placeholder is always `string`. */
+  kind: ArgumentKind | "unknown";
+  values?: readonly string[];
+  range?: readonly [number, number];
+  note?: string;
+}
+
+export interface TableEngineSpec {
+  capabilities: EngineCapabilities;
+  /** The server's own usage line. */
+  syntax: string;
+  /**
+   * The engine's arguments, or `undefined` when the syntax line is not an
+   * `ENGINE = Name(...)` line the generator can read (`View`,
+   * `MaterializedView`, `WindowView`, `Loop`).
+   */
+  args?: readonly ArgumentSpec[];
+  /** True when an overlay types every argument. */
+  typed: boolean;
+  /** A MergeTree family member, Replicated or not. */
+  mergeTree: boolean;
+  /** For a `Replicated*` engine, the engine it replicates. */
+  replicates?: string;
+  summary: string;
+}
+
+export interface DatabaseEngineSpec {
+  syntax: string;
+  summary: string;
+}
+
+export interface TypeFamilySpec {
+  /** The canonical family: itself, or what an alias stands for. */
+  canonical: string;
+  caseInsensitive: boolean;
+}
+
+export interface CodecSpec {
+  compression: boolean;
+  generic: boolean;
+  encryption: boolean;
+  timeseries: boolean;
+  experimental: boolean;
+  role: CodecOverlay["role"];
+  parameters: CodecOverlay["parameters"];
+  summary: string;
+}
+
+export interface SkipIndexSpec {
+  syntax: string;
+  args?: readonly ArgumentSpec[];
+  summary: string;
+}
+
+export interface SettingSpec {
+  /** The server's setting type (`UInt64`, `Bool`, `MergeSelectorAlgorithm`). */
+  type: string;
+  default: string;
+  tier: string;
+  obsolete: boolean;
+  /** The server's `readonly` flag for the setting. */
+  readonly: boolean;
+}

package/src/clickhouse/container.ts

@@ -0,0 +1,176 @@
+/**
+ * A throwaway `clickhouse-server` in a container: started on a random loopback
+ * port under a unique name, and always removed (the shared core's
+ * `../core/container.ts`, ready when it answers `/ping`).
+ *
+ * Generation uses it on a pin move to read the pinned server's catalog. The
+ * live tests use the same helper so every container chant starts is started
+ * and cleaned up one way. A cluster of replicas with embedded Keeper is
+ * ClickHouse's own.
+ */
+
+import { execFile } from "node:child_process";
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { clickhousePing, clickhouseQuery, type ClickHouseEndpoint } from "./http";
+import { publishedPort, startScratchContainer, uniqueContainerName } from "../core/container";
+
+export { dockerAvailable } from "../core/container";
+
+const exec = promisify(execFile);
+
+export interface ScratchServer {
+  endpoint: ClickHouseEndpoint;
+  /** The container's name, for a log line. */
+  name: string;
+  /** Remove the container. Safe to call twice. */
+  stop(): Promise<void>;
+}
+
+/**
+ * Start `image` and wait until it answers `/ping`. Pulls the image when it is
+ * not present, which is the one network step here.
+ */
+export async function startScratchServer(
+  image: string,
+  options: { namePrefix?: string; readyTimeoutMs?: number } = {},
+): Promise<ScratchServer> {
+  const endpointOf = (port: string): ClickHouseEndpoint => ({ url: `http://127.0.0.1:${port}` });
+  const c = await startScratchContainer({
+    image,
+    namePrefix: options.namePrefix ?? "chant-sql",
+    containerPort: 8123,
+    env: { CLICKHOUSE_SKIP_USER_SETUP: "1" },
+    ready: (port) => clickhousePing(endpointOf(port)),
+    readyTimeoutMs: options.readyTimeoutMs ?? 60_000,
+    notReady: "did not answer /ping",
+  });
+  return { endpoint: endpointOf(c.port), name: c.name, stop: c.stop };
+}
+
+export interface ScratchCluster {
+  /** One endpoint per replica, in replica order (`r1`, `r2`, ...). */
+  replicas: ClickHouseEndpoint[];
+  /** The containers' common name prefix, for a log line. */
+  name: string;
+  /** Remove the containers and their network. Safe to call twice. */
+  stop(): Promise<void>;
+  /**
+   * Stop one replica's container (`docker stop`, by index into `replicas`),
+   * keeping its data. The first replica runs Keeper, so stopping it stops
+   * the cluster's Keeper too.
+   */
+  stopReplica(index: number): Promise<void>;
+  /**
+   * Start a stopped replica again and wait until it answers and reaches
+   * Keeper. Docker gives it a new host port, so `replicas[index]` is
+   * replaced with its new endpoint, which is also returned.
+   */
+  startReplica(index: number): Promise<ClickHouseEndpoint>;
+}
+
+/**
+ * Start `replicas` servers of `image` as one shard of replicas, on their own
+ * Docker network, and wait until each answers and reaches Keeper.
+ *
+ * Keeper is the server's embedded one (`keeper_server`), run by the first
+ * replica, so the pinned server image and its digest pin Keeper too. Each
+ * replica gets the macros `{shard}` = `s1` and `{replica}` = `r<n>`, which
+ * a `Replicated` database's arguments name. Configuration is copied into each
+ * container before it starts, with no bind mount.
+ */
+export async function startScratchCluster(
+  image: string,
+  options: { replicas?: number; namePrefix?: string; readyTimeoutMs?: number } = {},
+): Promise<ScratchCluster> {
+  const count = options.replicas ?? 2;
+  const name = uniqueContainerName(options.namePrefix ?? "chant-sql-cluster");
+  const network = `${name}-net`;
+  const nodes = Array.from({ length: count }, (_, i) => `${name}-r${i + 1}`);
+  const dir = mkdtempSync(join(tmpdir(), "chant-sql-cluster-"));
+  let removed = false;
+  const stop = async (): Promise<void> => {
+    if (removed) return;
+    removed = true;
+    await exec("docker", ["rm", "-f", ...nodes]).catch(() => undefined);
+    await exec("docker", ["network", "rm", network]).catch(() => undefined);
+    rmSync(dir, { recursive: true, force: true });
+  };
+
+  const keeper = nodes[0]!;
+  const config = (node: string, i: number) => `<clickhouse>
+${
+  i === 0
+    ? `  <keeper_server>
+    <tcp_port>9181</tcp_port>
+    <server_id>1</server_id>
+    <log_storage_path>/var/lib/clickhouse/coordination/log</log_storage_path>
+    <snapshot_storage_path>/var/lib/clickhouse/coordination/snapshots</snapshot_storage_path>
+    <raft_configuration><server><id>1</id><hostname>${keeper}</hostname><port>9234</port></server></raft_configuration>
+  </keeper_server>
+`
+    : ""
+}  <zookeeper><node><host>${keeper}</host><port>9181</port></node></zookeeper>
+  <macros><shard>s1</shard><replica>r${i + 1}</replica></macros>
+  <interserver_http_host>${node}</interserver_http_host>
+</clickhouse>
+`;
+
+  const hostEndpoint = async (node: string): Promise<ClickHouseEndpoint> => ({ url: `http://127.0.0.1:${await publishedPort(node, 8123)}` });
+  const waitReady = async (node: string, endpoint: ClickHouseEndpoint, deadline: number): Promise<void> => {
+    for (;;) {
+      const ready = (await clickhousePing(endpoint)) && (await clickhouseQuery(endpoint, "SELECT count() FROM system.zookeeper WHERE path = '/'").then(() => true, () => false));
+      if (ready) return;
+      if (Date.now() > deadline) throw new Error(`${node} did not answer and reach Keeper within the timeout`);
+      await new Promise((r) => setTimeout(r, 500));
+    }
+  };
+
+  try {
+    await exec("docker", ["network", "create", network]);
+    const endpoints = await Promise.all(
+      nodes.map(async (node, i) => {
+        await exec(
+          "docker",
+          ["create", "--name", node, "--hostname", node, "--network", network, "-p", "127.0.0.1::8123", "-e", "CLICKHOUSE_SKIP_USER_SETUP=1", image],
+          { timeout: 600_000 },
+        );
+        const file = join(dir, `${node}.xml`);
+        writeFileSync(file, config(node, i));
+        // Readable by the server's own user once copied in, whatever the umask made it.
+        chmodSync(file, 0o644);
+        await exec("docker", ["cp", file, `${node}:/etc/clickhouse-server/config.d/chant-cluster.xml`]);
+        await exec("docker", ["start", node]);
+        return hostEndpoint(node);
+      }),
+    );
+
+    const deadline = Date.now() + (options.readyTimeoutMs ?? 90_000);
+    for (const [i, endpoint] of endpoints.entries()) await waitReady(nodes[i]!, endpoint, deadline);
+    const node = (index: number): string => {
+      const n = nodes[index];
+      if (!n) throw new Error(`no replica ${index} in ${name}`);
+      return n;
+    };
+    return {
+      replicas: endpoints,
+      name,
+      stop,
+      async stopReplica(index) {
+        await exec("docker", ["stop", node(index)], { timeout: 120_000 });
+      },
+      async startReplica(index) {
+        await exec("docker", ["start", node(index)]);
+        const endpoint = await hostEndpoint(node(index));
+        await waitReady(node(index), endpoint, Date.now() + (options.readyTimeoutMs ?? 90_000));
+        endpoints[index] = endpoint;
+        return endpoint;
+      },
+    };
+  } catch (err) {
+    await stop();
+    throw err;
+  }
+}