@intentius/chant-lexicon-sql 0.124.18 → 0.124.21

package/src/clickhouse/table-function.test.ts

@@ -0,0 +1,54 @@
+/**
+ * A table over a table function (#3911): `CREATE TABLE t AS numbers(10)`,
+ * with or without its columns, as the tag reads it, as the server prints it
+ * back, and the one statement a change takes. `live/kinds.e2e.test.ts` runs
+ * it against a server.
+ */
+
+import { describe, expect, test } from "vitest";
+import { table, CLICKHOUSE_ENTITY_TYPES } from "./entities";
+import { canonicalObject, objectKey } from "./plan/normalize";
+import { diffSchemas } from "./plan/diff";
+import { planStatements, type DeclaredObject } from "./apply/statements";
+import { renderStatement } from "./topology";
+
+const shown = "CREATE TABLE default.nums\n(\n    `number` UInt64\n) AS numbers(10)\nCOMMENT 'counting'";
+
+describe("a table over a table function", () => {
+  test("the tag reads the call, and the columns when written", () => {
+    const bare = table`CREATE TABLE default.nums AS numbers(10) COMMENT 'counting'`;
+    expect(bare.props).toMatchObject({ name: "nums", database: "default", asFunction: "numbers(10)", columns: [], comment: "counting" });
+    expect(bare.props.engine).toBeUndefined();
+    const typed = table`CREATE TABLE default.nums (number UInt64) AS numbers(10)`;
+    expect(typed.props.columns.map((c) => [c.name, c.type])).toEqual([["number", "UInt64"]]);
+  });
+
+  test("a declaration with no columns agrees with the columns the server inferred; one that lists them is compared on them", () => {
+    const same = (declared: string) => diffSchemas([{ key: "k", canonical: canonicalObject(shown) }], [{ key: "k", canonical: canonicalObject(declared) }]).changes;
+    expect(same("CREATE TABLE default.nums AS numbers(10) COMMENT 'counting'")).toEqual([]);
+    expect(same("CREATE TABLE default.nums (number UInt64) AS numbers(10) COMMENT 'counting'")).toEqual([]);
+    expect(same("CREATE TABLE default.nums (number UInt32) AS numbers(20) COMMENT 'counting'").map((c) => [c.field, c.rule, c.class])).toEqual([
+      ["asFunction", "SQLCH219", "metadata"],
+      ["columns.number", "SQLCH219", "metadata"],
+    ]);
+  });
+
+  test("a change replaces it whole, its comment with it; a table with data becoming one is a rebuild", () => {
+    const ddl = "CREATE TABLE default.nums AS numbers(20)";
+    const canonical = canonicalObject(ddl);
+    const obj: DeclaredObject = { exportName: "nums", type: CLICKHOUSE_ENTITY_TYPES.table, key: objectKey(canonical), ddl, canonical, dependsOn: [] };
+    const live = canonicalObject(shown);
+    const changes = diffSchemas([{ key: obj.key, canonical: live }], [{ key: obj.key, canonical }]).changes;
+    expect(changes.map((c) => c.field)).toEqual(["comment", "asFunction"]);
+    const entry = planStatements({ declared: [obj], changes, current: new Map([[obj.key, live]]) }).objects[0]!;
+    expect(entry.verdict === "alter" ? entry.steps.map((s) => s.sql) : []).toEqual(["CREATE OR REPLACE TABLE default.nums AS numbers(20) COMMENT '[chant managed-by=chant]'"]);
+
+    const stored = canonicalObject("CREATE TABLE default.nums (number UInt64) ENGINE = MergeTree ORDER BY number");
+    const rebuild = diffSchemas([{ key: obj.key, canonical: stored }], [{ key: obj.key, canonical }]).changes;
+    expect(rebuild.map((c) => [c.field, c.rule, c.class])).toEqual([["asFunction", "SQLCH223", "rebuild"]]);
+  });
+
+  test("ON CLUSTER after the name", () => {
+    expect(renderStatement("CREATE TABLE default.nums AS numbers(10)", { kind: "cluster", cluster: "main" })).toBe("CREATE TABLE default.nums ON CLUSTER `main` AS numbers(10)");
+  });
+});

package/src/clickhouse/testdata/server-ddl-baseline.json

