@intentius/chant-lexicon-sql 0.124.18 → 0.124.21

package/src/clickhouse/parser.ts

@@ -95,6 +95,12 @@ export interface TableNode extends StorageNode {
   indexes: IndexNode[];
   projections: ProjectionNode[];
   constraints: ConstraintNode[];
+  /**
+   * A table over a table function (#3911): `AS numbers(10)`, `AS remote(...)`,
+   * the call after `AS`. Such a table has no engine and no data of its own;
+   * its column list is optional, and the server prints the one it inferred.
+   */
+  asFunction?: Span;
   comment?: Span;
 }
 
@@ -200,6 +206,42 @@ const EXPRESSION_WORDS = new Set(
   ).split(" "),
 );
 
+/** The units an interval is counted in, singular and plural: what ends a refresh schedule before a column list. */
+const INTERVAL_UNIT_WORDS = new Set(
+  ["NANOSECOND", "MICROSECOND", "MILLISECOND", "SECOND", "MINUTE", "HOUR", "DAY", "WEEK", "MONTH", "QUARTER", "YEAR"].flatMap((u) => [u, `${u}S`]),
+);
+
+/**
+ * The `CREATE` kinds the pinned server has (26.8: `system.*` and its parser's
+ * own list) that chant does not declare, each with why (#3911). A statement
+ * of one is refused with that reason, by name, never as a parse error.
+ */
+export const REFUSED_CREATE_KINDS: ReadonlyArray<{ words: readonly string[]; kind: string; reason: string }> = [
+  { words: ["LIVE", "VIEW"], kind: "LIVE VIEW", reason: "the pinned server no longer has live views (removed in 25.x); a refreshable materialized view (REFRESH EVERY ...) is the replacement" },
+  {
+    words: ["WINDOW", "VIEW"],
+    kind: "WINDOW VIEW",
+    reason: "a window view is experimental and the pinned server refuses it under the default query analyzer (allow_experimental_analyzer), so it cannot be applied as declared",
+  },
+  { words: ["TEMPORARY"], kind: "TEMPORARY TABLE", reason: "a temporary table lives for one session and is never in the catalog a plan reads" },
+  {
+    words: ["NAMED", "COLLECTION"],
+    kind: "NAMED COLLECTION",
+    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. Create it from the server's configuration or by hand",
+  },
+  { words: ["MASKING", "POLICY"], kind: "MASKING POLICY", reason: "masking policies are available only in ClickHouse Cloud, not on the pinned server" },
+  { words: ["WORKLOAD"], kind: "WORKLOAD", reason: "a workload is server-level scheduling, configured with the server, not a schema object" },
+  { words: ["RESOURCE"], kind: "RESOURCE", reason: "a resource is a server-level scheduling resource (a disk's read or write), configured with the server, not a schema object" },
+  { words: ["HANDLER"], kind: "HANDLER", reason: "an HTTP handler is server-level configuration, not a schema object" },
+  {
+    words: ["INDEX"],
+    kind: "INDEX",
+    reason: "a skip index belongs to its table: declare it in the table's column list (INDEX name expr TYPE type GRANULARITY n), and a plan adds or drops it with ALTER TABLE",
+  },
+  { words: ["UNIQUE", "INDEX"], kind: "UNIQUE INDEX", reason: "the pinned server has no unique index on its table engines; declare a skip index in the table's column list" },
+  { words: ["HYPOTHETICAL", "INDEX"], kind: "HYPOTHETICAL INDEX", reason: "a hypothetical index is a session's what-if for the query planner, never stored" },
+];
+
 const STORAGE_KEYWORDS = ["ENGINE", "ORDER", "PRIMARY", "PARTITION", "SAMPLE", "TTL", "SETTINGS", "COMMENT"];
 
 /** A column's own clause words: an unknown one stops at the next of these (#3872). */
