@intentius/chant-lexicon-sql 0.124.46 → 0.124.49

package/dist/clickhouse/review-catalog.d.ts

@@ -0,0 +1,213 @@
+/**
+ * The needs-review catalog: the judgment calls that turn a table from another
+ * database into a ClickHouse table, each as a finding with the evidence it
+ * used. A source reader (`chant import` of SQL Server, #4398; `chant migrate`
+ * of Postgres, #4399) does the mechanical work, a type map and a rename,
+ * and asks this module for everything that is a decision.
+ *
+ * Nothing here knows a source dialect. A reader describes its table in the
+ * neutral facts below (a candidate sort key, a column's nullability, a
+ * constraint) and gets back the ClickHouse choice, a finding to report, and
+ * for a constraint the comment lines to keep in the DDL. The rules are the
+ * same whichever database the table came from.
+ *
+ * ## API
+ *
+ * - {@link sortKeyReview}: `ORDER BY` from the candidates the source offers,
+ *   in the priority `explicit-order`, `clustering-key`, `primary-key`,
+ *   `unique-key`, then `tuple()`. Returns `orderBy`, the `settings` the key
+ *   needs (`allow_nullable_key` when a key column is `Nullable`), and a
+ *   finding that names the chosen candidate and the others it passed over.
+ * - {@link engineReview}: `MergeTree` for an append-only table;
+ *   `ReplacingMergeTree(_version, _deleted)` for a CDC mirror, with the two
+ *   columns it adds in `extraColumns`. `cdcColumns` names them otherwise
+ *   (the Postgres pair uses the `CdcMirror` composite's `_is_deleted`).
+ * - {@link nullableReview}: a column's final type. A `NOT NULL` column keeps
+ *   its type with no finding. A nullable column becomes `Nullable(T)` with a
+ *   finding; when it has a default the finding says the default could
+ *   replace `Nullable`.
+ * - {@link lowCardinalityReview}: a finding for a `String` column whose name
+ *   and declared length suggest few distinct values. It never changes the
+ *   type; offline, the name and the type are all there is to read.
+ * - {@link constraintReview}: foreign keys, checks, unique and exclusion
+ *   constraints, which ClickHouse does not enforce. Returns `comments` (SQL `--` lines to
+ *   put before the `CREATE`) and one finding per constraint.
+ * - {@link REVIEW_RULES}: every rule id with its summary and the ClickHouse
+ *   documentation it rests on, for report metadata.
+ * - {@link findingText}: a finding as one line (object, message, evidence,
+ *   suggestion), the form a SARIF `message` takes.
+ *
+ * A finding's `severity` is `warning` for a decision the author must confirm
+ * and `info` for a note that changes nothing. The caller maps findings to its
+ * own diagnostic type; `at` carries the source line and column when the
+ * reader knows them.
+ *
+ * Every ClickHouse type and engine this module writes is checked against the
+ * pinned catalog (`src/generated/clickhouse.ts`, ClickHouse 26.8) in
+ * `review-catalog.test.ts`, so a pin move that drops one fails there.
+ *
+ * Sources: the MergeTree sorting key and `allow_nullable_key`
+ * (https://clickhouse.com/docs/engines/table-engines/mergetree-family/mergetree),
+ * `ReplacingMergeTree(ver, is_deleted)`
+ * (https://clickhouse.com/docs/engines/table-engines/mergetree-family/replacingmergetree),
+ * `Nullable` (https://clickhouse.com/docs/sql-reference/data-types/nullable),
+ * `LowCardinality`
+ * (https://clickhouse.com/docs/sql-reference/data-types/lowcardinality).
+ */
+export type ReviewSeverity = "warning" | "info";
+export type ReviewRuleId = "SQLRV001" | "SQLRV002" | "SQLRV003" | "SQLRV004" | "SQLRV005" | "SQLRV006" | "SQLRV007" | "SQLRV008" | "SQLRV009" | "SQLRV010" | "SQLRV011" | "SQLRV012";
+export interface ReviewRule {
+    id: ReviewRuleId;
+    name: string;
+    summary: string;
+    docs: readonly string[];
+}
+/**
+ * The rules. SQLRV001 to SQLRV005 are the shared ones; the rest are raised by
+ * a source reader for what only its dialect has, and live here so a report
+ * lists one catalog.
+ */
+export declare const REVIEW_RULES: Readonly<Record<ReviewRuleId, ReviewRule>>;
+export interface SourcePosition {
+    /** 1-based. */
+    line: number;
+    /** 1-based. */
+    column: number;
+}
+export interface ReviewFinding {
+    ruleId: ReviewRuleId;
+    severity: ReviewSeverity;
+    /** The table or view the finding is about, as the source names it. */
+    object: string;
+    /** The column, when the finding is about one. */
+    column?: string;
+    message: string;
+    /** What the decision was read from: each entry is a fact in the source. */
+    evidence: readonly string[];
+    suggestion?: string;
+    at?: SourcePosition;
+}
+/** A finding as one line. */
+export declare function findingText(f: ReviewFinding): string;
+/**
+ * Where a candidate sort key came from, strongest first. `explicit-order` is
+ * an ordering the author declared for storage (a columnstore `ORDER`),
+ * `clustering-key` the key the source stores rows in (a clustered index),
+ * then the primary key and the first unique key.
+ */
+export type SortKeyKind = "explicit-order" | "clustering-key" | "primary-key" | "unique-key";
+export interface SortKeyCandidate {
+    kind: SortKeyKind;
+    /** The index or constraint name, for the evidence. */
+    name?: string;
+    columns: readonly string[];
+    /** Columns the source sorts descending; ClickHouse's `ORDER BY` drops the direction. */
+    descending?: readonly string[];
+    /** The fact this candidate was read from, e.g. `CREATE CLUSTERED INDEX CX_t`. */
+    source: string;
+}
+export interface SortKeyInput {
+    object: string;
+    candidates: readonly SortKeyCandidate[];
+    /** Each column's ClickHouse type, by name; `Nullable(...)` marks a nullable key column. */
+    columnTypes: Readonly<Record<string, string>>;
+    at?: SourcePosition;
+}
+export interface SortKeyResult {
+    orderBy: string[];
+    /** MergeTree settings the key needs. */
+    settings: Record<string, string>;
+    finding: ReviewFinding;
+}
+export declare function sortKeyReview(input: SortKeyInput): SortKeyResult;
+export interface EngineInput {
+    object: string;
+    /**
+     * `append` for a table that is loaded and queried, `cdc` for a mirror of a
+     * table that changes in place (#4399): rows arrive as new versions and a
+     * delete arrives as a marker row.
+     */
+    mode: "append" | "cdc";
+    /** Facts about the source table that bear on the choice, as plain sentences. */
+    facts?: readonly string[];
+    /** The columns the source enforces unique, when it does. */
+    uniqueKey?: readonly string[];
+    /**
+     * For `cdc`, the names of the version and deleted columns, when the pipeline
+     * or the `CdcMirror` composite names them other than `_version` and
+     * `_deleted`. The names are the caller's; the catalog only writes them.
+     */
+    cdcColumns?: {
+        version: string;
+        deleted: string;
+    };
+    at?: SourcePosition;
+}
+export interface EngineResult {
+    /** The text after `ENGINE =`. */
+    engine: string;
+    /** Columns the engine needs and the source does not have. */
+    extraColumns: Array<{
+        name: string;
+        type: string;
+    }>;
+    finding: ReviewFinding;
+}
+export declare const CDC_VERSION_COLUMN: {
+    readonly name: "_version";
+    readonly type: "UInt64";
+};
+export declare const CDC_DELETED_COLUMN: {
+    readonly name: "_deleted";
+    readonly type: "UInt8";
+};
+export declare function engineReview(input: EngineInput): EngineResult;
+export interface NullableInput {
+    object: string;
+    column: string;
+    /** The column's ClickHouse type before `Nullable`. */
+    type: string;
+    sourceNullable: boolean;
+    /** The default as the ClickHouse expression it became, or the source text when it did not translate. */
+    defaultExpr?: string;
+    at?: SourcePosition;
+}
+export interface NullableResult {
+    type: string;
+    finding?: ReviewFinding;
+}
+export declare function nullableReview(input: NullableInput): NullableResult;
+export interface LowCardinalityInput {
+    object: string;
+    column: string;
+    /** The ClickHouse type as emitted. Only `String` and `Nullable(String)` are candidates. */
+    type: string;
+    /** The source's declared maximum length, when it has one. */
+    maxLength?: number;
+    at?: SourcePosition;
+}
+/** The longest declared length that still counts as supporting evidence. */
+export declare const LOW_CARDINALITY_MAX_LENGTH = 50;
+export declare function lowCardinalityReview(input: LowCardinalityInput): ReviewFinding | undefined;
+export interface ConstraintFact {
+    kind: "foreign-key" | "check" | "unique" | "exclusion";
+    name?: string;
+    columns?: readonly string[];
+    references?: {
+        table: string;
+        columns: readonly string[];
+    };
+    /** A check's expression, or an exclusion's `USING method (element WITH operator, ...)`, as the source wrote it. */
+    expression?: string;
+    at?: SourcePosition;
+}
+export interface ConstraintResult {
+    /** `-- ` lines to put before the `CREATE`; never contain a line break. */
+    comments: string[];
+    findings: ReviewFinding[];
+}
+export declare function constraintReview(input: {
+    object: string;
+    constraints: readonly ConstraintFact[];
+}): ConstraintResult;
+//# sourceMappingURL=review-catalog.d.ts.map

