@intentius/chant-lexicon-sql 0.124.45 → 0.124.48

package/dist/sqlserver/types.js

@@ -0,0 +1,133 @@
+/**
+ * The T-SQL to ClickHouse type map.
+ *
+ * Source types and their ranges, precisions and defaults are from Microsoft's
+ * data type reference
+ * (https://learn.microsoft.com/en-us/sql/t-sql/data-types/data-types-transact-sql)
+ * and the page of each type under it: `float(n)` is `real` for n in 1..24 and
+ * the 8-byte type for 25..53 with a default of 53; `decimal(p,s)` defaults to
+ * (18,0) with p up to 38; `datetime2` and `time` take a scale of 0 to 7 with
+ * a default of 7; `money` is a 64-bit integer with four decimals and
+ * `smallmoney` a 32-bit one; `rowversion` (`timestamp`) is an 8-byte counter.
+ *
+ * Target types are ClickHouse types of the pinned server (see
+ * `../spec/pin.ts`). `types.test.ts` checks every family this file writes
+ * against `TYPE_FAMILIES` in the generated catalog and every precision against
+ * the `DateTime64`, `Time64` and `Decimal` ranges, so a pin move that drops a
+ * type fails there.
+ *
+ * A type either maps with no judgment (`note` absent) or carries a `note`
+ * naming what the map could not keep. A type this file does not know
+ * (`sql_variant`, a user-defined alias type) is refused by name.
+ */
+const num = (args, i) => (typeof args[i] === "number" ? args[i] : undefined);
+/** Map a column type. `name` is lower-case, `args` the parenthesised arguments. */
+export function mapType(name, args) {
+    switch (name) {
+        case "tinyint":
+            return { ok: true, type: "UInt8" };
+        case "smallint":
+            return { ok: true, type: "Int16" };
+        case "int":
+        case "integer":
+            return { ok: true, type: "Int32" };
+        case "bigint":
+            return { ok: true, type: "Int64" };
+        case "bit":
+            return { ok: true, type: "Bool" };
+        case "decimal":
+        case "numeric":
+        case "dec": {
+            const p = num(args, 0) ?? 18;
+            const s = num(args, 1) ?? 0;
+            return { ok: true, type: `Decimal(${String(p)}, ${String(s)})` };
+        }
+        case "money":
+            return { ok: true, type: "Decimal(19, 4)" };
+        case "smallmoney":
+            return { ok: true, type: "Decimal(10, 4)" };
+        case "real":
+            return { ok: true, type: "Float32" };
+        case "float": {
+            const n = num(args, 0) ?? 53;
+            return { ok: true, type: n <= 24 ? "Float32" : "Float64" };
+        }
+        case "date":
+            return { ok: true, type: "Date32" };
+        case "time":
+            return { ok: true, type: `Time64(${String(num(args, 0) ?? 7)})` };
+        case "datetime2":
+            return { ok: true, type: `DateTime64(${String(num(args, 0) ?? 7)})` };
+        case "datetime":
+            return { ok: true, type: "DateTime64(3)" };
+        case "smalldatetime":
+            return { ok: true, type: "DateTime64(0)" };
+        case "datetimeoffset": {
+            const p = num(args, 0) ?? 7;
+            return {
+                ok: true,
+                type: `DateTime64(${String(p)}, 'UTC')`,
+                note: {
+                    message: "datetimeoffset is read as a UTC DateTime64; the stored offset is not kept.",
+                    evidence: ["datetimeoffset stores a time zone offset (-14:00 to +14:00) with each value; a ClickHouse DateTime64 holds an instant and one column time zone", "values must be converted to UTC when loaded"],
+                },
+            };
+        }
+        case "char":
+        case "varchar":
+        case "nchar":
+        case "nvarchar":
+        case "text":
+        case "ntext":
+        case "sysname": {
+            const max = name === "sysname" ? 128 : typeof args[0] === "number" ? args[0] : undefined;
+            return { ok: true, type: "String", ...(max !== undefined ? { maxLength: max } : {}) };
+        }
+        case "binary":
+        case "varbinary":
+        case "image": {
+            const max = typeof args[0] === "number" ? args[0] : undefined;
+            return { ok: true, type: "String", ...(max !== undefined ? { maxLength: max } : {}) };
+        }
+        case "uniqueidentifier":
+            return { ok: true, type: "UUID" };
+        case "json":
+            return { ok: true, type: "JSON" };
+        case "xml":
+            return {
+                ok: true,
+                type: "String",
+                note: { message: "xml is read as String; ClickHouse has no XML type.", evidence: ["the xml type validates and indexes documents; a String does neither"] },
+            };
+        case "rowversion":
+        case "timestamp":
+            return {
+                ok: true,
+                type: "String",
+                note: {
+                    message: `${name} is read as String; its 8 bytes are an opaque counter.`,
+                    evidence: ["rowversion is a database-wide counter that SQL Server writes on each row change, not a date or time", "a String keeps the bytes; a UInt64 version column has to be loaded from the source"],
+                },
+            };
+        case "hierarchyid":
+            return { ok: true, type: "String", note: { message: "hierarchyid is read as String; ClickHouse has no hierarchy type.", evidence: ["the binary form is kept as bytes; hierarchy methods (GetAncestor, IsDescendantOf) have no ClickHouse equivalent"] } };
+        case "geography":
+        case "geometry":
+            return { ok: true, type: "String", note: { message: `${name} is read as String; the spatial value is not converted.`, evidence: ["a spatial value needs a conversion (well-known text or binary) at load time", "ClickHouse has Point, Ring and Polygon types, which fit only some shapes"] } };
+        case "vector": {
+            const dims = num(args, 0);
+            return {
+                ok: true,
+                type: "Array(Float32)",
+                note: { message: "vector is read as Array(Float32).", evidence: [dims !== undefined ? `declared with ${String(dims)} dimensions, which an Array does not enforce` : "the dimension count is not enforced by an Array"] },
+            };
+        }
+        case "sql_variant":
+            return { ok: false, reason: "sql_variant holds values of any type, and no single ClickHouse type matches it" };
+        case "cursor":
+        case "table":
+            return { ok: false, reason: `${name} is not a type a stored column can have` };
+        default:
+            return { ok: false, reason: `the type ${name} is not a system type; user-defined alias types are not read` };
+    }
+}

