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

package/src/clickhouse/import/import.test.ts

@@ -0,0 +1,157 @@
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { ClickHouseSqlParser } from "./parser";
+import { ClickHouseGenerator } from "./generator";
+import { exportNames, objectsToIR, splitStatements, stripServerDefaults } from "./ir";
+import { exportResources } from "./live-export";
+import { fakeClickHouse, type FakeServer } from "../testing/fake-server";
+
+const SCHEMA = `
+CREATE DATABASE analytics ENGINE = Atomic;
+
+CREATE TABLE analytics.events
+(
+    \`user_id\` UUID,
+    \`kind\` LowCardinality(String),
+    \`my col\` String DEFAULT 'a\`b'
+)
+ENGINE = MergeTree
+ORDER BY (user_id, kind)
+SETTINGS index_granularity = 8192;
+
+CREATE MATERIALIZED VIEW analytics.counts TO analytics.daily
+(
+    \`kind\` LowCardinality(String),
+    \`n\` UInt64
+)
+AS SELECT kind, count() AS n
+FROM analytics.events
+GROUP BY kind;
+
+CREATE TABLE analytics.daily (kind LowCardinality(String), n UInt64) ENGINE = SummingMergeTree ORDER BY kind;
+`;
+
+describe("reading a file of statements", () => {
+  test("splits on top-level semicolons only", () => {
+    expect(splitStatements("CREATE TABLE a (s String DEFAULT ';') ENGINE = Log; ; CREATE DATABASE b")).toEqual([
+      "CREATE TABLE a (s String DEFAULT ';') ENGINE = Log",
+      "CREATE DATABASE b",
+    ]);
+  });
+
+  test("each statement becomes one resource of its type, a bad one a warning", () => {
+    const ir = new ClickHouseSqlParser().parse(`${SCHEMA}\nCREATE TABLE broken (a Strin g) ENGINE = Log;\nINSERT INTO t VALUES (1);`);
+    expect(ir.resources.map((r) => [r.logicalId, r.type])).toEqual([
+      ["analyticsDb", "ClickHouse::Database"],
+      ["events", "ClickHouse::Table"],
+      ["counts", "ClickHouse::MaterializedView"],
+      ["daily", "ClickHouse::Table"],
+    ]);
+    expect(ir.warnings).toHaveLength(2);
+  });
+});
+
+describe("export names", () => {
+  test("a database is suffixed Db, a shared table name takes its database, a reserved word is avoided", () => {
+    expect(
+      exportNames([
+        { type: "ClickHouse::Database", name: "default", ddl: "" },
+        { type: "ClickHouse::Table", database: "a", name: "events", ddl: "" },
+        { type: "ClickHouse::Table", database: "b", name: "events", ddl: "" },
+        { type: "ClickHouse::Table", database: "a", name: "class", ddl: "" },
+        { type: "ClickHouse::Table", database: "a", name: "00_raw", ddl: "" },
+      ]),
+    ).toEqual(["defaultDb", "aEvents", "bEvents", "classTable", "t00Raw"]);
+  });
+});
+
+describe("what the server adds is left out by default", () => {
+  test("a setting at its default goes, another stays", () => {
+    const out = stripServerDefaults(
+      "CREATE TABLE t\n(\n    `a` UInt8\n)\nENGINE = MergeTree\nORDER BY a\nSETTINGS index_granularity = 8192, min_bytes_for_wide_part = 0",
+    );
+    expect(out).toContain("SETTINGS min_bytes_for_wide_part = 0");
+    expect(out).not.toContain("index_granularity");
+  });
+
+  test("a view's inferred column list goes", () => {
+    const out = stripServerDefaults("CREATE VIEW v\n(\n    `id` UInt64\n)\nAS SELECT id\nFROM t");
+    expect(out).toBe("CREATE VIEW v\nAS SELECT id\nFROM t");
+  });
+});
+
+describe("generating declarations", () => {
+  const ir = new ClickHouseSqlParser().parse(SCHEMA);
+  const [file] = new ClickHouseGenerator().generate(ir);
+
+  test("one schema.ts, references interpolated, each declaration after what it references", () => {
+    expect(file!.path).toBe("schema.ts");
+    const src = file!.content;
+    expect(src).toContain('import { database, table, view } from "@intentius/chant-lexicon-sql/clickhouse";');
+    expect(src).toContain("CREATE TABLE ${analyticsDb}.events");
+    expect(src).toContain("TO ${daily}");
+    expect(src).toContain("FROM ${events}");
+    const order = [...src.matchAll(/export const (\w+)/g)].map((m) => m[1]);
+    expect(order).toEqual(["analyticsDb", "events", "daily", "counts"]);
+  });
+
+  test("identifiers lose their backquotes, and one that needs quoting is double-quoted", () => {
+    expect(file!.content).toContain("user_id UUID");
+    expect(file!.content).toContain('"my col" String');
+    expect(file!.content).toContain("DEFAULT 'a\\`b'");
+  });
+});
+
+describe("live export", () => {
+  let server: FakeServer;
+  beforeAll(async () => {
+    server = await fakeClickHouse([
+      { name: "default", engine: "Atomic", statement: "CREATE DATABASE default\nENGINE = Atomic" },
+      { name: "analytics", engine: "Atomic", statement: "CREATE DATABASE analytics\nENGINE = Atomic" },
+      {
+        database: "analytics",
+        name: "events",
+        engine: "MergeTree",
+        statement:
+          "CREATE TABLE analytics.events\n(\n    `id` UInt64\n)\nENGINE = MergeTree\nORDER BY id\nSETTINGS index_granularity = 8192\nCOMMENT 'Raw events [chant managed-by=chant stack=shop]'",
+        comment: "Raw events [chant managed-by=chant stack=shop]",
+      },
+    ]);
+  });
+  afterAll(() => server.close());
+
+  const run = (extra: Record<string, unknown> = {}) =>
+    exportResources({ environment: "x", config: {}, env: { CLICKHOUSE_URL: server.url }, ...extra });
+
+  test("exports every object but the default database, defaults stripped", async () => {
+    const ir = await run();
+    expect(ir.resources.map((r) => r.logicalId)).toEqual(["analyticsDb", "events"]);
+    expect(String(ir.resources[1]!.properties.ddl)).not.toContain("index_granularity");
+  });
+
+  test("verbatim keeps the statement as the server printed it", async () => {
+    const ir = await run({ verbatim: true });
+    expect(String(ir.resources[1]!.properties.ddl)).toContain("index_granularity = 8192");
+  });
+
+  test("a selector narrows by type and name", async () => {
+    expect((await run({ selector: { name: "analytics.events" } })).resources.map((r) => r.logicalId)).toEqual(["events"]);
+    expect((await run({ selector: { type: "ClickHouse::Database" } })).resources.map((r) => r.logicalId)).toEqual(["analyticsDb"]);
+  });
+
+  test("owned keeps the objects carrying chant's marker (#3208)", async () => {
+    const ir = await run({ owned: true });
+    expect(ir.resources.map((r) => r.logicalId)).toEqual(["events"]);
+  });
+
+  test("the ownership marker is never written into a declaration (#3208)", async () => {
+    const ddl = String((await run()).resources[1]!.properties.ddl);
+    expect(ddl).toContain("COMMENT 'Raw events'");
+    expect(ddl).not.toContain("[chant");
+  });
+
+  test("the IR builds back through the generator", async () => {
+    const ir = await run();
+    expect(objectsToIR([]).resources).toEqual([]);
+    expect(new ClickHouseGenerator().generate(ir)[0]!.content).toContain("CREATE TABLE ${analyticsDb}.events");
+  });
+});