@@ -22,6 +22,14 @@
     "YEARS"
   ],
   "failures": [
+    "CREATE TABLE ... AS <table> is not declared: the server copies the other table's columns and engine and keeps no link to it. Declare them (a composite can share them), or write AS <table function>(...) for a table over a table function at 'AS'",
+    "CREATE TABLE ... AS <table> is not declared: the server copies the other table's columns and engine and keeps no link to it. Declare them (a composite can share them), or write AS <table function>(...) for a table over a table function at 'as'",
+    "CREATE TABLE ... AS SELECT is not declared: it creates the table and fills it once, and the server keeps the columns, not the query. Declare the table's columns and fill it with INSERT ... SELECT, or declare a materialized view at 'AS'",
+    "CREATE TABLE ... AS SELECT is not declared: it creates the table and fills it once, and the server keeps the columns, not the query. Declare the table's columns and fill it with INSERT ... SELECT, or declare a materialized view at 'as'",
+    "CREATE TABLE ... CLONE AS is not declared: it copies another table's columns, engine and data once. Declare the columns and engine at 'CLONE'",
+    "CREATE TABLE ... EMPTY AS SELECT is not declared: the server keeps the query's columns, not the query. Declare the columns at 'empty'",
+    "declare one quota per template at ','",
+    "declare one settings profile per template at ','",
     "expected ')' at 'WITH'",
     "expected '='",
     "expected '=' at '('",
@@ -48,20 +56,15 @@
     "expected an expression",
     "expected an expression at ')'",
     "expected an expression at 'TYPE'",
-    "expected the column list (CREATE TABLE ... AS is not declared here) at 'AS'",
-    "expected the column list (CREATE TABLE ... AS is not declared here) at 'CLONE'",
-    "expected the column list (CREATE TABLE ... AS is not declared here) at 'COMMENT'",
-    "expected the column list (CREATE TABLE ... AS is not declared here) at 'ENGINE'",
-    "expected the column list (CREATE TABLE ... AS is not declared here) at 'Engine'",
-    "expected the column list (CREATE TABLE ... AS is not declared here) at 'ORDER'",
-    "expected the column list (CREATE TABLE ... AS is not declared here) at 'SQL'",
-    "expected the column list (CREATE TABLE ... AS is not declared here) at 'TO'",
-    "expected the column list (CREATE TABLE ... AS is not declared here) at 'as'",
-    "expected the column list (CREATE TABLE ... AS is not declared here) at 'empty'",
-    "expected the column list (CREATE TABLE ... AS is not declared here) at 'engine'",
+    "expected the column list (a table declared without one, CREATE TABLE ... ENGINE = ... AS SELECT, is not declared: declare the columns) at 'COMMENT'",
+    "expected the column list (a table declared without one, CREATE TABLE ... ENGINE = ... AS SELECT, is not declared: declare the columns) at 'ENGINE'",
+    "expected the column list (a table declared without one, CREATE TABLE ... ENGINE = ... AS SELECT, is not declared: declare the columns) at 'Engine'",
+    "expected the column list (a table declared without one, CREATE TABLE ... ENGINE = ... AS SELECT, is not declared: declare the columns) at 'ORDER'",
+    "expected the column list (a table declared without one, CREATE TABLE ... ENGINE = ... AS SELECT, is not declared: declare the columns) at 'SQL'",
+    "expected the column list (a table declared without one, CREATE TABLE ... ENGINE = ... AS SELECT, is not declared: declare the columns) at 'TO'",
+    "expected the column list (a table declared without one, CREATE TABLE ... ENGINE = ... AS SELECT, is not declared: declare the columns) at 'engine'",
     "unexpected end of statement",
-    "unexpected token after the table definition at 'AS'",
-    "unexpected token after the table definition at 'SETTINGS'",
-    "unexpected token after the table definition at 'as'"
+    "unexpected ipv6_prefix_bits: expected IN, KEYED BY, KEY BY, NOT KEYED, FOR, TO at 'ipv6_prefix_bits'",
+    "unexpected token after the table definition at 'SETTINGS'"
   ]
 }

package/src/clickhouse/testing/fake-server.ts

@@ -26,6 +26,8 @@ export interface FakeOptions {
   version?: string;
   /** The SQL user-defined functions `system.functions` lists. Default: none. */
   functions?: Array<{ name: string; statement: string }>;
+  /** What the undeclarable-kind probes (`../live/undeclarable.ts`) find, by the coverage table's kind. Default: nothing. */
+  undeclarable?: Array<{ kind: string; database?: string; name: string }>;
 }
 
 const row = (o: Record<string, unknown>) => `${JSON.stringify(o)}\n`;
