@intentius/chant-lexicon-sql 0.116.0 → 0.118.0

package/src/clickhouse/entities.ts

@@ -1,6 +1,7 @@
 /**
- * The ClickHouse entities: `database`, `table` and `view` tagged templates that
- * parse their DDL at fold time into one Declarable each (chant #3196, #3197).
+ * The ClickHouse entities: `database`, `table`, `view`, `dictionary` and
+ * `func` (#3682) tagged templates that parse their DDL at fold time into one
+ * Declarable each (chant #3196, #3197).
  *
  * ```ts
  * import { table, view } from "@intentius/chant-lexicon-sql/clickhouse";
@@ -40,6 +41,7 @@ import type { AttrRef } from "@intentius/chant/attrref";
 import { setInterpolationFields } from "@intentius/chant/provenance";
 import { CLICKHOUSE_LEXICAL, isTrivia, SqlSyntaxError, untokenize } from "./tokens";
 import { parseCreate, unquote, type ColumnNode, type CreateNode, type Span, type StorageNode } from "./parser";
+import { parseAccess, type AccessNode } from "./access";
 import { feed, lineage, spanText as text, splice as spliceWith, templateSyntaxError, type TemplateCtx, type TemplateDialect } from "../core/interpolation";
 import { SQL_LEXICON, SqlObject, isColumnRefOf, isSqlObjectOf, makeSqlEntity } from "../core/entity";
 import type { LineageEdge } from "../core/references";
@@ -54,6 +56,12 @@ export const CLICKHOUSE_ENTITY_TYPES = {
   table: "ClickHouse::Table",
   view: "ClickHouse::View",
   materializedView: "ClickHouse::MaterializedView",
+  dictionary: "ClickHouse::Dictionary",
+  function: "ClickHouse::Function",
+  user: "ClickHouse::User",
+  role: "ClickHouse::Role",
+  rowPolicy: "ClickHouse::RowPolicy",
+  grant: "ClickHouse::Grant",
 } as const;
 
 export type ClickHouseEntityType = (typeof CLICKHOUSE_ENTITY_TYPES)[keyof typeof CLICKHOUSE_ENTITY_TYPES];
@@ -136,6 +144,36 @@ export interface ViewProps extends CommonProps, StorageProps {
   ifNotExists?: boolean;
 }
 
+/** One attribute of a dictionary, as declared. */
+export interface DictionaryAttributeDef {
+  name: string;
+  type: string;
+  /** The value for a key the source does not have: `DEFAULT expr`. */
+  default?: string;
+  /** `EXPRESSION expr`: what the source computes the attribute from. */
+  expression?: string;
+  /** `HIERARCHICAL`, `BIDIRECTIONAL`, `INJECTIVE`, `IS_OBJECT_ID`, as written. */
+  flags?: string[];
+}
+
+export interface DictionaryProps extends CommonProps {
+  /** The attributes, key columns included. */
+  columns: DictionaryAttributeDef[];
+  /** The key columns: `PRIMARY KEY id`. */
+  primaryKey: string;
+  /** What is inside `SOURCE(...)`: `CLICKHOUSE(TABLE 'rates' DB 'shop')`. */
+  dataSource: string;
+  /** What is inside `LAYOUT(...)`: `HASHED()`. */
+  layout: string;
+  /** What is inside `LIFETIME(...)`: `300`, `MIN 0 MAX 300`. */
+  lifetime?: string;
+  /** What is inside `RANGE(...)`, for a range layout. */
+  range?: string;
+  settings?: Record<string, string>;
+  orReplace?: boolean;
+  ifNotExists?: boolean;
+}
+
 /**
  * A string as a quoted, escaped ClickHouse string literal. An interpolated
  * plain string is SQL text; wrap it in `literal()` when it is a value.
@@ -176,6 +214,109 @@ export interface ClickHouseView extends ClickHouseRelation {
   readonly props: ViewProps;
 }
 
+/** A SQL user-defined function, `CREATE FUNCTION name AS (x) -> expr`. It belongs to no database. */
+export interface FunctionProps {
+  name: string;
+  onCluster?: string;
+  /** The parameter names, in order. */
+  params: string[];
+  /** The expression after `->`, as written. */
+  body: string;
+  orReplace?: boolean;
+  ifNotExists?: boolean;
+  ddl: string;
+  source: { strings: string[] };
+}
+
+export interface ClickHouseFunction extends ClickHouseObject {
+  readonly entityType: "ClickHouse::Function";
+  readonly props: FunctionProps;
+}
+
+/** A user (#3682). Its password is the environment's and is never declared (`./access.ts`). */
+export interface UserProps {
+  name: string;
+  onCluster?: string;
+  /** `IDENTIFIED ...` after the keyword, for a method that holds no secret; `NOT IDENTIFIED` as itself. */
+  identified?: string;
+  host?: string;
+  validUntil?: string;
+  defaultRole?: string;
+  defaultDatabase?: string;
+  grantees?: string;
+  settings?: string;
+  orReplace?: boolean;
+  ifNotExists?: boolean;
+  ddl: string;
+  source: { strings: string[] };
+}
+
+export interface RoleProps {
+  name: string;
+  onCluster?: string;
+  settings?: string;
+  orReplace?: boolean;
+  ifNotExists?: boolean;
+  ddl: string;
+  source: { strings: string[] };
+}
+
+export interface RowPolicyProps {
+  name: string;
+  onCluster?: string;
+  /** The table's database, when the DDL qualifies it. */
+  database?: string;
+  table: string;
+  /** `PERMISSIVE` or `RESTRICTIVE`. */
+  as?: string;
+  for?: string;
+  using: string;
+  to?: string;
+  orReplace?: boolean;
+  ifNotExists?: boolean;
+  ddl: string;
+  source: { strings: string[] };
+}
+
+export interface GrantProps {
+  /** The grant's name in chant: its grantees, for a report. */
+  name: string;
+  onCluster?: string;
+  /** The privileges granted (`SELECT(a)`, `SHOW TABLES`), or the roles. */
+  privileges?: string[];
+  roles?: string[];
+  /** `db.table`, `db.*`, `*.*`. */
+  on?: string;
+  to: string[];
+  withGrantOption?: boolean;
+  withAdminOption?: boolean;
+  ddl: string;
+  source: { strings: string[] };
+}
+
+export interface ClickHouseUser extends ClickHouseObject {
+  readonly entityType: "ClickHouse::User";
+  readonly props: UserProps;
+}
+export interface ClickHouseRole extends ClickHouseObject {
+  readonly entityType: "ClickHouse::Role";
+  readonly props: RoleProps;
+}
+export interface ClickHouseRowPolicy extends ClickHouseObject {
+  readonly entityType: "ClickHouse::RowPolicy";
+  readonly props: RowPolicyProps;
+}
+export interface ClickHouseGrant extends ClickHouseObject {
+  readonly entityType: "ClickHouse::Grant";
+  readonly props: GrantProps;
+}
+
+/** A dictionary: its attributes are columns `dictGet` reads, so SQL can reference them. */
+export interface ClickHouseDictionary extends ClickHouseRelation {
+  readonly entityType: "ClickHouse::Dictionary";
+  readonly props: DictionaryProps;
+}
+
 function makeEntity(
   entityType: ClickHouseEntityType,
   sqlName: string,
@@ -303,7 +444,7 @@ function qualified(ctx: Ctx, span: Span): { database?: string; name: string } {
   return pieces.length >= 2 ? { database: pieces[pieces.length - 2], name: pieces[pieces.length - 1]! } : { name: pieces[0] ?? "" };
 }
 
-type Expect = "database" | "table" | "view";
+type Expect = "database" | "table" | "view" | "dictionary" | "func";
 
 function build(tag: Expect, strings: TemplateStringsArray | readonly string[], values: readonly unknown[]): ClickHouseObject {
   const parts = templateParts(strings);
@@ -317,9 +458,18 @@ function build(tag: Expect, strings: TemplateStringsArray | readonly string[], v
   }
   const ctx: Ctx = { d: CLICKHOUSE_TEMPLATES, tokens, values, fed: values.map(() => new Set<string>()) };
   for (const t of tokens) if (t.splice !== undefined) ctx.fed[t.splice]!.add("ddl");
-  if (node.statement !== tag) {
-    const holds = node.statement === "database" ? "CREATE DATABASE" : node.statement === "table" ? "CREATE TABLE" : "CREATE VIEW";
-    throw new SqlTemplateError(tag, `holds a ${holds}; use the ${node.statement} tag`, 0, 0);
+  if (node.statement !== (tag === "func" ? "function" : tag)) {
+    const holds =
+      node.statement === "database"
+        ? "CREATE DATABASE"
+        : node.statement === "table"
+          ? "CREATE TABLE"
+          : node.statement === "dictionary"
+            ? "CREATE DICTIONARY"
+            : node.statement === "function"
+              ? "CREATE FUNCTION"
+              : "CREATE VIEW";
+    throw new SqlTemplateError(tag, `holds a ${holds}; use the ${node.statement === "function" ? "func" : node.statement} tag`, 0, 0);
   }
   const { database, name } = qualified(ctx, node.name);
   const sqlName = database ? `${quoteIdentifier(database)}.${quoteIdentifier(name)}` : quoteIdentifier(name);
@@ -375,6 +525,50 @@ function build(tag: Expect, strings: TemplateStringsArray | readonly string[], v
     return done(makeEntity(CLICKHOUSE_ENTITY_TYPES.table, sqlName, props, columns.map((c) => c.name), dependsOn));
   }
 
+  if (node.statement === "function") {
+    for (const p of node.params) feed(ctx, p.span, "params");
+    const props: FunctionProps = strip({
+      name,
+      onCluster: common.onCluster,
+      orReplace: node.orReplace,
+      ifNotExists: node.ifNotExists,
+      params: node.params.map((p) => p.name || req(text(ctx, p.span))),
+      body: req(text(ctx, node.body, "body")),
+      ddl,
+      source,
+    });
+    return done(makeEntity(CLICKHOUSE_ENTITY_TYPES.function, quoteIdentifier(name), props, undefined, dependsOn));
+  }
+
+  if (node.statement === "dictionary") {
+    const columns: DictionaryAttributeDef[] = node.attributes.map((a) => {
+      for (const span of [a.nameSpan, a.type, a.default, a.expression]) feed(ctx, span, "columns");
+      return strip({
+        name: a.name || req(text(ctx, a.nameSpan)),
+        type: req(text(ctx, a.type)),
+        default: text(ctx, a.default),
+        expression: text(ctx, a.expression),
+        flags: a.flags.length > 0 ? a.flags : undefined,
+      });
+    });
+    const settings = text(ctx, node.settings, "settings");
+    const props: DictionaryProps = strip({
+      ...common,
+      orReplace: node.orReplace,
+      ifNotExists: node.ifNotExists,
+      columns,
+      primaryKey: req(text(ctx, node.primaryKey, "primaryKey")),
+      dataSource: req(text(ctx, node.source, "dataSource")),
+      layout: req(text(ctx, node.layout, "layout")),
+      lifetime: text(ctx, node.lifetime, "lifetime"),
+      range: text(ctx, node.range, "range"),
+      settings: settings === undefined ? undefined : dictionarySettings(settings),
+      ddl,
+      source,
+    });
+    return done(makeEntity(CLICKHOUSE_ENTITY_TYPES.dictionary, sqlName, props, columns.map((c) => c.name), dependsOn));
+  }
+
   const lin = lineage<ClickHouseObject>(ctx, node.select);
   let to: ClickHouseObject | string | undefined;
   if (node.to) {
@@ -406,6 +600,26 @@ function build(tag: Expect, strings: TemplateStringsArray | readonly string[], v
   return done(makeEntity(type, sqlName, props, outputs, dependsOn));
 }
 
+/** `a = 1, b = 'x'` as a record of each setting's value as written. */
+function dictionarySettings(text: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  let depth = 0;
+  let cur = "";
+  const flush = () => {
+    const at = cur.indexOf("=");
+    if (at > 0) out[cur.slice(0, at).trim()] = cur.slice(at + 1).trim();
+    cur = "";
+  };
+  for (const ch of text) {
+    if (ch === "(") depth++;
+    else if (ch === ")") depth--;
+    if (ch === "," && depth === 0) flush();
+    else cur += ch;
+  }
+  flush();
+  return out;
+}
+
 /** `` database`CREATE DATABASE ...` ``: one ClickHouse database, parsed at build time. */
 export function database(strings: TemplateStringsArray, ...values: unknown[]): ClickHouseDatabase {
   return build("database", strings, values) as ClickHouseDatabase;
@@ -423,3 +637,139 @@ export function table(strings: TemplateStringsArray, ...values: unknown[]): Clic
 export function view(strings: TemplateStringsArray, ...values: unknown[]): ClickHouseView {
   return build("view", strings, values) as ClickHouseView;
 }
+
+/**
+ * `` dictionary`CREATE DICTIONARY ...` ``: one dictionary, its attributes,
+ * key, source, layout and lifetime, parsed at build time (#3682). Its
+ * attributes are columns: `${rates.columns.rate}`.
+ */
+export function dictionary(strings: TemplateStringsArray, ...values: unknown[]): ClickHouseDictionary {
+  return build("dictionary", strings, values) as ClickHouseDictionary;
+}
+
+/**
+ * `` func`CREATE FUNCTION ...` ``: one SQL user-defined function, a lambda
+ * with a name (#3682). It belongs to no database, and has no comment, so it
+ * carries no ownership marker: chant replaces it when its declaration
+ * changes and never drops it.
+ */
+export function func(strings: TemplateStringsArray, ...values: unknown[]): ClickHouseFunction {
+  return build("func", strings, values) as ClickHouseFunction;
+}
+
+type AccessTag = "user" | "role" | "policy" | "grant";
+const ACCESS_STATEMENT: Record<AccessTag, AccessNode["statement"]> = { user: "user", role: "role", policy: "rowPolicy", grant: "grant" };
+const ACCESS_HOLDS: Record<AccessNode["statement"], [string, AccessTag]> = {
+  user: ["CREATE USER", "user"],
+  role: ["CREATE ROLE", "role"],
+  rowPolicy: ["CREATE ROW POLICY", "policy"],
+  grant: ["GRANT", "grant"],
+};
+
+function buildAccess(tag: AccessTag, strings: TemplateStringsArray | readonly string[], values: readonly unknown[]): ClickHouseObject {
+  const parts = templateParts(strings);
+  const tokens = splice(tag, parts, values);
+  let node: AccessNode;
+  try {
+    node = parseAccess(tokens);
+  } catch (err) {
+    if (!(err instanceof SqlSyntaxError)) throw err;
+    throw templateSyntaxError(tag, parts, err);
+  }
+  if (node.statement !== ACCESS_STATEMENT[tag]) {
+    const [holds, use] = ACCESS_HOLDS[node.statement];
+    throw new SqlTemplateError(tag, `holds a ${holds}; use the ${use} tag`, 0, 0);
+  }
+  if (node.revoke) throw new SqlTemplateError(tag, "holds a REVOKE; declare the grants a grantee keeps, and a plan revokes the rest", 0, 0);
+  const ctx: Ctx = { d: CLICKHOUSE_TEMPLATES, tokens, values, fed: values.map(() => new Set<string>()) };
+  for (const t of tokens) if (t.splice !== undefined) ctx.fed[t.splice]!.add("ddl");
+  const ddl = req(untokenize(tokens, (i) => renderReference(values[i])).trim().replace(/;\s*$/, ""));
+  const source = { strings: parts };
+  const dependsOn = [...new Set(values.filter((v) => isClickHouseObject(v) || isColumnRef(v)))];
+  const done = <T extends ClickHouseObject>(entity: T): T => {
+    setInterpolationFields(entity, ctx.fed.map((paths) => [...paths].sort()));
+    return entity;
+  };
+  const rendered = (span: Span | undefined): string | undefined =>
+    span ? untokenize(tokens.slice(span.from, span.to), (i) => renderReference(values[i])).trim() || undefined : undefined;
+  const name = node.name ? unquote(rendered(node.name) ?? "") : "";
+  const c = node.clauses;
+  const common = { name, onCluster: text(ctx, node.onCluster, "onCluster"), orReplace: node.orReplace || undefined, ifNotExists: node.ifNotExists || undefined };
+  if (node.statement === "user") {
+    const props: UserProps = strip({
+      ...common,
+      identified: c.notIdentified ? "NOT IDENTIFIED" : rendered(c.identified),
+      host: rendered(c.host),
+      validUntil: rendered(c.validUntil),
+      defaultRole: rendered(c.defaultRole),
+      defaultDatabase: rendered(c.defaultDatabase),
+      grantees: rendered(c.grantees),
+      settings: rendered(c.settings),
+      ddl,
+      source,
+    });
+    return done(makeEntity(CLICKHOUSE_ENTITY_TYPES.user, quoteIdentifier(name), props, undefined, dependsOn));
+  }
+  if (node.statement === "role") {
+    const props: RoleProps = strip({ ...common, settings: rendered(c.settings), ddl, source });
+    return done(makeEntity(CLICKHOUSE_ENTITY_TYPES.role, quoteIdentifier(name), props, undefined, dependsOn));
+  }
+  if (node.statement === "rowPolicy") {
+    const { database, name: tableName } = qualified(ctx, node.table!);
+    const props: RowPolicyProps = strip({
+      ...common,
+      database,
+      table: tableName,
+      as: rendered(c.as)?.toUpperCase(),
+      for: rendered(c.for),
+      using: req(rendered(c.using)),
+      to: rendered(c.to),
+      ddl,
+      source,
+    });
+    return done(makeEntity(CLICKHOUSE_ENTITY_TYPES.rowPolicy, quoteIdentifier(name), props, undefined, dependsOn));
+  }
+  const items = node.items.map((i) => rendered(i) ?? "");
+  const to = node.grantees.map((g) => unquote(rendered(g) ?? ""));
+  const props: GrantProps = strip({
+    name: to.join(", "),
+    onCluster: common.onCluster,
+    privileges: node.target ? items : undefined,
+    roles: node.target ? undefined : items.map(unquote),
+    on: rendered(node.target),
+    to,
+    withGrantOption: node.withOption === "GRANT" || undefined,
+    withAdminOption: node.withOption === "ADMIN" || undefined,
+    ddl,
+    source,
+  });
+  return done(makeEntity(CLICKHOUSE_ENTITY_TYPES.grant, "", props, undefined, dependsOn));
+}
+
+/**
+ * `` user`CREATE USER ...` ``: one user (#3682). A password is the
+ * environment's: `IDENTIFIED BY` is refused, and a user declared without
+ * `IDENTIFIED` is compared without it and is not created by chant.
+ */
+export function user(strings: TemplateStringsArray, ...values: unknown[]): ClickHouseUser {
+  return buildAccess("user", strings, values) as ClickHouseUser;
+}
+
+/** `` role`CREATE ROLE ...` ``: one role (#3682). Interpolate it where a grant or a user names it. */
+export function role(strings: TemplateStringsArray, ...values: unknown[]): ClickHouseRole {
+  return buildAccess("role", strings, values) as ClickHouseRole;
+}
+
+/** `` policy`CREATE ROW POLICY ...` ``: one row policy on one table (#3682). */
+export function policy(strings: TemplateStringsArray, ...values: unknown[]): ClickHouseRowPolicy {
+  return buildAccess("policy", strings, values) as ClickHouseRowPolicy;
+}
+
+/**
+ * `` grant`GRANT ...` ``: privileges or roles granted to users or roles
+ * (#3682). Every grant declaration naming a grantee adds up to its complete
+ * list: a plan revokes what it holds besides.
+ */
+export function grant(strings: TemplateStringsArray, ...values: unknown[]): ClickHouseGrant {
+  return buildAccess("grant", strings, values) as ClickHouseGrant;
+}

package/src/clickhouse/function.test.ts

@@ -0,0 +1,91 @@
+/**
+ * SQL user-defined functions (#3682): the `func` tag, a function keyed
+ * apart from any database, a changed lambda replacing it (SQLCH260), no
+ * marker and no restamp, and `ON CLUSTER` per topology.
+ * `live/functions.e2e.test.ts` runs them against a server.
+ */
+
+import { describe, expect, test } from "vitest";
+import { func, table, CLICKHOUSE_ENTITY_TYPES } from "./entities";
+import { canonicalObject, objectKey, scopeOf } from "./plan/normalize";
+import { diffSchemas } from "./plan/diff";
+import { CLASSIFIER_RULES } from "./plan/rules";
+import { createStatement, dropStatement, planStatements, type DeclaredObject } from "./apply/statements";
+import { renderStatement } from "./topology";
+
+const DECLARED = "CREATE FUNCTION linear AS (x, k, b) -> k*x + b";
+// What clickhouse-server 26.8.15.10 prints for DECLARED (`system.functions.create_query`).
+const SHOWN = "CREATE FUNCTION linear AS (x, k, b) -> ((k * x) + b)";
+
+const declared = (ddl: string): DeclaredObject => {
+  const canonical = canonicalObject(ddl);
+  return { exportName: "linear", type: CLICKHOUSE_ENTITY_TYPES.function, key: objectKey(canonical), ddl, canonical, dependsOn: [] };
+};
+
+describe("the func tag", () => {
+  test("parses the name, the parameters and the expression; a function has no database", () => {
+    const f = func([DECLARED] as unknown as TemplateStringsArray);
+    expect(f.entityType).toBe("ClickHouse::Function");
+    expect(f.sqlName).toBe("linear");
+    expect(f.props).toMatchObject({ name: "linear", params: ["x", "k", "b"], body: "k*x + b" });
+    expect(func(["CREATE FUNCTION twice AS x -> x * 2"] as unknown as TemplateStringsArray).props.params).toEqual(["x"]);
+  });
+
+  test("a qualified name, a missing arrow and another statement are refused", () => {
+    expect(() => func(["CREATE FUNCTION shop.linear AS (x) -> x"] as unknown as TemplateStringsArray)).toThrow(/no database/);
+    expect(() => func(["CREATE FUNCTION linear AS (x) x"] as unknown as TemplateStringsArray)).toThrow(/expected ->/);
+    expect(() => table([DECLARED] as unknown as TemplateStringsArray)).toThrow(/use the func tag/);
+  });
+
+  test("keyed and scoped apart from a database of the same name", () => {
+    const f = canonicalObject("CREATE FUNCTION shop AS (x) -> x");
+    const db = canonicalObject("CREATE DATABASE shop");
+    expect([objectKey(f), objectKey(db)]).toEqual(["function shop", "shop"]);
+    expect([scopeOf(f), scopeOf(db)]).toEqual(["function shop", "shop"]);
+  });
+});
+
+describe("a function compared and changed", () => {
+  test("a changed expression is SQLCH260; the server's formatting is left to its formatter", () => {
+    const changes = diffSchemas([{ key: "f", canonical: canonicalObject(SHOWN) }], [{ key: "f", canonical: canonicalObject(DECLARED) }]).changes;
+    // The rules leave the parentheses the server adds; a plan against a server asks its formatter (`dropFormattingOnly`).
+    expect(changes.map((c) => [c.field, c.rule])).toEqual([["lambda", "SQLCH260"]]);
+    expect(CLASSIFIER_RULES.SQLCH260.class).toBe("metadata");
+    expect(diffSchemas([{ key: "f", canonical: canonicalObject(DECLARED) }], [{ key: "f", canonical: canonicalObject("CREATE FUNCTION linear AS (x, k, b) -> k * x + b") }]).changes).toEqual([]);
+  });
+
+  test("created as declared, with no marker; replaced with CREATE OR REPLACE; never restamped", () => {
+    const marker = { stack: "shop", env: "prod" };
+    expect(createStatement(declared(DECLARED), marker)).toBe(DECLARED);
+    const after = declared("CREATE FUNCTION linear AS (x, k, b) -> k*x + b + 1");
+    const current = new Map([[after.key, canonicalObject(DECLARED)]]);
+    const changes = diffSchemas([{ key: after.key, canonical: canonicalObject(DECLARED) }], [{ key: after.key, canonical: after.canonical }]).changes;
+    const plan = planStatements({ declared: [after], changes, current, marker, carriesMarker: () => false });
+    const entry = plan.objects[0]!;
+    expect(entry.verdict === "alter" ? entry.steps.map((s) => s.sql) : []).toEqual(["CREATE OR REPLACE FUNCTION linear AS (x, k, b) -> k*x + b + 1"]);
+    // As declared, and with no marker to carry: nothing is sent.
+    const same = planStatements({ declared: [declared(DECLARED)], changes: [], current: new Map([[after.key, canonicalObject(DECLARED)]]), marker, carriesMarker: () => false });
+    expect(same.objects[0]!.verdict === "alter" ? same.objects[0]!.steps : ["?"]).toEqual([]);
+    expect(dropStatement(CLICKHOUSE_ENTITY_TYPES.function, undefined, "linear")).toBe("DROP FUNCTION `linear`");
+  });
+
+  test("ON CLUSTER on a cluster, and in the replicated topology its cluster, since a function is in no database", () => {
+    expect(renderStatement(DECLARED, { kind: "cluster", cluster: "main" })).toBe("CREATE FUNCTION linear ON CLUSTER `main` AS (x, k, b) -> k*x + b");
+    expect(renderStatement(DECLARED, { kind: "replicated", cluster: "main" })).toBe("CREATE FUNCTION linear ON CLUSTER `main` AS (x, k, b) -> k*x + b");
+    expect(renderStatement(DECLARED, { kind: "replicated" })).toBe(DECLARED);
+    expect(renderStatement(DECLARED, { kind: "single" })).toBe(DECLARED);
+    expect(renderStatement("DROP FUNCTION `linear`", { kind: "cluster", cluster: "main" })).toBe("DROP FUNCTION `linear` ON CLUSTER `main`");
+  });
+});
+
+describe("importing a function", () => {
+  test("the server's statement becomes a func declaration", async () => {
+    const { ClickHouseSqlParser } = await import("./import/parser");
+    const { ClickHouseGenerator } = await import("./import/generator");
+    const ir = new ClickHouseSqlParser().parse(`${SHOWN};`);
+    expect(ir.resources.map((r) => [r.logicalId, r.type])).toEqual([["linear", "ClickHouse::Function"]]);
+    const [file] = new ClickHouseGenerator().generate(ir);
+    expect(file!.content).toContain('import { func } from "@intentius/chant-lexicon-sql/clickhouse";');
+    expect(file!.content).toContain("export const linear = func`");
+  });
+});

package/src/clickhouse/http.ts

@@ -7,12 +7,16 @@
  * line, which is all generation (and, later, observation and import) reads.
  */
 
+import type { CredentialSource } from "../token-source";
+
 /** Where a server answers, and as whom. */
 export interface ClickHouseEndpoint {
   /** Base URL of the HTTP interface, e.g. `http://127.0.0.1:8123`. */
   url: string;
   user?: string;
   password?: string;
+  /** Mints the password for each request, in place of `password` (a profile's token source, #3685). */
+  token?: CredentialSource;
 }
 
 /** A query the server refused, with the server's own message. */
@@ -49,7 +53,8 @@ export async function clickhouseQuery<Row = Record<string, unknown>>(
 ): Promise<Row[]> {
   const headers: Record<string, string> = { "content-type": "text/plain; charset=utf-8" };
   if (endpoint.user !== undefined) headers["X-ClickHouse-User"] = endpoint.user;
-  if (endpoint.password !== undefined) headers["X-ClickHouse-Key"] = endpoint.password;
+  const password = endpoint.token ? await endpoint.token.get() : endpoint.password;
+  if (password !== undefined) headers["X-ClickHouse-Key"] = password;
   const params = new URLSearchParams({ default_format: "JSONEachRow", ...(opts.queryId !== undefined ? { query_id: opts.queryId } : {}), ...opts.settings });
   const res = await fetch(`${endpoint.url.replace(/\/$/, "")}/?${params.toString()}`, {
     method: "POST",
@@ -58,7 +63,11 @@ export async function clickhouseQuery<Row = Record<string, unknown>>(
     ...(opts.signal ? { signal: opts.signal } : {}),
   });
   const text = await res.text();
-  if (!res.ok) throw new ClickHouseQueryError(res.status, text, sql);
+  if (!res.ok) {
+    // A refused token is not reused: the next request mints another.
+    if (endpoint.token && (res.status === 401 || res.status === 403 || /AUTHENTICATION_FAILED|Code: 516/.test(text))) endpoint.token.invalidate();
+    throw new ClickHouseQueryError(res.status, text, sql);
+  }
   return text
     .split("\n")
     .filter((line) => line.length > 0)