package/src/clickhouse/import/ir.ts

@@ -0,0 +1,171 @@
+/**
+ * ClickHouse DDL into the import IR, and back out as `database`, `table` and
+ * `view` declarations.
+ *
+ * `chant import --from <env>` reads each object's `SHOW CREATE` and `chant
+ * import schema.sql` reads a file of CREATE statements; both arrive here as
+ * statements. The generated declaration is the statement itself, the
+ * server's canonical form when it came from a server (#3046 question 5), with
+ * two changes:
+ *
+ * - a qualified name of another imported object becomes a reference to its
+ *   export (`FROM analytics.events` is `FROM ${events}`), and the database
+ *   part of an object's own name becomes a reference to the database's export,
+ *   so dependency order survives the import;
+ * - a backquoted identifier that needs no quoting is written bare, and one that
+ *   does is double-quoted, so the template has no backquotes to escape.
+ *
+ * Columns written by name inside a view's SELECT stay text: which table a
+ * bare name belongs to is the server's to resolve, and a guess would be
+ * wrong lineage. An imported view therefore records its reads, not its column
+ * lineage, until its column references are written as `${t.columns.c}`.
+ */
+
+import type { ResourceIR, TemplateIR } from "@intentius/chant/import/parser";
+import { isTrivia, tokenizeText, untokenize, type Token } from "../tokens";
+import { parseCreate, unquote, type CreateNode, type Span } from "../parser";
+import { CLICKHOUSE_ENTITY_TYPES, type ClickHouseEntityType } from "../entities";
+import { MERGE_TREE_SETTINGS } from "../../generated/clickhouse";
+
+export interface ImportedObject {
+  type: ClickHouseEntityType;
+  database?: string;
+  name: string;
+  /** The CREATE statement. */
+  ddl: string;
+}
+
+const JS_RESERVED = new Set(
+  "break case catch class const continue debugger default delete do else enum export extends false finally for function if import in instanceof new null return super switch this throw true try typeof var void while with yield let static implements interface package private protected public await".split(
+    " ",
+  ),
+);
+
+function camel(name: string): string {
+  const words = name.split(/[^A-Za-z0-9]+/).filter(Boolean);
+  if (words.length === 0) return "object";
+  const s = words.map((w, i) => (i === 0 ? w[0]!.toLowerCase() + w.slice(1) : w[0]!.toUpperCase() + w.slice(1))).join("");
+  return /^[0-9]/.test(s) ? `t${s}` : s;
+}
+
+/**
+ * Export names for a set of objects. A table or view is its name in camel
+ * case, prefixed with its database when two databases share a name; a
+ * database is its name with `Db` after it, so `analytics` the database and
+ * `analytics` a table do not collide.
+ */
+export function exportNames(objects: readonly ImportedObject[]): string[] {
+  const relations = objects.filter((o) => o.type !== CLICKHOUSE_ENTITY_TYPES.database);
+  const count = new Map<string, number>();
+  for (const o of relations) count.set(o.name, (count.get(o.name) ?? 0) + 1);
+  const used = new Set<string>();
+  return objects.map((o) => {
+    let base =
+      o.type === CLICKHOUSE_ENTITY_TYPES.database
+        ? `${camel(o.name)}Db`
+        : (count.get(o.name) ?? 0) > 1 && o.database
+          ? camel(`${o.database}_${o.name}`)
+          : camel(o.name);
+    if (JS_RESERVED.has(base)) base = `${base}Table`;
+    let name = base;
+    for (let i = 2; used.has(name); i++) name = `${base}${i}`;
+    used.add(name);
+    return name;
+  });
+}
+
+/** Split a file of statements on top-level `;`. */
+export function splitStatements(text: string): string[] {
+  const out: string[] = [];
+  let current: Token[] = [];
+  const flush = () => {
+    const stmt = current.map((t) => t.text).join("").trim();
+    if (current.some((t) => !isTrivia(t))) out.push(stmt);
+    current = [];
+  };
+  for (const t of tokenizeText(text, 0)) {
+    if (t.kind === "punct" && t.text === ";") flush();
+    else current.push(t);
+  }
+  flush();
+  return out;
+}
+
+const statementType = (node: CreateNode): ClickHouseEntityType =>
+  node.statement === "database"
+    ? CLICKHOUSE_ENTITY_TYPES.database
+    : node.statement === "table"
+      ? CLICKHOUSE_ENTITY_TYPES.table
+      : node.materialized
+        ? CLICKHOUSE_ENTITY_TYPES.materializedView
+        : CLICKHOUSE_ENTITY_TYPES.view;
+
+function nameOf(tokens: Token[], span: Span): { database?: string; name: string } {
+  const parts = tokens
+    .slice(span.from, span.to)
+    .filter((t) => !isTrivia(t) && !(t.kind === "punct" && t.text === "."))
+    .map((t) => unquote(t.text));
+  return parts.length >= 2 ? { database: parts[parts.length - 2], name: parts[parts.length - 1]! } : { name: parts[0] ?? "" };
+}
+
+/** Read a statement's kind and name. Throws the parser's error when it does not parse. */
+export function describeStatement(ddl: string): ImportedObject {
+  const tokens = tokenizeText(ddl, 0);
+  const node = parseCreate(tokens);
+  return { type: statementType(node), ...nameOf(tokens, node.name), ddl };
+}
+
+/**
+ * Leave out what the server adds and the declaration would not say: settings
+ * at the pinned server's default (`index_granularity = 8192`), and a view's
+ * column list, which the server infers from the SELECT. A server re-adds both
+ * on create, so the stripped statement creates the same object.
+ */
+export function stripServerDefaults(ddl: string): string {
+  const tokens = tokenizeText(ddl, 0);
+  let node: CreateNode;
+  try {
+    node = parseCreate(tokens);
+  } catch {
+    return ddl;
+  }
+  const edits: Array<{ span: Span; text: string }> = [];
+  if (node.statement !== "database" && node.settings && node.settingsClause) {
+    const text = (s: Span) => tokens.slice(s.from, s.to).map((t) => t.text).join("").trim();
+    const kept = node.settings.filter((s) => {
+      const def = (MERGE_TREE_SETTINGS as Record<string, { default: string } | undefined>)[s.key];
+      return !def || text(s.value).replace(/^'|'$/g, "") !== def.default;
+    });
+    if (kept.length !== node.settings.length) {
+      edits.push({
+        span: node.settingsClause,
+        text: kept.length === 0 ? "" : `SETTINGS ${kept.map((s) => `${s.key} = ${text(s.value)}`).join(", ")}`,
+      });
+    }
+  }
+  if (node.statement === "view" && node.columnsSpan) edits.push({ span: node.columnsSpan, text: "" });
+  if (edits.length === 0) return ddl;
+  edits.sort((a, b) => b.span.from - a.span.from);
+  const out = [...tokens];
+  for (const e of edits) {
+    out.splice(e.span.from, e.span.to - e.span.from, { kind: "ws", text: e.text, part: 0, start: 0, end: 0 });
+  }
+  return out
+    .map((t) => t.text)
+    .join("")
+    .split("\n")
+    .filter((line) => line.trim().length > 0)
+    .join("\n")
+    .replace(/[ \t]+$/gm, "");
+}
+
+/** The IR for a set of objects. */
+export function objectsToIR(objects: readonly ImportedObject[], warnings: string[] = []): TemplateIR {
+  const names = exportNames(objects);
+  const resources: ResourceIR[] = objects.map((o, i) => ({
+    logicalId: names[i]!,
+    type: o.type,
+    properties: { ...(o.database ? { database: o.database } : {}), name: o.name, ddl: o.ddl },
+  }));
+  return { resources, parameters: [], ...(warnings.length ? { warnings } : {}) };
+}