package/dist/clickhouse/review-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-catalog.d.ts","sourceRoot":"","sources":["../../src/clickhouse/review-catalog.ts"],"names":[],"mappings":"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"}

package/dist/clickhouse/review-catalog.js

@@ -0,0 +1,330 @@
+/**
+ * The needs-review catalog: the judgment calls that turn a table from another
+ * database into a ClickHouse table, each as a finding with the evidence it
+ * used. A source reader (`chant import` of SQL Server, #4398; `chant migrate`
+ * of Postgres, #4399) does the mechanical work, a type map and a rename,
+ * and asks this module for everything that is a decision.
+ *
+ * Nothing here knows a source dialect. A reader describes its table in the
+ * neutral facts below (a candidate sort key, a column's nullability, a
+ * constraint) and gets back the ClickHouse choice, a finding to report, and
+ * for a constraint the comment lines to keep in the DDL. The rules are the
+ * same whichever database the table came from.
+ *
+ * ## API
+ *
+ * - {@link sortKeyReview}: `ORDER BY` from the candidates the source offers,
+ *   in the priority `explicit-order`, `clustering-key`, `primary-key`,
+ *   `unique-key`, then `tuple()`. Returns `orderBy`, the `settings` the key
+ *   needs (`allow_nullable_key` when a key column is `Nullable`), and a
+ *   finding that names the chosen candidate and the others it passed over.
+ * - {@link engineReview}: `MergeTree` for an append-only table;
+ *   `ReplacingMergeTree(_version, _deleted)` for a CDC mirror, with the two
+ *   columns it adds in `extraColumns`. `cdcColumns` names them otherwise
+ *   (the Postgres pair uses the `CdcMirror` composite's `_is_deleted`).
+ * - {@link nullableReview}: a column's final type. A `NOT NULL` column keeps
+ *   its type with no finding. A nullable column becomes `Nullable(T)` with a
+ *   finding; when it has a default the finding says the default could
+ *   replace `Nullable`.
+ * - {@link lowCardinalityReview}: a finding for a `String` column whose name
+ *   and declared length suggest few distinct values. It never changes the
+ *   type; offline, the name and the type are all there is to read.
+ * - {@link constraintReview}: foreign keys, checks, unique and exclusion
+ *   constraints, which ClickHouse does not enforce. Returns `comments` (SQL `--` lines to
+ *   put before the `CREATE`) and one finding per constraint.
+ * - {@link REVIEW_RULES}: every rule id with its summary and the ClickHouse
+ *   documentation it rests on, for report metadata.
+ * - {@link findingText}: a finding as one line (object, message, evidence,
+ *   suggestion), the form a SARIF `message` takes.
+ *
+ * A finding's `severity` is `warning` for a decision the author must confirm
+ * and `info` for a note that changes nothing. The caller maps findings to its
+ * own diagnostic type; `at` carries the source line and column when the
+ * reader knows them.
+ *
+ * Every ClickHouse type and engine this module writes is checked against the
+ * pinned catalog (`src/generated/clickhouse.ts`, ClickHouse 26.8) in
+ * `review-catalog.test.ts`, so a pin move that drops one fails there.
+ *
+ * Sources: the MergeTree sorting key and `allow_nullable_key`
+ * (https://clickhouse.com/docs/engines/table-engines/mergetree-family/mergetree),
+ * `ReplacingMergeTree(ver, is_deleted)`
+ * (https://clickhouse.com/docs/engines/table-engines/mergetree-family/replacingmergetree),
+ * `Nullable` (https://clickhouse.com/docs/sql-reference/data-types/nullable),
+ * `LowCardinality`
+ * (https://clickhouse.com/docs/sql-reference/data-types/lowcardinality).
+ */
+const CH_MERGETREE = "https://clickhouse.com/docs/engines/table-engines/mergetree-family/mergetree";
+/**
+ * The rules. SQLRV001 to SQLRV005 are the shared ones; the rest are raised by
+ * a source reader for what only its dialect has, and live here so a report
+ * lists one catalog.
+ */
+export const REVIEW_RULES = {
+    SQLRV001: {
+        id: "SQLRV001",
+        name: "sort-key",
+        summary: "The ORDER BY key is a suggestion from the source's indexes.",
+        docs: [CH_MERGETREE],
+    },
+    SQLRV002: {
+        id: "SQLRV002",
+        name: "engine",
+        summary: "The table engine is a choice the source does not make.",
+        docs: [CH_MERGETREE, "https://clickhouse.com/docs/engines/table-engines/mergetree-family/replacingmergetree"],
+    },
+    SQLRV003: {
+        id: "SQLRV003",
+        name: "nullable",
+        summary: "A nullable column becomes Nullable(T), which costs storage and speed; a default can replace it.",
+        docs: ["https://clickhouse.com/docs/sql-reference/data-types/nullable"],
+    },
+    SQLRV004: {
+        id: "SQLRV004",
+        name: "low-cardinality",
+        summary: "A String column that may hold few distinct values could be LowCardinality(String).",
+        docs: ["https://clickhouse.com/docs/sql-reference/data-types/lowcardinality"],
+    },
+    SQLRV005: {
+        id: "SQLRV005",
+        name: "constraint",
+        summary: "ClickHouse does not enforce this constraint; it is kept as a comment.",
+        docs: ["https://clickhouse.com/docs/sql-reference/statements/create/table"],
+    },
+    SQLRV006: {
+        id: "SQLRV006",
+        name: "generated-column",
+        summary: "An identity, sequence, computed or system-generated column has no ClickHouse equivalent.",
+        docs: ["https://clickhouse.com/docs/sql-reference/statements/create/table"],
+    },
+    SQLRV007: {
+        id: "SQLRV007",
+        name: "type-judgment",
+        summary: "The type has no exact ClickHouse match; the nearest one was chosen.",
+        docs: ["https://clickhouse.com/docs/sql-reference/data-types"],
+    },
+    SQLRV008: {
+        id: "SQLRV008",
+        name: "default-expression",
+        summary: "A default expression was translated or dropped.",
+        docs: ["https://clickhouse.com/docs/sql-reference/statements/create/table"],
+    },
+    SQLRV009: {
+        id: "SQLRV009",
+        name: "storage-option",
+        summary: "A storage option of the source (filegroup, partitioning, compression, versioning) has no counterpart here.",
+        docs: [CH_MERGETREE],
+    },
+    SQLRV010: {
+        id: "SQLRV010",
+        name: "query-text",
+        summary: "A view body is copied as written and is not translated.",
+        docs: ["https://clickhouse.com/docs/sql-reference/statements/create/view"],
+    },
+    SQLRV011: {
+        id: "SQLRV011",
+        name: "not-carried",
+        summary: "An object or statement of the source is not carried over, and is named here.",
+        docs: [],
+    },
+    SQLRV012: {
+        id: "SQLRV012",
+        name: "emulator-rejected",
+        summary: "The ClickHouse emulator refused a statement the import would write.",
+        docs: [],
+    },
+};
+/** A finding as one line. */
+export function findingText(f) {
+    const where = f.column ? `${f.object}.${f.column}` : f.object;
+    const parts = [`${where}: ${f.message}`];
+    if (f.evidence.length > 0)
+        parts.push(`Evidence: ${f.evidence.join("; ")}.`);
+    if (f.suggestion)
+        parts.push(`Suggestion: ${f.suggestion}`);
+    return parts.join(" ");
+}
+const q = (name) => (/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) ? name : `\`${name.replace(/`/g, "\\`")}\``);
+const list = (names) => names.join(", ");
+const SORT_KEY_PRIORITY = ["explicit-order", "clustering-key", "primary-key", "unique-key"];
+export function sortKeyReview(input) {
+    const ranked = SORT_KEY_PRIORITY.flatMap((kind) => input.candidates.filter((c) => c.kind === kind && c.columns.length > 0));
+    const chosen = ranked[0];
+    const evidence = [];
+    const settings = {};
+    let orderBy = [];
+    let message;
+    let suggestion;
+    if (chosen) {
+        orderBy = [...chosen.columns];
+        evidence.push(`${chosen.source} (${list(chosen.columns)})`);
+        for (const other of ranked.slice(1))
+            evidence.push(`passed over: ${other.source} (${list(other.columns)})`);
+        if (chosen.descending && chosen.descending.length > 0)
+            evidence.push(`descending in the source, ascending here: ${list(chosen.descending)}`);
+        const nullable = orderBy.filter((c) => (input.columnTypes[c] ?? "").startsWith("Nullable("));
+        if (nullable.length > 0) {
+            settings.allow_nullable_key = "1";
+            evidence.push(`Nullable key column${nullable.length > 1 ? "s" : ""}: ${list(nullable)}, so allow_nullable_key = 1 is set`);
+        }
+        message = `ORDER BY (${list(orderBy.map(q))}) suggested from the ${chosen.kind.replace("-", " ")}.`;
+        suggestion = "Put the columns your queries filter on first, and the one with the fewest distinct values before the one with the most.";
+    }
+    else {
+        orderBy = [];
+        evidence.push("no clustering key, primary key or unique key in the source");
+        message = "ORDER BY tuple() used because the source gives no key to suggest.";
+        suggestion = "Choose the columns your queries filter on; a MergeTree table without a sort key cannot skip granules.";
+    }
+    return {
+        orderBy,
+        settings,
+        finding: { ruleId: "SQLRV001", severity: "warning", object: input.object, message, evidence, ...(suggestion ? { suggestion } : {}), ...(input.at ? { at: input.at } : {}) },
+    };
+}
+export const CDC_VERSION_COLUMN = { name: "_version", type: "UInt64" };
+export const CDC_DELETED_COLUMN = { name: "_deleted", type: "UInt8" };
+export function engineReview(input) {
+    const evidence = [...(input.facts ?? [])];
+    const unique = input.uniqueKey && input.uniqueKey.length > 0 ? list(input.uniqueKey) : undefined;
+    if (input.mode === "cdc") {
+        evidence.push(`the table is mirrored from a source that updates rows in place${unique ? `, keyed on (${unique})` : ""}`);
+        const version = input.cdcColumns?.version ?? CDC_VERSION_COLUMN.name;
+        const deleted = input.cdcColumns?.deleted ?? CDC_DELETED_COLUMN.name;
+        return {
+            engine: `ReplacingMergeTree(${version}, ${deleted})`,
+            extraColumns: [
+                { name: version, type: CDC_VERSION_COLUMN.type },
+                { name: deleted, type: CDC_DELETED_COLUMN.type },
+            ],
+            finding: {
+                ruleId: "SQLRV002",
+                severity: "warning",
+                object: input.object,
+                message: `ReplacingMergeTree(${version}, ${deleted}) chosen for a mirror; it adds the columns ${version} and ${deleted}.`,
+                evidence,
+                suggestion: `The sort key must be the source key, because rows with an equal sort key collapse to the highest ${version} on merge. Read with FINAL, or filter on ${deleted}, to see the collapsed rows before a merge.`,
+                ...(input.at ? { at: input.at } : {}),
+            },
+        };
+    }
+    if (unique)
+        evidence.push(`the source enforces uniqueness on (${unique}); MergeTree does not`);
+    return {
+        engine: "MergeTree",
+        extraColumns: [],
+        finding: {
+            ruleId: "SQLRV002",
+            severity: "warning",
+            object: input.object,
+            message: "MergeTree chosen; the source has no engine to carry over.",
+            evidence,
+            suggestion: unique
+                ? "If rows can arrive twice, ReplacingMergeTree collapses duplicates of the sort key on merge, not on insert."
+                : "Pick another MergeTree variant for pre-aggregation (SummingMergeTree, AggregatingMergeTree) when the table is a rollup.",
+            ...(input.at ? { at: input.at } : {}),
+        },
+    };
+}
+export function nullableReview(input) {
+    if (!input.sourceNullable)
+        return { type: input.type };
+    const evidence = [`${input.column} allows NULL in the source`];
+    let suggestion;
+    if (input.defaultExpr !== undefined) {
+        evidence.push(`it has the default ${input.defaultExpr}`);
+        suggestion = `If NULL is never stored on purpose, declare ${input.type} DEFAULT ${input.defaultExpr} and load the default instead of NULL.`;
+    }
+    else {
+        evidence.push("it has no default");
+        suggestion = `If a sentinel value can stand for missing, declare ${input.type} DEFAULT <sentinel>; a Nullable column keeps a separate null mask.`;
+    }
+    return {
+        type: `Nullable(${input.type})`,
+        finding: {
+            ruleId: "SQLRV003",
+            severity: "warning",
+            object: input.object,
+            column: input.column,
+            message: `Kept as Nullable(${input.type}) so no stored NULL is lost.`,
+            evidence,
+            suggestion,
+            ...(input.at ? { at: input.at } : {}),
+        },
+    };
+}
+// --- LowCardinality -------------------------------------------------------
+/** Last words of a column name that usually mean a small set of values. */
+const LOW_CARDINALITY_WORDS = new Set("status state type kind category country currency region level channel gender lang language locale unit code flag method mode grade tier priority".split(" "));
+/** A column name's last word: `order_status` and `OrderStatus` both give `status`. */
+function lastWord(name) {
+    const words = name.replace(/([a-z0-9])([A-Z])/g, "$1_$2").split(/[^A-Za-z0-9]+/).filter(Boolean);
+    return (words[words.length - 1] ?? "").toLowerCase();
+}
+/** The longest declared length that still counts as supporting evidence. */
+export const LOW_CARDINALITY_MAX_LENGTH = 50;
+export function lowCardinalityReview(input) {
+    if (input.type !== "String" && input.type !== "Nullable(String)")
+        return undefined;
+    if (!LOW_CARDINALITY_WORDS.has(lastWord(input.column)))
+        return undefined;
+    const evidence = [`the name ${input.column} ends in a word that usually names a small set of values`, `the type is ${input.type}`];
+    if (input.maxLength !== undefined && input.maxLength <= LOW_CARDINALITY_MAX_LENGTH)
+        evidence.push(`the declared length is ${String(input.maxLength)}`);
+    evidence.push("no data was read, so the distinct count is unknown");
+    const wrapped = input.type.startsWith("Nullable(") ? "LowCardinality(Nullable(String))" : "LowCardinality(String)";
+    return {
+        ruleId: "SQLRV004",
+        severity: "warning",
+        object: input.object,
+        column: input.column,
+        message: `${input.column} is a LowCardinality candidate and stays ${input.type}.`,
+        evidence,
+        suggestion: `ClickHouse documents ${wrapped} as helpful below roughly ten thousand distinct values; count them with uniqExact(${q(input.column)}) before changing the type.`,
+        ...(input.at ? { at: input.at } : {}),
+    };
+}
+const oneLine = (s) => s.replace(/\s+/g, " ").trim();
+export function constraintReview(input) {
+    const comments = [];
+    const findings = [];
+    for (const c of input.constraints) {
+        const label = c.name ? ` ${c.name}` : "";
+        let text;
+        let message;
+        let suggestion;
+        if (c.kind === "foreign-key") {
+            const target = c.references ? `${c.references.table} (${list(c.references.columns)})` : "an unknown table";
+            text = `FOREIGN KEY${label} (${list(c.columns ?? [])}) REFERENCES ${target}`;
+            message = `Foreign key${label} is not enforced by ClickHouse and is kept as a comment.`;
+            suggestion = "Check referential integrity in the load pipeline, or join on the column and accept orphan rows.";
+        }
+        else if (c.kind === "unique") {
+            text = `UNIQUE${label} (${list(c.columns ?? [])})`;
+            message = `Unique constraint${label} is not enforced by ClickHouse and is kept as a comment.`;
+            suggestion = "A MergeTree sort key does not make rows unique. ReplacingMergeTree collapses duplicates on merge only.";
+        }
+        else if (c.kind === "exclusion") {
+            text = `EXCLUDE${label} ${oneLine(c.expression ?? "")}`;
+            message = `Exclusion constraint${label} is not enforced by ClickHouse and is kept as a comment.`;
+            suggestion = "ClickHouse has no constraint that rejects overlapping rows. Check for overlaps in the load, or in a query.";
+        }
+        else {
+            text = `CHECK${label} ${oneLine(c.expression ?? "")}`;
+            message = `Check constraint${label} is not translated and is kept as a comment.`;
+            suggestion = "ClickHouse has CONSTRAINT name CHECK expr, enforced on INSERT. Rewrite the expression in ClickHouse SQL to use it.";
+        }
+        comments.push(`-- ${oneLine(text)}`);
+        findings.push({
+            ruleId: "SQLRV005",
+            severity: "warning",
+            object: input.object,
+            ...(c.kind !== "check" && c.kind !== "exclusion" && c.columns && c.columns.length === 1 ? { column: c.columns[0] } : {}),
+            message,
+            evidence: [oneLine(text)],
+            suggestion,
+            ...(c.at ? { at: c.at } : {}),
+        });
+    }
+    return { comments, findings };
+}

