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

package/src/clickhouse/parser.ts

@@ -0,0 +1,459 @@
+/**
+ * A hand-written recursive-descent parser for the ClickHouse statements the
+ * dialect declares: `CREATE DATABASE`, `CREATE TABLE`, `CREATE VIEW` and
+ * `CREATE MATERIALIZED VIEW` (chant #3196).
+ *
+ * Statement structure is parsed; expressions are not. An expression (a
+ * default, a codec, a sort key, a TTL, a view's SELECT) is kept as a span of
+ * tokens: its source text, verbatim, and the interpolations inside it. That is
+ * what entities, references, dependency order and lineage need. Comparing
+ * `INTERVAL 1 DAY` with the server's `toIntervalDay(1)` is normalization's job,
+ * which asks the server.
+ *
+ * An interpolation (`ref` token) is accepted wherever a name, a type or an
+ * expression goes. At build time the tag has already spliced plain strings into
+ * the token list as SQL text, so a `ref` left here is an entity or a column
+ * reference. Lint parses the source with every interpolation still a `ref`,
+ * because it cannot know the values; accepting them keeps it from reporting an
+ * error the build would not have.
+ */
+
+import type { Token } from "./tokens";
+import { kw, SqlCursor, unquoteWith, type Span } from "../core/cursor";
+
+export type { Span } from "../core/cursor";
+
+export interface ColumnNode {
+  /** The name as written, unquoted. Empty when the name is an interpolation. */
+  name: string;
+  nameSpan: Span;
+  type?: Span;
+  /** `NULL` / `NOT NULL` after the type. */
+  nullable?: boolean;
+  default?: { kind: "DEFAULT" | "MATERIALIZED" | "ALIAS" | "EPHEMERAL"; expr?: Span };
+  comment?: Span;
+  codec?: Span;
+  ttl?: Span;
+  statistics?: Span;
+  settings?: Span;
+  /** `PRIMARY KEY` written on the column. */
+  primaryKey?: boolean;
+}
+
+export interface IndexNode {
+  name: string;
+  expr: Span;
+  type: Span;
+  granularity?: Span;
+}
+
+export interface ProjectionNode {
+  name: string;
+  body: Span;
+}
+
+export interface ConstraintNode {
+  name: string;
+  kind: "CHECK" | "ASSUME";
+  expr: Span;
+}
+
+export interface StorageNode {
+  engine?: { name: string; nameSpan: Span; args?: Span[]; span: Span };
+  orderBy?: Span;
+  primaryKey?: Span;
+  partitionBy?: Span;
+  sampleBy?: Span;
+  ttl?: Span;
+  settings?: Array<{ key: string; value: Span }>;
+  /** The whole `SETTINGS ...` clause, keyword included. */
+  settingsClause?: Span;
+}
+
+export interface DatabaseNode {
+  statement: "database";
+  ifNotExists: boolean;
+  name: Span;
+  onCluster?: Span;
+  engine?: { name: string; nameSpan: Span; args?: Span[]; span: Span };
+  settings?: Array<{ key: string; value: Span }>;
+  comment?: Span;
+}
+
+export interface TableNode extends StorageNode {
+  statement: "table";
+  orReplace: boolean;
+  ifNotExists: boolean;
+  name: Span;
+  onCluster?: Span;
+  columns: ColumnNode[];
+  indexes: IndexNode[];
+  projections: ProjectionNode[];
+  constraints: ConstraintNode[];
+  comment?: Span;
+}
+
+export interface ViewNode extends StorageNode {
+  statement: "view";
+  materialized: boolean;
+  orReplace: boolean;
+  ifNotExists: boolean;
+  name: Span;
+  onCluster?: Span;
+  refresh?: Span;
+  append: boolean;
+  to?: Span;
+  columns: ColumnNode[];
+  /** The parenthesised column list, parentheses included, when there is one. */
+  columnsSpan?: Span;
+  populate: boolean;
+  empty: boolean;
+  /** `DEFINER = ...` and `SQL SECURITY ...`, as written. */
+  security?: Span;
+  select: Span;
+  comment?: Span;
+}
+
+export type CreateNode = DatabaseNode | TableNode | ViewNode;
+
+/** A token that can stand where a name goes. */
+const isNameToken = (t: Token | undefined): boolean =>
+  t !== undefined &&
+  (t.kind === "ident" || t.kind === "qident" || t.kind === "ref" || (t.kind === "number" && /[A-Za-z_]/.test(t.text)));
+
+/** A name with its `` ` `` or `"` quotes taken off. */
+export const unquote = (text: string): string => unquoteWith(text, '`"');
+
+const countOf = (text: string, c: string): number => text.split(c).length - 1;
+
+const STORAGE_KEYWORDS = ["ENGINE", "ORDER", "PRIMARY", "PARTITION", "SAMPLE", "TTL", "SETTINGS", "COMMENT"];
+
+class Parser extends SqlCursor {
+  /** `ORDER`, `PARTITION`, `SAMPLE` and `GROUP` stop only before `BY`, `PRIMARY` only before `KEY`. */
+  protected override stopsAt(stop: readonly string[]): boolean {
+    if (!super.stopsAt(stop)) return false;
+    const word = this.peek()!.text.toUpperCase();
+    const two = ["ORDER", "PARTITION", "SAMPLE", "GROUP"].includes(word) ? kw(this.peek(1), "BY") : true;
+    const key = word === "PRIMARY" ? kw(this.peek(1), "KEY") : true;
+    return two && key;
+  }
+
+  /** Array and map literals: `[` and `]` arrive inside operator runs. */
+  protected override depthChange(t: Token): number {
+    if (t.kind === "op") return countOf(t.text, "[") + countOf(t.text, "{") - countOf(t.text, "]") - countOf(t.text, "}");
+    return super.depthChange(t);
+  }
+
+  /** One name token. */
+  private name(what = "a name"): { text: string; span: Span } {
+    const t = this.next();
+    if (!isNameToken(t)) this.fail(`expected ${what}`, t);
+    const i = this.idx(-1);
+    return { text: t.kind === "ref" ? "" : unquote(t.text), span: { from: i, to: i + 1, refs: t.kind === "ref" ? [t.part] : [] } };
+  }
+
+  /** A name, optionally `db.`-qualified. */
+  private qualifiedName(): Span {
+    const from = this.idx();
+    const refs: number[] = [];
+    const one = () => {
+      const t = this.next();
+      if (!isNameToken(t)) this.fail("expected a name", t);
+      if (t.kind === "ref") refs.push(t.part);
+    };
+    one();
+    while (this.isPunct(".")) {
+      this.p++;
+      one();
+    }
+    return this.span(from, refs);
+  }
+
+  /** `UInt64`, `Nullable(String)`, `DateTime64(3, 'UTC')`, `Tuple(a UInt8, b String)`. */
+  private typeSpan(): Span {
+    const from = this.idx();
+    const t = this.next();
+    if (t.kind !== "ident" && t.kind !== "ref") this.fail("expected a type", t);
+    // `DOUBLE PRECISION`, `CHAR VARYING`, `CHAR LARGE OBJECT`: the SQL-compatible multi-word aliases.
+    while (kw(this.peek(), "PRECISION", "VARYING", "UNSIGNED", "SIGNED", "LARGE", "OBJECT")) this.p++;
+    if (this.isPunct("(")) this.parenthesized();
+    // MySQL-compatible modifiers the server accepts and ignores, kept with the type as written.
+    for (;;) {
+      if (kw(this.peek(), "COLLATE") && isNameToken(this.peek(1))) this.p += 2;
+      else if (kw(this.peek(), "AUTO_INCREMENT", "UNSIGNED", "SIGNED")) this.p++;
+      else break;
+    }
+    return this.span(from, t.kind === "ref" ? [t.part] : []);
+  }
+
+  private column(typed: boolean): ColumnNode {
+    const { text, span } = this.name("a column name");
+    const col: ColumnNode = { name: text, nameSpan: span };
+    const STOP = ["COMMENT", "CODEC", "TTL", "STATISTICS", "SETTINGS", "PRIMARY"];
+    const at = this.peek();
+    const bare = at === undefined || (at.kind === "punct" && (at.text === "," || at.text === ")"));
+    if (!bare && !kw(at, "DEFAULT", "MATERIALIZED", "ALIAS", "EPHEMERAL", "NULL", "NOT", ...STOP)) {
+      col.type = this.typeSpan();
+    } else if (typed && bare) {
+      this.fail("expected a column type");
+    }
+    for (;;) {
+      if (this.accept("NULL")) col.nullable = true;
+      else if (kw(this.peek(), "NOT") && kw(this.peek(1), "NULL")) {
+        this.p += 2;
+        col.nullable = false;
+      } else if (kw(this.peek(), "DEFAULT", "MATERIALIZED", "ALIAS")) {
+        const kind = this.next().text.toUpperCase() as "DEFAULT" | "MATERIALIZED" | "ALIAS";
+        col.default = { kind, expr: this.expr(STOP) };
+      } else if (this.accept("EPHEMERAL")) {
+        const t = this.peek();
+        const hasExpr = t && !(t.kind === "punct" && (t.text === "," || t.text === ")")) && !kw(t, ...STOP);
+        col.default = { kind: "EPHEMERAL", expr: hasExpr ? this.expr(STOP) : undefined };
+      } else if (this.accept("COMMENT")) col.comment = this.expr(STOP);
+      else if (this.accept("CODEC")) col.codec = this.parenthesized();
+      else if (this.accept("STATISTICS")) col.statistics = this.parenthesized();
+      else if (this.accept("TTL")) col.ttl = this.expr(STOP);
+      else if (this.accept("SETTINGS")) col.settings = this.parenthesized();
+      else if (kw(this.peek(), "PRIMARY") && kw(this.peek(1), "KEY")) {
+        this.p += 2;
+        col.primaryKey = true;
+      } else break;
+    }
+    return col;
+  }
+
+  /** True when the element starting here is `INDEX name ... TYPE ...`, not a column named `index`. */
+  private looksLikeIndex(): boolean {
+    if (!kw(this.peek(), "INDEX") || !isNameToken(this.peek(1))) return false;
+    let depth = 0;
+    for (let n = 2; ; n++) {
+      const t = this.peek(n);
+      if (t === undefined) return false;
+      if (t.kind === "punct" && t.text === "(") depth++;
+      else if (t.kind === "punct" && t.text === ")") {
+        if (depth === 0) return false;
+        depth--;
+      } else if (depth === 0 && t.kind === "punct" && t.text === ",") return false;
+      else if (depth === 0 && kw(t, "TYPE")) return true;
+    }
+  }
+
+  private tableElements(node: Pick<TableNode, "columns" | "indexes" | "projections" | "constraints">, typed: boolean): void {
+    this.expectPunct("(");
+    for (;;) {
+      if (this.looksLikeIndex()) {
+        this.p++;
+        const name = this.name("an index name").text;
+        const expr = this.expr(["TYPE"]);
+        this.expect("TYPE");
+        const type = this.expr(["GRANULARITY"]);
+        const granularity = this.accept("GRANULARITY") ? this.expr() : undefined;
+        node.indexes.push({ name, expr, type, granularity });
+      } else if (kw(this.peek(), "PROJECTION") && isNameToken(this.peek(1)) && this.isPunct("(", 2)) {
+        this.p++;
+        const name = this.name("a projection name").text;
+        node.projections.push({ name, body: this.parenthesized() });
+      } else if (kw(this.peek(), "PROJECTION") && isNameToken(this.peek(1)) && kw(this.peek(2), "INDEX")) {
+        // `PROJECTION p INDEX expr TYPE basic`: a projection kept as an index.
+        this.p++;
+        const name = this.name("a projection name").text;
+        const from = this.idx();
+        this.p++;
+        const expr = this.expr(["TYPE"]);
+        this.expect("TYPE");
+        const type = this.expr();
+        node.projections.push({ name, body: { from, to: type.to, refs: [...expr.refs, ...type.refs] } });
+      } else if (kw(this.peek(), "CONSTRAINT") && isNameToken(this.peek(1)) && kw(this.peek(2), "CHECK", "ASSUME")) {
+        this.p++;
+        const name = this.name("a constraint name").text;
+        const kind = this.next().text.toUpperCase() as "CHECK" | "ASSUME";
+        node.constraints.push({ name, kind, expr: this.expr() });
+      } else if (kw(this.peek(), "PRIMARY") && kw(this.peek(1), "KEY")) {
+        // `PRIMARY KEY (a, b)` inside the column list.
+        this.p += 2;
+        (node as TableNode).primaryKey = this.expr();
+      } else {
+        node.columns.push(this.column(typed));
+      }
+      // A trailing comma before the closing parenthesis is accepted, as the server accepts it.
+      if (this.acceptPunct(",")) {
+        if (this.acceptPunct(")")) return;
+        continue;
+      }
+      this.expectPunct(")");
+      return;
+    }
+  }
+
+  private engine(): NonNullable<StorageNode["engine"]> {
+    const from = this.idx(-1);
+    this.acceptPunct("=");
+    const { text, span } = this.name("an engine name");
+    let args: Span[] | undefined;
+    if (this.acceptPunct("(")) {
+      args = [];
+      if (!this.acceptPunct(")")) {
+        for (;;) {
+          args.push(this.expr());
+          if (this.acceptPunct(",")) continue;
+          this.expectPunct(")");
+          break;
+        }
+      }
+    }
+    return { name: text, nameSpan: span, args, span: this.span(from, [...span.refs, ...(args?.flatMap((a) => a.refs) ?? [])]) };
+  }
+
+  private settingsList(stop: readonly string[]): Array<{ key: string; value: Span }> {
+    const out: Array<{ key: string; value: Span }> = [];
+    for (;;) {
+      const key = this.name("a setting name").text;
+      this.expectPunct("=");
+      out.push({ key, value: this.expr(stop) });
+      if (!this.acceptPunct(",")) return out;
+    }
+  }
+
+  /** ENGINE and the storage clauses, in any order, as ClickHouse accepts them. */
+  private storage(into: StorageNode, terminators: readonly string[]): void {
+    const STOP = [...STORAGE_KEYWORDS, ...terminators];
+    for (;;) {
+      if (this.accept("ENGINE")) into.engine = this.engine();
+      else if (kw(this.peek(), "ORDER") && kw(this.peek(1), "BY")) {
+        this.p += 2;
+        into.orderBy = this.expr(STOP, false);
+      } else if (kw(this.peek(), "PRIMARY") && kw(this.peek(1), "KEY")) {
+        this.p += 2;
+        into.primaryKey = this.expr(STOP, false);
+      } else if (kw(this.peek(), "PARTITION") && kw(this.peek(1), "BY")) {
+        this.p += 2;
+        into.partitionBy = this.expr(STOP, false);
+      } else if (kw(this.peek(), "SAMPLE") && kw(this.peek(1), "BY")) {
+        this.p += 2;
+        into.sampleBy = this.expr(STOP, false);
+      } else if (this.accept("TTL")) into.ttl = this.expr(STOP, false);
+      else if (kw(this.peek(), "SETTINGS")) {
+        const from = this.idx();
+        this.p++;
+        into.settings = this.settingsList(STOP);
+        into.settingsClause = this.span(from, into.settings.flatMap((s) => s.value.refs));
+      } else return;
+    }
+  }
+
+  parse(): CreateNode {
+    this.expect("CREATE");
+    let orReplace = false;
+    if (this.accept("OR")) {
+      this.expect("REPLACE");
+      orReplace = true;
+    }
+    if (this.accept("DATABASE")) return this.database();
+    if (this.accept("TABLE")) return this.table(orReplace);
+    const materialized = this.accept("MATERIALIZED");
+    if (this.accept("VIEW")) return this.view(orReplace, materialized);
+    return this.fail(materialized ? "expected VIEW" : "expected DATABASE, TABLE, VIEW or MATERIALIZED VIEW");
+  }
+
+  private ifNotExists(): boolean {
+    if (kw(this.peek(), "IF") && kw(this.peek(1), "NOT") && kw(this.peek(2), "EXISTS")) {
+      this.p += 3;
+      return true;
+    }
+    return false;
+  }
+
+  private onCluster(): Span | undefined {
+    if (kw(this.peek(), "ON") && kw(this.peek(1), "CLUSTER")) {
+      this.p += 2;
+      return this.qualifiedName();
+    }
+    return undefined;
+  }
+
+  /** A `UUID '...'` clause after the name, as `SHOW CREATE` can print it. Skipped. */
+  private uuid(): void {
+    if (kw(this.peek(), "UUID") && this.peek(1)?.kind === "string") this.p += 2;
+  }
+
+  private finish(what: string): void {
+    this.acceptPunct(";");
+    if (this.peek() !== undefined) this.fail(`unexpected token after the ${what}`);
+  }
+
+  private database(): DatabaseNode {
+    const node: DatabaseNode = { statement: "database", ifNotExists: this.ifNotExists(), name: this.qualifiedName() };
+    this.uuid();
+    node.onCluster = this.onCluster();
+    if (this.accept("ENGINE")) node.engine = this.engine();
+    if (this.accept("SETTINGS")) node.settings = this.settingsList(["COMMENT"]);
+    if (this.accept("COMMENT")) node.comment = this.expr();
+    this.finish("database definition");
+    return node;
+  }
+
+  private table(orReplace: boolean): TableNode {
+    const ifNotExists = this.ifNotExists();
+    const name = this.qualifiedName();
+    this.uuid();
+    const node: TableNode = {
+      statement: "table",
+      orReplace,
+      ifNotExists,
+      name,
+      onCluster: this.onCluster(),
+      columns: [],
+      indexes: [],
+      projections: [],
+      constraints: [],
+    };
+    if (!this.isPunct("(")) this.fail("expected the column list (CREATE TABLE ... AS is not declared here)");
+    this.tableElements(node, true);
+    this.storage(node, []);
+    if (this.accept("COMMENT")) node.comment = this.expr();
+    this.finish("table definition");
+    return node;
+  }
+
+  private view(orReplace: boolean, materialized: boolean): ViewNode {
+    const ifNotExists = this.ifNotExists();
+    const name = this.qualifiedName();
+    this.uuid();
+    const node: ViewNode = {
+      statement: "view",
+      materialized,
+      orReplace,
+      ifNotExists,
+      name,
+      onCluster: this.onCluster(),
+      append: false,
+      columns: [],
+      populate: false,
+      empty: false,
+      select: { from: 0, to: 0, refs: [] },
+    };
+    if (this.accept("REFRESH")) node.refresh = this.expr(["TO", "ENGINE", "AS", "EMPTY", "APPEND", "DEPENDS", "SETTINGS"]);
+    if (this.accept("APPEND")) node.append = true;
+    if (this.accept("TO")) node.to = this.qualifiedName();
+    if (this.isPunct("(")) {
+      const from = this.idx();
+      const holder = { columns: node.columns, indexes: [], projections: [], constraints: [] };
+      this.tableElements(holder, false);
+      node.columnsSpan = this.span(from, []);
+    }
+    this.storage(node, ["AS", "POPULATE", "EMPTY", "DEFINER", "SQL"]);
+    if (this.accept("POPULATE")) node.populate = true;
+    if (this.accept("EMPTY")) node.empty = true;
+    if (kw(this.peek(), "DEFINER", "SQL")) node.security = this.expr(["AS"], false);
+    this.expect("AS");
+    node.select = this.expr(["COMMENT"], false);
+    if (this.accept("COMMENT")) node.comment = this.expr();
+    this.finish("view's SELECT");
+    return node;
+  }
+}
+
+/** Parse one CREATE statement. Throws {@link SqlSyntaxError} located in the template. */
+export function parseCreate(tokens: Token[]): CreateNode {
+  return new Parser(tokens).parse();
+}