package/src/clickhouse/import/live-export.ts

@@ -0,0 +1,53 @@
+/**
+ * Live export: `chant import --from <env>` writes the server's schema as
+ * `database`, `table` and `view` declarations.
+ *
+ * Every object in the environment's databases is read with `SHOW CREATE`, the
+ * server's canonical form, which is the baseline #3046 question 5 asks for.
+ * By default what the server adds on its own is left out (settings at their
+ * default, a view's inferred column list), so the declaration says what an
+ * author would; `verbatim` keeps the statement as the server printed it.
+ *
+ * - `selector.type` is an entity type (`ClickHouse::Table`); `selector.name` is
+ *   an object name, `db.name` or `name`.
+ * - `owned` keeps the objects whose comment carries chant's ownership marker
+ *   (`../ownership.ts`), the trailer the applier stamps. The trailer itself is
+ *   never written into a declaration: `readLiveSchema` takes it off.
+ */
+
+import type { ExportedTemplate, ResourceSelector } from "@intentius/chant/lexicon";
+import { bindClickHouse, type BindOptions } from "../live/bind";
+import { readLiveSchema } from "../live/catalog";
+import { objectsToIR, stripServerDefaults, type ImportedObject } from "./ir";
+import { isChantManaged } from "../ownership";
+
+export interface ExportOptions extends Omit<BindOptions, "environment"> {
+  environment: string;
+  stack?: string;
+  region?: string;
+  selector?: ResourceSelector;
+  owned?: boolean;
+  verbatim?: boolean;
+}
+
+export async function exportResources(options: ExportOptions): Promise<ExportedTemplate> {
+  const target = await bindClickHouse(options);
+  const live = await readLiveSchema(target);
+  const selected = live.filter((o) => {
+    if (options.owned && !isChantManaged(o.comment)) return false;
+    if (options.selector?.type && o.type !== options.selector.type) return false;
+    const name = options.selector?.name;
+    if (name !== undefined && name !== o.name && name !== `${o.database}.${o.name}`) return false;
+    return true;
+  });
+  const objects: ImportedObject[] = selected
+    // The `default` database exists on every server; declaring it would make apply create what is there.
+    .filter((o) => !(o.type === "ClickHouse::Database" && o.name === "default"))
+    .map((o) => ({
+      type: o.type,
+      ...(o.database ? { database: o.database } : {}),
+      name: o.name,
+      ddl: options.verbatim ? o.statement : stripServerDefaults(o.statement),
+    }));
+  return objectsToIR(objects) as ExportedTemplate;
+}

