@chkit/clickhouse 0.1.2-beta.7 → 0.2.0-beta.12

package/dist/ddl-propagation.d.ts

@@ -1,18 +1,74 @@
 import type { ClickHouseExecutor } from './index.js';
-export declare function waitForTable(executor: ClickHouseExecutor, database: string, tableName: string): Promise<void>;
-export declare function waitForView(executor: ClickHouseExecutor, database: string, viewName: string): Promise<void>;
-export declare function waitForDictionary(executor: ClickHouseExecutor, database: string, dictionaryName: string): Promise<void>;
-export declare function waitForColumn(executor: ClickHouseExecutor, database: string, tableName: string, columnName: string): Promise<void>;
+/**
+ * Where a propagation wait looks. Pass the configured `clickhouse.cluster`;
+ * without one the `default` cluster is probed (ObsessionDB). On a target with
+ * several replicas the wait holds until every replica shows the change: the
+ * next statement may land on any of them, and an ALTER that runs on a replica
+ * that has not applied the previous one can write back its stale schema.
+ */
+export interface PropagationOptions {
+    cluster?: string;
+    /**
+     * The statement that ran. A MODIFY COLUMN wait reads what the statement sets
+     * from it, and a RENAME COLUMN wait reads the old and new names.
+     */
+    statement?: string;
+}
+export declare function waitForTable(executor: ClickHouseExecutor, database: string, tableName: string, options?: PropagationOptions): Promise<void>;
+export declare function waitForView(executor: ClickHouseExecutor, database: string, viewName: string, options?: PropagationOptions): Promise<void>;
+/**
+ * Waits until the dictionary's catalog row is on every replica.
+ *
+ * `system.dictionaries` is the wrong signal. It lists each replica's
+ * in-memory loader (`ExternalLoader` load results), not the replicated
+ * catalog. `CREATE OR REPLACE DICTIONARY` drops that loader entry while the
+ * replica reloads, so a replica can omit the dictionary for the whole retry
+ * budget after the DDL is already in `system.tables`. A following statement
+ * only needs the catalog object.
+ *
+ * On several replicas the wait holds until every replica stores the same
+ * non-nil `uuid`. A replace does not remove the row, and ClickHouse redacts
+ * a SOURCE password to `[HIDDEN]` in `create_table_query`, so a password-only
+ * replace compares equal to the previous definition. `CREATE OR REPLACE`
+ * still assigns one new UUID in the replicated DDL (an `ON CLUSTER` statement
+ * and a Replicated database), and every replica that has applied it reports
+ * that UUID. `metadata_modification_time` is each replica's metadata-file
+ * mtime at second precision: it can stay unchanged across a replace in the
+ * same second, and two replicas that have both applied the DDL can disagree.
+ */
+export declare function waitForDictionary(executor: ClickHouseExecutor, database: string, dictionaryName: string, options?: PropagationOptions): Promise<void>;
+export declare function waitForColumn(executor: ClickHouseExecutor, database: string, tableName: string, columnName: string, options?: PropagationOptions): Promise<void>;
+export declare function waitForColumnAbsent(executor: ClickHouseExecutor, database: string, tableName: string, columnName: string, options?: PropagationOptions): Promise<void>;
+/**
+ * Waits until every replica lists both tables of `EXCHANGE TABLES a AND b`
+ * with one uuid each, and the two uuids differ. The replica that ran the
+ * statement has swapped them, so once all replicas agree, all have. A
+ * statement that runs on a replica that has not applied the swap yet would
+ * see the old names: a following DROP of the pre-cutover table would drop the
+ * new one.
+ *
+ * With `clickhouse.cluster` the statement ran `ON CLUSTER`, which returns once
+ * every host executed it, and each host may hold its own uuids, so there is
+ * nothing to wait for. A single replica has nothing to wait for either.
+ */
+export declare function waitForExchange(executor: ClickHouseExecutor, statement: string, options?: PropagationOptions): Promise<void>;
+interface QualifiedName {
+    database: string;
+    name: string;
+}
+/** The two tables of `EXCHANGE TABLES db.a AND db.b`, or undefined. */
+export declare function parseExchangeTables(statement: string): [QualifiedName, QualifiedName] | undefined;
 /**
  * Polls a query until its rows satisfy `predicate`, then returns them. Use for
  * reads that race DDL/DML propagation on managed ClickHouse (e.g. journal rows
  * written by a just-finished migration that aren't yet visible via FINAL).
  */
 export declare function waitForRows<T>(executor: ClickHouseExecutor, sql: string, predicate: (rows: T[]) => boolean, label?: string): Promise<T[]>;