package/dist/sqlserver/validate.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `chant import --validate` for a translated schema (#4398): create the
+ * emitted DDL on the pinned ClickHouse server, as `chant migrate --validate`
+ * runs the emitted YAML through the target's linter.
+ *
+ * `validateOnEmulator` starts its own throwaway container of the pinned image
+ * (`../clickhouse/container.ts`) and removes it afterwards. It never reads
+ * `CLICKHOUSE_URL`, so a validation cannot reach a server that holds data.
+ * `validateStatements` is the part that needs no Docker: it runs statements
+ * through any `run` function, in the order a server needs them (databases,
+ * then tables, then views), and turns each refusal into an `error`
+ * diagnostic naming the object.
+ */
+import type { ImportDiagnostic, TemplateIR } from "@intentius/chant/import/parser";
+export interface ValidationStatement {
+    /** The object, as the diagnostic names it. */
+    name: string;
+    ddl: string;
+    type: string;
+}
+/** The IR's ClickHouse objects as statements in creation order. */
+export declare function statementsOf(ir: TemplateIR): ValidationStatement[];
+/** Run each statement; a refusal is an error diagnostic, and the run goes on to the next. */
+export declare function validateStatements(statements: readonly ValidationStatement[], run: (sql: string) => Promise<void>): Promise<ImportDiagnostic[]>;
+/**
+ * Create the IR's objects on a throwaway server of the pinned image. Throws,
+ * naming the cause, when Docker is not available: the caller reports that the
+ * validation did not run, rather than reporting a pass.
+ */
+export declare function validateOnEmulator(ir: TemplateIR): Promise<ImportDiagnostic[]>;
+//# sourceMappingURL=validate.d.ts.map

package/dist/sqlserver/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/sqlserver/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAMnF,MAAM,WAAW,mBAAmB;IAClC,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AASD,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,EAAE,EAAE,UAAU,GAAG,mBAAmB,EAAE,CAQlE;AAED,6FAA6F;AAC7F,wBAAsB,kBAAkB,CAAC,UAAU,EAAE,SAAS,mBAAmB,EAAE,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAWrJ;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,EAAE,EAAE,UAAU,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAWpF"}

package/dist/sqlserver/validate.js

@@ -0,0 +1,67 @@
+/**
+ * `chant import --validate` for a translated schema (#4398): create the
+ * emitted DDL on the pinned ClickHouse server, as `chant migrate --validate`
+ * runs the emitted YAML through the target's linter.
+ *
+ * `validateOnEmulator` starts its own throwaway container of the pinned image
+ * (`../clickhouse/container.ts`) and removes it afterwards. It never reads
+ * `CLICKHOUSE_URL`, so a validation cannot reach a server that holds data.
+ * `validateStatements` is the part that needs no Docker: it runs statements
+ * through any `run` function, in the order a server needs them (databases,
+ * then tables, then views), and turns each refusal into an `error`
+ * diagnostic naming the object.
+ */
+import { CLICKHOUSE_ENTITY_TYPES } from "../clickhouse/entities.js";
+import { ClickHouseQueryError, clickhouseQuery } from "../clickhouse/http.js";
+import { dockerAvailable, startScratchServer } from "../clickhouse/container.js";
+import { clickhouseImage } from "../spec/pin.js";
+const RANK = {
+    [CLICKHOUSE_ENTITY_TYPES.database]: 0,
+    [CLICKHOUSE_ENTITY_TYPES.table]: 1,
+    [CLICKHOUSE_ENTITY_TYPES.view]: 2,
+    [CLICKHOUSE_ENTITY_TYPES.materializedView]: 2,
+};
+/** The IR's ClickHouse objects as statements in creation order. */
+export function statementsOf(ir) {
+    const out = ir.resources.map((r, i) => {
+        const p = r.properties;
+        return { name: p.database ? `${p.database}.${p.name}` : p.name, ddl: p.ddl, type: r.type, i };
+    });
+    return out
+        .sort((a, b) => (RANK[a.type] ?? 3) - (RANK[b.type] ?? 3) || a.i - b.i)
+        .map(({ name, ddl, type }) => ({ name, ddl, type }));
+}
+/** Run each statement; a refusal is an error diagnostic, and the run goes on to the next. */
+export async function validateStatements(statements, run) {
+    const out = [];
+    for (const s of statements) {
+        try {
+            await run(s.ddl);
+        }
+        catch (e) {
+            const msg = e instanceof ClickHouseQueryError ? e.serverMessage.trim().split("\n")[0] : e instanceof Error ? e.message : String(e);
+            out.push({ ruleId: "SQLRV012", severity: "error", message: `${s.name}: the emulator rejected the statement. ${msg}`, entity: s.name });
+        }
+    }
+    return out;
+}
+/**
+ * Create the IR's objects on a throwaway server of the pinned image. Throws,
+ * naming the cause, when Docker is not available: the caller reports that the
+ * validation did not run, rather than reporting a pass.
+ */
+export async function validateOnEmulator(ir) {
+    if (ir.resources.some((r) => r.type.startsWith("Postgres::")))
+        throw new Error("--validate checks ClickHouse DDL; this template holds Postgres objects");
+    if (!(await dockerAvailable()))
+        throw new Error("Docker is not available, so the ClickHouse emulator cannot start");
+    const server = await startScratchServer(clickhouseImage(), { namePrefix: "chant-sql-import-validate" });
+    try {
+        return await validateStatements(statementsOf(ir), async (sql) => {
+            await clickhouseQuery(server.endpoint, sql);
+        });
+    }
+    finally {
+        await server.stop();
+    }
+}

package/dist/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,EAAgD,KAAK,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAMtH,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAkFvF,wBAAsB,QAAQ,CAAC,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAoEpF"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,EAAgD,KAAK,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAMtH,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAuFvF,wBAAsB,QAAQ,CAAC,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAoEpF"}