package/src/clickhouse/import/parser.ts

@@ -0,0 +1,27 @@
+/**
+ * `chant import schema.sql`: a file of ClickHouse CREATE statements into the
+ * import IR. Each statement must parse; one that does not is reported in the
+ * IR's warnings and left out, with the parser's message.
+ */
+
+import type { TemplateIR, TemplateParser } from "@intentius/chant/import/parser";
+import { describeStatement, objectsToIR, splitStatements, type ImportedObject } from "./ir";
+
+export class ClickHouseSqlParser implements TemplateParser {
+  parse(content: string): TemplateIR {
+    const objects: ImportedObject[] = [];
+    const warnings: string[] = [];
+    for (const stmt of splitStatements(content)) {
+      if (!/^\s*CREATE\b/i.test(stmt)) {
+        warnings.push(`not a CREATE statement, left out: ${stmt.split("\n")[0]!.slice(0, 80)}`);
+        continue;
+      }
+      try {
+        objects.push(describeStatement(stmt));
+      } catch (err) {
+        warnings.push(`does not parse, left out (${(err as Error).message}): ${stmt.split("\n")[0]!.slice(0, 80)}`);
+      }
+    }
+    return objectsToIR(objects, warnings);
+  }
+}

package/src/clickhouse/import/roundtrip.test.ts