@@ -208,6 +250,8 @@ const COLUMN_WORDS = ["DEFAULT", "MATERIALIZED", "ALIAS", "EPHEMERAL", "NULL", "
 class Parser extends SqlCursor {
   /** Where the clause-aware expression being read started (#3872); undefined outside one. */
   private clauseFrom: number | undefined;
+  /** Reading a refreshable materialized view's schedule, which a column list ends. */
+  private refreshing = false;
 
   /**
    * `ORDER`, `PARTITION`, `SAMPLE` and `GROUP` stop only before `BY`, `PRIMARY`
@@ -215,6 +259,8 @@ class Parser extends SqlCursor {
    * not know stops it too.
    */
   protected override stopsAt(stop: readonly string[]): boolean {
+    // `REFRESH EVERY 1 HOUR (a UInt64) ENGINE ...`, as `SHOW CREATE` prints it: the column list follows the schedule.
+    if (this.refreshing && this.isPunct("(") && INTERVAL_UNIT_WORDS.has(this.peek(-1)?.text.toUpperCase() ?? "")) return true;
     if (!super.stopsAt(stop)) return this.startsUnknownClause();
     const word = this.peek()!.text.toUpperCase();
     const two = ["ORDER", "PARTITION", "SAMPLE", "GROUP"].includes(word) ? kw(this.peek(1), "BY") : true;
@@ -478,6 +524,22 @@ class Parser extends SqlCursor {
     if (this.accept("FUNCTION")) return this.function(orReplace);
     const materialized = this.accept("MATERIALIZED");
     if (this.accept("VIEW")) return this.view(orReplace, materialized);
+    if (!materialized) {
+      const refused = REFUSED_CREATE_KINDS.find((k) => k.words.every((w, i) => kw(this.peek(i), w)));
+      if (refused) this.fail(`CREATE ${refused.kind} is not declared: ${refused.reason}`);
+      // Access control is read by its own tags (`./access.ts`).
+      const access: Array<[string[], string, string]> = [
+        [["USER"], "USER", "user"],
+        [["ROLE"], "ROLE", "role"],
+        [["ROW", "POLICY"], "ROW POLICY", "policy"],
+        [["POLICY"], "ROW POLICY", "policy"],
+        [["QUOTA"], "QUOTA", "quota"],
+        [["SETTINGS", "PROFILE"], "SETTINGS PROFILE", "settingsProfile"],
+        [["PROFILE"], "SETTINGS PROFILE", "settingsProfile"],
+      ];
+      const hit = access.find(([words]) => words.every((w, i) => kw(this.peek(i), w)));
+      if (hit) this.fail(`CREATE ${hit[1]} is access control: declare it with the ${hit[2]} tag`);
+    }
     return this.fail(materialized ? "expected VIEW" : "expected DATABASE, TABLE, VIEW, MATERIALIZED VIEW, DICTIONARY or FUNCTION");
   }
 
@@ -540,14 +602,53 @@ class Parser extends SqlCursor {
       projections: [],
       constraints: [],
     };
-    if (!this.isPunct("(")) this.fail("expected the column list (CREATE TABLE ... AS is not declared here)");
-    this.tableElements(node, true);
+    if (this.isPunct("(")) this.tableElements(node, true);
+    else if (!kw(this.peek(), "AS")) this.refuseCopy();
+    const asWord = this.peek();
+    if (this.accept("AS")) {
+      // `AS numbers(10)`: a table over a table function. `AS other` and `AS SELECT` copy, and are refused.
+      if (kw(this.peek(), "SELECT", "WITH") || this.isPunct("(")) this.refuseCopy("select", asWord);
+      const from = this.idx();
+      this.qualifiedName();
+      if (!this.isPunct("(")) this.refuseCopy("table", asWord);
+      this.parenthesized();
+      node.asFunction = this.span(from, this.tokens.slice(from, this.idx(-1) + 1).flatMap((t) => (t.kind === "ref" ? [t.part] : [])));
+      if (this.accept("COMMENT")) node.comment = this.clauseExpr();
+      if (kw(this.peek(), ...STORAGE_KEYWORDS)) this.fail("a table over a table function has no engine or storage clauses: the function is its storage");
+      this.finish("table definition", ["COMMENT"]);
+      return node;
+    }
     this.storage(node, []);
     if (this.accept("COMMENT")) node.comment = this.clauseExpr();
+    if (kw(this.peek(), "AS") && (kw(this.peek(1), "SELECT", "WITH") || this.peek(1)?.text === "(")) this.refuseCopy("select");
     this.finish("table definition", STORAGE_KEYWORDS);
     return node;
   }
 
+  /**
+   * The `CREATE TABLE` forms that copy another table or a query, refused
+   * with why (#3911). Each is a one-off the server keeps no trace of: it
+   * prints the copied columns and engine, or the query's result's, as if
+   * they were written out.
+   */
+  private refuseCopy(what?: "select" | "table", at: Token | undefined = this.peek()): never {
+    if (what === "select") {
+      return this.fail(
+        "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,
+      );
+    }
+    if (what === "table") {
+      return this.fail(
+        "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,
+      );
+    }
+    if (kw(this.peek(), "CLONE")) return this.fail("CREATE TABLE ... CLONE AS is not declared: it copies another table's columns, engine and data once. Declare the columns and engine");
+    if (kw(this.peek(), "EMPTY")) return this.fail("CREATE TABLE ... EMPTY AS SELECT is not declared: the server keeps the query's columns, not the query. Declare the columns");
+    return this.fail("expected the column list (a table declared without one, CREATE TABLE ... ENGINE = ... AS SELECT, is not declared: declare the columns)");
+  }
+
   private dictionaryAttribute(): DictionaryAttributeNode {
     const { text, span } = this.name("an attribute name");
     const STOP = ["DEFAULT", "EXPRESSION", "HIERARCHICAL", "BIDIRECTIONAL", "INJECTIVE", "IS_OBJECT_ID"];
@@ -644,7 +745,14 @@ class Parser extends SqlCursor {
       empty: false,
       select: { from: 0, to: 0, refs: [] },
     };
-    if (this.accept("REFRESH")) node.refresh = this.expr(["TO", "ENGINE", "AS", "EMPTY", "APPEND", "DEPENDS", "SETTINGS"]);
+    if (this.accept("REFRESH")) {
+      this.refreshing = true;
+      try {
+        node.refresh = this.expr(["TO", "ENGINE", "AS", "EMPTY", "APPEND", "DEPENDS", "SETTINGS"]);
+      } finally {
+        this.refreshing = false;
+      }
+    }
     if (this.accept("APPEND")) node.append = true;
     if (this.accept("TO")) node.to = this.qualifiedName();
     if (this.isPunct("(")) {

package/src/clickhouse/plan/deep.ts

@@ -37,7 +37,7 @@ import { ACCESS_ENTITY_TYPES, ACCESS_UNMANAGED_DETAIL, accessOf, readLiveAccess,
 import { clickhouseQuery } from "../http";
 import { sqlString } from "../apply/statements";
 import { stripMarkerFromStatement } from "../ownership";
-import { database, dictionary, func, policy, role, table, user, view, CLICKHOUSE_ENTITY_TYPES, type ColumnDef } from "../entities";
+import { database, dictionary, func, policy, quota, role, settingsProfile, table, user, view, CLICKHOUSE_ENTITY_TYPES, type ColumnDef } from "../entities";
 import { canonicalObject, grantsObject, objectKey, type CanonicalColumn, type CanonicalObject } from "./normalize";
 import { grantStatement, grantsByGrantee, revokeStatement, type GrantAtom } from "../access";
 import { renderFor } from "../topology";
@@ -67,7 +67,11 @@ function liveProps(o: LiveObject): Props {
                 ? role
                 : o.type === CLICKHOUSE_ENTITY_TYPES.rowPolicy
                   ? policy
-                  : view;
+                  : o.type === CLICKHOUSE_ENTITY_TYPES.quota
+                    ? quota
+                    : o.type === CLICKHOUSE_ENTITY_TYPES.settingsProfile
+                      ? settingsProfile
+                      : view;
   const strings = Object.assign([o.statement], { raw: [o.statement] }) as unknown as TemplateStringsArray;
   return { ...(tag(strings).props as unknown as Props) };
 }
@@ -89,8 +93,10 @@ export function inDeclaredVocabulary(declared: Props, live: Props, d: CanonicalO
   adopt("name", d.name === l.name);
   adopt("database", d.database === l.database);
   adopt("engine", same("engine"));
-  for (const k of ["orderBy", "primaryKey", "partitionBy", "sampleBy", "ttl", "comment", "select", "refresh", "dataSource", "layout", "lifetime", "range"] as const) adopt(k, same(k));
+  for (const k of ["orderBy", "primaryKey", "partitionBy", "sampleBy", "ttl", "comment", "select", "refresh", "dataSource", "layout", "lifetime", "range", "asFunction"] as const) adopt(k, same(k));
   adopt("settings", same("settings"));
+  // A view's DEFINER and SQL SECURITY are not compared by a plan; the server adds its own to a refreshable materialized view (#3911).
+  adopt("security", d.kind === "view" || d.kind === "materializedView");
   // A user's, role's or row policy's fields, compared as `../access.ts` reads them.
   if (d.kind === "user" || d.kind === "role" || d.kind === "rowPolicy") {
     for (const k of ["identified", "host", "validUntil", "defaultRole", "defaultDatabase", "grantees", "settings", "as", "for", "using", "to"]) {
@@ -100,6 +106,12 @@ export function inDeclaredVocabulary(declared: Props, live: Props, d: CanonicalO
     // A user's authentication is the environment's unless the declaration says it.
     if (d.kind === "user" && declared.identified === undefined) delete out.identified;
   }
+  // A quota's or settings profile's fields; a quota's intervals are one prop, the same when every interval is.
+  if (d.kind === "quota" || d.kind === "settingsProfile") {
+    const fields = (o: CanonicalObject, pick: (k: string) => boolean) => JSON.stringify(Object.entries(o.access ?? {}).filter(([k]) => pick(k)));
+    for (const k of ["keyed", "settings", "to"]) adopt(k, d.access?.[k] === l.access?.[k]);
+    adopt("intervals", fields(d, (k) => k.startsWith("interval.")) === fields(l, (k) => k.startsWith("interval.")));
+  }
   // A function's parameters and expression are one lambda: the same lambda is the declaration's words.
   adopt("params", d.kind === "function" && same("lambda"));
   adopt("body", d.kind === "function" && same("lambda"));
@@ -108,8 +120,8 @@ export function inDeclaredVocabulary(declared: Props, live: Props, d: CanonicalO
   adopt("constraints", same("constraints"));
 
   const declaredColumns = (declared.columns as ColumnDef[] | undefined) ?? [];
-  if (d.kind === "view" || d.kind === "materializedView") {
-    // The server infers a view's columns; a declaration that lists none is not drift.
+  if (d.kind === "view" || d.kind === "materializedView" || (d.kind === "table" && d.asFunction !== undefined && declaredColumns.length === 0)) {
+    // The server infers a view's columns, and a table function's (#3911); a declaration that lists none is not drift.
     if (declaredColumns.length === 0) out.columns = [];
   } else if (d.kind === "table" || d.kind === "dictionary") {
     const liveColumns = (live.columns as ColumnDef[] | undefined) ?? [];
@@ -124,7 +136,14 @@ export function inDeclaredVocabulary(declared: Props, live: Props, d: CanonicalO
 }
 
 /** The entity types that belong to no database. */
-const GLOBAL_TYPES: ReadonlySet<string> = new Set([CLICKHOUSE_ENTITY_TYPES.database, CLICKHOUSE_ENTITY_TYPES.function, CLICKHOUSE_ENTITY_TYPES.user, CLICKHOUSE_ENTITY_TYPES.role]);
+const GLOBAL_TYPES: ReadonlySet<string> = new Set([
+  CLICKHOUSE_ENTITY_TYPES.database,
+  CLICKHOUSE_ENTITY_TYPES.function,
+  CLICKHOUSE_ENTITY_TYPES.user,
+  CLICKHOUSE_ENTITY_TYPES.role,
+  CLICKHOUSE_ENTITY_TYPES.quota,
+  CLICKHOUSE_ENTITY_TYPES.settingsProfile,
+]);
 
 /** Whether the server's formatter prints two expressions the same. A formatter that cannot parse them says no. */
 async function sameExpression(target: ClickHouseTarget, a: string, b: string): Promise<boolean> {

package/src/clickhouse/plan/diff.ts

@@ -179,6 +179,17 @@ function diffObject(key: string, before: CanonicalObject, after: CanonicalObject
     return;
   }
 
+  if (before.kind === "quota" || before.kind === "settingsProfile") {
+    const rule = before.kind === "quota" ? "SQLCH275" : "SQLCH276";
+    const b = before.access ?? {};
+    const a = after.access ?? {};
+    // In the order the server prints them: the key, each interval by length, the settings, whom it applies to.
+    const rank = (f: string) => (f === "keyed" ? 0 : f.startsWith("interval.") ? 1 + Number(f.slice("interval.".length)) / 1e9 : f === "settings" ? 2 : 3);
+    const fields = [...new Set([...Object.keys(b), ...Object.keys(a)])].sort((x, y) => rank(x) - rank(y));
+    for (const field of fields) if (b[field] !== a[field]) out.push(change(key, field, rule, b[field], a[field]));
+    return;
+  }
+
   if (before.kind === "grants") {
     const b = before.access ?? {};
     const a = after.access ?? {};
@@ -212,6 +223,11 @@ function diffObject(key: string, before: CanonicalObject, after: CanonicalObject
     return;
   }
 
+  if (before.asFunction !== undefined || after.asFunction !== undefined) {
+    diffTableFunction(key, before, after, out);
+    return;
+  }
+
   // A table.
   if (before.engine !== after.engine) out.push(change(key, "engine", "SQLCH223", before.engine, after.engine));
   const added = diffColumns(key, before, after, out, hints);
@@ -244,6 +260,30 @@ function diffObject(key: string, before: CanonicalObject, after: CanonicalObject
   diffMap(key, "constraints", before.constraints, after.constraints, "SQLCH215", out);
 }
 
+/**
+ * A table over a table function (#3911), on either side. It stores nothing,
+ * so every change but its comment replaces it (SQLCH219); a table with data
+ * of its own becoming one would lose that data, which is a rebuild
+ * (SQLCH223). A declaration with no column list takes the columns the server
+ * infers, so they are compared only when it lists them.
+ */
+function diffTableFunction(key: string, before: CanonicalObject, after: CanonicalObject, out: Change[]): void {
+  if (before.asFunction === undefined) {
+    out.push(change(key, "asFunction", "SQLCH223", before.engine, `AS ${after.asFunction}`));
+    return;
+  }
+  if (before.asFunction !== after.asFunction) out.push(change(key, "asFunction", "SQLCH219", before.asFunction, after.asFunction));
+  if (after.asFunction !== undefined && after.columns.length === 0) return;
+  const column = (c: CanonicalColumn) => [c.type, c.nullable ? "NULL" : "", c.defaultKind ?? "", c.defaultExpr ?? "", c.codec ? `CODEC(${c.codec})` : "", c.comment ? `COMMENT ${c.comment}` : ""].filter(Boolean).join(" ");
+  const b = new Map(before.columns.map((c) => [c.name, column(c)]));
+  const a = new Map(after.columns.map((c) => [c.name, column(c)]));
+  for (const name of new Set([...b.keys(), ...a.keys()])) {
+    if (b.get(name) !== a.get(name)) out.push(change(key, `columns.${name}`, "SQLCH219", b.get(name), a.get(name)));
+  }
+  const order = (o: CanonicalObject) => o.columns.map((c) => c.name).join(", ");
+  if (order(before) !== order(after) && a.size === b.size && [...a.keys()].every((n) => b.has(n))) out.push(change(key, "columns.order", "SQLCH219", order(before), order(after)));
+}
+
 /** A dictionary: every change but its comment replaces it (SQLCH245). */
 function diffDictionary(key: string, before: CanonicalObject, after: CanonicalObject, out: Change[]): void {
   const attribute = (c: CanonicalColumn) =>
@@ -272,7 +312,7 @@ export function diffSchemas(before: readonly SchemaObject[], after: readonly Sch
   const matches = matchByIdentity(before, after, {
     qualified,
     // A function, a user, a role, a row policy and a grantee's grants are not renamed: one under a new name is a create.
-    previously: (o) => (o.kind === "function" || o.kind === "user" || o.kind === "role" || o.kind === "rowPolicy" || o.kind === "grants" ? undefined : o.previously),
+    previously: (o) => (o.kind === "function" || o.kind === "user" || o.kind === "role" || o.kind === "rowPolicy" || o.kind === "quota" || o.kind === "settingsProfile" || o.kind === "grants" ? undefined : o.previously),
     previousNames: (o, prev) => [prev, `${o.database}.${prev}`],
   });
   for (const m of matches) {

package/src/clickhouse/plan/normalize.ts

@@ -41,7 +41,7 @@ import { accessCanonical, grantsCanonical, isAccessStatement } from "../access";
 
 export { previouslyIn } from "../../core/normalize";
 
-export type ObjectKind = "database" | "table" | "view" | "materializedView" | "dictionary" | "function" | "user" | "role" | "rowPolicy" | "grants";
+export type ObjectKind = "database" | "table" | "view" | "materializedView" | "dictionary" | "function" | "user" | "role" | "rowPolicy" | "quota" | "settingsProfile" | "grants";
 
 export interface CanonicalColumn {
   name: string;
@@ -84,6 +84,8 @@ export interface CanonicalObject {
   select?: string;
   to?: string;
   refresh?: string;
+  /** A table over a table function (#3911): the call after `AS`. */
+  asFunction?: string;
   /** A dictionary's `SOURCE`, `LAYOUT`, `LIFETIME` and `RANGE`, each what is inside the parentheses. */
   dataSource?: string;
   layout?: string;
@@ -94,8 +96,9 @@ export interface CanonicalObject {
   /** A row policy's table. */
   table?: string;
   /**
-   * A user's, role's or row policy's fields (`../access.ts`), each absent at
-   * the server's default; a grantee's grants, by atom.
+   * A user's, role's, row policy's, quota's or settings profile's fields
+   * (`../access.ts`), each absent at the server's default; a grantee's
+   * grants, by atom.
    */
   access?: Record<string, string>;
   /** `-- previously: <name>` before the statement: the object's previous name. */
@@ -374,6 +377,7 @@ export function canonicalObject(ddl: string, defaultDatabase = "default"): Canon
   }
 
   if (node.statement === "table") {
+    if (node.asFunction) obj.asFunction = canonicalExpression(spanText(tokens, node.asFunction) ?? "", database);
     node.columns.forEach((c, i) => obj.columns.push(column(tokens, c, i, database)));
     for (const ix of node.indexes) {
       obj.indexes[ix.name] = [expr(ix.expr), "TYPE", expr(ix.type), ix.granularity ? `GRANULARITY ${expr(ix.granularity)}` : ""]
@@ -556,6 +560,8 @@ export function objectKey(o: { kind?: ObjectKind; type?: string; database?: stri
   if (kind === "function") return `function ${o.name}`;
   if (kind === "user") return `user ${o.name}`;
   if (kind === "role") return `role ${o.name}`;
+  if (kind === "quota") return `quota ${o.name}`;
+  if (kind === "settingsProfile") return `settings profile ${o.name}`;
   if (kind === "grants") return `grants ${o.name}`;
   if (kind === "rowPolicy") return `row policy ${o.name} ON ${o.database}.${o.table}`;
   return o.database !== undefined ? `${o.database}.${o.name}` : o.name;
@@ -566,6 +572,8 @@ const KIND_OF_TYPE: Record<string, ObjectKind> = {
   "ClickHouse::User": "user",
   "ClickHouse::Role": "role",
   "ClickHouse::RowPolicy": "rowPolicy",
+  "ClickHouse::Quota": "quota",
+  "ClickHouse::SettingsProfile": "settingsProfile",
   "ClickHouse::Grant": "grants",
 };
 
@@ -582,7 +590,7 @@ export function grantsObject(ddl: string, grantee: string, defaultDatabase = "de
  */
 export function scopeOf(o: { kind?: ObjectKind; type?: string; database?: string; name: string; table?: string }): string {
   const kind = o.kind ?? KIND_OF_TYPE[o.type ?? ""];
-  if (kind === "function" || kind === "user" || kind === "role" || kind === "grants") return objectKey(o);
+  if (kind === "function" || kind === "user" || kind === "role" || kind === "quota" || kind === "settingsProfile" || kind === "grants") return objectKey(o);
   return o.database ?? o.name;
 }
 

package/src/clickhouse/plan/rules.ts

@@ -35,7 +35,7 @@ const DOCS = "https://clickhouse.com/docs/sql-reference/statements";
 const rule = (id: string, cls: ChangeClass, title: string, restriction: string, cite: string): ClassifierRule => classifierRule(id, cls, title, restriction, cite);
 
 export const CLASSIFIER_RULES = {
-  SQLCH200: rule("SQLCH200", "create", "Create an object", "A new database, table, view, dictionary, function, user, role or row policy is created, or a grantee gets its first grants; nothing existing changes.", `${DOCS}/create`),
+  SQLCH200: rule("SQLCH200", "create", "Create an object", "A new database, table, view, dictionary, function, user, role, row policy, quota or settings profile is created, or a grantee gets its first grants; nothing existing changes.", `${DOCS}/create`),
   SQLCH201: rule(
     "SQLCH201",
     "metadata",
@@ -150,6 +150,13 @@ export const CLASSIFIER_RULES = {
     "A table setting the server marks read-only (such as index_granularity) is fixed when the table is created and needs a new table to change.",
     `${DOCS}/alter/setting`,
   ),
+  SQLCH219: rule(
+    "SQLCH219",
+    "metadata",
+    "Replace a table over a table function",
+    "A table declared AS a table function (numbers, remote, s3, url) stores no data of its own and has no ALTER for its function; CREATE OR REPLACE TABLE replaces its call and columns, and queries read through the new one.",
+    `${DOCS}/create/table#from-a-table-function`,
+  ),
   SQLCH220: rule(
     "SQLCH220",
     "rebuild",
@@ -278,6 +285,20 @@ export const CLASSIFIER_RULES = {
     "REVOKE takes a privilege or a role away, including one granted by hand to a grantee the build declares grants for; queries that relied on it fail from then on.",
     `${DOCS}/revoke`,
   ),
+  SQLCH275: rule(
+    "SQLCH275",
+    "metadata",
+    "Change a quota",
+    "ALTER QUOTA sets the quota's key, one interval's limits (NO LIMITS takes the interval away) or whom it applies to, on the quota that is there, so what names it still does.",
+    `${DOCS}/alter/quota`,
+  ),
+  SQLCH276: rule(
+    "SQLCH276",
+    "metadata",
+    "Change a settings profile",
+    "ALTER SETTINGS PROFILE replaces the profile's settings, constraints and inherited profiles, or whom it applies to; the users, roles and profiles that name it keep it. Sessions already open keep the old settings.",
+    `${DOCS}/alter/settings-profile`,
+  ),
   SQLCH290: rule(
     "SQLCH290",
     "rebuild",

package/src/clickhouse/quota-profile.test.ts

@@ -0,0 +1,186 @@
+/**
+ * Quotas and settings profiles (#3911): the `quota` and `settingsProfile`
+ * tags, each compared with what the pinned server prints for it, the
+ * `ALTER` each change takes, `ON CLUSTER` per topology, and reading them
+ * from a `.sql` file. `live/quota-profile.e2e.test.ts` runs them against a
+ * server.
+ */
+
+import { describe, expect, test } from "vitest";
+import { quota, role, settingsProfile, 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";
+import { readClickHouse } from "../files/clickhouse";
+import { clickhouseTemplates } from "./import/generator";
+
+const t = (s: string) => [s] as unknown as TemplateStringsArray;
+
+describe("the tags", () => {
+  test("a quota: its key, its intervals as written, whom it applies to", () => {
+    const reader = role`CREATE ROLE reader`;
+    const q = quota`CREATE QUOTA IF NOT EXISTS per_user KEYED BY user_name FOR INTERVAL 1 hour MAX queries = 100, errors = 5, FOR RANDOMIZED INTERVAL 1 day TRACKING ONLY TO ${reader}`;
+    expect(q.entityType).toBe("ClickHouse::Quota");
+    expect(q.props).toMatchObject({
+      name: "per_user",
+      ifNotExists: true,
+      keyed: "user_name",
+      intervals: "FOR INTERVAL 1 hour MAX queries = 100, errors = 5, FOR RANDOMIZED INTERVAL 1 day TRACKING ONLY",
+      to: "reader",
+    });
+    expect(q.props.ddl).toBe("CREATE QUOTA IF NOT EXISTS per_user KEYED BY user_name FOR INTERVAL 1 hour MAX queries = 100, errors = 5, FOR RANDOMIZED INTERVAL 1 day TRACKING ONLY TO reader");
+  });
+
+  test("a settings profile, written either way, inheriting another", () => {
+    const base = settingsProfile`CREATE SETTINGS PROFILE base SETTINGS max_threads = 8`;
+    const p = settingsProfile`CREATE PROFILE analysts SETTINGS PROFILE ${base}, max_memory_usage = 10000000000 MIN 1000000 MAX 20000000000, readonly = 1 CONST TO ALL EXCEPT admin`;
+    expect(p.entityType).toBe("ClickHouse::SettingsProfile");
+    expect(p.props).toMatchObject({ name: "analysts", settings: "PROFILE base, max_memory_usage = 10000000000 MIN 1000000 MAX 20000000000, readonly = 1 CONST", to: "ALL EXCEPT admin" });
+    expect(p.dependsOn).toContain(base);
+  });
+
+  test("one per template, the wrong tag, and malformed intervals are refused", () => {
+    expect(() => quota(t("CREATE QUOTA a, b"))).toThrow(/one quota per template/);
+    expect(() => settingsProfile(t("CREATE SETTINGS PROFILE a, b"))).toThrow(/one settings profile per template/);
+    expect(() => quota(t("CREATE SETTINGS PROFILE p"))).toThrow(/holds a CREATE SETTINGS PROFILE; use the settingsProfile tag/);
+    expect(() => settingsProfile(t("CREATE QUOTA q"))).toThrow(/holds a CREATE QUOTA; use the quota tag/);
+    expect(() => role(t("CREATE QUOTA q"))).toThrow(/use the quota tag/);
+    expect(() => quota(t("CREATE QUOTA q KEYED BY user_name NOT KEYED"))).toThrow(/both written/);
+    expect(() => quota(t("CREATE QUOTA q FOR INTERVAL 1 hour MAX queries = 1 TO r FOR INTERVAL 1 day MAX queries = 2"))).toThrow(/FOR is written twice/);
+    expect(() => canonicalObject("CREATE QUOTA q FOR INTERVAL 1 fortnight MAX queries = 1")).toThrow(/whole number and a unit/);
+  });
+});
+
+describe("compared with what the server prints", () => {
+  const same = (declared: string, shown: string) => diffSchemas([{ key: "k", canonical: canonicalObject(shown) }], [{ key: "k", canonical: canonicalObject(declared) }]).changes;
+
+  test("a quota: units in seconds, limits sorted and lower case, numbers as the server keeps them, NO LIMITS as no interval", () => {
+    expect(
+      same(
+        "CREATE QUOTA q KEYED BY 'user_name' FOR INTERVAL 60 MINUTE MAX QUERIES 100, errors = 5, FOR RANDOMIZED INTERVAL 1 DAY MAX execution_time = 1000.0, read_bytes = 1e9, FOR INTERVAL 1 week NO LIMITS TO r1",
+        "CREATE QUOTA q KEYED BY user_name FOR INTERVAL 1 hour MAX queries = 100, errors = 5, FOR RANDOMIZED INTERVAL 1 day MAX read_bytes = 1000000000, execution_time = 1000 TO r1",
+      ),
+    ).toEqual([]);
+    // Three months are a quarter, as the server counts them.
+    expect(same("CREATE QUOTA q FOR INTERVAL 3 month MAX queries = 1", "CREATE QUOTA q FOR INTERVAL 1 quarter MAX queries = 1")).toEqual([]);
+    expect(same("CREATE QUOTA q NOT KEYED TO NONE", "CREATE QUOTA q")).toEqual([]);
+    // `KEY BY` is `KEYED BY`; an IP key's prefix bits are part of the key.
+    expect(same("CREATE QUOTA q KEY BY ip_address ipv6_prefix_bits 64", "CREATE QUOTA q KEYED BY ip_address IPV6_PREFIX_BITS 64")).toEqual([]);
+    expect(canonicalObject("CREATE QUOTA q KEYED BY ip_address ipv4_prefix_bits 16 ipv6_prefix_bits 48").access).toEqual({ keyed: "ip_address ipv4_prefix_bits 16 ipv6_prefix_bits 48" });
+    // A name may start with a digit, as the server's own tests write them.
+    expect(canonicalObject("CREATE SETTINGS PROFILE 02294_profile1 SETTINGS max_execution_time = 0.5 TO default").name).toBe("02294_profile1");
+    expect(canonicalObject("CREATE QUOTA `q x` KEYED BY client_key, user_name FOR INTERVAL 2 week MAX queries = 1 TO ALL").access).toEqual({
+      keyed: "client_key , user_name",
+      "interval.1209600": "MAX queries = 1",
+      to: "ALL",
+    });
+  });
+
+  test("a changed quota is SQLCH275 per field and per interval", () => {
+    expect(
+      same(
+        "CREATE QUOTA q KEYED BY ip_address FOR INTERVAL 1 hour MAX queries = 7, FOR INTERVAL 1 day TRACKING ONLY",
+        "CREATE QUOTA q KEYED BY user_name FOR INTERVAL 1 hour MAX queries = 5, errors = 2, FOR INTERVAL 1 week MAX queries = 1 TO r",
+      ).map((c) => [c.field, c.rule, c.before, c.after]),
+    ).toEqual([
+      ["keyed", "SQLCH275", "user_name", "ip_address"],
+      ["interval.3600", "SQLCH275", "MAX errors = 2 , queries = 5", "MAX queries = 7"],
+      ["interval.86400", "SQLCH275", undefined, "TRACKING ONLY"],
+      ["interval.604800", "SQLCH275", "MAX queries = 1", undefined],
+      ["to", "SQLCH275", "r", undefined],
+    ]);
+  });
+
+  test("a settings profile: READONLY as CONST, PROFILE 'x' as INHERIT x, the name quoted or not", () => {
+    expect(
+      same(
+        "CREATE PROFILE p2 SETTINGS PROFILE 'p1', readonly = 1, max_threads READONLY, max_memory_usage = 100 MIN 90 MAX 110 TO b, a",
+        "CREATE SETTINGS PROFILE `p2` SETTINGS INHERIT `p1`, readonly = 1, max_memory_usage = 100 MIN 90 MAX 110, max_threads CONST TO a, b",
+      ),
+    ).toEqual([]);
+    expect(same("CREATE SETTINGS PROFILE p SETTINGS max_threads = 4", "CREATE SETTINGS PROFILE `p` SETTINGS max_threads = 5 TO r").map((c) => [c.field, c.rule])).toEqual([
+      ["settings", "SQLCH276"],
+      ["to", "SQLCH276"],
+    ]);
+  });
+});
+
+describe("the statements", () => {
+  const decl = (type: string, ddl: string): DeclaredObject => {
+    const canonical = canonicalObject(ddl);
+    return { exportName: "x", type: type as DeclaredObject["type"], key: objectKey(canonical), ddl, canonical, dependsOn: [] };
+  };
+  const steps = (obj: DeclaredObject, shown?: string) => {
+    const live = shown === undefined ? undefined : canonicalObject(shown);
+    const changes = diffSchemas(live ? [{ key: obj.key, canonical: live }] : [], [{ key: obj.key, canonical: obj.canonical }]).changes;
+    const entry = planStatements({ declared: [obj], changes, current: new Map(live ? [[obj.key, live]] : []) }).objects[0]!;
+    return entry.verdict === "create" || entry.verdict === "alter" ? entry.steps.map((s) => s.sql) : [entry.verdict];
+  };
+
+  test("a quota is created as declared, then changed with ALTER QUOTA, never replaced", () => {
+    const q = decl(CLICKHOUSE_ENTITY_TYPES.quota, "CREATE QUOTA q KEYED BY ip_address FOR RANDOMIZED INTERVAL 1 hour MAX queries = 7, errors = 1 TO r");
+    expect(q.key).toBe("quota q");
+    expect(steps(q)).toEqual(["CREATE QUOTA q KEYED BY ip_address FOR RANDOMIZED INTERVAL 1 hour MAX queries = 7, errors = 1 TO r"]);
+    expect(steps(q, "CREATE QUOTA q FOR INTERVAL 1 hour MAX queries = 5, FOR INTERVAL 1 day MAX queries = 100")).toEqual([
+      "ALTER QUOTA `q` KEYED BY ip_address",
+      "ALTER QUOTA `q` FOR RANDOMIZED INTERVAL 3600 second MAX errors = 1, queries = 7",
+      "ALTER QUOTA `q` FOR INTERVAL 86400 second NO LIMITS",
+      "ALTER QUOTA `q` TO r",
+    ]);
+    expect(steps(decl(CLICKHOUSE_ENTITY_TYPES.quota, "CREATE QUOTA q"), "CREATE QUOTA q KEYED BY user_name TO r")).toEqual(["ALTER QUOTA `q` NOT KEYED", "ALTER QUOTA `q` TO NONE"]);
+  });
+
+  test("a settings profile is changed with ALTER SETTINGS PROFILE, so what inherits it keeps it", () => {
+    const p = decl(CLICKHOUSE_ENTITY_TYPES.settingsProfile, "CREATE SETTINGS PROFILE p SETTINGS max_threads = 4 TO r");
+    expect(p.key).toBe("settings profile p");
+    expect(steps(p, "CREATE SETTINGS PROFILE `p` SETTINGS max_threads = 8")).toEqual(["ALTER SETTINGS PROFILE `p` SETTINGS max_threads = 4", "ALTER SETTINGS PROFILE `p` TO r"]);
+    expect(steps(decl(CLICKHOUSE_ENTITY_TYPES.settingsProfile, "CREATE PROFILE p"), "CREATE SETTINGS PROFILE `p` SETTINGS max_threads = 8 TO r")).toEqual([
+      "ALTER SETTINGS PROFILE `p` SETTINGS NONE",
+      "ALTER SETTINGS PROFILE `p` TO NONE",
+    ]);
+  });
+
+  test("neither is ever dropped", () => {
+    const live = [
+      { key: "quota q", canonical: canonicalObject("CREATE QUOTA q") },
+      { key: "settings profile p", canonical: canonicalObject("CREATE SETTINGS PROFILE p") },
+    ];
+    const gone = diffSchemas(live, []).changes;
+    expect(planStatements({ declared: [], changes: gone, current: new Map(live.map((l) => [l.key, l.canonical])), allowDestructive: true }).drops).toEqual([]);
+  });
+
+  test("ON CLUSTER on a cluster, since neither is in a database", () => {
+    const cluster = { kind: "cluster" as const, cluster: "main" };
+    expect(renderStatement("CREATE QUOTA q KEYED BY user_name", cluster)).toBe("CREATE QUOTA q ON CLUSTER `main` KEYED BY user_name");
+    expect(renderStatement("CREATE SETTINGS PROFILE p SETTINGS max_threads = 1", cluster)).toBe("CREATE SETTINGS PROFILE p ON CLUSTER `main` SETTINGS max_threads = 1");
+    expect(renderStatement("CREATE PROFILE p", cluster)).toBe("CREATE PROFILE p ON CLUSTER `main`");
+    expect(renderStatement("ALTER QUOTA `q` TO r", cluster)).toBe("ALTER QUOTA `q` ON CLUSTER `main` TO r");
+    expect(renderStatement("ALTER SETTINGS PROFILE `p` SETTINGS NONE", cluster)).toBe("ALTER SETTINGS PROFILE `p` ON CLUSTER `main` SETTINGS NONE");
+  });
+});
+
+describe("import", () => {
+  test("a .sql file's quotas and settings profiles are read by their tags", () => {
+    const problems: string[] = [];
+    const objects = readClickHouse(
+      "CREATE SETTINGS PROFILE `p` SETTINGS max_threads = 4;\nCREATE QUOTA q KEYED BY user_name FOR INTERVAL 1 hour MAX queries = 5 TO r;\nCREATE NAMED COLLECTION c AS password = 'x';\n",
+      { origin: "access.sql" },
+      problems,
+    );
+    expect(objects.map((o) => [o.type, o.name])).toEqual([
+      ["ClickHouse::SettingsProfile", "p"],
+      ["ClickHouse::Quota", "q"],
+    ]);
+    expect(problems).toEqual([expect.stringMatching(/^named collection: chant cannot declare it \(a named collection holds credentials/)]);
+  });
+
+  test("the generator writes them with their tags, never as a relation another object names", () => {
+    const items = [
+      { exportName: "q", type: CLICKHOUSE_ENTITY_TYPES.quota, name: "q", ddl: "CREATE QUOTA q TO events" },
+      { exportName: "events", type: CLICKHOUSE_ENTITY_TYPES.table, database: "default", name: "events", ddl: "CREATE TABLE default.events (a UInt8) ENGINE = Log" },
+    ];
+    const { bodies } = clickhouseTemplates(items);
+    expect(bodies.get("q")!.refs).toEqual([]);
+  });
+});