@intentius/chant-lexicon-sql 0.0.0-stage → 0.112.1

package/README.md

@@ -1,3 +1,40 @@
-# Temporary Holding Version
+# @intentius/chant-lexicon-sql
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+SQL lexicon for [chant](https://github.com/INTENTIUS/chant): database schema as typed declarations, one database dialect at a time. Two dialects ship: ClickHouse at `@intentius/chant-lexicon-sql/clickhouse` and Postgres at `@intentius/chant-lexicon-sql/postgres`.
+
+```bash
+npm install --save-dev @intentius/chant @intentius/chant-lexicon-sql
+```
+
+chant is spec-true per dialect, not database-agnostic. A dialect's engines, column types, codecs and settings are that database's own, read from a pinned server, and its change rules are that database's `ALTER` restrictions. There is no neutral schema model between dialects.
+
+What the package holds:
+
+- SQL-shaped tagged templates that parse each dialect's DDL at build time into entities, with references, dependency order and column-level lineage for views. ClickHouse has `database`, `table`, `view` and materialized views; Postgres has schemas, tables, indexes, views, materialized views, sequences, enum types, domains and extensions. `chant build` writes a JSON schema document and the statements, in creation order, to `clickhouse.sql` or `postgres.sql`.
+- Lint at the token (SQLCH001 to SQLCH003, SQLPG001 to SQLPG004) and after the build (SQLCH101 to SQLCH120, SQLPG101 to SQLPG118), checked against what the pinned server accepts.
+- Type catalogs generated from pinned servers and committed as snapshots: `clickhouse/clickhouse-server:26.8.15.10`'s `system.*` tables, and one Postgres server per major from 14 to 18, with hand-written overlays for the grammar a catalog does not carry.
+- Composites for both dialects, among them events, audit-log, soft-delete and tenant tables, rollup and refreshed views, and a CDC mirror.
+
+```ts
+import { table, view } from "@intentius/chant-lexicon-sql/clickhouse";
+
+export const events = table`
+  CREATE TABLE events (user_id UUID, kind LowCardinality(String), ts DateTime)
+  ENGINE = MergeTree ORDER BY (user_id, ts)`;
+
+export const byKind = view`
+  CREATE VIEW by_kind AS
+  SELECT ${events.columns.kind} AS kind, count() AS n FROM ${events} GROUP BY kind`;
+```
+
+- `chant import --from <env>` writes a live server's schema as declarations; `describeResources` and `observeResourcesDeep` read the server `sql.profiles.<env>` binds, and `chant lifecycle diff <env> --live` reports drift on it.
+- Every schema change classified before it runs: `chant sql diff <base.json> <head.json>` offline, `chant sql plan <env> <build.json>` against a server. A ClickHouse change is metadata only, a background rewrite or a rebuild, citing the `ALTER` restriction behind it; a Postgres change names the lock it takes. A rebuild is refused in place, and `chant sql plan` exits 2 on one.
+- Applying through `ApplyOp`: `target: "clickhouse"` (`clickhouseApply`) and `target: "postgres"` (`postgresApply`, in transactions, with `CONCURRENTLY` outside them). A ClickHouse rebuild runs as `ClickHouseRebuildOp`; a Postgres column rename or type change as `PostgresMigrationOp`, expand and contract.
+
+## Generating
+
+`npm run generate` reads the committed snapshots; no Docker or network is needed. Moving a pin (`src/spec/pin.ts` for ClickHouse, `src/spec/postgres-pin.ts` for Postgres) makes generation start that server in a throwaway container and rewrite its snapshot. See `docs/pages/clickhouse-catalog.mdx` and `docs/pages/postgres-majors.mdx`.
+
+## Rule ids
+
+`SQL` prefixes every rule this lexicon ships. Rules that hold in every dialect are `SQL` plus three digits; the ClickHouse dialect's are `SQLCH` and the Postgres dialect's `SQLPG`, each plus three digits.

package/dist/clickhouse/apply/apply.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The ClickHouse applier (#3208): make a server hold what a build declares,
+ * for every change the classifier (`../plan/rules.ts`) puts in the metadata
+ * or background-rewrite class, and refuse the rest.
+ *
+ * Per declared object, exactly one verdict (lexicon-authoring/applying.mdx):
+ *
+ * - APPLIED `created`: absent on the server; created from its declared
+ *   `CREATE`, with chant's ownership marker in its comment.
+ * - APPLIED `updated`: present, and the `ALTER`s for its changes ran. A
+ *   background rewrite (a column type change, a TTL change) is waited on in
+ *   `system.mutations` before the object counts as applied.
+ * - APPLIED `unchanged`: present, nothing to change, the marker in place.
+ * - NOT-ATTEMPTED `unsupported-kind`: a change ClickHouse cannot make with
+ *   `ALTER` (a sorting key, a partition key, an engine, a key column's type).
+ *   Nothing is sent for the object; the detail names each rule and the
+ *   restriction behind it, and names the rebuild migration Op to run instead
+ *   (`ClickHouseRebuildOp`, #3198).
+ * - NOT-ATTEMPTED `filtered`: the change drops a column, which destroys its
+ *   data, and the apply was not allowed to delete.
+ * - NOT-ATTEMPTED `dependency-failed`: an object it references is not on the
+ *   server, because creating it failed or was not attempted.
+ * - NOT-ATTEMPTED with the binding's reason: no server to apply to.
+ *
+ * A statement the server refuses is neither: the object was attempted and did
+ * not converge. The rest of the apply goes on, and the applier then throws
+ * {@link ClickHouseApplyError}, which carries the outcome so far.
+ *
+ * Prune, when asked for, drops the objects in the declared databases that the
+ * build no longer declares and whose comment carries this project's marker
+ * (stack and env). Nothing else is ever dropped: an object without the marker
+ * is not chant's, and one with another stack's marker is that stack's.
+ */
+import type { OwnershipMarker } from "@intentius/chant/ownership";
+import type { ApplyRef } from "@intentius/chant/apply";
+import { SqlApplyError, type SqlApplyOutcome } from "../../core/apply.js";
+import type { ClickHouseTarget } from "../live/bind.js";
+import { type CanonicalObject } from "../plan/normalize.js";
+import { type Change } from "../plan/diff.js";
+import { type DeclaredObject } from "./statements.js";
+export type { FailedObject } from "../../core/apply.js";
+/**
+ * The objects a `chant build` output declares, in creation order. Takes the
+ * sql lexicon's primary output, or a multi-lexicon output holding it under
+ * `sql` (the shared core's reader).
+ */
+export declare function declaredObjects(json: string, defaultDatabase?: string): DeclaredObject[];
+/** The plan axis: one ref per declared object, by its kind and its name on the server. */
+export declare const planRefs: (declared: readonly DeclaredObject[]) => ApplyRef[];
+export interface ClickHouseApplyOptions {
+    /** The marker to stamp, and the identity a prune matches. Without a stack, prune declines. */
+    marker?: OwnershipMarker;
+    /** Drop owned objects the build no longer declares, and allow column drops. Default: off. */
+    prune?: boolean;
+    /** How long to wait for one table's mutations. Default: ten minutes. */
+    mutationTimeoutMs?: number;
+    signal?: AbortSignal;
+    /** Where to report each statement. Default: nowhere. */
+    log?: (line: string) => void;
+}
+/**
+ * The shared core's outcome: `target` is the server's URL, `source` where the
+ * binding came from (`sql.profiles.<env>` or `env CLICKHOUSE_URL`).
+ */
+export type ClickHouseApplyOutcome = SqlApplyOutcome;
+/** An apply in which the server refused a statement. The outcome says what did and did not happen. */
+export declare class ClickHouseApplyError extends SqlApplyError<ClickHouseApplyOutcome> {
+    constructor(outcome: ClickHouseApplyOutcome);
+}
+/**
+ * The classified changes from the server to the declarations, keyed by the
+ * declared object (`database.name`), with formatting-only differences dropped
+ * by asking the server, as `chant sql plan` does.
+ */
+export declare function plannedChanges(target: ClickHouseTarget, declared: readonly DeclaredObject[], live: Map<string, CanonicalObject>): Promise<Change[]>;
+/**
+ * Apply the declarations to the server. Returns every declared object in
+ * exactly one of applied or not attempted, and every pruned orphan; throws
+ * {@link ClickHouseApplyError} when the server refused a statement.
+ */
+export declare function applyClickHouse(target: ClickHouseTarget, declared: readonly DeclaredObject[], opts?: ClickHouseApplyOptions): Promise<ClickHouseApplyOutcome>;
+//# sourceMappingURL=apply.d.ts.map

package/dist/clickhouse/apply/apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../src/clickhouse/apply/apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EACL,aAAa,EAKb,KAAK,eAAe,EACrB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,EAAe,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAIxD,OAAO,EAUL,KAAK,cAAc,EAEpB,MAAM,cAAc,CAAC;AAGtB,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,eAAe,SAAY,GAAG,cAAc,EAAE,CAY3F;AAED,0FAA0F;AAC1F,eAAO,MAAM,QAAQ,GAAI,UAAU,SAAS,cAAc,EAAE,KAAG,QAAQ,EAA0D,CAAC;AAElI,MAAM,WAAW,sBAAsB;IACrC,8FAA8F;IAC9F,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,6FAA6F;IAC7F,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,wEAAwE;IACxE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,wDAAwD;IACxD,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG,eAAe,CAAC;AAErD,sGAAsG;AACtG,qBAAa,oBAAqB,SAAQ,aAAa,CAAC,sBAAsB,CAAC;gBACjE,OAAO,EAAE,sBAAsB;CAI5C;AAwBD;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,SAAS,cAAc,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAMzJ;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,SAAS,cAAc,EAAE,EAAE,IAAI,GAAE,sBAA2B,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAmFvK"}

package/dist/clickhouse/apply/mutations.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Waiting on a background rewrite (#3208).
+ *
+ * A column type change or a TTL change returns as soon as the server has
+ * recorded it; the rewrite of existing parts runs afterwards as a mutation,
+ * listed in `system.mutations` until it is done. An apply that reported
+ * APPLIED at that point would claim a table had converged while its parts
+ * were still being rewritten, so the applier waits for every unfinished
+ * mutation on the table, and reports the ids when it stops waiting.
+ */
+import { type ClickHouseEndpoint } from "../http.js";
+export interface PendingMutation {
+    mutation_id: string;
+    command: string;
+    latest_fail_reason: string;
+}
+/** A mutation that did not finish in time. The ids are what `system.mutations` and `KILL MUTATION` name. */
+export declare class MutationTimeoutError extends Error {
+    readonly table: string;
+    readonly mutationIds: string[];
+    readonly timeoutMs: number;
+    constructor(table: string, mutationIds: string[], timeoutMs: number);
+}
+/** A mutation the server keeps failing. It is retried forever, so waiting longer does not help. */
+export declare class MutationFailedError extends Error {
+    readonly table: string;
+    readonly mutationId: string;
+    readonly reason: string;
+    constructor(table: string, mutationId: string, reason: string);
+}
+/** The table's mutations that are not done. */
+export declare function pendingMutations(endpoint: ClickHouseEndpoint, database: string, table: string): Promise<PendingMutation[]>;
+export interface WaitOptions {
+    /** How long to wait in all. Default: ten minutes. */
+    timeoutMs?: number;
+    /** First poll interval; it doubles up to two seconds. Default: 100ms. */
+    intervalMs?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Wait until the table has no unfinished mutation. Returns the ids waited on.
+ * Throws {@link MutationFailedError} as soon as one reports a failure, and
+ * {@link MutationTimeoutError} naming the ids still running at the deadline.
+ */
+export declare function waitForMutations(endpoint: ClickHouseEndpoint, database: string, table: string, opts?: WaitOptions): Promise<string[]>;
+//# sourceMappingURL=mutations.d.ts.map

package/dist/clickhouse/apply/mutations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutations.d.ts","sourceRoot":"","sources":["../../../src/clickhouse/apply/mutations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAmB,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAGnE,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,4GAA4G;AAC5G,qBAAa,oBAAqB,SAAQ,KAAK;IAE3C,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM;gBAFjB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EAAE,EACrB,SAAS,EAAE,MAAM;CAQ7B;AAED,mGAAmG;AACnG,qBAAa,mBAAoB,SAAQ,KAAK;IAE1C,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM;gBAFd,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM;CAQ1B;AAED,+CAA+C;AAC/C,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAMhI;AAED,MAAM,WAAW,WAAW;IAC1B,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAiB/I"}

package/dist/clickhouse/apply/statements.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The statements that make one classified change (#3208): a `CREATE` with
+ * chant's marker in its comment, the `ALTER`s for the metadata and
+ * background-rewrite classes, and the `DROP` a prune issues.
+ *
+ * Each function here takes a declared object and the changes the classifier
+ * reported for it, and returns SQL; nothing is sent. The applier
+ * (`./apply.ts`) sends them, and the rebuild migration (#3198) builds its new
+ * table and swaps it in with the same pieces.
+ *
+ * The SQL is taken from the declaration's own text wherever it can be: a
+ * column's definition, an index's expression, a TTL, a setting's value are
+ * the spans the parser found in the declared `CREATE`, not the normalized
+ * forms the classifier compared. The normalized form is for comparing; what
+ * the server is sent is what the author wrote.
+ */
+import type { OwnershipMarker } from "@intentius/chant/ownership";
+import { type CanonicalObject } from "../plan/normalize.js";
+import type { Change } from "../plan/diff.js";
+import { type ClickHouseEntityType } from "../entities.js";
+/** A backquoted identifier. */
+export declare const ident: (name: string) => string;
+/** `database.name` backquoted, or a database's bare name. */
+export declare const qualifiedIdent: (database: string | undefined, name: string) => string;
+/** A single-quoted string literal. */
+export declare const sqlString: (value: string) => string;
+/** `db.name` split at its first dot. */
+export declare function splitQualified(name: string): {
+    database?: string;
+    name: string;
+};
+/** One object as a build declares it, in the shape the applier works with. */
+export interface DeclaredObject {
+    /** The export name: the object's identity in chant. */
+    exportName: string;
+    type: ClickHouseEntityType;
+    /** `database.name` for a table or view, the name for a database: its identity on the server. */
+    key: string;
+    ddl: string;
+    canonical: CanonicalObject;
+    /** The export names this object references. */
+    dependsOn: string[];
+}
+/** One statement to send, and whether it starts a background rewrite to wait on. */
+export interface Step {
+    sql: string;
+    /** A mutation follows on the server; wait on `system.mutations` before the next step. */
+    rewrite: boolean;
+}
+/** The object's name on the server, quoted. */
+export declare const objectIdent: (obj: DeclaredObject) => string;
+/**
+ * The declared `CREATE` with chant's ownership marker in its comment: the
+ * declared comment, if any, with the trailer after it, or a `COMMENT` clause
+ * added at the end. Set in the `CREATE` itself, so no object is ever created
+ * unmarked. `orReplace` turns `CREATE VIEW` into `CREATE OR REPLACE VIEW`;
+ * `trailer` adds pairs to the marker (the rebuild migration's working
+ * objects, `../rebuild/`).
+ */
+export declare function createStatement(obj: DeclaredObject, marker: OwnershipMarker | undefined, opts?: {
+    orReplace?: boolean;
+    trailer?: Readonly<Record<string, string>>;
+}): string;
+/** Restamp the object's comment: the declared comment with this project's marker. */
+export declare function commentStatement(obj: DeclaredObject, marker: OwnershipMarker | undefined): string;
+/** The `DROP` for an object a prune removes. `SYNC` so the name is free when it returns. */
+export declare function dropStatement(type: string, database: string | undefined, name: string): string;
+/** Changes a plan refuses to make in place: they run as the rebuild migration (#3198). */
+export declare const isRebuild: (c: Change) => boolean;
+/** Changes that remove data from an object the build still declares: withheld unless the apply may delete. */
+export declare const isDestructiveAlter: (c: Change) => boolean;
+/**
+ * A refused change in a sentence: the rule, the restriction, where it is
+ * stated, and where the change goes instead: the rebuild migration Op for
+ * the table (`key`, `database.name`), or for a view or database, which the
+ * Op does not rebuild, a drop and a create.
+ */
+export declare function refusalDetail(changes: readonly Change[], key?: string, type?: string): string;
+/**
+ * The declaration under another name in the same database: the rebuild
+ * migration creates its new table from the declared `CREATE` this way.
+ */
+export declare function renamedDeclaration(obj: DeclaredObject, name: string, defaultDatabase?: string): DeclaredObject;
+/**
+ * The statements that make an existing object match its declaration, for the
+ * metadata and background-rewrite changes the classifier reported for it.
+ * Rebuild-class changes are not handled here: the caller refuses them.
+ * `live` is the object's current definition, which a column reorder needs.
+ *
+ * The object's own comment, and chant's marker in it, are not set here
+ * (`commentStatement`), except where a plain view is replaced whole.
+ */
+export declare function alterSteps(obj: DeclaredObject, changes: readonly Change[], opts?: {
+    live?: CanonicalObject;
+    marker?: OwnershipMarker;
+}): Step[];
+/** Whether the steps for these changes already set the object's comment (a plain view replaced whole). */
+export declare function stepsSetComment(obj: DeclaredObject, changes: readonly Change[]): boolean;
+//# sourceMappingURL=statements.d.ts.map

package/dist/clickhouse/apply/statements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statements.d.ts","sourceRoot":"","sources":["../../../src/clickhouse/apply/statements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAGlE,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAG3C,OAAO,EAA2B,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEjF,+BAA+B;AAC/B,eAAO,MAAM,KAAK,GAAI,MAAM,MAAM,KAAG,MAA2C,CAAC;AAEjF,6DAA6D;AAC7D,eAAO,MAAM,cAAc,GAAI,UAAU,MAAM,GAAG,SAAS,EAAE,MAAM,MAAM,KAAG,MACA,CAAC;AAE7E,sCAAsC;AACtC,eAAO,MAAM,SAAS,GAAI,OAAO,MAAM,KAAG,MAAkE,CAAC;AAE7G,wCAAwC;AACxC,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAGhF;AAED,8EAA8E;AAC9E,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,oBAAoB,CAAC;IAC3B,gGAAgG;IAChG,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,eAAe,CAAC;IAC3B,+CAA+C;IAC/C,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,oFAAoF;AACpF,MAAM,WAAW,IAAI;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,yFAAyF;IACzF,OAAO,EAAE,OAAO,CAAC;CAClB;AA4BD,+CAA+C;AAC/C,eAAO,MAAM,WAAW,GAAI,KAAK,cAAc,KAAG,MAAoE,CAAC;AAYvH;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,eAAe,GAAG,SAAS,EACnC,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAAO,GAC7E,MAAM,CAmBR;AAED,qFAAqF;AACrF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,eAAe,GAAG,SAAS,GAAG,MAAM,CAKjG;AAED,4FAA4F;AAC5F,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAI9F;AAED,0FAA0F;AAC1F,eAAO,MAAM,SAAS,GAAI,GAAG,MAAM,KAAG,OAAgC,CAAC;AAEvE,8GAA8G;AAC9G,eAAO,MAAM,kBAAkB,GAAI,GAAG,MAAM,KAAG,OAAgC,CAAC;AAEhF;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAW7F;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,eAAe,SAAY,GAAG,cAAc,CAejH;AA8KD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,cAAc,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,eAAe,CAAC;IAAC,MAAM,CAAC,EAAE,eAAe,CAAA;CAAO,GAAG,IAAI,EAAE,CAWnJ;AAED,0GAA0G;AAC1G,wBAAgB,eAAe,CAAC,GAAG,EAAE,cAAc,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAExF"}

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

@@ -0,0 +1,76 @@
+/**
+ * The shapes of the generated ClickHouse catalog tables
+ * (`src/generated/clickhouse.ts`). The data is generated; these types are
+ * not, so the generated module stays data and a reader of it has one place to
+ * look for what a field means.
+ */
+import type { ArgumentKind, ArgumentOverlay } from "./overlays/kinds.js";
+import type { CodecOverlay } from "./overlays/codecs.js";
+import type { EngineCapabilities } from "../spec/catalog.js";
+export type { ArgumentKind, ArgumentOverlay, EngineCapabilities };
+/** One engine or skip-index argument: its place in the syntax line, and its kind where the overlay knows it. */
+export interface ArgumentSpec {
+    name: string;
+    position: number;
+    optional: boolean;
+    repeated: boolean;
+    /** Written `name = value`. */
+    named: boolean;
+    /** `"unknown"` for an argument no overlay types; a quoted placeholder is always `string`. */
+    kind: ArgumentKind | "unknown";
+    values?: readonly string[];
+    range?: readonly [number, number];
+    note?: string;
+}
+export interface TableEngineSpec {
+    capabilities: EngineCapabilities;
+    /** The server's own usage line. */
+    syntax: string;
+    /**
+     * The engine's arguments, or `undefined` when the syntax line is not an
+     * `ENGINE = Name(...)` line the generator can read (`View`,
+     * `MaterializedView`, `WindowView`, `Loop`).
+     */
+    args?: readonly ArgumentSpec[];
+    /** True when an overlay types every argument. */
+    typed: boolean;
+    /** A MergeTree family member, Replicated or not. */
+    mergeTree: boolean;
+    /** For a `Replicated*` engine, the engine it replicates. */
+    replicates?: string;
+    summary: string;
+}
+export interface DatabaseEngineSpec {
+    syntax: string;
+    summary: string;
+}
+export interface TypeFamilySpec {
+    /** The canonical family: itself, or what an alias stands for. */
+    canonical: string;
+    caseInsensitive: boolean;
+}
+export interface CodecSpec {
+    compression: boolean;
+    generic: boolean;
+    encryption: boolean;
+    timeseries: boolean;
+    experimental: boolean;
+    role: CodecOverlay["role"];
+    parameters: CodecOverlay["parameters"];
+    summary: string;
+}
+export interface SkipIndexSpec {
+    syntax: string;
+    args?: readonly ArgumentSpec[];
+    summary: string;
+}
+export interface SettingSpec {
+    /** The server's setting type (`UInt64`, `Bool`, `MergeSelectorAlgorithm`). */
+    type: string;
+    default: string;
+    tier: string;
+    obsolete: boolean;
+    /** The server's `readonly` flag for the setting. */
+    readonly: boolean;
+}
+//# sourceMappingURL=catalog-types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-types.d.ts","sourceRoot":"","sources":["../../src/clickhouse/catalog-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1D,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,CAAC;AAElE,gHAAgH;AAChH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,8BAA8B;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,6FAA6F;IAC7F,IAAI,EAAE,YAAY,GAAG,SAAS,CAAC;IAC/B,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,KAAK,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,kBAAkB,CAAC;IACjC,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC/B,iDAAiD;IACjD,KAAK,EAAE,OAAO,CAAC;IACf,oDAAoD;IACpD,SAAS,EAAE,OAAO,CAAC;IACnB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;IACtB,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IAC3B,UAAU,EAAE,YAAY,CAAC,YAAY,CAAC,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,oDAAoD;IACpD,QAAQ,EAAE,OAAO,CAAC;CACnB"}

package/dist/clickhouse/container.d.ts

@@ -0,0 +1,63 @@
+/**
+ * A throwaway `clickhouse-server` in a container: started on a random loopback
+ * port under a unique name, and always removed (the shared core's
+ * `../core/container.ts`, ready when it answers `/ping`).
+ *
+ * Generation uses it on a pin move to read the pinned server's catalog. The
+ * live tests use the same helper so every container chant starts is started
+ * and cleaned up one way. A cluster of replicas with embedded Keeper is
+ * ClickHouse's own.
+ */
+import { type ClickHouseEndpoint } from "./http.js";
+export { dockerAvailable } from "../core/container.js";
+export interface ScratchServer {
+    endpoint: ClickHouseEndpoint;
+    /** The container's name, for a log line. */
+    name: string;
+    /** Remove the container. Safe to call twice. */
+    stop(): Promise<void>;
+}
+/**
+ * Start `image` and wait until it answers `/ping`. Pulls the image when it is
+ * not present, which is the one network step here.
+ */
+export declare function startScratchServer(image: string, options?: {
+    namePrefix?: string;
+    readyTimeoutMs?: number;
+}): Promise<ScratchServer>;
+export interface ScratchCluster {
+    /** One endpoint per replica, in replica order (`r1`, `r2`, ...). */
+    replicas: ClickHouseEndpoint[];
+    /** The containers' common name prefix, for a log line. */
+    name: string;
+    /** Remove the containers and their network. Safe to call twice. */
+    stop(): Promise<void>;
+    /**
+     * Stop one replica's container (`docker stop`, by index into `replicas`),
+     * keeping its data. The first replica runs Keeper, so stopping it stops
+     * the cluster's Keeper too.
+     */
+    stopReplica(index: number): Promise<void>;
+    /**
+     * Start a stopped replica again and wait until it answers and reaches
+     * Keeper. Docker gives it a new host port, so `replicas[index]` is
+     * replaced with its new endpoint, which is also returned.
+     */
+    startReplica(index: number): Promise<ClickHouseEndpoint>;
+}
+/**
+ * Start `replicas` servers of `image` as one shard of replicas, on their own
+ * Docker network, and wait until each answers and reaches Keeper.
+ *
+ * Keeper is the server's embedded one (`keeper_server`), run by the first
+ * replica, so the pinned server image and its digest pin Keeper too. Each
+ * replica gets the macros `{shard}` = `s1` and `{replica}` = `r<n>`, which
+ * a `Replicated` database's arguments name. Configuration is copied into each
+ * container before it starts, with no bind mount.
+ */
+export declare function startScratchCluster(image: string, options?: {
+    replicas?: number;
+    namePrefix?: string;
+    readyTimeoutMs?: number;
+}): Promise<ScratchCluster>;
+//# sourceMappingURL=container.d.ts.map

package/dist/clickhouse/container.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../../src/clickhouse/container.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,OAAO,EAAmC,KAAK,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAGlF,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAIpD,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7D,OAAO,CAAC,aAAa,CAAC,CAYxB;AAED,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,QAAQ,EAAE,kBAAkB,EAAE,CAAC;IAC/B,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB;;;;OAIG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C;;;;OAIG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAC1D;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAO,GAChF,OAAO,CAAC,cAAc,CAAC,CAyFzB"}

package/dist/clickhouse/engine-syntax.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Read the argument list out of a ClickHouse engine's one-line `syntax`
+ * (`system.table_engines.syntax`, `system.data_skipping_index_types.syntax`).
+ *
+ * The line is prose, not grammar: `ReplacingMergeTree([ver [, is_deleted]])`,
+ * `Join(join_strictness, join_type, k1[, k2, ...])`,
+ * `File(format[, path | fd])`. What it does give reliably is each argument's
+ * name, position, whether it sits inside brackets (optional), whether it is a
+ * quoted placeholder (a string literal), and a trailing `...` (repeatable).
+ * That is the generated half of an engine's argument types; what kind of value
+ * each argument takes is the overlay's half (`overlays/engines.ts`).
+ *
+ * A line this reader cannot follow yields `undefined`, never a guess, and the
+ * engine's arguments stay untyped.
+ */
+export interface SyntaxArgument {
+    /** The placeholder's name. Alternatives are joined with `|`: `path|fd`. A quoted placeholder keeps its text: `host:port`. */
+    name: string;
+    /** 0-based position among the arguments. */
+    position: number;
+    /** Inside `[...]` in the syntax line. */
+    optional: boolean;
+    /** Written as a quoted placeholder, so the argument is a string literal. */
+    quoted: boolean;
+    /** Followed by `...`: the argument repeats. */
+    repeated: boolean;
+    /** Written `name = value`: a named parameter, not a positional one (`text(tokenizer = ...)`). */
+    named: boolean;
+}
+export interface ParsedSyntax {
+    /** The engine or index type name the line opens with. */
+    name: string;
+    /** False when the line has no parenthesised list at all (`ENGINE = Log`). */
+    parenthesised: boolean;
+    args: SyntaxArgument[];
+}
+/**
+ * Parse `ENGINE = Name(args) ...` or `INDEX name expr TYPE Name(args) ...`.
+ * Returns `undefined` for a line that is not one of those shapes or whose
+ * argument list does not follow the bracket-and-comma convention.
+ */
+export declare function parseEngineSyntax(syntax: string): ParsedSyntax | undefined;
+//# sourceMappingURL=engine-syntax.d.ts.map

package/dist/clickhouse/engine-syntax.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-syntax.d.ts","sourceRoot":"","sources":["../../src/clickhouse/engine-syntax.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,cAAc;IAC7B,6HAA6H;IAC7H,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,QAAQ,EAAE,OAAO,CAAC;IAClB,4EAA4E;IAC5E,MAAM,EAAE,OAAO,CAAC;IAChB,+CAA+C;IAC/C,QAAQ,EAAE,OAAO,CAAC;IAClB,iGAAiG;IACjG,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,aAAa,EAAE,OAAO,CAAC;IACvB,IAAI,EAAE,cAAc,EAAE,CAAC;CACxB;AAiDD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAiF1E"}