package/dist/validate.js

@@ -43,6 +43,11 @@ const REQUIRED_ENTITIES = [
     "PostgresCollation",
     "PostgresCast",
     "PostgresEventTrigger",
+    "PostgresOperator",
+    "PostgresStatistics",
+    "PostgresForeignDataWrapper",
+    "PostgresForeignServer",
+    "PostgresPublication",
     "PostgresExtension",
     "PostgresFunction",
     "PostgresProcedure",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-sql",
-  "version": "0.124.45",
+  "version": "0.124.48",
   "description": "SQL lexicon for chant — database schema as typed declarations, one dialect at a time; ClickHouse first, with types read from a pinned server's catalog",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -72,6 +72,6 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.124.45"
+    "@intentius/chant": "^0.124.48"
   }
 }

package/src/change-set.ts

@@ -25,7 +25,7 @@
  * dialects' `CHANGE_CLASSES` and `PG_CHANGE_CLASSES` price them:
  *
  * - a `drop` class is a `delete` (`destroy`); a `create` class a `create`;
- * - a `rebuild` or `expand` class, or a step a migration Op makes, is a
+ * - a `rebuild`, `replace` or `expand` class, or a step a migration Op makes, is a
  *   `replace` (`replace`): the object, or a column of it, is built again;
  * - anything else is an `update`, its disruption the worst class's
  *   (`metadata` in-place; `validate`, `concurrently` and `rewrite` rolling).