@@ -0,0 +1,90 @@
+/**
+ * The import round trip, offline: a file of CREATE statements is imported as
+ * declarations, the declarations are built back into statements, and importing
+ * those gives the same declarations. Nothing the import writes is lost or
+ * reordered by the build.
+ *
+ * The same schema runs against two live servers in `../live/roundtrip.e2e.test.ts`
+ * (import, build, apply, catalog unchanged); this file is the part of that
+ * round trip that needs no Docker.
+ */
+
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { build } from "@intentius/chant/build";
+import type { SerializerResult } from "@intentius/chant/serializer";
+import { sqlPlugin } from "../../plugin";
+import { CLICKHOUSE_DDL_FILE, sqlSerializer } from "../../serializer";
+import { SCHEMA } from "../testing/roundtrip-schema";
+import { ClickHouseGenerator } from "./generator";
+import { splitStatements } from "./ir";
+import { ClickHouseSqlParser } from "./parser";
+
+// Inside the package, so the declarations resolve `@intentius/chant-lexicon-sql/clickhouse` as the e2e test does.
+const dir = join(import.meta.dirname, "..", "..", "..", `.roundtrip-offline-tmp-${process.pid}`);
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+const parser = new ClickHouseSqlParser();
+const generator = new ClickHouseGenerator();
+
+/** Whitespace folded: the build keeps an author's own line breaks and indent, and the import indents the text it writes. */
+const squash = (text: string) => text.replace(/\s+/g, " ").trim();
+
+/** A generated file as its export declarations, whitespace folded and sorted: the order follows dependencies. */
+const declarations = (content: string) => content.split(/^export const /m).slice(1).map(squash).sort();
+
+/** Declarations to the statements the build writes, in the order it wrote them. */
+async function buildStatements(name: string, source: string): Promise<string[]> {
+  const project = join(dir, name);
+  mkdirSync(join(project, "src"), { recursive: true });
+  writeFileSync(join(project, "chant.config.ts"), 'export default { lexicons: ["sql"] };\n');
+  writeFileSync(join(project, "src", "schema.ts"), source);
+  const result = await build(join(project, "src"), [sqlSerializer], undefined, {
+    fold: true,
+    intrinsics: sqlPlugin.intrinsics!(),
+    lexicons: ["sql"],
+  });
+  expect(result.errors).toEqual([]);
+  return splitStatements((result.outputs.get("sql") as SerializerResult).files![CLICKHOUSE_DDL_FILE]!);
+}
+
+describe("import, build, import again", () => {
+  const ir = parser.parse(SCHEMA.join(";\n"));
+  const [file] = generator.generate(ir);
+
+  test("every statement of the schema is imported", () => {
+    expect(ir.warnings ?? []).toEqual([]);
+    expect(ir.resources.map((r) => r.type)).toEqual([
+      "ClickHouse::Database",
+      "ClickHouse::Table",
+      "ClickHouse::Table",
+      "ClickHouse::Table",
+      "ClickHouse::MaterializedView",
+      "ClickHouse::View",
+      "ClickHouse::Table",
+    ]);
+    expect(file!.content).toContain("export const events = table`");
+  });
+
+  test("the declarations build back to one statement per object, dependencies first", async () => {
+    const statements = await buildStatements("first", file!.content);
+    expect(statements).toHaveLength(SCHEMA.length);
+    const at = (needle: string) => statements.findIndex((s) => s.includes(needle));
+    expect(at("CREATE DATABASE analytics")).toBeLessThan(at("analytics.events"));
+    expect(at("analytics.events")).toBeLessThan(at("daily_mv"));
+    expect(at("analytics.daily")).toBeLessThan(at("daily_mv"));
+  });
+
+  test("importing the built statements gives the same declarations", async () => {
+    const statements = await buildStatements("second", file!.content);
+    const again = generator.generate(parser.parse(statements.join(";\n")));
+    expect(declarations(again[0]!.content)).toEqual(declarations(file!.content));
+  });
+
+  test("a second build writes the same statements, in whatever order dependencies allow", async () => {
+    const first = await buildStatements("third", file!.content);
+    const second = await buildStatements("fourth", generator.generate(parser.parse(first.join(";\n")))[0]!.content);
+    expect(second.map(squash).sort()).toEqual(first.map(squash).sort());
+  });
+});

