@intentius/chant-lexicon-sql 0.124.18 → 0.124.19

package/src/core/undeclarable.test.ts

@@ -0,0 +1,138 @@
+/**
+ * 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: "aggregate", schema: "app", name: "total(integer)" },
+    { kind: "cast", name: "(app.pair AS text)" },
+    { kind: "composite type", schema: "app", name: "pair" },
+    { kind: "event trigger", name: "audit_ddl" },
+  ],
+};
+
+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 ["  - aggregate app.total(integer)", "  - cast (app.pair AS text)", "  - composite type app.pair", "  - event trigger audit_ddl"]) {
+      expect(message).toContain(line);
+    }
+    expect(message).toContain("  - aggregate: no tag declares an aggregate yet");
+    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("aggregate app.total(integer) is left out (--skip-undeclarable): no tag declares an aggregate yet");
+  });
+
+  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: "aggregate", schema: "auth", name: "x(integer)" }] };
+    pg.provider = "supabase";
+    try {
+      const ir = await exportPostgres({ environment: "prod" });
+      expect(ir.warnings).toContain("aggregate auth.x(integer) 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: "quota", name: "q1" },
+          { kind: "settings profile", name: "sp1" },
+          { 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(/  - quota q1\n  - settings profile sp1\n  - window view analytics\.wv\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 TYPE app.pair AS (a int, b text);
+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(/aggregate: chant cannot declare it \(no tag declares an aggregate yet\): CREATE AGGREGATE app\.total/);
+  });
+
+  test("skipUndeclarable imports the rest and lists them as warnings", () => {
+    const ir = new SqlFileParser("postgres", { skipUndeclarable: true }).parse(DDL);
+    expect(ir.resources.map((r) => r.properties.name)).toEqual(["app", "t"]);
+    expect(ir.warnings).toEqual([
+      "left out (skipUndeclarable): aggregate: chant cannot declare it (no tag declares an aggregate yet): CREATE AGGREGATE app.total(int) (sfunc = int4pl, stype = int)",
+      "left out (skipUndeclarable): composite type: chant cannot declare it (no tag declares a composite type yet): CREATE TYPE app.pair AS (a int, b text)",
+      "left out (skipUndeclarable): collation: chant cannot declare it (no tag declares a collation yet): CREATE COLLATION app.ci (provider = icu, locale = 'und')",
+    ]);
+  });
+
+  test("ClickHouse: a quota in a file is refused too", () => {
+    expect(() => new SqlFileParser("clickhouse").parse("CREATE DATABASE a;\nCREATE QUOTA q1")).toThrow(/quota: chant cannot declare it/);
+  });
+});

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": "no declaration holds an HTTP handler yet" },
+    { "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": "no declaration holds a masking policy yet" },
+    { "command": "CREATE NAMED COLLECTION", "kind": "named collection", "status": "refused", "reason": "no declaration holds a named collection yet; one usually carries credentials" },
+    { "command": "CREATE QUOTA", "kind": "quota", "status": "refused", "reason": "no declaration holds a quota yet" },
+    { "command": "CREATE RESOURCE", "kind": "workload resource", "status": "refused", "reason": "no declaration holds a workload scheduling resource yet" },
+    { "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": "refused", "reason": "no declaration holds a settings profile yet" },
+    { "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": "no declaration holds a window view, an experimental feature" },
+    { "command": "CREATE WORKLOAD", "kind": "workload", "status": "refused", "reason": "no declaration holds a workload yet" }
+  ]
+}

package/src/coverage/postgres-commands.json

@@ -0,0 +1,245 @@
+{
+  "source": "doc/src/sgml/ref/create_*.sgml <refname>, at each pinned major's tag",
+  "majors": {
+    "14": {
+      "version": "14.24",
+      "tag": "REL_14_24",
+      "commands": [
+        "CREATE ACCESS METHOD",
+        "CREATE AGGREGATE",
+        "CREATE CAST",
+        "CREATE COLLATION",
+        "CREATE CONVERSION",
+        "CREATE DATABASE",
+        "CREATE DOMAIN",
+        "CREATE EVENT TRIGGER",
+        "CREATE EXTENSION",
+        "CREATE FOREIGN DATA WRAPPER",
+        "CREATE FOREIGN TABLE",
+        "CREATE FUNCTION",
+        "CREATE GROUP",
+        "CREATE INDEX",
+        "CREATE LANGUAGE",
+        "CREATE MATERIALIZED VIEW",
+        "CREATE OPERATOR",
+        "CREATE OPERATOR CLASS",
+        "CREATE OPERATOR FAMILY",
+        "CREATE POLICY",
+        "CREATE PROCEDURE",
+        "CREATE PUBLICATION",
+        "CREATE ROLE",
+        "CREATE RULE",
+        "CREATE SCHEMA",
+        "CREATE SEQUENCE",
+        "CREATE SERVER",
+        "CREATE STATISTICS",
+        "CREATE SUBSCRIPTION",
+        "CREATE TABLE",
+        "CREATE TABLE AS",
+        "CREATE TABLESPACE",
+        "CREATE TEXT SEARCH CONFIGURATION",
+        "CREATE TEXT SEARCH DICTIONARY",
+        "CREATE TEXT SEARCH PARSER",
+        "CREATE TEXT SEARCH TEMPLATE",
+        "CREATE TRANSFORM",
+        "CREATE TRIGGER",
+        "CREATE TYPE",
+        "CREATE USER",
+        "CREATE USER MAPPING",
+        "CREATE VIEW"
+      ]
+    },
+    "15": {
+      "version": "15.19",
+      "tag": "REL_15_19",
+      "commands": [
+        "CREATE ACCESS METHOD",
+        "CREATE AGGREGATE",
+        "CREATE CAST",
+        "CREATE COLLATION",
+        "CREATE CONVERSION",
+        "CREATE DATABASE",
+        "CREATE DOMAIN",
+        "CREATE EVENT TRIGGER",
+        "CREATE EXTENSION",
+        "CREATE FOREIGN DATA WRAPPER",
+        "CREATE FOREIGN TABLE",
+        "CREATE FUNCTION",
+        "CREATE GROUP",
+        "CREATE INDEX",
+        "CREATE LANGUAGE",
+        "CREATE MATERIALIZED VIEW",
+        "CREATE OPERATOR",
+        "CREATE OPERATOR CLASS",
+        "CREATE OPERATOR FAMILY",
+        "CREATE POLICY",
+        "CREATE PROCEDURE",
+        "CREATE PUBLICATION",
+        "CREATE ROLE",
+        "CREATE RULE",
+        "CREATE SCHEMA",
+        "CREATE SEQUENCE",
+        "CREATE SERVER",
+        "CREATE STATISTICS",
+        "CREATE SUBSCRIPTION",
+        "CREATE TABLE",
+        "CREATE TABLE AS",
+        "CREATE TABLESPACE",
+        "CREATE TEXT SEARCH CONFIGURATION",
+        "CREATE TEXT SEARCH DICTIONARY",
+        "CREATE TEXT SEARCH PARSER",
+        "CREATE TEXT SEARCH TEMPLATE",
+        "CREATE TRANSFORM",
+        "CREATE TRIGGER",
+        "CREATE TYPE",
+        "CREATE USER",
+        "CREATE USER MAPPING",
+        "CREATE VIEW"
+      ]
+    },
+    "16": {
+      "version": "16.15",
+      "tag": "REL_16_15",
+      "commands": [
+        "CREATE ACCESS METHOD",
+        "CREATE AGGREGATE",
+        "CREATE CAST",
+        "CREATE COLLATION",
+        "CREATE CONVERSION",
+        "CREATE DATABASE",
+        "CREATE DOMAIN",
+        "CREATE EVENT TRIGGER",
+        "CREATE EXTENSION",
+        "CREATE FOREIGN DATA WRAPPER",
+        "CREATE FOREIGN TABLE",
+        "CREATE FUNCTION",
+        "CREATE GROUP",
+        "CREATE INDEX",
+        "CREATE LANGUAGE",
+        "CREATE MATERIALIZED VIEW",
+        "CREATE OPERATOR",
+        "CREATE OPERATOR CLASS",
+        "CREATE OPERATOR FAMILY",
+        "CREATE POLICY",
+        "CREATE PROCEDURE",
+        "CREATE PUBLICATION",
+        "CREATE ROLE",
+        "CREATE RULE",
+        "CREATE SCHEMA",
+        "CREATE SEQUENCE",
+        "CREATE SERVER",
+        "CREATE STATISTICS",
+        "CREATE SUBSCRIPTION",
+        "CREATE TABLE",
+        "CREATE TABLE AS",
+        "CREATE TABLESPACE",
+        "CREATE TEXT SEARCH CONFIGURATION",
+        "CREATE TEXT SEARCH DICTIONARY",
+        "CREATE TEXT SEARCH PARSER",
+        "CREATE TEXT SEARCH TEMPLATE",
+        "CREATE TRANSFORM",
+        "CREATE TRIGGER",
+        "CREATE TYPE",
+        "CREATE USER",
+        "CREATE USER MAPPING",
+        "CREATE VIEW"
+      ]
+    },
+    "17": {
+      "version": "17.11",
+      "tag": "REL_17_11",
+      "commands": [
+        "CREATE ACCESS METHOD",
+        "CREATE AGGREGATE",
+        "CREATE CAST",
+        "CREATE COLLATION",
+        "CREATE CONVERSION",
+        "CREATE DATABASE",
+        "CREATE DOMAIN",
+        "CREATE EVENT TRIGGER",
+        "CREATE EXTENSION",
+        "CREATE FOREIGN DATA WRAPPER",
+        "CREATE FOREIGN TABLE",
+        "CREATE FUNCTION",
+        "CREATE GROUP",
+        "CREATE INDEX",
+        "CREATE LANGUAGE",
+        "CREATE MATERIALIZED VIEW",
+        "CREATE OPERATOR",
+        "CREATE OPERATOR CLASS",
+        "CREATE OPERATOR FAMILY",
+        "CREATE POLICY",
+        "CREATE PROCEDURE",
+        "CREATE PUBLICATION",
+        "CREATE ROLE",
+        "CREATE RULE",
+        "CREATE SCHEMA",
+        "CREATE SEQUENCE",
+        "CREATE SERVER",
+        "CREATE STATISTICS",
+        "CREATE SUBSCRIPTION",
+        "CREATE TABLE",
+        "CREATE TABLE AS",
+        "CREATE TABLESPACE",
+        "CREATE TEXT SEARCH CONFIGURATION",
+        "CREATE TEXT SEARCH DICTIONARY",
+        "CREATE TEXT SEARCH PARSER",
+        "CREATE TEXT SEARCH TEMPLATE",
+        "CREATE TRANSFORM",
+        "CREATE TRIGGER",
+        "CREATE TYPE",
+        "CREATE USER",
+        "CREATE USER MAPPING",
+        "CREATE VIEW"
+      ]
+    },
+    "18": {
+      "version": "18.6",
+      "tag": "REL_18_6",
+      "commands": [
+        "CREATE ACCESS METHOD",
+        "CREATE AGGREGATE",
+        "CREATE CAST",
+        "CREATE COLLATION",
+        "CREATE CONVERSION",
+        "CREATE DATABASE",
+        "CREATE DOMAIN",
+        "CREATE EVENT TRIGGER",
+        "CREATE EXTENSION",
+        "CREATE FOREIGN DATA WRAPPER",
+        "CREATE FOREIGN TABLE",
+        "CREATE FUNCTION",
+        "CREATE GROUP",
+        "CREATE INDEX",
+        "CREATE LANGUAGE",
+        "CREATE MATERIALIZED VIEW",
+        "CREATE OPERATOR",
+        "CREATE OPERATOR CLASS",
+        "CREATE OPERATOR FAMILY",
+        "CREATE POLICY",
+        "CREATE PROCEDURE",
+        "CREATE PUBLICATION",
+        "CREATE ROLE",
+        "CREATE RULE",
+        "CREATE SCHEMA",
+        "CREATE SEQUENCE",
+        "CREATE SERVER",
+        "CREATE STATISTICS",
+        "CREATE SUBSCRIPTION",
+        "CREATE TABLE",
+        "CREATE TABLE AS",
+        "CREATE TABLESPACE",
+        "CREATE TEXT SEARCH CONFIGURATION",
+        "CREATE TEXT SEARCH DICTIONARY",
+        "CREATE TEXT SEARCH PARSER",
+        "CREATE TEXT SEARCH TEMPLATE",
+        "CREATE TRANSFORM",
+        "CREATE TRIGGER",
+        "CREATE TYPE",
+        "CREATE USER",
+        "CREATE USER MAPPING",
+        "CREATE VIEW"
+      ]
+    }
+  }
+}

package/src/coverage/postgres.json

@@ -0,0 +1,51 @@
+{
+  "dialect": "postgres",
+  "kinds": [
+    { "command": "CREATE ACCESS METHOD", "kind": "access method", "status": "refused", "reason": "no tag declares an access method; an extension usually installs one, and the extension is declared instead" },
+    { "command": "CREATE AGGREGATE", "kind": "aggregate", "status": "refused", "reason": "no tag declares an aggregate yet" },
+    { "command": "CREATE CAST", "kind": "cast", "status": "refused", "reason": "no tag declares a cast yet" },
+    { "command": "CREATE COLLATION", "kind": "collation", "status": "refused", "reason": "no tag declares a collation yet" },
+    { "command": "CREATE CONVERSION", "kind": "conversion", "status": "refused", "reason": "no tag declares an encoding conversion" },
+    { "command": "CREATE DATABASE", "kind": "database", "status": "out-of-scope", "reason": "a project's schema lives in one database, which the environment provides (sql.profiles.<env>)" },
+    { "command": "CREATE DOMAIN", "kind": "domain", "status": "declared", "entity": "Postgres::Domain" },
+    { "command": "CREATE EVENT TRIGGER", "kind": "event trigger", "status": "refused", "reason": "no tag declares an event trigger yet" },
+    { "command": "CREATE EXTENSION", "kind": "extension", "status": "declared", "entity": "Postgres::Extension" },
+    { "command": "CREATE FOREIGN DATA WRAPPER", "kind": "foreign data wrapper", "status": "refused", "reason": "no tag declares a foreign data wrapper yet; one an extension installs comes with the extension" },
+    { "command": "CREATE FOREIGN TABLE", "kind": "foreign table", "status": "refused", "reason": "no tag declares a foreign table yet" },
+    { "command": "CREATE FUNCTION", "kind": "function", "status": "declared", "entity": "Postgres::Function" },
+    { "command": "CREATE FUNCTION", "form": "RETURN or BEGIN ATOMIC body", "match": "\\b(?:RETURN|BEGIN\\s+ATOMIC)\\b", "kind": "routine with a SQL-standard body", "status": "refused", "reason": "the server stores a SQL-standard body parsed and prints it back rewritten, so a declaration cannot be compared with it; declare the routine with a string body (AS $$ ... $$)" },
+    { "command": "CREATE GROUP", "kind": "group", "status": "declared", "entity": "Postgres::Role", "note": "an alias of CREATE ROLE" },
+    { "command": "CREATE INDEX", "kind": "index", "status": "declared", "entity": "Postgres::Index" },
+    { "command": "CREATE LANGUAGE", "kind": "procedural language", "status": "refused", "reason": "no tag declares a procedural language; an extension installs one, and the extension is declared instead" },
+    { "command": "CREATE MATERIALIZED VIEW", "kind": "materialized view", "status": "declared", "entity": "Postgres::MaterializedView" },
+    { "command": "CREATE OPERATOR", "kind": "operator", "status": "refused", "reason": "no tag declares an operator yet" },
+    { "command": "CREATE OPERATOR CLASS", "kind": "operator class", "status": "refused", "reason": "no tag declares an operator class yet" },
+    { "command": "CREATE OPERATOR FAMILY", "kind": "operator family", "status": "refused", "reason": "no tag declares an operator family yet" },
+    { "command": "CREATE POLICY", "kind": "policy", "status": "declared", "entity": "Postgres::Policy", "note": "read where the profile manages access (sql.profiles.<env>.access)" },
+    { "command": "CREATE PROCEDURE", "kind": "procedure", "status": "declared", "entity": "Postgres::Procedure" },
+    { "command": "CREATE PUBLICATION", "kind": "publication", "status": "refused", "reason": "no tag declares a publication yet" },
+    { "command": "CREATE ROLE", "kind": "role", "status": "declared", "entity": "Postgres::Role", "note": "import reads only the roles a build declares, since a role is the cluster's" },
+    { "command": "CREATE RULE", "kind": "rule", "status": "refused", "reason": "no tag declares a rewrite rule; a view's own rule is the view's" },
+    { "command": "CREATE SCHEMA", "kind": "schema", "status": "declared", "entity": "Postgres::Schema" },
+    { "command": "CREATE SEQUENCE", "kind": "sequence", "status": "declared", "entity": "Postgres::Sequence" },
+    { "command": "CREATE SERVER", "kind": "foreign server", "status": "refused", "reason": "no tag declares a foreign server yet" },
+    { "command": "CREATE STATISTICS", "kind": "extended statistics", "status": "refused", "reason": "no tag declares extended statistics yet" },
+    { "command": "CREATE SUBSCRIPTION", "kind": "subscription", "status": "refused", "reason": "no tag declares a subscription yet" },
+    { "command": "CREATE TABLE", "kind": "table", "status": "declared", "entity": "Postgres::Table" },
+    { "command": "CREATE TABLE AS", "kind": "table from a query", "status": "declared", "entity": "Postgres::Table", "note": "the server keeps no query, so the table it made reads as a CREATE TABLE" },
+    { "command": "CREATE TABLESPACE", "kind": "tablespace", "status": "out-of-scope", "reason": "a tablespace is the cluster's, a directory on the server; a table's TABLESPACE clause is kept" },
+    { "command": "CREATE TEXT SEARCH CONFIGURATION", "kind": "text search configuration", "status": "refused", "reason": "no tag declares a text search configuration yet" },
+    { "command": "CREATE TEXT SEARCH DICTIONARY", "kind": "text search dictionary", "status": "refused", "reason": "no tag declares a text search dictionary yet" },
+    { "command": "CREATE TEXT SEARCH PARSER", "kind": "text search parser", "status": "refused", "reason": "no tag declares a text search parser; one is C code an extension installs" },
+    { "command": "CREATE TEXT SEARCH TEMPLATE", "kind": "text search template", "status": "refused", "reason": "no tag declares a text search template; one is C code an extension installs" },
+    { "command": "CREATE TRANSFORM", "kind": "transform", "status": "refused", "reason": "no tag declares a transform; an extension installs one" },
+    { "command": "CREATE TRIGGER", "kind": "trigger", "status": "declared", "entity": "Postgres::Trigger" },
+    { "command": "CREATE TYPE", "form": "AS ENUM", "match": "\\bAS\\s+ENUM\\b", "kind": "enum type", "status": "declared", "entity": "Postgres::Enum" },
+    { "command": "CREATE TYPE", "form": "AS (...)", "match": "\\bAS\\s*\\(", "kind": "composite type", "status": "refused", "reason": "no tag declares a composite type yet" },
+    { "command": "CREATE TYPE", "form": "AS RANGE", "match": "\\bAS\\s+RANGE\\b", "kind": "range type", "status": "refused", "reason": "no tag declares a range type yet" },
+    { "command": "CREATE TYPE", "form": "INPUT, OUTPUT, or a shell type", "kind": "base type", "status": "refused", "reason": "no tag declares a base type; its input and output functions are C code an extension installs" },
+    { "command": "CREATE USER", "kind": "user", "status": "declared", "entity": "Postgres::Role", "note": "an alias of CREATE ROLE ... LOGIN" },
+    { "command": "CREATE USER MAPPING", "kind": "user mapping", "status": "refused", "reason": "no tag declares a user mapping yet" },
+    { "command": "CREATE VIEW", "kind": "view", "status": "declared", "entity": "Postgres::View" }
+  ]
+}

package/src/coverage.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from "vitest";
+import { KIND_COVERAGE, PINNED_COMMANDS, kindCoverageProblems, pinnedCommandsCurrent, statementKind } from "./coverage";
+import { POSTGRES_PROBES } from "./postgres/live/undeclarable";
+import { CLICKHOUSE_PROBES } from "./clickhouse/live/undeclarable";
+import { SQL_DIALECTS } from "./dialects";
+
+describe("the object coverage table (#3911)", () => {
+  test.each(SQL_DIALECTS)("%s: every CREATE command a pinned server has is marked, and nothing else", (dialect) => {
+    expect(kindCoverageProblems(dialect)).toEqual([]);
+  });
+
+  test.each(SQL_DIALECTS)("%s: the command lists are the pinned servers' (run scripts/sql-create-commands.ts after a pin move)", (dialect) => {
+    expect(pinnedCommandsCurrent(dialect)).toEqual([]);
+  });
+
+  test("a pinned server with a command no row covers fails the check", () => {
+    const pins = [{ version: "19.0", commands: [...PINNED_COMMANDS.postgres[0]!.commands, "CREATE PROPERTY GRAPH"] }];
+    expect(kindCoverageProblems("postgres", { pins })).toContain("postgres 19.0 has CREATE PROPERTY GRAPH, and no row in src/coverage/postgres.json covers it");
+  });
+
+  test("a row must say why it is not declared, and name its entity when it is", () => {
+    const rows = [
+      { command: "CREATE CAST", kind: "cast", status: "refused" as const },
+      { command: "CREATE TABLE", kind: "table", status: "declared" as const },
+    ];
+    expect(kindCoverageProblems("postgres", { pins: [{ version: "x", commands: ["CREATE CAST", "CREATE TABLE"] }], rows })).toEqual([
+      "cast is refused, and gives no reason",
+      "table is declared, and names no entity type",
+    ]);
+  });
+
+  test("every refused kind has the live query that finds it, and every query a refused-or-declared row", () => {
+    const probes = { postgres: POSTGRES_PROBES, clickhouse: CLICKHOUSE_PROBES };
+    for (const dialect of SQL_DIALECTS) {
+      const refused = KIND_COVERAGE[dialect].filter((r) => r.status === "refused").map((r) => r.kind);
+      for (const kind of refused) expect(Object.keys(probes[dialect]), `${dialect} ${kind}`).toContain(kind);
+      const kinds = KIND_COVERAGE[dialect].map((r) => r.kind);
+      for (const kind of Object.keys(probes[dialect])) expect(kinds, `${dialect} probe ${kind}`).toContain(kind);
+    }
+  });
+});
+
+describe("a statement's kind", () => {
+  test.each([
+    ["CREATE TYPE app.pair AS (a int, b text)", "composite type"],
+    ["CREATE TYPE app.r AS RANGE (subtype = float8)", "range type"],
+    ["CREATE TYPE app.mood AS ENUM ('ok')", "enum type"],
+    ["CREATE TYPE app.shell", "base type"],
+    ["CREATE AGGREGATE app.total(int) (sfunc = int4pl, stype = int)", "aggregate"],
+    ["CREATE CAST (app.pair AS text) WITH FUNCTION app.f(app.pair)", "cast"],
+    ["CREATE OR REPLACE TRUSTED PROCEDURAL LANGUAGE plx", "procedural language"],
+    ["CREATE DEFAULT CONVERSION c FOR 'LATIN1' TO 'UTF8' FROM f", "conversion"],
+    ["CREATE OPERATOR CLASS c FOR TYPE int USING btree AS OPERATOR 1 <", "operator class"],
+    ["CREATE TEXT SEARCH CONFIGURATION app.eng (COPY = english)", "text search configuration"],
+    ["CREATE USER MAPPING FOR app SERVER s", "user mapping"],
+    ["CREATE UNIQUE INDEX i ON app.t (a)", "index"],
+    // A body's RETURN is inside its string, not a SQL-standard body.
+    ["CREATE FUNCTION app.f() RETURNS int LANGUAGE plpgsql AS $$ BEGIN RETURN 1; END $$", "function"],
+    ["CREATE FUNCTION app.f(a int) RETURNS int LANGUAGE sql RETURN a + 1", "routine with a SQL-standard body"],
+  ])("postgres: %s is a %s", (sql, kind) => {
+    expect(statementKind("postgres", sql)?.kind).toBe(kind);
+  });
+
+  test.each([
+    ["CREATE TEMPORARY TABLE t (a Int8)", "temporary table"],
+    ["CREATE TABLE t (a Int8) ENGINE = Memory", "table"],
+    ["CREATE WINDOW VIEW w AS SELECT 1", "window view"],
+    ["CREATE SETTINGS PROFILE p SETTINGS max_threads = 1", "settings profile"],
+    ["CREATE OR REPLACE FUNCTION f AS (x) -> x + 1", "SQL function"],
+    ["CREATE QUOTA q FOR INTERVAL 1 hour MAX queries = 10", "quota"],
+  ])("clickhouse: %s is a %s", (sql, kind) => {
+    expect(statementKind("clickhouse", sql)?.kind).toBe(kind);
+  });
+
+  test("a statement that is not a CREATE has no kind", () => {
+    expect(statementKind("postgres", "ALTER TABLE t ADD COLUMN a int")).toBeUndefined();
+  });
+});