@@ -67,6 +67,7 @@ export const SQL_CLASS_DISRUPTION: Readonly<Record<string, ChangeSetDisruption>>
   validate: "rolling",
   concurrently: "rolling",
   rewrite: "rolling",
+  replace: "replace",
   rebuild: "replace",
   expand: "replace",
   drop: "destroy",

package/src/clickhouse/apply/statements.ts

@@ -24,6 +24,7 @@ import { CLASSIFIER_RULES, type ChangeClass, type ClassifierRuleId } from "../pl
 import { stampedComment } from "../ownership";
 import { CLICKHOUSE_ENTITY_TYPES, type ClickHouseEntityType } from "../entities";
 import { renderFor, type Topology } from "../topology";
+import { readsTable } from "../plan/stream";
 import { accessClauseText, alterAccessField, alterQuotaOrProfileField, grantStatement, revokeStatement, SECRETLESS, type GrantAtom } from "../access";
 
 /** A backquoted identifier. */
@@ -613,6 +614,24 @@ function deferredDefaultRoles(
   return out;
 }
 
+/**
+ * The statements that replace a stream table (#4396), in the order they run:
+ * detach each materialized view that reads it (`readers`, as the server has
+ * them), drop the table, create it as declared, attach the views. The table
+ * holds no rows, so nothing is copied; a view that stays detached for the
+ * length of the replacement reads nothing, and the messages wait in the
+ * broker (or the files in the bucket) for the new table.
+ */
+export function replaceStreamSteps(obj: DeclaredObject, live: CanonicalObject, readers: readonly CanonicalObject[], marker: OwnershipMarker | undefined): Step[] {
+  const view = (r: CanonicalObject) => qualifiedIdent(r.database, r.name);
+  return [
+    ...readers.map((r) => stepFor(`DETACH TABLE ${view(r)}`, "SQLCH225")),
+    stepFor(`DROP TABLE ${qualifiedIdent(live.database, live.name)} SYNC`, "SQLCH225"),
+    stepFor(createStatement(obj, marker), "SQLCH225"),
+    ...readers.map((r) => stepFor(`ATTACH TABLE ${view(r)}`, "SQLCH225")),
+  ];
+}
+
 function planDeclared(input: StatementPlanInput): StatementPlan {
   const keyOf = input.keyOf ?? ((o: DeclaredObject) => o.key);
   const byObject = new Map<string, Change[]>();
@@ -640,6 +659,12 @@ function planDeclared(input: StatementPlanInput): StatementPlan {
     const renamedFrom = mine.find((c) => c.rule === "SQLCH230" || c.rule === "SQLCH231")?.before;
     const currentKey = renamedFrom !== undefined && input.current.has(renamedFrom) ? renamedFrom : key;
     const live = input.current.get(currentKey);
+    // A stream table (#4396): the views that read it are detached, it is dropped and created, and they are attached again.
+    if (live && mine.some((c) => c.rule === "SQLCH225")) {
+      const dropped = new Set(input.changes.filter((c) => c.rule === "SQLCH250").map((c) => c.object));
+      const readers = [...input.current].filter(([k, o]) => !dropped.has(k) && readsTable(o, live)).map(([, o]) => o);
+      return { verdict: "alter", obj, changes: mine, steps: replaceStreamSteps(obj, live, readers, input.marker) };
+    }
     // A function has no comment, so nothing to restamp: it never carries the marker.
     const restamp =
       obj.type !== CLICKHOUSE_ENTITY_TYPES.function && !stepsSetComment(obj, mine) && (mine.some((c) => c.field === "comment") || !(input.carriesMarker?.(currentKey) ?? true));

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

@@ -23,12 +23,16 @@
  *   (#3745), so a use is found by that body (`./inlined.ts`) as well as by
  *   the name. A function carries no comment, so `owned` does
  *   not apply to it.
- * - An object of a kind no declaration holds (a window view, a quota, a
- *   settings profile, a named collection, ...; `../live/undeclarable.ts`)
- *   fails the import, which names every one of them (#3911).
+ * - An object of a kind no declaration holds (a window view, a workload,
+ *   an HTTP handler, ...; `../live/undeclarable.ts`) fails the import, which
+ *   names every one of them (#3911).
  *   `skipUndeclarable` (`--skip-undeclarable`) imports the rest and lists
  *   them as warnings. A selector or `owned` import asks for objects chant can
  *   hold, so it does not look.
+ * - A SQL-defined named collection is the environment's (#4395): the import
+ *   reads its name only, never its values, and lists it as a prerequisite
+ *   (a warning, and `metadata.prerequisites` with the imported objects that
+ *   name it) instead of refusing the server.
  */
 
 import type { ExportedTemplate, ResourceSelector } from "@intentius/chant/lexicon";
@@ -41,8 +45,9 @@ import { isTrivia, tokenizeText } from "../tokens";
 import { unquote } from "../parser";
 import type { LiveObject } from "../live/catalog";
 import { inlinedFunctions } from "./inlined";
-import { readUndeclarable } from "../live/undeclarable";
+import { readReferenced, readUndeclarable } from "../live/undeclarable";
 import { refuseUndeclarable } from "../../core/undeclarable";
+import { namedCollectionPrerequisites } from "../named-collections";
 
 /** The functions among `names` a statement calls: a name followed by `(`. */
 export function calledFunctions(ddl: string, names: ReadonlySet<string>): string[] {
@@ -137,5 +142,15 @@ export async function exportResources(options: ExportOptions): Promise<ExportedT
       name: o.name,
       ddl: options.verbatim ? o.statement : stripServerDefaults(o.statement),
     }));
-  return objectsToIR(objects, warnings) as ExportedTemplate;
+  // Named collections are the environment's (#4395): listed as prerequisites, never imported.
+  const referenced = await readReferenced(target);
+  for (const u of referenced.unread) warnings.push(`the server's named collections were not read, so the import cannot list them as prerequisites: ${u}`);
+  const { prerequisites, warnings: prereq } = namedCollectionPrerequisites(referenced.objects, objects, {
+    of: options.environment,
+    found: "the server holds it",
+    unseen: "the reader did not see it on the server (it needs SHOW NAMED COLLECTIONS)",
+  });
+  warnings.push(...prereq);
+  const ir = objectsToIR(objects, warnings);
+  return (prerequisites.length > 0 ? { ...ir, metadata: { ...ir.metadata, prerequisites } } : ir) as ExportedTemplate;
 }

package/src/clickhouse/live/named-collections.e2e.test.ts

@@ -0,0 +1,88 @@
+/**
+ * Named collections against the pinned server (#4395): a plan fails naming a
+ * collection the build references and the server lacks, and passes once it
+ * exists, without reading its values; import from a server that holds one
+ * succeeds and lists it as a prerequisite.
+ *
+ * Needs Docker; skips cleanly without it. One throwaway
+ * `clickhouse/clickhouse-server` container at the pin, removed afterwards
+ * even on failure.
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import type { SerializerResult } from "@intentius/chant/serializer";
+import { dockerAvailable, startScratchServer, type ScratchServer } from "../container";
+import { clickhouseQuery } from "../http";
+import { clickhouseImage } from "../../spec/pin";
+import { database, table } from "../entities";
+import { sqlSerializer } from "../../serializer";
+import { planAgainstServer } from "../plan/commands";
+import { renderDiff } from "../plan/report";
+import { exportResources } from "../import/live-export";
+
+const enabled = await dockerAvailable();
+let server: ScratchServer | undefined;
+const dir = mkdtempSync(join(tmpdir(), "chant-sql-named-collections-"));
+const buildFile = join(dir, "lake.json");
+const q = (sql: string) => clickhouseQuery(server!.endpoint, sql);
+
+const DB = "lakehouse";
+const db = database`CREATE DATABASE lakehouse`;
+const lake = table`CREATE TABLE ${db}.lake (a Int32) ENGINE = S3(lake_creds, url = 'http://minio:9000/bucket/x.parquet', format = 'Parquet')`;
+
+beforeAll(async () => {
+  if (!enabled) return;
+  server = await startScratchServer(clickhouseImage(), { namePrefix: "chant-sql-named-collections" });
+  const out = sqlSerializer.serialize(new Map<string, unknown>([["db", db], ["lake", lake]]) as never) as SerializerResult;
+  writeFileSync(buildFile, out.primary);
+}, 600_000);
+
+afterAll(async () => {
+  await server?.stop();
+  rmSync(dir, { recursive: true, force: true });
+});
+
+const env = (user?: string) => ({ config: {}, env: { CLICKHOUSE_URL: server!.endpoint.url, ...(user ? { CLICKHOUSE_USER: user } : {}) } });
+
+describe.skipIf(!enabled)("named collections on the pinned server", () => {
+  test("a plan against a server without lake_creds fails, naming it", async () => {
+    const diff = await planAgainstServer("e2e", buildFile, env());
+    expect(diff.namedCollections).toEqual({ referenced: ["lake_creds"], missing: ["lake_creds"] });
+    expect(renderDiff(diff)).toMatch(/Refused: the build references a named collection the server does not have: lake_creds\./);
+  }, 120_000);
+
+  test("with it, the plan passes, and no query reads its values", async () => {
+    await q("CREATE NAMED COLLECTION lake_creds AS access_key_id = 'AKIAEXAMPLE', secret_access_key = 'not-a-real-secret', url = 'http://minio:9000/bucket/'");
+    const diff = await planAgainstServer("e2e", buildFile, env());
+    expect(diff.namedCollections).toEqual({ referenced: ["lake_creds"], missing: [] });
+    await q("SYSTEM FLUSH LOGS");
+    const reads = await clickhouseQuery<{ query: string }>(
+      server!.endpoint,
+      "SELECT query FROM system.query_log WHERE type = 'QueryFinish' AND query LIKE '%chant%' AND query LIKE '%named_collections%' AND query NOT LIKE '%query_log%'",
+    );
+    expect(reads.length).toBeGreaterThan(0);
+    for (const r of reads) expect(r.query).not.toMatch(/\bcollection\b(?! \*\/)|create_query/);
+  }, 120_000);
+
+  test("a user without SHOW NAMED COLLECTIONS sees none, and the plan says so", async () => {
+    await q("CREATE USER IF NOT EXISTS planner IDENTIFIED WITH no_password");
+    await q("GRANT SELECT, SHOW ON *.* TO planner");
+    const diff = await planAgainstServer("e2e", buildFile, env("planner"));
+    expect(diff.namedCollections?.missing).toEqual(["lake_creds"]);
+    expect(renderDiff(diff)).toMatch(/grant the plan's user SHOW NAMED COLLECTIONS/);
+  }, 120_000);
+
+  test("import from a server with a SQL-defined named collection succeeds and lists it as a prerequisite", async () => {
+    await q(`CREATE DATABASE IF NOT EXISTS ${DB}`);
+    await q(`CREATE TABLE IF NOT EXISTS ${DB}.lake (a Int32) ENGINE = S3(lake_creds, url = 'http://minio:9000/bucket/x.parquet', format = 'Parquet')`);
+    const ir = await exportResources({ environment: "e2e", ...env() });
+    expect(ir.resources.map((r) => r.properties.name)).toEqual([DB, "lake"]);
+    expect(ir.metadata?.prerequisites).toEqual([{ kind: "named collection", name: "lake_creds", referencedBy: [`${DB}.lake`] }]);
+    expect(ir.warnings).toContainEqual(expect.stringMatching(/^named collection lake_creds is a prerequisite of e2e, named by lakehouse\.lake: the server holds it/));
+    // The import carries the name, never a value.
+    expect(JSON.stringify(ir)).not.toMatch(/AKIAEXAMPLE|not-a-real-secret/);
+  }, 120_000);
+});

package/src/clickhouse/live/named-collections.ts

@@ -0,0 +1,61 @@
+/**
+ * The plan's existence check for the named collections a build references
+ * (#4395): by name, in `system.named_collections`, never the `collection`
+ * or `create_query` columns, which hold the values.
+ *
+ * Checked against the pinned server (26.8.15.10): the table's columns are
+ * `name`, `collection` (a `Map(String, String)`), `source` (`SQL` or
+ * `Config`) and `create_query`. A user with `SHOW NAMED COLLECTIONS` and
+ * without `SHOW NAMED COLLECTIONS SECRETS` sees every key, with each value as
+ * `'[HIDDEN]'`, so keys could be compared without the secrets grant. A user
+ * without `SHOW NAMED COLLECTIONS` reads the table without an error and sees
+ * no rows; a collection that user cannot see is reported missing, with the
+ * grant named.
+ */
+
+import { readFileSync } from "node:fs";
+import { clickhouseQuery, type ClickHouseEndpoint } from "../http";
+import type { NamedCollectionCheck } from "../plan/diff";
+
+const quote = (s: string) => `'${s.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+
+/** The named collections a build output references (its document's `namedCollections`). */
+export function referencedCollections(buildJson: string): string[] {
+  const doc = JSON.parse(buildJson) as { namedCollections?: unknown };
+  return Array.isArray(doc.namedCollections) ? doc.namedCollections.filter((n): n is string => typeof n === "string") : [];
+}
+
+/** {@link referencedCollections} of a build output file. */
+export const referencedCollectionsOf = (buildFile: string): string[] => referencedCollections(readFileSync(buildFile, "utf-8"));
+
+/** Which of `names` the server has, by name. Undefined when nothing is referenced. */
+export async function checkNamedCollections(endpoint: ClickHouseEndpoint, names: readonly string[]): Promise<NamedCollectionCheck | undefined> {
+  if (names.length === 0) return undefined;
+  const referenced = [...new Set(names)].sort();
+  try {
+    const rows = await clickhouseQuery<{ name: string }>(
+      endpoint,
+      `/* chant plan: named collections */ SELECT name FROM system.named_collections WHERE name IN (${referenced.map(quote).join(", ")})`,
+    );
+    const have = new Set(rows.map((r) => r.name));
+    return { referenced, missing: referenced.filter((n) => !have.has(n)) };
+  } catch (err) {
+    return { referenced, missing: referenced, unread: err instanceof Error ? err.message.split("\n")[0]! : String(err) };
+  }
+}
+
+/** Whether the check fails the plan. */
+export const namedCollectionsFail = (c: NamedCollectionCheck | undefined): boolean => c !== undefined && c.missing.length > 0;
+
+/** The report's lines for a failed check; none when it passed. */
+export function renderNamedCollections(c: NamedCollectionCheck | undefined): string[] {
+  if (!c || c.missing.length === 0) return [];
+  if (c.unread !== undefined) {
+    return ["", `Refused: the build references named collection(s) ${c.missing.join(", ")}, and the server's could not be read to check them: ${c.unread}`];
+  }
+  return [
+    "",
+    `Refused: the build references ${c.missing.length === 1 ? "a named collection" : "named collections"} the server does not have: ${c.missing.join(", ")}. ` +
+      "Create each on the server (chant never declares one), or grant the plan's user SHOW NAMED COLLECTIONS if it is there and hidden from that user.",
+  ];
+}