package/src/clickhouse/live/bind.ts

@@ -0,0 +1,126 @@
+/**
+ * Which ClickHouse server a chant environment reads: the config lookup and
+ * the binding, shared by observation and live export so both read the same
+ * server.
+ */
+
+import type { ChantConfig } from "@intentius/chant/config";
+import type { UnobservedReason } from "@intentius/chant/observation";
+import { ClickHouseQueryError, clickhouseQuery, type ClickHouseEndpoint } from "../http";
+
+export interface ClickHouseTarget {
+  endpoint: ClickHouseEndpoint;
+  /** Where the binding came from: `sql.profiles.prod` or `env CLICKHOUSE_URL`. */
+  source: string;
+  /** The databases in scope; undefined is every database but the server's own. */
+  databases?: string[];
+  defaultDatabase: string;
+}
+
+export interface UnresolvedTarget {
+  reason: "no-binding" | "no-credentials";
+  detail: string;
+}
+
+export const isUnresolvedTarget = (v: ClickHouseTarget | UnresolvedTarget): v is UnresolvedTarget => "reason" in v;
+
+/**
+ * The server an environment reads. Pure: `config` and `env` are passed in.
+ *
+ * 1. `sql.profiles.<environment>`. A profile naming a credential variable that
+ *    is not set is `no-credentials`: the profile said how to authenticate.
+ * 2. `CLICKHOUSE_URL`, with `CLICKHOUSE_USER` and `CLICKHOUSE_PASSWORD` when set.
+ * 3. Otherwise `no-binding`.
+ */
+export function resolveClickHouseTarget(input: {
+  environment?: string;
+  config?: Pick<ChantConfig, "sql">;
+  env?: Record<string, string | undefined>;
+}): ClickHouseTarget | UnresolvedTarget {
+  const env = input.env ?? process.env;
+  const profile = input.environment !== undefined ? input.config?.sql?.profiles?.[input.environment] : undefined;
+  if (profile) {
+    const source = `sql.profiles.${input.environment}`;
+    const endpoint: ClickHouseEndpoint = { url: profile.url.replace(/\/+$/, "") };
+    for (const key of ["user", "password"] as const) {
+      const ref = profile[key];
+      if (!ref) continue;
+      const value = env[ref.env];
+      if (value === undefined) return { reason: "no-credentials", detail: `${source}.${key} names ${ref.env}, which is not set` };
+      endpoint[key] = value;
+    }
+    return {
+      endpoint,
+      source,
+      ...(profile.databases ? { databases: profile.databases } : {}),
+      defaultDatabase: profile.defaultDatabase ?? "default",
+    };
+  }
+  const url = env.CLICKHOUSE_URL;
+  if (!url) {
+    const where = input.environment !== undefined ? `sql.profiles.${input.environment} is not declared and ` : "";
+    return { reason: "no-binding", detail: `${where}CLICKHOUSE_URL is not set, so there is no ClickHouse server to read` };
+  }
+  return {
+    endpoint: {
+      url: url.replace(/\/+$/, ""),
+      ...(env.CLICKHOUSE_USER !== undefined ? { user: env.CLICKHOUSE_USER } : {}),
+      ...(env.CLICKHOUSE_PASSWORD !== undefined ? { password: env.CLICKHOUSE_PASSWORD } : {}),
+    },
+    source: "env CLICKHOUSE_URL",
+    defaultDatabase: "default",
+  };
+}
+
+/** A target that could not be resolved. */
+export class ClickHouseBindingError extends Error {
+  constructor(readonly unresolved: UnresolvedTarget) {
+    super(unresolved.detail);
+    this.name = "ClickHouseBindingError";
+  }
+}
+
+export interface BindOptions {
+  environment?: string;
+  /** The project's config; loaded from `cwd` when omitted. */
+  config?: Pick<ChantConfig, "sql">;
+  cwd?: string;
+  env?: Record<string, string | undefined>;
+}
+
+async function loadConfig(cwd: string): Promise<Pick<ChantConfig, "sql"> | undefined> {
+  try {
+    const { loadChantConfig } = await import("@intentius/chant/config");
+    return (await loadChantConfig(cwd)).config;
+  } catch {
+    // No project config: the environment variables still bind.
+    return undefined;
+  }
+}
+
+/** Resolve the environment's server. Throws {@link ClickHouseBindingError} when there is none. */
+export async function bindClickHouse(options: BindOptions = {}): Promise<ClickHouseTarget> {
+  const config = options.config ?? (await loadConfig(options.cwd ?? process.cwd()));
+  const target = resolveClickHouseTarget({ environment: options.environment, config, env: options.env });
+  if (isUnresolvedTarget(target)) throw new ClickHouseBindingError(target);
+  return target;
+}
+
+/** What a failed bind or read means, in the observation vocabulary. */
+export function classifyClickHouseFailure(err: unknown): { reason: UnobservedReason; detail: string } {
+  if (err instanceof ClickHouseBindingError) return { reason: err.unresolved.reason, detail: err.unresolved.detail };
+  if (err instanceof ClickHouseQueryError) {
+    // 516 AUTHENTICATION_FAILED and 497 ACCESS_DENIED arrive as 401/403 or in the message.
+    if (err.status === 401 || err.status === 403 || /AUTHENTICATION_FAILED|ACCESS_DENIED|Code: 516|Code: 497/.test(err.serverMessage)) {
+      return { reason: "no-credentials", detail: `${err.message} (the server refused the credentials)` };
+    }
+    return { reason: "read-failed", detail: err.message };
+  }
+  return { reason: "read-failed", detail: err instanceof Error ? err.message.split("\n")[0]! : String(err) };
+}
+
+/** `SELECT version()` on the target. */
+export async function serverVersion(target: ClickHouseTarget): Promise<string> {
+  const [row] = await clickhouseQuery<{ v: string }>(target.endpoint, "SELECT version() AS v");
+  return row?.v ?? "";
+}