@@ -38,6 +40,9 @@ export async function fakeClickHouse(objects: FakeObject[], options: FakeOptions
     queries.push(body);
     if (options.fail) return { status: options.fail.status, text: options.fail.body };
     if (/version\(\)/.test(body)) return ok(row({ v: options.version ?? "26.8.15.10" }));
+    // A probe for one undeclarable kind (`../live/undeclarable.ts`), which its comment names.
+    const probe = /^\/\* chant undeclarable: (.+?) \*\//.exec(body);
+    if (probe) return ok((options.undeclarable ?? []).filter((u) => u.kind === probe[1]).map((u) => row({ database: u.database ?? "", name: u.name })).join(""));
     if (/FROM system\.databases/.test(body)) {
       return ok(
         objects

package/src/clickhouse/topology.ts

@@ -352,7 +352,7 @@ function renderOtherCreate(tokens: Token[], topology: Topology): string {
   if (w.accept("OR")) w.accept("REPLACE");
   w.accept("TEMPORARY");
   // Access control (`./access.ts`) belongs to no database: like a database's own DDL, it reaches every replica through the cluster.
-  if (w.accept("USER", "ROLE", "POLICY", "QUOTA") || w.acceptSeq("ROW", "POLICY") || w.acceptSeq("SETTINGS", "PROFILE")) {
+  if (w.accept("USER", "ROLE", "POLICY", "QUOTA", "PROFILE") || w.acceptSeq("ROW", "POLICY") || w.acceptSeq("SETTINGS", "PROFILE")) {
     w.acceptSeq("IF", "NOT", "EXISTS") || w.acceptSeq("OR", "REPLACE");
     if (!w.name()) return applyEdits(tokens, []);
     const edit = onClusterEdit(w, databaseCluster(topology, true), w.end());
@@ -430,7 +430,9 @@ export function renderStatement(sql: string, topology: Topology): string {
     if (word(head, "DROP", "DETACH", "ATTACH")) w.accept("TEMPORARY");
     if (w.accept("DATABASE")) return renderAfterName(tokens, w, databaseCluster(topology, word(head, "DROP")));
     // A function and access control belong to no database: like the database's own DDL, they reach every replica through the cluster.
-    if (w.accept("FUNCTION", "USER", "ROLE", "POLICY") || w.acceptSeq("ROW", "POLICY")) return renderAfterName(tokens, w, databaseCluster(topology, true));
+    if (w.accept("FUNCTION", "USER", "ROLE", "POLICY", "QUOTA", "PROFILE") || w.acceptSeq("ROW", "POLICY") || w.acceptSeq("SETTINGS", "PROFILE")) {
+      return renderAfterName(tokens, w, databaseCluster(topology, true));
+    }
     // `TRUNCATE t` may leave out TABLE.
     if (w.accept("TABLE", "VIEW", "DICTIONARY") || word(head, "TRUNCATE")) return renderAfterName(tokens, w, objectCluster(topology));
     return sql;

package/src/clickhouse.ts

@@ -18,6 +18,8 @@ export {
   role,
   policy,
   grant,
+  quota,
+  settingsProfile,
   literal,
   SqlLiteral,
   SqlTemplateError,
@@ -35,6 +37,10 @@ export {
   type ClickHouseRole,
   type ClickHouseRowPolicy,
   type ClickHouseGrant,
+  type ClickHouseQuota,
+  type ClickHouseSettingsProfile,
+  type QuotaProps,
+  type SettingsProfileProps,
   type UserProps,
   type RoleProps,
   type RowPolicyProps,

package/src/codegen/classifier-page.test.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { expect, test } from "vitest";
 import { renderClassifierPage } from "./classifier-page";
 import { renderPostgresClassifierPage } from "./postgres-classifier-page";
+import { renderCoveragePage } from "./coverage-page";
 
 test("the committed classifier page is what the rules render (run npm run docs)", () => {
   const committed = readFileSync(join(import.meta.dirname, "..", "..", "docs", "pages", "change-classifier.mdx"), "utf-8");
@@ -14,3 +15,8 @@ test("the committed Postgres classifier page is what the rules render (run npm r
   const committed = readFileSync(join(import.meta.dirname, "..", "..", "docs", "pages", "postgres-change-classifier.mdx"), "utf-8");
   expect(committed).toBe(renderPostgresClassifierPage());
 });
+
+test("the committed object coverage page is what the coverage tables render (run npm run docs)", () => {
+  const committed = readFileSync(join(import.meta.dirname, "..", "..", "docs", "pages", "object-coverage.mdx"), "utf-8");
+  expect(committed).toBe(renderCoveragePage());
+});

package/src/codegen/coverage-page.ts

@@ -0,0 +1,77 @@
+/**
+ * `docs/pages/object-coverage.mdx`, written from the coverage tables
+ * (`../coverage/<dialect>.json`) by `npm run docs`, so the page cannot
+ * disagree with what import refuses.
+ */
+
+import { KIND_COVERAGE, PINNED_COMMANDS, type KindRow } from "../coverage";
+import type { SqlDialect } from "../dialects";
+
+const cell = (s: string) => s.replace(/\|/g, "\\|").replace(/[{}<>]/g, (c) => `\\${c}`);
+
+const STATUS: Record<KindRow["status"], string> = { declared: "declared", refused: "refused", "out-of-scope": "out of scope" };
+
+function table(dialect: SqlDialect): string {
+  const rows = [...KIND_COVERAGE[dialect]].sort((a, b) => (a.command < b.command ? -1 : a.command > b.command ? 1 : 0));
+  return [
+    "| Command | Kind | Status | Declared by, or why not |",
+    "|---|---|---|---|",
+    ...rows.map((r) => {
+      const command = `\`${r.command}\`${r.form ? ` (${cell(r.form)})` : ""}`;
+      const why = r.status === "declared" ? `\`${r.entity}\`${r.note ? `: ${cell(r.note)}` : ""}` : cell(r.reason ?? "");
+      return `| ${command} | ${cell(r.kind)} | ${STATUS[r.status]} | ${why} |`;
+    }),
+  ].join("\n");
+}
+
+function counts(dialect: SqlDialect): string {
+  const rows = KIND_COVERAGE[dialect];
+  const n = (s: KindRow["status"]) => rows.filter((r) => r.status === s).length;
+  return `${n("declared")} declared, ${n("refused")} refused, ${n("out-of-scope")} out of scope`;
+}
+
+export function renderCoveragePage(): string {
+  const pg = PINNED_COMMANDS.postgres.map((p) => p.version).join(", ");
+  const ch = PINNED_COMMANDS.clickhouse.map((p) => p.version).join(", ");
+  return `---
+title: "Object Coverage"
+label: "Object Coverage"
+description: "Every kind of object each pinned Postgres and ClickHouse server can create, marked declared, refused with a reason, or out of scope, and what import does with each"
+diataxis: reference
+order: 3
+---
+
+{/* Written by src/codegen/coverage-page.ts from src/coverage/postgres.json and src/coverage/clickhouse.json. Edit the tables, then run npm run docs. */}
+
+Each row is a \`CREATE\` command a pinned server has, or one form of a command where chant treats the forms apart (\`CREATE TYPE ... AS ENUM\` is declared, \`CREATE TYPE ... AS RANGE\` is not). The commands come from the servers' own sources at each pinned version (\`scripts/sql-create-commands.ts\`), and a test fails when a pinned server has a command with no row here, so a new server release cannot add a kind nobody looked at.
+
+- **declared**: a tag declares it, and import writes it as that declaration.
+- **refused**: no declaration holds it yet. \`chant import --from <env>\` fails when the server has one, naming every such object (kind, schema, name) at once, and \`chant import schema.sql\` fails on the statement. Nothing is left out without a word.
+- **out of scope**: the environment's, not a schema's: import never reads it.
+
+\`--skip-undeclarable\` (\`--parser-option skipUndeclarable\` for a file) imports everything else and lists the refused objects as warnings, for an adopter who keeps those objects by hand for now:
+
+\`\`\`bash
+chant import --from prod --skip-undeclarable
+chant import schema.sql --parser-option skipUndeclarable
+\`\`\`
+
+What a managed provider, an extension or the server's configuration files define is never refused: an extension's aggregates and casts are the extension's, declared with it, and a quota from \`users.xml\` is the server's. An import with \`--type\`, \`--name\` or \`--owned\` asks only for objects chant can hold, and does not look for the rest.
+
+## Postgres
+
+Pinned majors: ${pg}. ${counts("postgres")}.
+
+${table("postgres")}
+
+## ClickHouse
+
+Pinned release: ${ch}. ${counts("clickhouse")}.
+
+${table("clickhouse")}
+
+## Declaring a refused kind
+
+A kind becomes declarable in three steps: a tag that declares it, the catalog reader reading it (\`src/postgres/live/catalog.ts\`, \`src/clickhouse/live/catalog.ts\`), and its row flipped to \`declared\` with the entity type, its reason taken out. The row's flip is what stops import refusing the kind. After moving a pin, run \`npx tsx scripts/sql-create-commands.ts\` and give each new command a row.
+`;
+}

package/src/codegen/docs.ts

@@ -9,6 +9,7 @@ import { writeFileSync } from "fs";
 import { docsPipeline, writeDocsSite, type DocsConfig } from "@intentius/chant/codegen/docs";
 import { renderClassifierPage } from "./classifier-page";
 import { renderPostgresClassifierPage } from "./postgres-classifier-page";
+import { renderCoveragePage } from "./coverage-page";
 
 const overview = `The sql lexicon declares database schema in TypeScript. It has two dialects,
 each a subpath of the one package: ClickHouse at
@@ -143,6 +144,9 @@ Both dialects:
 - [Composites](./composites/): five ClickHouse and five Postgres composites.
 - [Lint Rules and Checks](./lint-rules/): every lint rule and post-synth
   check.
+- [Object Coverage](./object-coverage/): every kind of object the pinned
+  servers can create, declared, refused or out of scope, and what import
+  does with each.
 
 ## Schema changes and \`chant migrate\`
 
@@ -201,6 +205,7 @@ export async function generateDocs(opts?: { verbose?: boolean }): Promise<void>
 
   writeFileSync(join(pkgDir, "docs", "pages", "change-classifier.mdx"), renderClassifierPage());
   writeFileSync(join(pkgDir, "docs", "pages", "postgres-change-classifier.mdx"), renderPostgresClassifierPage());
+  writeFileSync(join(pkgDir, "docs", "pages", "object-coverage.mdx"), renderCoveragePage());
 
   const config: DocsConfig = {
     name: "sql",

package/src/codegen/postgres-classifier-page.ts

@@ -72,7 +72,7 @@ Two rules change class across the supported majors: a STORED generated column's
 
 ## Identity and renames
 
-An object is identified by its export name between two builds, and by its schema-qualified name against a server, which has no export names. Tables, views, materialized views, sequences and indexes share one namespace per schema, types and domains another, and schemas and extensions are matched by name. Functions and procedures share a namespace of their own and are told apart by their input parameter types, so an overload is another object; a trigger is matched by its name on its table.
+An object is identified by its export name between two builds, and by its schema-qualified name against a server, which has no export names. Tables, views, materialized views, sequences and indexes share one namespace per schema, types and domains another, and schemas and extensions are matched by name. Functions, procedures and aggregates share a namespace of their own and are told apart by their input parameter types, so an overload is another object; composite and range types share the types' namespace, collations have one of their own, a cast is named by its two types and an event trigger by its name in the database; a trigger is matched by its name on its table.
 
 A rename is declared where it happens. Before a CREATE, \`-- previously: <old name>\` says the object had another name; on a column's line, it says the column did:
 

package/src/codegen/registry.ts

@@ -23,6 +23,8 @@ const KINDS: Record<string, string> = {
   Role: CLICKHOUSE_ENTITY_TYPES.role,
   RowPolicy: CLICKHOUSE_ENTITY_TYPES.rowPolicy,
   Grant: CLICKHOUSE_ENTITY_TYPES.grant,
+  Quota: CLICKHOUSE_ENTITY_TYPES.quota,
+  SettingsProfile: CLICKHOUSE_ENTITY_TYPES.settingsProfile,
   PostgresSchema: POSTGRES_ENTITY_TYPES.schema,
   PostgresTable: POSTGRES_ENTITY_TYPES.table,
   PostgresIndex: POSTGRES_ENTITY_TYPES.index,
@@ -30,7 +32,13 @@ const KINDS: Record<string, string> = {
   PostgresMaterializedView: POSTGRES_ENTITY_TYPES.materializedView,
   PostgresSequence: POSTGRES_ENTITY_TYPES.sequence,
   PostgresEnum: POSTGRES_ENTITY_TYPES.enum,
+  PostgresCompositeType: POSTGRES_ENTITY_TYPES.composite,
+  PostgresRangeType: POSTGRES_ENTITY_TYPES.range,
   PostgresDomain: POSTGRES_ENTITY_TYPES.domain,
+  PostgresAggregate: POSTGRES_ENTITY_TYPES.aggregate,
+  PostgresCollation: POSTGRES_ENTITY_TYPES.collation,
+  PostgresCast: POSTGRES_ENTITY_TYPES.cast,
+  PostgresEventTrigger: POSTGRES_ENTITY_TYPES.eventTrigger,
   PostgresExtension: POSTGRES_ENTITY_TYPES.extension,
   PostgresFunction: POSTGRES_ENTITY_TYPES.function,
   PostgresProcedure: POSTGRES_ENTITY_TYPES.procedure,

package/src/core/undeclarable.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Import never leaves an object out without a word (#3911): an object of a
+ * kind no declaration holds fails the import, which names every one, and
+ * `skipUndeclarable` turns the failure into a warning per object. Against
+ * fakes; the e2e tests (`../postgres/live/undeclarable.e2e.test.ts`,
+ * `../clickhouse/live/undeclarable.e2e.test.ts`) run the same against servers.
+ */
+
+import { afterAll, beforeAll, describe, expect, test, vi } from "vitest";
+import { fakeClient, type FakeCatalog } from "../postgres/testing/fake-client";
+import { fakeClickHouse, type FakeServer } from "../clickhouse/testing/fake-server";
+import { exportResources as exportClickHouse } from "../clickhouse/import/live-export";
+import { SqlFileParser } from "../import-parser";
+import { UndeclarableObjectsError } from "./undeclarable";
+
+const pg: { catalog: FakeCatalog; provider?: string } = { catalog: {} };
+
+vi.mock("../postgres/live/bind", async (orig) => ({
+  ...(await orig<typeof import("../postgres/live/bind")>()),
+  bindPostgres: async () => ({
+    target: { endpoint: { url: "postgres://x/db" }, source: "test", defaultSchema: "public", ...(pg.provider ? { provider: pg.provider } : {}) },
+    client: fakeClient(pg.catalog),
+  }),
+}));
+
+const { exportResources: exportPostgres } = await import("../postgres/import/live-export");
+
+const CATALOG: FakeCatalog = {
+  schemas: [{ name: "app" }],
+  tables: [{ schema: "app", name: "users", columns: [{ name: "id", type: "bigint", notnull: true }] }],
+  undeclarable: [
+    { kind: "access method", name: "heap2" },
+    { kind: "conversion", schema: "app", name: "latin1_utf8" },
+    { kind: "rule", schema: "app", name: "users_notify ON users" },
+    { kind: "base type", schema: "app", name: "later" },
+  ],
+};
+
+describe("Postgres live import", () => {
+  test("fails naming every object of a kind chant cannot declare, and why", async () => {
+    pg.catalog = CATALOG;
+    const err = await exportPostgres({ environment: "prod" }).then(
+      () => undefined,
+      (e: unknown) => e,
+    );
+    expect(err).toBeInstanceOf(UndeclarableObjectsError);
+    const message = (err as Error).message;
+    for (const line of ["  - access method heap2", "  - conversion app.latin1_utf8", "  - rule app.users_notify ON users", "  - base type app.later"]) {
+      expect(message).toContain(line);
+    }
+    expect(message).toContain("  - conversion: no tag declares an encoding conversion");
+    expect(message).toContain("--skip-undeclarable");
+  });
+
+  test("with skipUndeclarable, imports the rest and warns once per object", async () => {
+    pg.catalog = CATALOG;
+    const ir = await exportPostgres({ environment: "prod", skipUndeclarable: true });
+    expect(ir.resources.map((r) => r.properties.name)).toContain("users");
+    const left = (ir.warnings ?? []).filter((w) => w.includes("is left out (--skip-undeclarable)"));
+    expect(left).toHaveLength(4);
+    expect(left[0]).toBe("access method heap2 is left out (--skip-undeclarable): no tag declares an access method; an extension usually installs one, and the extension is declared instead");
+  });
+
+  test("a selector or owned import does not look", async () => {
+    pg.catalog = CATALOG;
+    await expect(exportPostgres({ environment: "prod", selector: { type: "Postgres::Table" } })).resolves.toBeDefined();
+    await expect(exportPostgres({ environment: "prod", owned: true })).resolves.toBeDefined();
+  });
+
+  test("a managed provider's own objects are its, with a warning, not a refusal", async () => {
+    pg.catalog = { ...CATALOG, undeclarable: [{ kind: "conversion", schema: "auth", name: "x" }] };
+    pg.provider = "supabase";
+    try {
+      const ir = await exportPostgres({ environment: "prod" });
+      expect(ir.warnings).toContain("conversion auth.x is kept by Supabase; left out");
+    } finally {
+      pg.provider = undefined;
+    }
+  });
+});
+
+describe("ClickHouse live import", () => {
+  let server: FakeServer;
+  beforeAll(async () => {
+    server = await fakeClickHouse(
+      [
+        { 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" },
+        { database: "analytics", name: "wv", engine: "WindowView", statement: "CREATE WINDOW VIEW analytics.wv AS SELECT 1" },
+      ],
+      {
+        undeclarable: [
+          { kind: "named collection", name: "nc1" },
+          { kind: "workload", name: "all" },
+          { kind: "window view", database: "analytics", name: "wv" },
+        ],
+      },
+    );
+  });
+  afterAll(() => server.close());
+  const run = (extra: Record<string, unknown> = {}) => exportClickHouse({ environment: "x", config: {}, env: { CLICKHOUSE_URL: server.url }, ...extra });
+
+  test("fails naming them", async () => {
+    await expect(run()).rejects.toThrow(/  - named collection nc1\n  - window view analytics\.wv\n  - workload all\n/);
+  });
+
+  test("with skipUndeclarable, warns, and the window view is not imported as a table", async () => {
+    const ir = await run({ skipUndeclarable: true });
+    expect(ir.resources.map((r) => r.properties.name)).toEqual(["analytics", "events"]);
+    expect((ir.warnings ?? []).filter((w) => w.includes("--skip-undeclarable"))).toHaveLength(3);
+  });
+});
+
+describe("file import", () => {
+  const DDL = `CREATE SCHEMA app;
+CREATE TABLE app.t (id int PRIMARY KEY);
+CREATE AGGREGATE app.total(int) (sfunc = int4pl, stype = int);
+CREATE CONVERSION app.latin1_utf8 FOR 'LATIN1' TO 'UTF8' FROM iso8859_1_to_utf8;
+CREATE TYPE app.pair AS (a int, b text);
+CREATE TYPE app.later;
+CREATE COLLATION app.ci (provider = icu, locale = 'und');`;
+
+  test("a CREATE of a kind chant cannot declare is an error naming it", () => {
+    expect(() => new SqlFileParser("postgres").parse(DDL)).toThrow(/conversion: chant cannot declare it \(no tag declares an encoding conversion\): CREATE CONVERSION app\.latin1_utf8/);
+  });
+
+  test("skipUndeclarable imports the rest and lists them as warnings", () => {
+    const ir = new SqlFileParser("postgres", { skipUndeclarable: true }).parse(DDL);
+    // An aggregate, a composite type and a collation are declared kinds (#3911): imported, not refused.
+    expect(ir.resources.map((r) => r.properties.name)).toEqual(["app", "t", "total", "pair", "ci"]);
+    expect(ir.warnings).toEqual([
+      "left out (skipUndeclarable): conversion: chant cannot declare it (no tag declares an encoding conversion): CREATE CONVERSION app.latin1_utf8 FOR 'LATIN1' TO 'UTF8' FROM iso8859_1_to_utf8",
+      "left out (skipUndeclarable): base type: chant cannot declare it (no tag declares a base type; its input and output functions are C code an extension installs): CREATE TYPE app.later",
+    ]);
+  });
+
+  test("ClickHouse: a named collection in a file is refused too; a quota is declared (#3911)", () => {
+    expect(() => new SqlFileParser("clickhouse").parse("CREATE DATABASE a;\nCREATE NAMED COLLECTION c AS url = 'x'")).toThrow(/named collection: chant cannot declare it/);
+    expect(new SqlFileParser("clickhouse").parse("CREATE DATABASE a;\nCREATE QUOTA q1").resources.map((r) => r.type)).toEqual(["ClickHouse::Database", "ClickHouse::Quota"]);
+  });
+});

package/src/core/undeclarable.ts

@@ -0,0 +1,66 @@
+/**
+ * Objects an import finds that no declaration can hold (#3911).
+ *
+ * Import reads every kind of object the server has, not only the kinds chant
+ * declares, so none is left out without a word. An object of a kind the
+ * coverage table marks refused (`../coverage.ts`) is collected here, and the
+ * import fails naming every one of them at once: kind, schema and name.
+ * `--skip-undeclarable` imports the rest and lists them as warnings instead,
+ * so an adopter is not stuck behind an aggregate they mean to keep by hand.
+ */
+
+import { kindRow } from "../coverage";
+import type { SqlDialect } from "../dialects";
+
+/** One object of a kind chant cannot declare. */
+export interface UndeclarableObject {
+  /** The coverage table's kind: `aggregate`, `composite type`. */
+  kind: string;
+  /** The Postgres schema or ClickHouse database it is in; absent for a database-wide or server-wide object. */
+  schema?: string;
+  /** Its name, with what identifies it besides: an aggregate's argument types, a rule's table, a cast's types. */
+  name: string;
+  /** The role or user that owns it, where that tells a managed provider's own object from the database owner's. */
+  owner?: string;
+}
+
+/** `aggregate app.total(integer)`. */
+export const describeUndeclarable = (o: UndeclarableObject): string => `${o.kind} ${o.schema ? `${o.schema}.` : ""}${o.name}`;
+
+const DOCS = "https://intentius.io/chant/lexicons/sql/object-coverage/";
+
+/** The import's refusal: every undeclarable object, then why for each kind among them. */
+export class UndeclarableObjectsError extends Error {
+  constructor(
+    readonly dialect: SqlDialect,
+    readonly objects: readonly UndeclarableObject[],
+  ) {
+    const kinds = [...new Set(objects.map((o) => o.kind))];
+    const n = objects.length;
+    super(
+      [
+        `the ${dialect === "postgres" ? "Postgres" : "ClickHouse"} server has ${n === 1 ? "an object" : `${n} objects`} of a kind chant cannot declare, so the import would leave ${n === 1 ? "it" : "them"} out:`,
+        ...objects.map((o) => `  - ${describeUndeclarable(o)}`),
+        "Why, by kind:",
+        ...kinds.map((k) => `  - ${k}: ${kindRow(dialect, k).reason ?? "not declared"}`),
+        `To import everything else and list ${n === 1 ? "it" : "these"} as warnings, run the import again with --skip-undeclarable. Which kinds chant declares: ${DOCS}`,
+      ].join("\n"),
+    );
+    this.name = "UndeclarableObjectsError";
+  }
+}
+
+/** One warning per object, for `--skip-undeclarable`. */
+export function undeclarableWarnings(dialect: SqlDialect, objects: readonly UndeclarableObject[]): string[] {
+  return objects.map((o) => `${describeUndeclarable(o)} is left out (--skip-undeclarable): ${kindRow(dialect, o.kind).reason ?? "chant cannot declare it"}`);
+}
+
+/**
+ * Refuse the import when it found undeclarable objects, or, with `skip`,
+ * add a warning per object to `warnings`. Nothing found is nothing to do.
+ */
+export function refuseUndeclarable(dialect: SqlDialect, objects: readonly UndeclarableObject[], skip: boolean | undefined, warnings: string[]): void {
+  if (objects.length === 0) return;
+  if (!skip) throw new UndeclarableObjectsError(dialect, objects);
+  warnings.push(...undeclarableWarnings(dialect, objects));
+}

package/src/coverage/clickhouse-commands.json

@@ -0,0 +1,24 @@
+{
+  "source": "src/Parsers/ParserCreate*.h and src/Parsers/Access/ParserCreate*.h, at the pinned release's tag",
+  "version": "26.8.15.10",
+  "tag": "v26.8.15.10-lts",
+  "commands": [
+    "CREATE DATABASE",
+    "CREATE DICTIONARY",
+    "CREATE FUNCTION",
+    "CREATE HANDLER",
+    "CREATE INDEX",
+    "CREATE MASKING POLICY",
+    "CREATE NAMED COLLECTION",
+    "CREATE QUOTA",
+    "CREATE RESOURCE",
+    "CREATE ROLE",
+    "CREATE ROW POLICY",
+    "CREATE SETTINGS PROFILE",
+    "CREATE TABLE",
+    "CREATE USER",
+    "CREATE VIEW",
+    "CREATE WINDOW VIEW",
+    "CREATE WORKLOAD"
+  ]
+}

package/src/coverage/clickhouse.json

@@ -0,0 +1,25 @@
+{
+  "dialect": "clickhouse",
+  "kinds": [
+    { "command": "CREATE DATABASE", "kind": "database", "status": "declared", "entity": "ClickHouse::Database" },
+    { "command": "CREATE DICTIONARY", "kind": "dictionary", "status": "declared", "entity": "ClickHouse::Dictionary" },
+    { "command": "CREATE FUNCTION", "kind": "SQL function", "status": "declared", "entity": "ClickHouse::Function" },
+    { "command": "CREATE FUNCTION", "form": "LANGUAGE WASM, or with a driver", "match": "\\bLANGUAGE\\b|\\bUSING\\s+DRIVER\\b", "kind": "non-SQL function", "status": "refused", "reason": "only a SQL function (CREATE FUNCTION f AS (x) -> ...) is declared" },
+    { "command": "CREATE HANDLER", "kind": "HTTP handler", "status": "refused", "reason": "an HTTP handler is server-level configuration, not a schema object" },
+    { "command": "CREATE INDEX", "kind": "index", "status": "declared", "entity": "ClickHouse::Table", "note": "an index is part of its table: SHOW CREATE TABLE prints it, and the table's declaration holds it" },
+    { "command": "CREATE MASKING POLICY", "kind": "masking policy", "status": "refused", "reason": "masking policies are available only in ClickHouse Cloud, not on the pinned server" },
+    { "command": "CREATE NAMED COLLECTION", "kind": "named collection", "status": "refused", "reason": "a named collection holds credentials (a password, a secret key), which are the environment's and never in a build; the server hides its values, so a plan could not compare them either" },
+    { "command": "CREATE QUOTA", "kind": "quota", "status": "declared", "entity": "ClickHouse::Quota", "note": "import reads only the access objects a build declares" },
+    { "command": "CREATE RESOURCE", "kind": "workload resource", "status": "refused", "reason": "a resource is server-level scheduling (a disk's reads or writes), configured with the server, not a schema object" },
+    { "command": "CREATE ROLE", "kind": "role", "status": "declared", "entity": "ClickHouse::Role", "note": "import reads only the access objects a build declares" },
+    { "command": "CREATE ROW POLICY", "kind": "row policy", "status": "declared", "entity": "ClickHouse::RowPolicy", "note": "import reads only the access objects a build declares" },
+    { "command": "CREATE SETTINGS PROFILE", "kind": "settings profile", "status": "declared", "entity": "ClickHouse::SettingsProfile", "note": "import reads only the access objects a build declares" },
+    { "command": "CREATE TABLE", "kind": "table", "status": "declared", "entity": "ClickHouse::Table" },
+    { "command": "CREATE TABLE", "form": "TEMPORARY", "match": "^CREATE\\s+TEMPORARY\\b", "kind": "temporary table", "status": "out-of-scope", "reason": "a temporary table lives in one session" },
+    { "command": "CREATE USER", "kind": "user", "status": "declared", "entity": "ClickHouse::User", "note": "import reads only the access objects a build declares" },
+    { "command": "CREATE VIEW", "kind": "view", "status": "declared", "entity": "ClickHouse::View" },
+    { "command": "CREATE VIEW", "form": "MATERIALIZED", "match": "^CREATE\\s+(?:OR\\s+REPLACE\\s+)?MATERIALIZED\\b", "kind": "materialized view", "status": "declared", "entity": "ClickHouse::MaterializedView" },
+    { "command": "CREATE WINDOW VIEW", "kind": "window view", "status": "refused", "reason": "a window view is experimental, and the pinned server refuses it under its default query analyzer" },
+    { "command": "CREATE WORKLOAD", "kind": "workload", "status": "refused", "reason": "a workload is server-level scheduling, configured with the server, not a schema object" }
+  ]
+}