package/dist/codegen/classifier-page.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"classifier-page.d.ts","sourceRoot":"","sources":["../../src/codegen/classifier-page.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAcH,wBAAgB,oBAAoB,IAAI,MAAM,CAiF7C"}
+{"version":3,"file":"classifier-page.d.ts","sourceRoot":"","sources":["../../src/codegen/classifier-page.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAeH,wBAAgB,oBAAoB,IAAI,MAAM,CAwH7C"}

package/dist/codegen/classifier-page.js

@@ -8,6 +8,7 @@ const LABEL = {
     drop: "drop",
     metadata: "metadata only",
     rewrite: "background rewrite",
+    replace: "replace table",
     rebuild: "rebuild",
 };
 const cell = (s) => s.replace(/\|/g, "\\|");
@@ -16,7 +17,7 @@ export function renderClassifierPage() {
     return `---
 title: "Planning ClickHouse Changes"
 label: "Planning and the Change Classifier"
-description: "How a ClickHouse schema change is classified as metadata only, a background rewrite or a rebuild, each with the ALTER restriction behind it"
+description: "How a ClickHouse schema change is classified as metadata only, a background rewrite, a replacement or a rebuild, each with the ALTER restriction behind it"
 diataxis: reference
 group: "ClickHouse"
 order: 1
@@ -30,9 +31,10 @@ Every change between two ClickHouse schemas is classified before anything runs:
 |---|---|
 | metadata only | the server records the change and touches no existing data |
 | background rewrite | a mutation rewrites existing parts in the background, with no rollback |
+| replace table | ClickHouse cannot alter a stream-engine table, and it stores no rows, so the applier drops and creates it around the views that read it |
 | rebuild | ClickHouse cannot make the change to the existing table, and the data has to be copied into a new one; a plan refuses to make it in place |
 
-Two commands report the classification, and \`chant lifecycle plan\` reports it as each update's disruption (metadata only is \`in-place\`, a rewrite \`rolling\`, a rebuild \`replace\`):
+Two commands report the classification, and \`chant lifecycle plan\` reports it as each update's disruption (metadata only is \`in-place\`, a rewrite \`rolling\`, a replacement or a rebuild \`replace\`):
 
 \`\`\`bash
 chant sql diff base.json head.json     # two chant build outputs, offline
@@ -41,13 +43,28 @@ chant sql plan prod schema.json        # a build output against the prod server
 
 Both exit 2 when a change needs a rebuild. \`chant sql diff\` compares a pull request's base and head builds with no server. \`chant sql plan\` reads the server \`sql.profiles.<env>\` binds, and asks that server's formatter about any expression the normalization rules leave different, so the server's own rewriting (\`INTERVAL 1 DAY\` as \`toIntervalDay(1)\`, \`a+b*2\` as \`a + (b * 2)\`) is not reported as a change.
 
-\`chant sql plan\` also exits 2 when a declared database holds an object whose definition it cannot read. It names each one under \`Refused\` (\`unreadable\` in \`--json\`) instead of leaving it out. Dictionaries are read and planned like the other objects: any change but a comment replaces one (SQLCH245).
+\`chant sql plan\` also exits 2 when a declared database holds an object whose definition it cannot read. It names each one under \`Refused\` (\`unreadable\` in \`--json\`) instead of leaving it out. It exits 2 as well when the build names a named collection the server doesn't have, naming each under \`Refused\` (\`namedCollections.missing\` in \`--json\`); see [Named collections](../clickhouse-ddl/#named-collections). Dictionaries are read and planned like the other objects: any change but a comment replaces one (SQLCH245).
 
 A clause chant's parser does not know ([Plain .sql Files](../sql-files/#clauses-chant-does-not-read)) is compared as text, and the rest of its object is planned as usual. A change to one is SQLCH290, refused for review with no rebuild Op suggested, since chant cannot tell what the change takes. A clause only the server prints is a hint, not a change: a newer server printing a clause with its default looks the same as a clause removed from the declaration.
 
+## Stream tables
+
+A table on Kafka, S3Queue, AzureQueue, RabbitMQ, NATS or FileLog stores no rows. It is the consumer that a materialized view reads through, and the position it has reached lives in the broker's committed offsets or in Keeper. There is no \`ALTER\` for its engine arguments, settings or columns, and there is nothing to copy, so a change to one is neither metadata nor a rebuild. It is SQLCH225, in the replace class (\`diffStreamTable\` in \`src/clickhouse/plan/diff.ts\`). The plan refuses nothing for it.
+
+The applier makes the change in place, in this order (\`replaceStreamSteps\` in \`src/clickhouse/apply/statements.ts\`): \`DETACH TABLE\` for each materialized view on the server that reads the table, \`DROP TABLE ... SYNC\`, the declared \`CREATE TABLE\`, then \`ATTACH TABLE\` for the same views. The plan names the views in a hint. Messages wait in the broker, and files wait in the bucket, while the views are detached. A change that moves a table to or from a stream engine is still SQLCH223, a rebuild, and \`ClickHouseRebuildOp\` refuses a stream-engine table by name (\`streamRefusal\` in \`src/clickhouse/rebuild/observe.ts\`).
+
+Two replacements lose the table's position, and the change carries a note saying so (\`positionWarnings\` in \`src/clickhouse/plan/stream.ts\`):
+
+- A different \`kafka_group_name\`, as a setting or as the third engine argument, is a different consumer group. It starts from its own committed offsets, or from the start of the topic when it has none.
+- A different S3Queue \`keeper_path\` is a different record of processed files. Every file already seen is processed again.
+
+An apply killed between the detach and the attach leaves the views detached, and a detached view is not in \`system.tables\`. Nothing re-attaches it: run \`ATTACH TABLE\` for each view by hand, then plan again. This has not been run against a server.
+
+The \`StreamIngest\` composite declares the stream table, the view and the MergeTree target together: see [Composites](../composites/#streamingest).
+
 ## After the plan
 
-The plan only reports. [\`clickhouseApply\`](../applying/) makes the metadata-only and background-rewrite changes, and refuses a rebuild the same way the plan does, sending nothing for that object. A rebuild runs as \`ClickHouseRebuildOp\`, a gated migration Op that creates the new table, backfills it, verifies it and swaps it in: see [Rebuilding a Table](../rebuild/). Both commands print the Op declaration to start from for each refused table.
+The plan only reports. [\`clickhouseApply\`](../applying/) makes the metadata-only, background-rewrite and stream-table changes, and refuses a rebuild the same way the plan does, sending nothing for that object. A rebuild runs as \`ClickHouseRebuildOp\`, a gated migration Op that creates the new table, backfills it, verifies it and swaps it in: see [Rebuilding a Table](../rebuild/). Both commands print the Op declaration to start from for each refused table.
 
 \`chant migrate\` plays no part in any of this. It translates a file from one lexicon's format into another's, such as a GitHub Actions workflow into GitLab CI, and does not run schema migrations.
 
@@ -70,6 +87,29 @@ A rebuild is never DDL: it is a step naming \`ClickHouseRebuildOp\`, or for a vi
 
 \`--topology\` renders the statements for where they will run: \`single\` (the default), \`cluster:<name>\`, \`replicated\` or \`cloud\`. On a cluster every statement carries \`ON CLUSTER\` and a MergeTree-family table becomes \`Replicated*MergeTree\` with its Keeper path; in a \`Replicated\` database the tables are \`Replicated*MergeTree\` with no path and no \`ON CLUSTER\`. \`diffStatements(before, after, { topology })\` takes the same choice; see [Applying to a Server](../applying/#topology).
 
+## Migration files on a pull request
+
+A workspace member that is a goose, golang-migrate, clickhouse-migrations or Flyway directory (see [Workspace kinds](/chant/reference/workspace-kinds/)) has no declaration to diff. On a pull request, \`chant components pr-plan\` lists each migration file the pull request adds to such a member, and the plan note gives every statement in it the class the rules below give the same change. This is the "check" level of adopting chant beside an existing migration tool: it reads files, applies nothing and contacts no server, so it needs no \`--env\`.
+
+The up statements are the ones \`chant sql replay\` would run: goose's \`-- +goose Up\` section, the whole \`.up.sql\` file for golang-migrate, the whole file for clickhouse-migrations, and a Flyway file after placeholder substitution with the values in \`flyway.toml\` or \`flyway.conf\`. A file the base commit already has is not new, whatever the pull request does to it. Undo files are left out.
+
+\`\`\`text
+\`db/00002_orders.sql\` (member \`ledger\`, postgres)
+- 1. \`CREATE INDEX orders_status_idx ON orders (status)\`: needs CONCURRENTLY (SQLPG241, SHARE)
+- 2. \`ALTER TABLE orders ALTER COLUMN a TYPE bigint\`: undecided between SQLPG206 metadata only and SQLPG207 ACCESS EXCLUSIVE rewrite or scan
+\`\`\`
+
+Each statement is read with the dialect's parser (\`CREATE\`, \`GRANT\`, \`COMMENT ON\`) or word by word (\`ALTER\`, \`DROP\`, \`RENAME\`), and the lock on a Postgres statement is the one its rule's text names. The code is \`lexicons/sql/src/postgres/plan/statements.ts\` and \`lexicons/sql/src/clickhouse/plan/statements.ts\`.
+
+A statement alone cannot always decide a rule, and then the note names the candidates and does not guess:
+
+- \`ALTER COLUMN ... TYPE\` is SQLPG206 or SQLPG207 by the column's old type, and SQLPG208 as well with a \`USING\` expression.
+- \`MODIFY COLUMN <type>\` is SQLCH210 or SQLCH211, \`DROP COLUMN\` SQLCH202 or SQLCH213, and \`RENAME COLUMN\` SQLCH212 or SQLCH213, by whether the column is in a key. When the same file creates the table, its keys are known and the statement is classified.
+- \`MODIFY ORDER BY\` is SQLCH220, a rebuild. It is SQLCH216 or SQLCH220 when the same \`ALTER\` adds the columns the new key ends with, unless the file created the table and shows the old key is kept.
+- \`CREATE OR REPLACE VIEW\` is SQLPG250 or SQLPG251 by whether the view keeps its columns.
+
+A statement that reads or writes rows (\`INSERT\`, \`UPDATE\`, \`TRUNCATE\`) is listed as data. A schema change no rule covers, such as \`ALTER TABLE ... OWNER TO\` or a ClickHouse \`DROP PARTITION\`, is listed as having no class.
+
 ## Identity and renames
 
 An object is identified by its export name between two builds, so a changed name in the SQL under the same export is a rename. Against a server, which has no export names, an object is identified by \`database.name\`; a declaration renamed since the server last saw it says so with \`-- previously: <old name>\` before its CREATE.

package/dist/codegen/clickhouse-module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clickhouse-module.d.ts","sourceRoot":"","sources":["../../src/codegen/clickhouse-module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAc,MAAM,iBAAiB,CAAC;AA6BrE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAmED,MAAM,WAAW,cAAc;IAC7B,0GAA0G;IAC1G,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,CAmKjF"}
+{"version":3,"file":"clickhouse-module.d.ts","sourceRoot":"","sources":["../../src/codegen/clickhouse-module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAc,MAAM,iBAAiB,CAAC;AA6BrE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAmED,MAAM,WAAW,cAAc;IAC7B,0GAA0G;IAC1G,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,CAsKjF"}