package/src/clickhouse/live/undeclarable.e2e.test.ts

@@ -1,7 +1,8 @@
 /**
  * Import against a real ClickHouse server never leaves an object out without
- * a word (#3911): a server holding a named collection and a workload made
- * with SQL, beside a table, fails the import, which names both; a quota and a
+ * a word (#3911): a server holding a workload made with SQL, beside a
+ * table, fails the import, which names it; a named collection is the
+ * environment's (#4395), listed as a prerequisite and not refused; a quota and a
  * settings profile are declared kinds, which an import reads only when a
  * build declares them, so they are not refused; with `skipUndeclarable` the table is imported and
  * they are warnings. What `users.xml` defines (the `default` quota and
@@ -43,7 +44,7 @@ afterAll(async () => {
 
 const run = (extra: Record<string, unknown> = {}) => exportResources({ environment: "x", config: {}, env: { CLICKHOUSE_URL: server!.endpoint.url }, ...extra });
 
-const NAMED = ["named collection nc_s3", "workload all"];
+const NAMED = ["workload all"];
 
 describe.skipIf(!enabled)("importing a server with objects chant cannot declare", () => {
   test("fails, naming every one of them", async () => {
@@ -61,5 +62,6 @@ describe.skipIf(!enabled)("importing a server with objects chant cannot declare"
     expect(ir.resources.map((r) => r.properties.name)).toEqual(["analytics", "events"]);
     const left = (ir.warnings ?? []).filter((w) => w.includes("is left out (--skip-undeclarable)"));
     expect(left.map((w) => w.split(" is left out")[0]).sort()).toEqual(NAMED);
+    expect(ir.metadata?.prerequisites).toEqual([{ kind: "named collection", name: "nc_s3", referencedBy: [] }]);
   }, 120_000);
 });

package/src/clickhouse/live/undeclarable.ts

@@ -3,9 +3,11 @@
  * (#3911), found so import can refuse them by name instead of leaving them
  * out (`../../core/undeclarable.ts`).
  *
- * One `system.*` query per kind the coverage table marks refused
- * (`../../coverage/clickhouse.json`), keyed by the row's `kind`. A kind whose
- * row is flipped to declared is no longer asked about.
+ * One `system.*` query per kind the coverage table marks refused or
+ * referenced (`../../coverage/clickhouse.json`), keyed by the row's `kind`. A
+ * kind whose row is flipped to declared is no longer asked about. A
+ * referenced kind (a named collection, #4395) is read by name only, as a
+ * prerequisite the import lists, never as a refusal.
  *
  * What the server's configuration files define (`storage = 'users_xml'`, a
  * named collection whose source is the config, an executable function) is
@@ -47,12 +49,26 @@ export const CLICKHOUSE_PROBES: Readonly<Record<string, Probe>> = {
  * pass.
  */
 export async function readUndeclarable(target: ClickHouseTarget): Promise<{ objects: UndeclarableObject[]; unread: string[] }> {
+  return readKinds(target, "refused");
+}
+
+/**
+ * Every object of a kind the coverage table marks referenced (#4395): the
+ * server's SQL-defined named collections, by name. Their values are never
+ * read. A reader without `SHOW NAMED COLLECTIONS` sees none, and the server
+ * says nothing about that, so an empty list is not proof there are none.
+ */
+export async function readReferenced(target: ClickHouseTarget): Promise<{ objects: UndeclarableObject[]; unread: string[] }> {
+  return readKinds(target, "referenced");
+}
+
+async function readKinds(target: ClickHouseTarget, status: "refused" | "referenced"): Promise<{ objects: UndeclarableObject[]; unread: string[] }> {
   const scope = (column: string) =>
     target.databases ? `${column} IN (${target.databases.map(quote).join(", ")})` : `${column} NOT IN (${[...SYSTEM_DATABASES].map(quote).join(", ")})`;
   const objects: UndeclarableObject[] = [];
   const unread: string[] = [];
   for (const row of KIND_COVERAGE.clickhouse) {
-    if (row.status !== "refused") continue;
+    if (row.status !== status) continue;
     const probe = CLICKHOUSE_PROBES[row.kind];
     if (!probe) throw new Error(`no system table query finds a ClickHouse ${row.kind} (src/clickhouse/live/undeclarable.ts)`);
     try {