-export declare function waitForTableAbsent(executor: ClickHouseExecutor, database: string, tableName: string): Promise<void>;
+export declare function waitForTableAbsent(executor: ClickHouseExecutor, database: string, tableName: string, options?: PropagationOptions): Promise<void>;
 /**
  * Waits for DDL propagation based on the operation type and key.
  * Called after each DDL statement in the migration execution loop.
  */
-export declare function waitForDDLPropagation(executor: ClickHouseExecutor, operationType: string, operationKey: string): Promise<void>;
+export declare function waitForDDLPropagation(executor: ClickHouseExecutor, operationType: string, operationKey: string, options?: PropagationOptions): Promise<void>;
+export {};
 //# sourceMappingURL=ddl-propagation.d.ts.map

package/dist/ddl-propagation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ddl-propagation.d.ts","sourceRoot":"","sources":["../src/ddl-propagation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAIpD,wBAAsB,YAAY,CAChC,QAAQ,EAAE,kBAAkB,EAC5B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CASf;AAED,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,kBAAkB,EAC5B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CASf;AAED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,kBAAkB,EAC5B,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CASf;AAED,wBAAsB,aAAa,CACjC,QAAQ,EAAE,kBAAkB,EAC5B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAWf;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,QAAQ,EAAE,kBAAkB,EAC5B,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,OAAO,EACjC,KAAK,SAAgB,GACpB,OAAO,CAAC,CAAC,EAAE,CAAC,CAQd;AAED,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,kBAAkB,EAC5B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAWf;AAwBD;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,kBAAkB,EAC5B,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CA0Cf"}
+{"version":3,"file":"ddl-propagation.d.ts","sourceRoot":"","sources":["../src/ddl-propagation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAwCpD;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,wBAAsB,YAAY,CAChC,QAAQ,EAAE,kBAAkB,EAC5B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,kBAAkB,EAC5B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,kBAAkB,EAC5B,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,EACtB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,wBAAsB,aAAa,CACjC,QAAQ,EAAE,kBAAkB,EAC5B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,kBAAkB,EAC5B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAOf;AAgHD;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,kBAAkB,EAC5B,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED,UAAU,aAAa;IACrB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;CACb;AAQD,uEAAuE;AACvE,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,CAAC,aAAa,EAAE,aAAa,CAAC,GAAG,SAAS,CASjG;AAOD;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,QAAQ,EAAE,kBAAkB,EAC5B,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,OAAO,EACjC,KAAK,SAAgB,GACpB,OAAO,CAAC,CAAC,EAAE,CAAC,CAQd;AAED,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,kBAAkB,EAC5B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAOf;AA4DD;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,kBAAkB,EAC5B,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAyFf"}

package/dist/ddl-propagation.js

@@ -1,36 +1,223 @@
 import pRetry from 'p-retry';
+import { parseModifyColumnIntent, parseRenameColumn } from './alter-column-statement.js';
+import { allReplicas, resolveReplicaFanout, stringLiteral } from './replicas.js';
 const RETRY_OPTIONS = { retries: 20, minTimeout: 500, factor: 1 };
-export async function waitForTable(executor, database, tableName) {
-    await pRetry(async () => {
-        const rows = await executor.query(`SELECT 1 AS x FROM system.tables WHERE database = '${database}' AND name = '${tableName}'`);
-        if (rows.length === 0) {
-            throw new Error(`waitForTable: ${database}.${tableName} not yet visible`);
-        }
-    }, RETRY_OPTIONS);
+// Upper bound on a column definition or rename wait, including slow queries.
+const DEFINITION_WAIT_DEADLINE_MS = 30_000;
+// The `system.columns` fields a column definition wait compares.
+const COLUMN_FIELDS = ['type', 'default_kind', 'default_expression', 'comment', 'compression_codec'];
+// What each ALTER or rename appends to the `<kind>:<database>.<name>` key of the
+// object it changes. Creates and drops use the bare key.
+const KEY_SUFFIXES = new Map([
+    ['alter_materialized_view_modify_refresh', ':refresh'],
+    ['alter_table_add_column', ':column:'],
+    ['alter_table_modify_column', ':column:'],
+    ['alter_table_drop_column', ':column:'],
+    ['alter_table_rename_column', ':column_rename:'],
+    ['alter_table_add_index', ':index:'],
+    ['alter_table_drop_index', ':index:'],
+    ['alter_table_add_projection', ':projection:'],
+    ['alter_table_drop_projection', ':projection:'],
+    ['alter_table_add_constraint', ':constraint:'],
+    ['alter_table_drop_constraint', ':constraint:'],
+    ['alter_table_modify_setting', ':setting:'],
+    ['alter_table_reset_setting', ':setting:'],
+    ['alter_table_modify_ttl', ':ttl'],
+    ['alter_table_rename_table', ':rename_table'],
+    ['rename_dictionary', ':rename_dictionary'],
+]);
+export async function waitForTable(executor, database, tableName, options) {
+    await waitForSystemRows(executor, {
+        source: 'system.tables',
+        where: `database = ${stringLiteral(database)} AND name = ${stringLiteral(tableName)}`,
+        want: 'present',
+        label: `waitForTable: ${database}.${tableName} not yet visible`,
+    }, options);
 }
-export async function waitForView(executor, database, viewName) {
-    await pRetry(async () => {
-        const rows = await executor.query(`SELECT 1 AS x FROM system.tables WHERE database = '${database}' AND name = '${viewName}' AND engine LIKE '%View%'`);
-        if (rows.length === 0) {
-            throw new Error(`waitForView: ${database}.${viewName} not yet visible`);
-        }
-    }, RETRY_OPTIONS);
+export async function waitForView(executor, database, viewName, options) {
+    await waitForSystemRows(executor, {
+        source: 'system.tables',
+        where: `database = ${stringLiteral(database)} AND name = ${stringLiteral(viewName)} AND engine LIKE '%View%'`,
+        want: 'present',
+        label: `waitForView: ${database}.${viewName} not yet visible`,
+    }, options);
 }
-export async function waitForDictionary(executor, database, dictionaryName) {
+/**
+ * Waits until the dictionary's catalog row is on every replica.
+ *
+ * `system.dictionaries` is the wrong signal. It lists each replica's
+ * in-memory loader (`ExternalLoader` load results), not the replicated
+ * catalog. `CREATE OR REPLACE DICTIONARY` drops that loader entry while the
+ * replica reloads, so a replica can omit the dictionary for the whole retry
+ * budget after the DDL is already in `system.tables`. A following statement
+ * only needs the catalog object.
+ *
+ * On several replicas the wait holds until every replica stores the same
+ * non-nil `uuid`. A replace does not remove the row, and ClickHouse redacts
+ * a SOURCE password to `[HIDDEN]` in `create_table_query`, so a password-only
+ * replace compares equal to the previous definition. `CREATE OR REPLACE`
+ * still assigns one new UUID in the replicated DDL (an `ON CLUSTER` statement
+ * and a Replicated database), and every replica that has applied it reports
+ * that UUID. `metadata_modification_time` is each replica's metadata-file
+ * mtime at second precision: it can stay unchanged across a replace in the
+ * same second, and two replicas that have both applied the DDL can disagree.
+ */
+export async function waitForDictionary(executor, database, dictionaryName, options) {
+    const where = `database = ${stringLiteral(database)} AND name = ${stringLiteral(dictionaryName)} AND engine = 'Dictionary'`;
+    const label = `waitForDictionary: ${database}.${dictionaryName} not yet visible`;
+    const fanout = await resolveReplicaFanout(executor, options?.cluster);
     await pRetry(async () => {
-        const rows = await executor.query(`SELECT 1 AS x FROM system.dictionaries WHERE database = '${database}' AND name = '${dictionaryName}'`);
-        if (rows.length === 0) {
-            throw new Error(`waitForDictionary: ${database}.${dictionaryName} not yet visible`);
-        }
+        if (!(await dictionaryCatalogVisible(executor, where, fanout)))
+            throw new Error(label);
     }, RETRY_OPTIONS);
 }
-export async function waitForColumn(executor, database, tableName, columnName) {
-    await pRetry(async () => {
-        const rows = await executor.query(`SELECT 1 AS x FROM system.columns WHERE database = '${database}' AND table = '${tableName}' AND name = '${columnName}'`);
-        if (rows.length === 0) {
-            throw new Error(`waitForColumn: ${database}.${tableName}.${columnName} not yet visible`);
+export async function waitForColumn(executor, database, tableName, columnName, options) {
+    await waitForSystemRows(executor, {
+        source: 'system.columns',
+        where: columnWhere(database, tableName, columnName),
+        want: 'present',
+        label: `waitForColumn: ${database}.${tableName}.${columnName} not yet visible`,
+    }, options);
+}
+export async function waitForColumnAbsent(executor, database, tableName, columnName, options) {
+    await waitForSystemRows(executor, {
+        source: 'system.columns',
+        where: columnWhere(database, tableName, columnName),
+        want: 'absent',
+        label: `waitForColumnAbsent: ${database}.${tableName}.${columnName} still present`,
+    }, options);
+}
+/**
+ * Waits until every replica reports the column with one definition, and with
+ * what `intent` says the statement set.
+ *
+ * Agreement: the replica that ran an ALTER has applied it when the statement
+ * returns, so once every replica reports the same `type`, `default_kind`,
+ * `default_expression`, `comment` and `compression_codec`, all of them have.
+ * Each replica formats these values itself, so the comparison is between
+ * server-formatted text and never trips over how chkit wrote an expression.
+ *
+ * Intent: agreement alone passes when every replica kept the old definition,
+ * e.g. ObsessionDB ignoring `MODIFY COLUMN ... EPHEMERAL <default>` (#285). So
+ * the fields the statement sets are compared too: the default kind and comment
+ * verbatim, a removed codec as empty, and the default expression after the
+ * server formats it with `formatQuerySingleLine`, the formatter that writes
+ * `system.columns.default_expression`. Types and codecs the statement sets are
+ * only compared between replicas: ClickHouse rewrites them (`Decimal(10,2)`
+ * becomes `Decimal(10, 2)`, `ZSTD` becomes `ZSTD(1)`).
+ */
+async function waitForColumnDefinition(executor, database, tableName, columnName, intent, options) {
+    const fanout = await resolveReplicaFanout(executor, options?.cluster);
+    const expected = await expectedColumnValues(executor, intent);
+    const source = fanout ? allReplicas(fanout, 'system.columns') : 'system.columns';
+    const sql = `SELECT hostName() AS replica, ${COLUMN_FIELDS.join(', ')} FROM ${source} WHERE ${columnWhere(database, tableName, columnName)}`;
+    await waitUntilApplied(`${database}.${tableName}.${columnName} definition`, async () => columnDefinitionMismatch(await executor.query(sql), fanout?.replicas ?? 1, expected));
+}
+/** Waits until no replica lists the old name and every replica lists the new one. */
+async function waitForColumnRename(executor, database, tableName, rename, options) {
+    const fanout = await resolveReplicaFanout(executor, options?.cluster);
+    const replicas = fanout?.replicas ?? 1;
+    const source = fanout ? allReplicas(fanout, 'system.columns') : 'system.columns';
+    const sql = `SELECT hostName() AS replica, name FROM ${source} WHERE database = ${stringLiteral(database)} AND table = ${stringLiteral(tableName)} AND name IN (${stringLiteral(rename.from)}, ${stringLiteral(rename.to)})`;
+    await waitUntilApplied(`${database}.${tableName} rename of column ${rename.from} to ${rename.to}`, async () => {
+        const rows = await executor.query(sql);
+        const stale = rows.filter((row) => row.name === rename.from).map((row) => row.replica);
+        if (stale.length > 0)
+            return `replica ${stale.join(', ')} still lists column ${rename.from}`;
+        const renamed = new Set(rows.filter((row) => row.name === rename.to).map((row) => row.replica));
+        if (renamed.size < replicas)
+            return `column ${rename.to} is listed on ${renamed.size} of ${replicas} replicas`;
+        return undefined;
+    });
+}
+async function waitForIndex(executor, database, tableName, indexName, want, options) {
+    await waitForSystemRows(executor, {
+        source: 'system.data_skipping_indices',
+        where: `database = ${stringLiteral(database)} AND table = ${stringLiteral(tableName)} AND name = ${stringLiteral(indexName)}`,
+        want,
+        label: `waitForIndex: ${database}.${tableName}.${indexName} ${want === 'present' ? 'not yet visible' : 'still present'}`,
+    }, options);
+}
+/**
+ * Waits until every replica's `create_table_query` lists the constraint. There
+ * is no system table of constraints. A replica that has not applied the ADD
+ * yet would let a following `DROP CONSTRAINT IF EXISTS` (a changed constraint)
+ * or `ADD CONSTRAINT IF NOT EXISTS` silently do nothing.
+ */
+async function waitForConstraint(executor, database, tableName, constraintName, options) {
+    await waitForSystemRows(executor, {
+        source: 'system.tables',
+        where: constraintWhere(database, tableName, constraintName),
+        want: 'present',
+        label: `waitForConstraint: ${database}.${tableName}.${constraintName} not yet visible`,
+    }, options);
+}
+async function waitForConstraintAbsent(executor, database, tableName, constraintName, options) {
+    await waitForSystemRows(executor, {
+        source: 'system.tables',
+        where: constraintWhere(database, tableName, constraintName),
+        want: 'absent',
+        label: `waitForConstraintAbsent: ${database}.${tableName}.${constraintName} still present`,
+    }, options);
+}
+/**
+ * Waits until every replica lists both tables of `EXCHANGE TABLES a AND b`
+ * with one uuid each, and the two uuids differ. The replica that ran the
+ * statement has swapped them, so once all replicas agree, all have. A
+ * statement that runs on a replica that has not applied the swap yet would
+ * see the old names: a following DROP of the pre-cutover table would drop the
+ * new one.
+ *
+ * With `clickhouse.cluster` the statement ran `ON CLUSTER`, which returns once
+ * every host executed it, and each host may hold its own uuids, so there is
+ * nothing to wait for. A single replica has nothing to wait for either.
+ */
+export async function waitForExchange(executor, statement, options) {
+    if (options?.cluster)
+        return;
+    const tables = parseExchangeTables(statement);
+    if (!tables)
+        return;
+    const fanout = await resolveReplicaFanout(executor);
+    if (!fanout)
+        return;
+    const [first, second] = tables;
+    const where = `(database = ${stringLiteral(first.database)} AND name = ${stringLiteral(first.name)}) OR (database = ${stringLiteral(second.database)} AND name = ${stringLiteral(second.name)})`;
+    const sql = `SELECT database, name, count(DISTINCT hostName()) AS replicas, uniqExact(uuid) AS uuids, any(toString(uuid)) AS sample_uuid FROM ${allReplicas(fanout, 'system.tables')} WHERE ${where} GROUP BY database, name`;
+    await waitUntilApplied(`EXCHANGE TABLES ${first.database}.${first.name} AND ${second.database}.${second.name}`, async () => {
+        const rows = await executor.query(sql);
+        if (rows.length < 2)
+            return `only ${rows.length} of the 2 tables are listed`;
+        for (const row of rows) {
+            if (Number(row.replicas) < fanout.replicas)
+                return `${row.database}.${row.name} is listed on ${row.replicas} of ${fanout.replicas} replicas`;
+            if (Number(row.uuids) !== 1)
+                return `replicas disagree on the uuid of ${row.database}.${row.name}`;
         }
-    }, RETRY_OPTIONS);
+        if (rows[0]?.sample_uuid === rows[1]?.sample_uuid)
+            return 'both names report the same uuid';
+        return undefined;
+    });
+}
+const QUOTED_OR_BARE = String.raw `(?:\`(?:[^\`\\]|\\.)*\`|[^\s.\`;]+)`;
+const EXCHANGE_PATTERN = new RegExp(String.raw `^\s*EXCHANGE\s+TABLES\s+(${QUOTED_OR_BARE})\.(${QUOTED_OR_BARE})\s+AND\s+(${QUOTED_OR_BARE})\.(${QUOTED_OR_BARE})`, 'i');
+/** The two tables of `EXCHANGE TABLES db.a AND db.b`, or undefined. */
+export function parseExchangeTables(statement) {
+    const match = EXCHANGE_PATTERN.exec(statement);
+    if (!match)
+        return undefined;
+    const [, db1, t1, db2, t2] = match;
+    if (!db1 || !t1 || !db2 || !t2)
+        return undefined;
+    return [
+        { database: unquote(db1), name: unquote(t1) },
+        { database: unquote(db2), name: unquote(t2) },
+    ];
+}
+function unquote(identifier) {
+    if (!identifier.startsWith('`'))
+        return identifier;
+    return identifier.slice(1, -1).replace(/\\(.)/g, '$1');
 }
 /**
  * Polls a query until its rows satisfy `predicate`, then returns them. Use for
@@ -46,60 +233,283 @@ export async function waitForRows(executor, sql, predicate, label = 'waitForRows
         return rows;
     }, RETRY_OPTIONS);
 }
-export async function waitForTableAbsent(executor, database, tableName) {
-    await pRetry(async () => {
-        const rows = await executor.query(`SELECT 1 AS x FROM system.tables WHERE database = '${database}' AND name = '${tableName}'`);
-        if (rows.length > 0) {
-            throw new Error(`waitForTableAbsent: ${database}.${tableName} still present`);
-        }
-    }, RETRY_OPTIONS);
+export async function waitForTableAbsent(executor, database, tableName, options) {
+    await waitForSystemRows(executor, {
+        source: 'system.tables',
+        where: `database = ${stringLiteral(database)} AND name = ${stringLiteral(tableName)}`,
+        want: 'absent',
+        label: `waitForTableAbsent: ${database}.${tableName} still present`,
+    }, options);
 }
 /**
  * Parses an operation key like "table:app.users", "table:app.users:column:name",
- * or "dictionary:app.users_dict" into its components.
+ * "dictionary:app.users_dict", "view:app.active_users" or
+ * "materialized_view:app.events_mv:refresh" into its components. `table` is the
+ * object's name in system.tables, which lists views and dictionaries too.
+ *
+ * Names may contain ':', so the object's name runs to the last occurrence of the
+ * suffix its operation type appends; without a known suffix the rest of the key
+ * is the name. The database runs to the first '.': the key cannot tell a '.'
+ * inside a database name from the separator, so objects in such a database are
+ * not found.
  */
-function parseOperationKey(key) {
-    const tableMatch = key.match(/^(?:table|dictionary):([^.]+)\.([^:]+)/);
-    if (!tableMatch)
+function parseOperationKey(operationType, key) {
+    const keyMatch = key.match(/^(?:table|dictionary|view|materialized_view):([^.]+)\.(.+)$/);
+    if (!keyMatch)
         return undefined;
     // biome-ignore lint/style/noNonNullAssertion: capture groups guaranteed by regex match
-    const database = tableMatch[1];
+    const database = keyMatch[1];
     // biome-ignore lint/style/noNonNullAssertion: capture groups guaranteed by regex match
-    const table = tableMatch[2];
-    const columnMatch = key.match(/:column:([^:]+)/);
-    return { database, table, column: columnMatch?.[1] };
+    const rest = keyMatch[2];
+    const suffix = KEY_SUFFIXES.get(operationType);
+    const at = suffix === undefined ? -1 : rest.lastIndexOf(suffix);
+    if (suffix === undefined || at < 1)
+        return { database, table: rest, column: undefined };
+    const member = rest.slice(at + suffix.length);
+    return {
+        database,
+        table: rest.slice(0, at),
+        column: suffix === ':column:' ? member : undefined,
+        constraint: suffix === ':constraint:' ? member : undefined,
+        index: suffix === ':index:' ? member : undefined,
+        rename: suffix === ':column_rename:' ? member : undefined,
+    };
+}
+/**
+ * The old and new names of a column rename. The statement names them; without
+ * it the key's `<from>:<to>` is split only when it holds exactly one ':'.
+ */
+function renamedColumn(member, statement) {
+    const parsed = statement === undefined ? undefined : parseRenameColumn(statement);
+    if (parsed && `${parsed.from}:${parsed.to}` === member)
+        return parsed;
+    const parts = member.split(':');
+    return parts.length === 2 && parts[0] && parts[1] ? { from: parts[0], to: parts[1] } : undefined;
 }
 /**
  * Waits for DDL propagation based on the operation type and key.
  * Called after each DDL statement in the migration execution loop.
  */
-export async function waitForDDLPropagation(executor, operationType, operationKey) {
-    const parsed = parseOperationKey(operationKey);
+export async function waitForDDLPropagation(executor, operationType, operationKey, options) {
+    // Backfill assertions execute SELECT guards. Their keys identify the guard,
+    // not an object changed by DDL, so there is no schema propagation to await.
+    if (operationType === 'assert_backfill')
+        return;
+    // Cutover guards, barriers, copies and the snapshot ALTER change no object
+    // in the catalog; the objects a cutover creates and drops use the regular
+    // create/drop operation types.
+    if (operationType.startsWith('cutover_'))
+        return;
+    if (operationType === 'exchange_tables') {
+        if (options?.statement === undefined)
+            return;
+        return waitForExchange(executor, options.statement, options);
+    }
+    const parsed = parseOperationKey(operationType, operationKey);
     if (!parsed)
         return; // database-level ops or unrecognized keys — no wait needed
     switch (operationType) {
         case 'create_table':
-            return waitForTable(executor, parsed.database, parsed.table);
+            return waitForTable(executor, parsed.database, parsed.table, options);
         case 'create_view':
         case 'create_materialized_view':
-            return waitForView(executor, parsed.database, parsed.table);
+            return waitForView(executor, parsed.database, parsed.table, options);
         case 'create_dictionary':
-            return waitForDictionary(executor, parsed.database, parsed.table);
+            return waitForDictionary(executor, parsed.database, parsed.table, options);
+        // ADD COLUMN IF NOT EXISTS leaves an existing column as it is, so only
+        // agreement between replicas is checked; MODIFY also checks what it sets.
         case 'alter_table_add_column':
         case 'alter_table_modify_column':
             if (parsed.column) {
-                return waitForColumn(executor, parsed.database, parsed.table, parsed.column);
+                const intent = operationType === 'alter_table_modify_column' && options?.statement !== undefined
+                    ? parseModifyColumnIntent(options.statement, parsed.column)
+                    : {};
+                return waitForColumnDefinition(executor, parsed.database, parsed.table, parsed.column, intent, options);
             }
             return;
+        case 'alter_table_rename_column': {
+            const rename = parsed.rename === undefined ? undefined : renamedColumn(parsed.rename, options?.statement);
+            if (rename)
+                return waitForColumnRename(executor, parsed.database, parsed.table, rename, options);
+            return waitForTable(executor, parsed.database, parsed.table, options);
+        }
+        case 'alter_table_add_index':
+        case 'alter_table_drop_index':
+            if (parsed.index) {
+                const want = operationType === 'alter_table_add_index' ? 'present' : 'absent';
+                return waitForIndex(executor, parsed.database, parsed.table, parsed.index, want, options);
+            }
+            return waitForTable(executor, parsed.database, parsed.table, options);
+        case 'alter_table_drop_column':
+            if (parsed.column) {
+                return waitForColumnAbsent(executor, parsed.database, parsed.table, parsed.column, options);
+            }
+            return waitForTable(executor, parsed.database, parsed.table, options);
+        case 'alter_table_add_constraint':
+            if (parsed.constraint) {
+                return waitForConstraint(executor, parsed.database, parsed.table, parsed.constraint, options);
+            }
+            return waitForTable(executor, parsed.database, parsed.table, options);
+        case 'alter_table_drop_constraint':
+            if (parsed.constraint) {
+                return waitForConstraintAbsent(executor, parsed.database, parsed.table, parsed.constraint, options);
+            }
+            return waitForTable(executor, parsed.database, parsed.table, options);
         case 'drop_table':
         case 'drop_view':
         case 'drop_materialized_view':
         case 'drop_dictionary':
-            return waitForTableAbsent(executor, parsed.database, parsed.table);
+            return waitForTableAbsent(executor, parsed.database, parsed.table, options);
         default:
-            // alter_table_add_index, alter_table_modify_setting, etc.
+            // alter_table_add_projection, alter_table_modify_setting,
+            // alter_materialized_view_modify_refresh, etc.
             // Wait for the table to exist as a basic sanity check.
-            return waitForTable(executor, parsed.database, parsed.table);
+            return waitForTable(executor, parsed.database, parsed.table, options);
+    }
+}
+async function waitForSystemRows(executor, wait, options) {
+    const fanout = await resolveReplicaFanout(executor, options?.cluster);
+    await pRetry(async () => {
+        if (!(await systemRowsMatch(executor, wait, fanout)))
+            throw new Error(wait.label);
+    }, RETRY_OPTIONS);
+}
+async function dictionaryCatalogVisible(executor, where, fanout) {
+    if (!fanout) {
+        const rows = await executor.query(`SELECT 1 AS x FROM system.tables WHERE ${where}`);
+        return rows.length > 0;
+    }
+    const rows = await executor.query(`SELECT count(DISTINCT hostName()) AS replicas, (min(uuid) = max(uuid) AND min(uuid) != toUUID('00000000-0000-0000-0000-000000000000') AND count(uuid) = count()) AS agreed FROM ${allReplicas(fanout, 'system.tables')} WHERE ${where}`);
+    const replicas = Number(rows[0]?.replicas ?? 0);
+    return replicas >= fanout.replicas && isAgreed(rows[0]?.agreed);
+}
+function isAgreed(value) {
+    return value === true || value === 1 || value === '1';
+}
+async function systemRowsMatch(executor, wait, fanout) {
+    if (!fanout) {
+        const rows = await executor.query(`SELECT 1 AS x FROM ${wait.source} WHERE ${wait.where}`);
+        return wait.want === 'present' ? rows.length > 0 : rows.length === 0;
+    }
+    const rows = await executor.query(`SELECT count(DISTINCT hostName()) AS replicas FROM ${allReplicas(fanout, wait.source)} WHERE ${wait.where}`);
+    const replicas = Number(rows[0]?.replicas ?? 0);
+    return wait.want === 'present' ? replicas >= fanout.replicas : replicas === 0;
+}
+function columnWhere(database, tableName, columnName) {
+    return `database = ${stringLiteral(database)} AND table = ${stringLiteral(tableName)} AND name = ${stringLiteral(columnName)}`;
+}
+// ClickHouse writes a constraint name bare when it is a plain identifier and
+// backquoted otherwise (`backQuoteIfNeed`), so match either spelling.
+function constraintWhere(database, tableName, constraintName) {
+    const quoted = `\`${constraintName.replace(/\\/g, '\\\\').replace(/`/g, '\\`')}\``;
+    const spellings = [`CONSTRAINT ${constraintName} `, `CONSTRAINT ${quoted} `];
+    const listed = spellings.map((spelling) => `position(create_table_query, ${stringLiteral(spelling)}) > 0`).join(' OR ');
+    return `database = ${stringLiteral(database)} AND name = ${stringLiteral(tableName)} AND (${listed})`;
+}
+/**
+ * Polls `check` until it reports no mismatch, with the retry budget of the
+ * other waits (21 checks, 500 ms apart) and a hard deadline: chkit's queries
+ * have no request timeout, so a check that does not return ends the wait at
+ * the deadline instead of holding the migration. On timeout the error names
+ * what was still different on the last check.
+ */
+async function waitUntilApplied(subject, check) {
+    const deadline = Date.now() + DEFINITION_WAIT_DEADLINE_MS;
+    let checks = 0;
+    let detail = '';
+    for (;;) {
+        checks += 1;
+        const outcome = await checkBefore(check, deadline);
+        if (outcome.mismatch === undefined && outcome.failure === undefined)
+            return;
+        detail = outcome.failure ?? outcome.mismatch ?? '';
+        if (checks > RETRY_OPTIONS.retries || Date.now() + RETRY_OPTIONS.minTimeout >= deadline)
+            break;
+        await new Promise((resolve) => setTimeout(resolve, RETRY_OPTIONS.minTimeout));
     }
+    throw new Error(`waitForDDLPropagation: ${subject} not applied on every replica after ${checks} checks: ${detail}`);
+}
+async function checkBefore(check, deadline) {
+    let timer;
+    const expired = new Promise((resolve) => {
+        timer = setTimeout(() => resolve({ failure: `a check did not return within the ${DEFINITION_WAIT_DEADLINE_MS / 1000}s deadline` }), Math.max(deadline - Date.now(), 0));
+    });
+    try {
+        return await Promise.race([
+            check().then((mismatch) => ({ mismatch }), (error) => ({ failure: error instanceof Error ? error.message : String(error) })),
+            expired,
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * The `system.columns` values `intent` pins down. The default expression is
+ * formatted by the server; when it cannot be formatted (a server without
+ * `formatQuerySingleLine`), the expression is left to the agreement check.
+ */
+async function expectedColumnValues(executor, intent) {
+    const expected = [];
+    if (intent.defaultKind !== undefined)
+        expected.push({ field: 'default_kind', value: intent.defaultKind });
+    if (intent.defaultKind === '')
+        expected.push({ field: 'default_expression', value: '' });
+    if (intent.typeDefault)
+        expected.push({ field: 'default_expression', value: 'defaultValueOfTypeName(', prefix: true });
+    if (intent.comment !== undefined)
+        expected.push({ field: 'comment', value: intent.comment });
+    if (intent.codecRemoved)
+        expected.push({ field: 'compression_codec', value: '' });
+    if (intent.defaultExpression !== undefined) {
+        const formatted = await formatExpression(executor, intent.defaultExpression);
+        if (formatted !== undefined)
+            expected.push({ field: 'default_expression', value: formatted });
+    }
+    return expected;
+}
+async function formatExpression(executor, expression) {
+    const select = 'SELECT ';
+    try {
+        const rows = await executor.query(`SELECT formatQuerySingleLine(${stringLiteral(`${select}${expression}`)}) AS formatted`);
+        const formatted = rows[0]?.formatted;
+        return formatted?.startsWith(select) ? formatted.slice(select.length) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Why the replicas' rows do not show the intended definition yet, or
+ * undefined when every replica reports it.
+ */
+function columnDefinitionMismatch(rows, replicas, expected) {
+    const listed = new Set(rows.map((row) => row.replica));
+    if (listed.size < replicas) {
+        const where = listed.size > 0 ? ` (${[...listed].join(', ')})` : '';
+        return `the column is listed on ${listed.size} of ${replicas} replicas${where}`;
+    }
+    for (const row of rows) {
+        const off = expected.find((want) => !matchesExpected(row[want.field], want));
+        if (!off)
+            continue;
+        const sets = off.prefix ? `${JSON.stringify(off.value)}...` : JSON.stringify(off.value);
+        const unanimous = rows.length > 1 && rows.every((other) => other[off.field] === row[off.field]);
+        return (`replica ${row.replica} reports ${off.field} ${JSON.stringify(row[off.field])}, the statement sets ${sets}` +
+            (unanimous ? '; every replica reports the same, so this is not replication lag: the server accepted the statement without applying it' : ''));
+    }
+    const [first, ...others] = rows;
+    if (!first)
+        return undefined;
+    for (const row of others) {
+        const field = COLUMN_FIELDS.find((name) => row[name] !== first[name]);
+        if (field) {
+            return `replica ${row.replica} reports ${field} ${JSON.stringify(row[field])}, replica ${first.replica} reports ${JSON.stringify(first[field])}`;
+        }
+    }
+    return undefined;
+}
+function matchesExpected(actual, want) {
+    return want.prefix ? actual.startsWith(want.value) : actual === want.value;
 }
 //# sourceMappingURL=ddl-propagation.js.map