@hypequery/clickhouse 1.6.0 → 1.6.2

package/dist/migrations/diff/diff.d.ts

@@ -0,0 +1,11 @@
+import type { Snapshot } from '../snapshot/types.js';
+import type { SnapshotDiffResult } from './types.js';
+/**
+ * Computes migration operations needed to move from one snapshot to another.
+ *
+ * The diff layer is deliberately SQL-free. It emits structured operations,
+ * warnings for potentially expensive changes, and unsupported-change diagnostics
+ * that the SQL renderer refuses to render automatically.
+ */
+export declare function diffSnapshots(previousSnapshot: Snapshot, nextSnapshot: Snapshot): SnapshotDiffResult;
+//# sourceMappingURL=diff.d.ts.map

package/dist/migrations/diff/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../../src/migrations/diff/diff.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EAIT,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAQV,kBAAkB,EAGnB,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,gBAAgB,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,GAAG,kBAAkB,CAqCpG"}

package/dist/migrations/diff/diff.js

@@ -0,0 +1,240 @@
+/**
+ * Computes migration operations needed to move from one snapshot to another.
+ *
+ * The diff layer is deliberately SQL-free. It emits structured operations,
+ * warnings for potentially expensive changes, and unsupported-change diagnostics
+ * that the SQL renderer refuses to render automatically.
+ */
+export function diffSnapshots(previousSnapshot, nextSnapshot) {
+    const warnings = [];
+    const unsupportedChanges = [];
+    const previousTables = toNameMap(previousSnapshot.tables);
+    const nextTables = toNameMap(nextSnapshot.tables);
+    const previousViews = toNameMap(previousSnapshot.materializedViews);
+    const nextViews = toNameMap(nextSnapshot.materializedViews);
+    const dropMaterializedViewOperations = diffDroppedMaterializedViews(previousViews, nextViews);
+    const dropTableOperations = diffDroppedTables(previousTables, nextTables);
+    const tableOperations = diffTables(previousSnapshot, nextSnapshot, previousTables, nextTables, warnings, unsupportedChanges);
+    const createTableOperations = diffCreatedTables(previousTables, nextTables);
+    const recreateMaterializedViewOperations = diffChangedMaterializedViews(previousViews, nextViews);
+    const createMaterializedViewOperations = diffCreatedMaterializedViews(previousViews, nextViews);
+    return {
+        previousSnapshot,
+        nextSnapshot,
+        operations: [
+            ...dropMaterializedViewOperations,
+            ...dropTableOperations,
+            ...tableOperations,
+            ...createTableOperations,
+            ...recreateMaterializedViewOperations,
+            ...createMaterializedViewOperations,
+        ],
+        warnings,
+        unsupportedChanges,
+    };
+}
+function diffDroppedMaterializedViews(previousViews, nextViews) {
+    return [...previousViews.values()]
+        .filter(view => !nextViews.has(view.name))
+        .map(view => ({
+        kind: 'DropMaterializedView',
+        viewName: view.name,
+    }));
+}
+function diffDroppedTables(previousTables, nextTables) {
+    return [...previousTables.values()]
+        .filter(table => !nextTables.has(table.name))
+        .map(table => ({
+        kind: 'DropTable',
+        tableName: table.name,
+    }));
+}
+function diffCreatedTables(previousTables, nextTables) {
+    return [...nextTables.values()]
+        .filter(table => !previousTables.has(table.name))
+        .map(table => ({
+        kind: 'CreateTable',
+        table,
+    }));
+}
+function diffCreatedMaterializedViews(previousViews, nextViews) {
+    return [...nextViews.values()]
+        .filter(view => !previousViews.has(view.name))
+        .map(view => ({
+        kind: 'CreateMaterializedView',
+        view,
+    }));
+}
+function diffChangedMaterializedViews(previousViews, nextViews) {
+    const operations = [];
+    for (const previousView of previousViews.values()) {
+        const nextView = nextViews.get(previousView.name);
+        if (!nextView) {
+            continue;
+        }
+        if (!isSameMaterializedView(previousView, nextView)) {
+            operations.push({
+                kind: 'RecreateMaterializedView',
+                previousView,
+                nextView,
+            });
+        }
+    }
+    return operations;
+}
+function diffTables(previousSnapshot, nextSnapshot, previousTables, nextTables, warnings, unsupportedChanges) {
+    const operations = [];
+    for (const previousTable of previousTables.values()) {
+        const nextTable = nextTables.get(previousTable.name);
+        if (!nextTable) {
+            continue;
+        }
+        if (!isSameTableEngine(previousTable.engine, nextTable.engine)) {
+            unsupportedChanges.push({
+                kind: 'TableEngineChanged',
+                tableName: previousTable.name,
+                message: `Table engine changed for "${previousTable.name}". Engine evolution is not auto-generated yet.`,
+            });
+        }
+        if (!isSameSettings(previousTable.settings, nextTable.settings)) {
+            unsupportedChanges.push({
+                kind: 'TableSettingsChanged',
+                tableName: previousTable.name,
+                message: `Table settings changed for "${previousTable.name}". Settings diffs are not auto-generated yet.`,
+            });
+        }
+        const tableMutations = diffColumns(previousTable, nextTable, warnings, unsupportedChanges);
+        if (tableMutations.length === 0) {
+            continue;
+        }
+        const dependentViewNames = getDependentViewNames(previousSnapshot, nextSnapshot, previousTable.name);
+        if (dependentViewNames.length > 0) {
+            operations.push({
+                kind: 'AlterTableWithDependentViews',
+                tableName: previousTable.name,
+                dependentViewNames,
+                operations: tableMutations,
+            });
+            continue;
+        }
+        operations.push(...tableMutations);
+    }
+    return operations;
+}
+function diffColumns(previousTable, nextTable, warnings, unsupportedChanges) {
+    const operations = [];
+    const previousColumns = toNameMap(previousTable.columns);
+    const nextColumns = toNameMap(nextTable.columns);
+    const droppedColumns = [...previousColumns.values()].filter(column => !nextColumns.has(column.name));
+    const addedColumns = [...nextColumns.values()].filter(column => !previousColumns.has(column.name));
+    detectPossibleRenames(previousTable.name, droppedColumns, addedColumns, unsupportedChanges);
+    for (const column of droppedColumns) {
+        operations.push({
+            kind: 'DropColumn',
+            tableName: previousTable.name,
+            columnName: column.name,
+        });
+    }
+    for (const column of addedColumns) {
+        operations.push({
+            kind: 'AddColumn',
+            tableName: previousTable.name,
+            column,
+        });
+    }
+    for (const previousColumn of previousColumns.values()) {
+        const nextColumn = nextColumns.get(previousColumn.name);
+        if (!nextColumn) {
+            continue;
+        }
+        if (previousColumn.type !== nextColumn.type) {
+            operations.push({
+                kind: 'ModifyColumnType',
+                tableName: previousTable.name,
+                columnName: previousColumn.name,
+                previousType: previousColumn.type,
+                nextType: nextColumn.type,
+            });
+            warnings.push({
+                kind: 'ModifyColumnTypeRequiresConfirmation',
+                tableName: previousTable.name,
+                columnName: previousColumn.name,
+                message: `Column type changed for "${previousTable.name}.${previousColumn.name}" ` +
+                    `from "${previousColumn.type}" to "${nextColumn.type}".`,
+            });
+        }
+        if (!isSameColumnDefault(previousColumn.default, nextColumn.default)) {
+            operations.push({
+                kind: 'ModifyColumnDefault',
+                tableName: previousTable.name,
+                columnName: previousColumn.name,
+                previousDefault: previousColumn.default,
+                nextDefault: nextColumn.default,
+            });
+        }
+    }
+    return operations;
+}
+function isSameColumnDefault(left, right) {
+    if (left === right) {
+        return true;
+    }
+    if (left === undefined || right === undefined) {
+        return false;
+    }
+    return left.kind === right.kind && left.value === right.value;
+}
+function detectPossibleRenames(tableName, droppedColumns, addedColumns, unsupportedChanges) {
+    for (const droppedColumn of droppedColumns) {
+        const renameCandidate = addedColumns.find(addedColumn => addedColumn.type === droppedColumn.type &&
+            isSameColumnDefault(addedColumn.default, droppedColumn.default));
+        if (!renameCandidate) {
+            continue;
+        }
+        unsupportedChanges.push({
+            kind: 'PossibleColumnRename',
+            tableName,
+            columnName: droppedColumn.name,
+            message: `Possible column rename detected in "${tableName}": ` +
+                `"${droppedColumn.name}" -> "${renameCandidate.name}". ` +
+                `Rename inference is not supported in generated migrations.`,
+        });
+    }
+}
+function getDependentViewNames(previousSnapshot, nextSnapshot, tableName) {
+    return [...new Set([
+            ...previousSnapshot.dependencies
+                .filter(edge => edge.kind === 'table_to_materialized_view' && edge.from === tableName)
+                .map(edge => edge.to),
+            ...nextSnapshot.dependencies
+                .filter(edge => edge.kind === 'table_to_materialized_view' && edge.from === tableName)
+                .map(edge => edge.to),
+        ])].sort((left, right) => left.localeCompare(right));
+}
+function isSameTableEngine(left, right) {
+    return left.type === right.type &&
+        isSameStringArray(left.orderBy, right.orderBy) &&
+        (left.partitionBy ?? null) === (right.partitionBy ?? null) &&
+        isSameStringArray(left.primaryKey, right.primaryKey) &&
+        (left.sampleBy ?? null) === (right.sampleBy ?? null);
+}
+function isSameSettings(left, right) {
+    const leftEntries = Object.entries(left);
+    const rightEntries = Object.entries(right);
+    if (leftEntries.length !== rightEntries.length) {
+        return false;
+    }
+    return leftEntries.every(([key, value]) => right[key] === value);
+}
+function isSameMaterializedView(left, right) {
+    return left.name === right.name &&
+        left.from === right.from &&
+        (left.to ?? null) === (right.to ?? null) &&
+        left.select === right.select;
+}
+function isSameStringArray(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function toNameMap(entries) {
+    return new Map(entries.map(entry => [entry.name, entry]));
+}

package/dist/migrations/diff/index.d.ts

@@ -0,0 +1,3 @@
+export { diffSnapshots } from './diff.js';
+export type { AddColumnOperation, AlterTableWithDependentViewsOperation, CreateMaterializedViewOperation, CreateTableOperation, DiffWarning, DropColumnOperation, DropMaterializedViewOperation, DropTableOperation, MigrationOperation, ModifyColumnDefaultOperation, ModifyColumnTypeOperation, RecreateMaterializedViewOperation, SnapshotDiffResult, TableMutationOperation, UnsupportedChange, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/migrations/diff/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/migrations/diff/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE1C,YAAY,EACV,kBAAkB,EAClB,qCAAqC,EACrC,+BAA+B,EAC/B,oBAAoB,EACpB,WAAW,EACX,mBAAmB,EACnB,6BAA6B,EAC7B,kBAAkB,EAClB,kBAAkB,EAClB,4BAA4B,EAC5B,yBAAyB,EACzB,iCAAiC,EACjC,kBAAkB,EAClB,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/migrations/diff/index.js

@@ -0,0 +1 @@
+export { diffSnapshots } from './diff.js';

package/dist/migrations/diff/types.d.ts

@@ -0,0 +1,74 @@
+import type { Snapshot, SnapshotColumn, SnapshotColumnDefault, SnapshotMaterializedView, SnapshotTable } from '../snapshot/types.js';
+export interface CreateTableOperation {
+    kind: 'CreateTable';
+    table: SnapshotTable;
+}
+export interface DropTableOperation {
+    kind: 'DropTable';
+    tableName: string;
+}
+export interface AddColumnOperation {
+    kind: 'AddColumn';
+    tableName: string;
+    column: SnapshotColumn;
+}
+export interface DropColumnOperation {
+    kind: 'DropColumn';
+    tableName: string;
+    columnName: string;
+}
+export interface ModifyColumnDefaultOperation {
+    kind: 'ModifyColumnDefault';
+    tableName: string;
+    columnName: string;
+    previousDefault?: SnapshotColumnDefault;
+    nextDefault?: SnapshotColumnDefault;
+}
+export interface ModifyColumnTypeOperation {
+    kind: 'ModifyColumnType';
+    tableName: string;
+    columnName: string;
+    previousType: string;
+    nextType: string;
+}
+export interface CreateMaterializedViewOperation {
+    kind: 'CreateMaterializedView';
+    view: SnapshotMaterializedView;
+}
+export interface DropMaterializedViewOperation {
+    kind: 'DropMaterializedView';
+    viewName: string;
+}
+export interface RecreateMaterializedViewOperation {
+    kind: 'RecreateMaterializedView';
+    previousView: SnapshotMaterializedView;
+    nextView: SnapshotMaterializedView;
+}
+export type TableMutationOperation = AddColumnOperation | DropColumnOperation | ModifyColumnDefaultOperation | ModifyColumnTypeOperation;
+export interface AlterTableWithDependentViewsOperation {
+    kind: 'AlterTableWithDependentViews';
+    tableName: string;
+    dependentViewNames: string[];
+    operations: TableMutationOperation[];
+}
+export type MigrationOperation = AlterTableWithDependentViewsOperation | CreateMaterializedViewOperation | CreateTableOperation | DropMaterializedViewOperation | DropTableOperation | RecreateMaterializedViewOperation | TableMutationOperation;
+export interface DiffWarning {
+    kind: 'ModifyColumnTypeRequiresConfirmation';
+    tableName: string;
+    columnName: string;
+    message: string;
+}
+export interface UnsupportedChange {
+    kind: 'PossibleColumnRename' | 'TableEngineChanged' | 'TableSettingsChanged';
+    message: string;
+    tableName: string;
+    columnName?: string;
+}
+export interface SnapshotDiffResult {
+    previousSnapshot: Snapshot;
+    nextSnapshot: Snapshot;
+    operations: MigrationOperation[];
+    warnings: DiffWarning[];
+    unsupportedChanges: UnsupportedChange[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/migrations/diff/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/migrations/diff/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,cAAc,EACd,qBAAqB,EACrB,wBAAwB,EACxB,aAAa,EACd,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,WAAW,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,WAAW,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,YAAY,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,qBAAqB,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,qBAAqB,CAAC;IACxC,WAAW,CAAC,EAAE,qBAAqB,CAAC;CACrC;AAED,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,kBAAkB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,+BAA+B;IAC9C,IAAI,EAAE,wBAAwB,CAAC;IAC/B,IAAI,EAAE,wBAAwB,CAAC;CAChC;AAED,MAAM,WAAW,6BAA6B;IAC5C,IAAI,EAAE,sBAAsB,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iCAAiC;IAChD,IAAI,EAAE,0BAA0B,CAAC;IACjC,YAAY,EAAE,wBAAwB,CAAC;IACvC,QAAQ,EAAE,wBAAwB,CAAC;CACpC;AAED,MAAM,MAAM,sBAAsB,GAC9B,kBAAkB,GAClB,mBAAmB,GACnB,4BAA4B,GAC5B,yBAAyB,CAAC;AAE9B,MAAM,WAAW,qCAAqC;IACpD,IAAI,EAAE,8BAA8B,CAAC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,UAAU,EAAE,sBAAsB,EAAE,CAAC;CACtC;AAED,MAAM,MAAM,kBAAkB,GAC1B,qCAAqC,GACrC,+BAA+B,GAC/B,oBAAoB,GACpB,6BAA6B,GAC7B,kBAAkB,GAClB,iCAAiC,GACjC,sBAAsB,CAAC;AAE3B,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,sCAAsC,CAAC;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EACA,sBAAsB,GACtB,oBAAoB,GACpB,sBAAsB,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,gBAAgB,EAAE,QAAQ,CAAC;IAC3B,YAAY,EAAE,QAAQ,CAAC;IACvB,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,kBAAkB,EAAE,iBAAiB,EAAE,CAAC;CACzC"}

package/dist/migrations/diff/types.js

@@ -0,0 +1 @@
+export {};

package/dist/migrations/plan/index.d.ts

@@ -0,0 +1,3 @@
+export { createMigrationPlan, isMigrationPlan } from './plan.js';
+export type { ClickHouseMigrationSyncSetting, ClickHouseMigrationPlanContext, ClickHouseTableCostStats, CreateMigrationPlanOptions, MigrationPlanAnalyzer, MigrationPlanAnalyzerContext, MigrationPlanAnalyzerResult, MigrationOperationClassification, MigrationOperationCostEstimate, MigrationPlan, MigrationPlanBlocker, MigrationPlanConfirmation, MigrationPlanDiagnostic, MigrationPlanDiagnosticLevel, MigrationPlanInput, PlannedMigrationOperation, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/migrations/plan/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/migrations/plan/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEjE,YAAY,EACV,8BAA8B,EAC9B,8BAA8B,EAC9B,wBAAwB,EACxB,0BAA0B,EAC1B,qBAAqB,EACrB,4BAA4B,EAC5B,2BAA2B,EAC3B,gCAAgC,EAChC,8BAA8B,EAC9B,aAAa,EACb,oBAAoB,EACpB,yBAAyB,EACzB,uBAAuB,EACvB,4BAA4B,EAC5B,kBAAkB,EAClB,yBAAyB,GAC1B,MAAM,YAAY,CAAC"}

package/dist/migrations/plan/index.js

@@ -0,0 +1 @@
+export { createMigrationPlan, isMigrationPlan } from './plan.js';

package/dist/migrations/plan/plan.d.ts

@@ -0,0 +1,12 @@
+import type { SnapshotDiffResult } from '../diff/types.js';
+import type { CreateMigrationPlanOptions, MigrationPlan, MigrationPlanInput } from './types.js';
+/**
+ * Converts a raw snapshot diff into an explicit migration plan.
+ *
+ * The initial planner is intentionally static: it classifies operations and
+ * carries diagnostics/blockers without querying a live ClickHouse instance.
+ * Later phases can enrich this plan with system-table cost estimates.
+ */
+export declare function createMigrationPlan(diff: SnapshotDiffResult, options?: CreateMigrationPlanOptions): MigrationPlan;
+export declare function isMigrationPlan(input: MigrationPlanInput): input is MigrationPlan;
+//# sourceMappingURL=plan.d.ts.map

package/dist/migrations/plan/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../../src/migrations/plan/plan.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,kBAAkB,EAEnB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAIV,0BAA0B,EAG1B,aAAa,EAMb,kBAAkB,EAEnB,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,kBAAkB,EACxB,OAAO,GAAE,0BAA+B,GACvC,aAAa,CAqFf;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,kBAAkB,GAAG,KAAK,IAAI,aAAa,CAMjF"}