package/src/clickhouse/plan/commands.ts

@@ -0,0 +1,101 @@
+/**
+ * `chant sql diff` and `chant sql plan`: the classified change between two
+ * builds, or between a build and a live server. A Postgres build (its output
+ * says `"dialect": "postgres"`) or a Postgres binding goes to
+ * `../../postgres/plan/commands.ts`.
+ *
+ *     chant sql diff <before.json> <after.json> [--json]
+ *     chant sql plan <env> <build.json> [--json]
+ *
+ * `diff` is offline: it compares two `chant build` outputs, say a pull
+ * request's base and head, and needs no server. `plan` compares a build with
+ * the server `sql.profiles.<env>` binds and asks that server's formatter about
+ * expressions the rules leave different. Both exit 2 when a change needs a
+ * rebuild, which a plan refuses to make in place, and 0 otherwise; for each
+ * refused table they name the `ClickHouseRebuildOp` to run instead
+ * (`rebuildOps` in `--json`, `./rebuild-handoff.ts`).
+ */
+
+import type { CommandGroup, CommandGroupContext } from "@intentius/chant/cli/command-group";
+import { diffSchemas, type SchemaDiff } from "./diff";
+import { renderDiff } from "./report";
+import { keyedByQualifiedName, schemaFromBuildFile, schemaFromServer } from "./schema";
+import { dropFormattingOnly } from "./server-format";
+import { bindClickHouse } from "../live/bind";
+import { rebuildOpSuggestions } from "./rebuild-handoff";
+import { readFileSync } from "node:fs";
+
+/** The dialect a build output names. */
+function outputDialect(path: string): string | undefined {
+  try {
+    return (JSON.parse(readFileSync(path, "utf-8")) as { dialect?: string }).dialect;
+  } catch {
+    return undefined;
+  }
+}
+
+function split(args: string[]): { positional: string[]; json: boolean } {
+  return { positional: args.filter((a) => !a.startsWith("--")), json: args.includes("--json") };
+}
+
+function emit(diff: SchemaDiff, json: boolean, title: string): number {
+  console.log(json ? JSON.stringify(diff, null, 2) : renderDiff(diff, { title }));
+  return diff.rebuilds.length > 0 ? 2 : 0;
+}
+
+export async function runDiff(ctx: CommandGroupContext): Promise<number> {
+  const { positional, json } = split(ctx.rawArgs);
+  if (positional.length !== 2) {
+    console.error("usage: chant sql diff <before.json> <after.json> [--json]");
+    return 1;
+  }
+  if (outputDialect(positional[1]!) === "postgres") {
+    const { diffPgBuildFiles, emitPg, projectMajor } = await import("../../postgres/plan/commands");
+    return emitPg(diffPgBuildFiles(positional[0]!, positional[1]!, await projectMajor()), json, `${positional[0]} -> ${positional[1]}`);
+  }
+  const after = schemaFromBuildFile(positional[1]!);
+  const diff = diffSchemas(schemaFromBuildFile(positional[0]!), after);
+  const rebuildOps = rebuildOpSuggestions(diff, new Map(after.map((o) => [o.key, o.canonical])), "<env>");
+  return emit(rebuildOps.length > 0 ? { ...diff, rebuildOps } : diff, json, `${positional[0]} -> ${positional[1]}`);
+}
+
+/** The declared objects against the server, keys and labels by `database.name`. */
+export async function planAgainstServer(environment: string, buildFile: string, options: Parameters<typeof bindClickHouse>[0] = {}): Promise<SchemaDiff> {
+  const target = await bindClickHouse({ ...options, environment });
+  const declared = keyedByQualifiedName(schemaFromBuildFile(buildFile, target.defaultDatabase));
+  const databases = new Set(declared.map((o) => o.canonical.database ?? o.canonical.name));
+  const live = await schemaFromServer(target, databases);
+  const diff = diffSchemas(live, declared);
+  const changes = await dropFormattingOnly(target.endpoint, diff.changes);
+  const rebuildOps = rebuildOpSuggestions(
+    { ...diff, changes, rebuilds: changes.filter((c) => c.class === "rebuild") },
+    new Map(declared.map((o) => [o.key, o.canonical])),
+    environment,
+  );
+  const label = new Map(declared.map((o) => [o.key, `${o.exportName} (${o.key})`]));
+  const relabel = changes.map((c) => ({ ...c, object: label.get(c.object) ?? c.object }));
+  return { changes: relabel, rebuilds: relabel.filter((c) => c.class === "rebuild"), hints: diff.hints, ...(rebuildOps.length > 0 ? { rebuildOps } : {}) };
+}
+
+export async function runPlan(ctx: CommandGroupContext): Promise<number> {
+  const { positional, json } = split(ctx.rawArgs);
+  if (positional.length !== 2) {
+    console.error("usage: chant sql plan <env> <build.json> [--json]");
+    return 1;
+  }
+  if (outputDialect(positional[1]!) === "postgres") {
+    const { planPgAgainstServer, emitPg } = await import("../../postgres/plan/commands");
+    return emitPg(await planPgAgainstServer(positional[0]!, positional[1]!), json, `${positional[1]} against ${positional[0]}`);
+  }
+  const diff = await planAgainstServer(positional[0]!, positional[1]!);
+  return emit(diff, json, `${positional[1]} against ${positional[0]}`);
+}
+
+export const sqlCommands: CommandGroup = {
+  name: "sql",
+  description: "Schema changes, classified: between two builds, or a build and a live server",
+  commands: [
+    { name: "diff", description: "Classify the change between two chant build outputs (offline)", handler: runDiff },
+    { name: "plan", description: "Classify the change from an environment's server to a chant build output", handler: runPlan },
+  ],
+};

package/src/clickhouse/plan/deep.ts

@@ -0,0 +1,124 @@
+/**
+ * `observeResourcesDeep()` for the ClickHouse dialect: each declared object's
+ * live definition as a property tree in the declaration's own shape, so
+ * `chant lifecycle diff --live` and `plan` report property drift with no false
+ * drift.
+ *
+ * The reader parses the server's `SHOW CREATE` with the same tag the
+ * declaration used, which gives the same props shape. A field whose canonical
+ * form (`./normalize.ts`) equals the declaration's is written with the
+ * declaration's own value, so `INTERVAL 180 DAY` and `toIntervalDay(180)` do
+ * not read as drift; a field that differs keeps the server's value.
+ * `deepNormalizationHooks` prunes what is not a property of the object (the
+ * DDL text, the template source, lineage, a view's reads and `TO` target).
+ * `chant sql plan` covers the target, and classifies every change.
+ */
+
+import { deepObservation, type DeepObservationResult, type DeepResourceObservation, type DeepNormalizationHooks } from "@intentius/chant/deep-observation";
+import type { UnobservedEntity } from "@intentius/chant/lexicon";
+import { bindClickHouse, classifyClickHouseFailure, type BindOptions } from "../live/bind";
+import { readLiveSchema, type LiveObject } from "../live/catalog";
+import { database, table, view, CLICKHOUSE_ENTITY_TYPES, type ColumnDef } from "../entities";
+import { canonicalObject, type CanonicalColumn, type CanonicalObject } from "./normalize";
+
+type Props = Record<string, unknown>;
+
+// `concurrently` is how a Postgres index is created, not a property of it.
+const PRUNED = new Set(["ddl", "source", "lineage", "reads", "to", "orReplace", "ifNotExists", "concurrently"]);
+
+export const sqlDeepNormalizationHooks: DeepNormalizationHooks = {
+  prune: (node) => PRUNED.has(node.pattern.split(/[.[]/)[0]!),
+};
+
+function liveProps(o: LiveObject): Props {
+  const tag = o.type === CLICKHOUSE_ENTITY_TYPES.database ? database : o.type === CLICKHOUSE_ENTITY_TYPES.table ? table : view;
+  const strings = Object.assign([o.statement], { raw: [o.statement] }) as unknown as TemplateStringsArray;
+  return { ...(tag(strings).props as unknown as Props) };
+}
+
+const sameColumn = (a: CanonicalColumn, b: CanonicalColumn) => {
+  const strip = ({ text: _t, position: _p, previously: _v, ...rest }: CanonicalColumn) => rest;
+  return JSON.stringify(strip(a)) === JSON.stringify(strip(b));
+};
+
+/** The live props, with each field the declaration means the same as written the declaration's way. */
+export function inDeclaredVocabulary(declared: Props, live: Props, d: CanonicalObject, l: CanonicalObject): Props {
+  const out: Props = { ...live };
+  const same = (k: keyof CanonicalObject) => JSON.stringify(d[k]) === JSON.stringify(l[k]);
+  const adopt = (key: string, equal: boolean) => {
+    if (!equal) return;
+    if (declared[key] === undefined) delete out[key];
+    else out[key] = declared[key];
+  };
+  adopt("name", d.name === l.name);
+  adopt("database", d.database === l.database);
+  adopt("engine", same("engine"));
+  for (const k of ["orderBy", "primaryKey", "partitionBy", "sampleBy", "ttl", "comment", "select", "refresh"] as const) adopt(k, same(k));
+  adopt("settings", same("settings"));
+  adopt("indexes", same("indexes"));
+  adopt("projections", same("projections"));
+  adopt("constraints", same("constraints"));
+
+  const declaredColumns = (declared.columns as ColumnDef[] | undefined) ?? [];
+  if (d.kind === "view" || d.kind === "materializedView") {
+    // The server infers a view's columns; a declaration that lists none is not drift.
+    if (declaredColumns.length === 0) out.columns = [];
+  } else if (d.kind === "table") {
+    const liveColumns = (live.columns as ColumnDef[] | undefined) ?? [];
+    out.columns = liveColumns.map((c, i) => {
+      const lc = l.columns[i];
+      const dc = d.columns.find((x) => x.name === c.name);
+      const di = dc ? declaredColumns[dc.position] : undefined;
+      return lc && dc && di && sameColumn(lc, dc) ? di : c;
+    });
+  }
+  return out;
+}
+
+export async function observeResourcesDeep(
+  options: {
+    environment: string;
+    entityNames: string[];
+    entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+  } & Omit<BindOptions, "environment">,
+): Promise<DeepObservationResult> {
+  const resources: Record<string, DeepResourceObservation> = {};
+  const unobserved: Record<string, UnobservedEntity> = {};
+  let target;
+  let live: LiveObject[];
+  try {
+    target = await bindClickHouse(options);
+    live = await readLiveSchema(target);
+  } catch (err) {
+    const why = classifyClickHouseFailure(err);
+    for (const name of options.entityNames) {
+      unobserved[name] = { type: options.entities.get(name)?.entityType ?? "", reason: why.reason, detail: why.detail };
+    }
+    return deepObservation({}, unobserved);
+  }
+  const byKey = new Map(live.map((o) => [`${o.database ?? ""}.${o.name}`, o]));
+  for (const name of options.entityNames) {
+    const entity = options.entities.get(name);
+    if (!entity || !entity.entityType.startsWith("ClickHouse::")) {
+      unobserved[name] = { type: entity?.entityType ?? "", reason: "unsupported-kind" };
+      continue;
+    }
+    const props = entity.props;
+    const isDb = entity.entityType === CLICKHOUSE_ENTITY_TYPES.database;
+    const db = isDb ? undefined : typeof props.database === "string" ? props.database : target.defaultDatabase;
+    const o = byKey.get(`${db ?? ""}.${String(props.name)}`);
+    if (!o) continue;
+    try {
+      const d = canonicalObject(String(props.ddl), target.defaultDatabase);
+      const l = canonicalObject(o.statement, target.defaultDatabase);
+      resources[name] = {
+        type: o.type,
+        physicalId: o.uuid ?? `${db ? `${db}.` : ""}${o.name}`,
+        properties: inDeclaredVocabulary(props, liveProps(o), d, l),
+      };
+    } catch (err) {
+      unobserved[name] = { type: entity.entityType, reason: "read-failed", detail: `the server's definition does not parse: ${(err as Error).message}` };
+    }
+  }
+  return deepObservation(resources, unobserved);
+}