oak-db 3.3.13 → 4.0.0

package/lib/migration.js

@@ -0,0 +1,1029 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeAttribute = normalizeAttribute;
+exports.normalizeIndex = normalizeIndex;
+exports.areAttributesEquivalent = areAttributesEquivalent;
+exports.areIndexesEquivalent = areIndexesEquivalent;
+exports.classifyAttributeChange = classifyAttributeChange;
+exports.buildMigrationPlan = buildMigrationPlan;
+const migrationSqlCategoryOrder = [
+    'prepareSql',
+    'forwardSql',
+    'onlineSql',
+    'manualSql',
+    'backwardSql',
+];
+function createEmptySummary() {
+    return {
+        newTables: 0,
+        removedTables: 0,
+        addedColumns: 0,
+        removedColumns: 0,
+        changedColumns: 0,
+        addedIndexes: 0,
+        removedIndexes: 0,
+        changedIndexes: 0,
+        addedForeignKeys: 0,
+        removedForeignKeys: 0,
+        changedForeignKeys: 0,
+        manualActions: 0,
+        onlineActions: 0,
+        largeTableIndexes: 0,
+    };
+}
+function createEmptySqlByCategory() {
+    return {
+        prepareSql: [],
+        forwardSql: [],
+        onlineSql: [],
+        manualSql: [],
+        backwardSql: [],
+    };
+}
+function appendUnique(target, additions) {
+    additions.forEach((sql) => {
+        if (!target.includes(sql)) {
+            target.push(sql);
+        }
+    });
+}
+function getChangePlanSql(changePlan) {
+    return {
+        prepareSql: [...(changePlan.prepareSql || [])],
+        forwardSql: [
+            ...(changePlan.forwardSql || []),
+            ...(changePlan.deferredForwardSql || []),
+        ],
+        onlineSql: [...(changePlan.onlineSql || [])],
+        manualSql: [...(changePlan.manualSql || [])],
+        backwardSql: [...(changePlan.backwardSql || [])],
+    };
+}
+function getSqlCategories(sql) {
+    return migrationSqlCategoryOrder.filter((category) => sql[category].length > 0);
+}
+function hasSqlInAnyCategory(sql) {
+    return getSqlCategories(sql).length > 0;
+}
+function appendSqlByCategory(target, additions) {
+    migrationSqlCategoryOrder.forEach((category) => {
+        appendUnique(target[category], additions[category]);
+    });
+}
+function createEmptyTableChange(entity, table, lifecycle) {
+    return {
+        entity,
+        table,
+        lifecycle,
+        summary: createEmptySummary(),
+        sql: createEmptySqlByCategory(),
+        columns: {
+            added: [],
+            removed: [],
+            changed: [],
+            renamed: [],
+        },
+        indexes: {
+            added: [],
+            removed: [],
+            changed: [],
+            renamed: [],
+        },
+        foreignKeys: {
+            added: [],
+            removed: [],
+            changed: [],
+        },
+        warnings: [],
+        renameCandidates: [],
+    };
+}
+function ensureTableChange(plan, tableChanges, entity, table, lifecycle) {
+    const existing = tableChanges.get(table);
+    if (existing) {
+        if (existing.lifecycle === 'alter' && lifecycle !== 'alter') {
+            existing.lifecycle = lifecycle;
+        }
+        return existing;
+    }
+    const tableChange = createEmptyTableChange(entity, table, lifecycle);
+    tableChanges.set(table, tableChange);
+    plan.tableChanges.push(tableChange);
+    return tableChange;
+}
+function mergeSummary(summary, patch) {
+    if (!patch) {
+        return;
+    }
+    Object.keys(patch).forEach((key) => {
+        summary[key] += patch[key] || 0;
+    });
+}
+function collectMeta(plan, changePlan, tableChange) {
+    plan.prepareSql.push(...(changePlan.prepareSql || []));
+    plan.onlineSql.push(...(changePlan.onlineSql || []));
+    plan.manualSql.push(...(changePlan.manualSql || []));
+    plan.warnings.push(...(changePlan.warnings || []));
+    plan.renameCandidates.push(...(changePlan.renameCandidates || []));
+    mergeSummary(plan.summary, changePlan.summary);
+    if (tableChange) {
+        appendSqlByCategory(tableChange.sql, getChangePlanSql(changePlan));
+        tableChange.warnings.push(...(changePlan.warnings || []));
+        tableChange.renameCandidates.push(...(changePlan.renameCandidates || []));
+        mergeSummary(tableChange.summary, changePlan.summary);
+    }
+}
+function hasTableChange(tableChange) {
+    if (Object.values(tableChange.summary).some((value) => value > 0)) {
+        return true;
+    }
+    if (tableChange.warnings.length > 0 || tableChange.renameCandidates.length > 0) {
+        return true;
+    }
+    return migrationSqlCategoryOrder.some((category) => tableChange.sql[category].length > 0);
+}
+function createSqlBuckets() {
+    return {
+        forwardTables: [],
+        forwardColumns: [],
+        forwardIndexes: [],
+        forwardForeignKeys: [],
+        backwardForeignKeys: [],
+        backwardIndexes: [],
+        backwardColumns: [],
+        backwardTables: [],
+    };
+}
+function normalizeDefaultValue(value) {
+    if (typeof value === 'string') {
+        return value.trim();
+    }
+    return value;
+}
+function resolveRefTarget(ref, schema) {
+    if (Array.isArray(ref)) {
+        return [...ref].map((item) => schema?.[item]?.storageName || item).sort();
+    }
+    if (typeof ref === 'string') {
+        return schema?.[ref]?.storageName || ref;
+    }
+    return ref;
+}
+function shouldCompareDatabaseRef(attr, compareForeignKeys = true) {
+    return compareForeignKeys
+        && attr.type === 'ref'
+        && typeof attr.ref === 'string';
+}
+function normalizeIntegerType(width, dialect) {
+    if (dialect === 'postgresql') {
+        switch (width) {
+            case 1:
+            case 2:
+                return 'smallint';
+            case 3:
+            case 4:
+            case undefined:
+                return 'integer';
+            default:
+                return 'bigint';
+        }
+    }
+    switch (width) {
+        case 1:
+            return 'tinyint';
+        case 2:
+            return 'smallint';
+        case 3:
+            return 'mediumint';
+        case 4:
+        case undefined:
+            return 'integer';
+        default:
+            return 'bigint';
+    }
+}
+function normalizeAttribute(attr, options) {
+    // diff 前先把方言差异、历史别名和 Oak 语义压成统一快照；
+    // 后面的分类逻辑只比较快照，避免直接比较原始 attr 时被存储细节噪音干扰。
+    let type = typeof attr.sequenceStart === 'number' ? 'sequence' : String(attr.type);
+    const enumeration = attr.enumeration ? [...attr.enumeration] : undefined;
+    const ref = shouldCompareDatabaseRef(attr, options?.compareForeignKeys)
+        ? resolveRefTarget(attr.ref, options?.schema)
+        : undefined;
+    let params = type === 'ref'
+        ? undefined
+        : (attr.params ? { ...attr.params } : undefined);
+    if (type === 'ref' && options?.compareForeignKeys === false) {
+        // 老 MySQL 库里可能只有 char(36) 列而没有物理 FK。
+        // 关闭 FK 对比时，把 ref 退化成列类型比较，先让旧库的 upgrade 计划收敛。
+        type = 'char';
+        params = {
+            length: 36,
+        };
+    }
+    if (type === 'int') {
+        type = normalizeIntegerType(params?.width, options?.dialect);
+        params = undefined;
+    }
+    else if (type === 'bool') {
+        type = 'boolean';
+    }
+    const isIdColumn = options?.column === 'id';
+    const isSequenceColumn = type === 'sequence';
+    return {
+        type,
+        params,
+        enumeration,
+        ref,
+        onRefDelete: ref ? (attr.onRefDelete || 'ignore') : undefined,
+        default: normalizeDefaultValue(attr.default),
+        notNull: isSequenceColumn ? false : (isIdColumn ? true : (!!attr.notNull || type === 'geometry')),
+        unique: isSequenceColumn ? false : !!attr.unique,
+        sequence: isSequenceColumn,
+    };
+}
+function normalizeTsConfig(tsConfig) {
+    if (Array.isArray(tsConfig)) {
+        return [...tsConfig].sort();
+    }
+    return tsConfig;
+}
+function normalizeIndexDirection(direction) {
+    return direction === 'ASC' ? undefined : direction;
+}
+function normalizeIndex(index) {
+    return {
+        name: index.name,
+        attributes: index.attributes.map(({ name, direction, size }) => ({
+            name: String(name),
+            direction: normalizeIndexDirection(direction),
+            size,
+        })),
+        config: {
+            unique: !!index.config?.unique,
+            type: index.config?.type || 'btree',
+            parser: index.config?.parser,
+            tsConfig: normalizeTsConfig(index.config?.tsConfig),
+            chineseParser: index.config?.chineseParser,
+        },
+    };
+}
+function recordAddedColumn(tableChange, name, attr, sql, options) {
+    tableChange.columns.added.push({
+        name,
+        categories: getSqlCategories(sql),
+        reason: options.reason,
+        definition: normalizeAttribute(attr, {
+            schema: options.schema,
+            column: name,
+            dialect: options.dialect,
+            compareForeignKeys: options.compareForeignKeys,
+        }),
+        sql,
+    });
+}
+function recordRemovedColumn(tableChange, name, attr, sql, options) {
+    tableChange.columns.removed.push({
+        name,
+        categories: getSqlCategories(sql),
+        definition: normalizeAttribute(attr, {
+            schema: options.schema,
+            column: name,
+            dialect: options.dialect,
+            compareForeignKeys: options.compareForeignKeys,
+        }),
+        sql,
+    });
+}
+function recordChangedColumn(tableChange, name, oldAttr, newAttr, sql, options) {
+    tableChange.columns.changed.push({
+        name,
+        categories: getSqlCategories(sql),
+        reason: options.reason,
+        before: normalizeAttribute(oldAttr, {
+            schema: options.oldSchema,
+            column: name,
+            dialect: options.dialect,
+            compareForeignKeys: options.compareForeignKeys,
+        }),
+        after: normalizeAttribute(newAttr, {
+            schema: options.newSchema,
+            column: name,
+            dialect: options.dialect,
+            compareForeignKeys: options.compareForeignKeys,
+        }),
+        sql,
+    });
+}
+function recordRenamedColumn(tableChange, from, to, oldAttr, newAttr, sql, options) {
+    tableChange.columns.renamed.push({
+        from,
+        to,
+        categories: getSqlCategories(sql),
+        reason: options.reason,
+        before: normalizeAttribute(oldAttr, {
+            schema: options.oldSchema,
+            column: from,
+            dialect: options.dialect,
+            compareForeignKeys: options.compareForeignKeys,
+        }),
+        after: normalizeAttribute(newAttr, {
+            schema: options.newSchema,
+            column: to,
+            dialect: options.dialect,
+            compareForeignKeys: options.compareForeignKeys,
+        }),
+        sql,
+    });
+}
+function recordAddedIndex(tableChange, index, sql) {
+    tableChange.indexes.added.push({
+        name: index.name,
+        categories: getSqlCategories(sql),
+        definition: normalizeIndex(index),
+        sql,
+    });
+}
+function recordRemovedIndex(tableChange, index, sql) {
+    tableChange.indexes.removed.push({
+        name: index.name,
+        categories: getSqlCategories(sql),
+        definition: normalizeIndex(index),
+        sql,
+    });
+}
+function recordChangedIndex(tableChange, oldIndex, newIndex, sql) {
+    tableChange.indexes.changed.push({
+        name: newIndex.name,
+        categories: getSqlCategories(sql),
+        before: normalizeIndex(oldIndex),
+        after: normalizeIndex(newIndex),
+        sql,
+    });
+}
+function recordRenamedIndex(tableChange, oldIndex, newIndex, sql) {
+    tableChange.indexes.renamed.push({
+        from: oldIndex.name,
+        to: newIndex.name,
+        categories: getSqlCategories(sql),
+        before: normalizeIndex(oldIndex),
+        after: normalizeIndex(newIndex),
+        sql,
+    });
+}
+function recordAddedForeignKey(tableChange, foreignKey, sql) {
+    tableChange.foreignKeys.added.push({
+        name: foreignKey.name,
+        categories: getSqlCategories(sql),
+        definition: {
+            ...foreignKey,
+        },
+        sql,
+    });
+}
+function recordRemovedForeignKey(tableChange, foreignKey, sql) {
+    tableChange.foreignKeys.removed.push({
+        name: foreignKey.name,
+        categories: getSqlCategories(sql),
+        definition: {
+            ...foreignKey,
+        },
+        sql,
+    });
+}
+function recordChangedForeignKey(tableChange, oldForeignKey, newForeignKey, sql) {
+    tableChange.foreignKeys.changed.push({
+        name: newForeignKey?.name || oldForeignKey?.name || 'unknown',
+        categories: getSqlCategories(sql),
+        before: oldForeignKey ? {
+            ...oldForeignKey,
+        } : undefined,
+        after: newForeignKey ? {
+            ...newForeignKey,
+        } : undefined,
+        sql,
+    });
+}
+function isObjectEqual(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+function areAttributesEquivalent(oldAttr, newAttr, options) {
+    return isObjectEqual(normalizeAttribute(oldAttr, {
+        schema: options?.oldSchema,
+        column: options?.oldColumn || options?.column,
+        dialect: options?.dialect,
+        compareForeignKeys: options?.compareForeignKeys,
+    }), normalizeAttribute(newAttr, {
+        schema: options?.newSchema,
+        column: options?.newColumn || options?.column,
+        dialect: options?.dialect,
+        compareForeignKeys: options?.compareForeignKeys,
+    }));
+}
+function areIndexesEquivalent(oldIndex, newIndex) {
+    const oldSnapshot = normalizeIndex(oldIndex);
+    const newSnapshot = normalizeIndex(newIndex);
+    return isObjectEqual({
+        ...oldSnapshot,
+        name: undefined,
+    }, {
+        ...newSnapshot,
+        name: undefined,
+    });
+}
+function getTypeFamily(type) {
+    const lowerType = type.toLowerCase();
+    if (['char', 'varchar', 'text'].includes(lowerType)) {
+        return 'text';
+    }
+    if (['decimal', 'numeric', 'float', 'double', 'real'].includes(lowerType)) {
+        return 'decimal';
+    }
+    if (['int', 'integer', 'smallint', 'bigint', 'tinyint', 'mediumint'].includes(lowerType)) {
+        return 'integer';
+    }
+    return lowerType;
+}
+function getIntegerRank(type) {
+    const rank = {
+        tinyint: 1,
+        smallint: 2,
+        mediumint: 3,
+        int: 4,
+        integer: 4,
+        bigint: 5,
+    };
+    return rank[type.toLowerCase()] || 0;
+}
+function isSameEnumerationPrefix(oldValues, newValues) {
+    if (newValues.length < oldValues.length) {
+        return false;
+    }
+    return oldValues.every((value, index) => newValues[index] === value);
+}
+function isTypeChangeSafe(oldAttr, newAttr) {
+    if (oldAttr.type === newAttr.type) {
+        switch (getTypeFamily(oldAttr.type)) {
+            case 'text': {
+                const oldLength = oldAttr.params?.length || 0;
+                const newLength = newAttr.params?.length || 0;
+                if (newAttr.type === 'text') {
+                    return true;
+                }
+                if (!oldLength || !newLength) {
+                    return true;
+                }
+                return newLength >= oldLength;
+            }
+            case 'decimal': {
+                const oldPrecision = oldAttr.params?.precision || 0;
+                const oldScale = oldAttr.params?.scale || 0;
+                const newPrecision = newAttr.params?.precision || 0;
+                const newScale = newAttr.params?.scale || 0;
+                return newPrecision >= oldPrecision && newScale >= oldScale;
+            }
+            case 'integer': {
+                return getIntegerRank(newAttr.type) >= getIntegerRank(oldAttr.type);
+            }
+            default: {
+                return false;
+            }
+        }
+    }
+    if (getTypeFamily(oldAttr.type) !== getTypeFamily(newAttr.type)) {
+        return false;
+    }
+    if (getTypeFamily(oldAttr.type) === 'text' && newAttr.type === 'text') {
+        return true;
+    }
+    if (getTypeFamily(oldAttr.type) === 'integer') {
+        return getIntegerRank(newAttr.type) >= getIntegerRank(oldAttr.type);
+    }
+    return false;
+}
+function classifyAttributeChange(oldAttr, newAttr, options) {
+    if (!oldAttr && !newAttr) {
+        return {
+            mode: 'none',
+        };
+    }
+    if (!oldAttr && newAttr) {
+        const normalized = normalizeAttribute(newAttr, {
+            dialect: options?.dialect,
+            column: options?.column,
+            schema: options?.newSchema,
+            compareForeignKeys: options?.compareForeignKeys,
+        });
+        if (normalized.notNull && normalized.default === undefined && !normalized.sequence) {
+            return {
+                mode: 'manual',
+                reason: '新字段为非空且没有默认值，需要先补齐历史数据',
+            };
+        }
+        return {
+            mode: 'forward',
+        };
+    }
+    if (oldAttr && !newAttr) {
+        return {
+            mode: 'forward',
+        };
+    }
+    if (areAttributesEquivalent(oldAttr, newAttr, options)) {
+        return {
+            mode: 'none',
+        };
+    }
+    const oldSnapshot = normalizeAttribute(oldAttr, {
+        schema: options?.oldSchema,
+        column: options?.column,
+        dialect: options?.dialect,
+        compareForeignKeys: options?.compareForeignKeys,
+    });
+    const newSnapshot = normalizeAttribute(newAttr, {
+        schema: options?.newSchema,
+        column: options?.column,
+        dialect: options?.dialect,
+        compareForeignKeys: options?.compareForeignKeys,
+    });
+    if (!isObjectEqual(oldSnapshot.ref, newSnapshot.ref)
+        || oldSnapshot.onRefDelete !== newSnapshot.onRefDelete) {
+        return {
+            mode: 'manual',
+            reason: '外键引用目标或删除规则发生变化，需要确认现有数据兼容',
+        };
+    }
+    if (oldSnapshot.unique !== newSnapshot.unique) {
+        return {
+            mode: 'manual',
+            reason: '唯一约束变化需要先确认历史数据是否满足约束',
+        };
+    }
+    if (oldSnapshot.type === 'enum' || newSnapshot.type === 'enum') {
+        if (oldSnapshot.type === 'enum'
+            && newSnapshot.type === 'enum'
+            && oldSnapshot.enumeration
+            && newSnapshot.enumeration
+            && isSameEnumerationPrefix(oldSnapshot.enumeration, newSnapshot.enumeration)) {
+            return {
+                mode: 'forward',
+                enumAppendOnly: true,
+            };
+        }
+        return {
+            mode: 'manual',
+            reason: '枚举值集合变化需要确认现有数据映射关系',
+        };
+    }
+    const typeChanged = oldSnapshot.type !== newSnapshot.type
+        || !isObjectEqual(oldSnapshot.params, newSnapshot.params);
+    if (typeChanged) {
+        if (!isTypeChangeSafe(oldSnapshot, newSnapshot)) {
+            return {
+                mode: 'manual',
+                reason: '字段类型变化可能需要显式转换或人工清洗数据',
+            };
+        }
+    }
+    if (oldSnapshot.notNull !== newSnapshot.notNull) {
+        if (!oldSnapshot.notNull && newSnapshot.notNull) {
+            return {
+                mode: 'manual',
+                reason: '字段要从可空改为非空，需要先补齐空值',
+            };
+        }
+    }
+    return {
+        mode: 'forward',
+    };
+}
+function buildTableMap(schema, adapter) {
+    const tableMap = new Map();
+    Object.keys(schema).forEach((table) => {
+        const tableDef = schema[table];
+        const actualName = adapter.getTableName(table, tableDef);
+        tableMap.set(adapter.normalizeIdentifier(actualName), {
+            key: table,
+            actualName,
+            tableDef,
+        });
+    });
+    return tableMap;
+}
+function pickRenameCandidates(tableName, oldAttrs, newAttrs, oldOnly, newOnly, oldSchema, newSchema, dialect, compareForeignKeys) {
+    const renameCandidates = [];
+    const pendingNew = [...newOnly];
+    for (const oldColumn of oldOnly) {
+        const matchIndex = pendingNew.findIndex((newColumn) => areAttributesEquivalent(oldAttrs[oldColumn], newAttrs[newColumn], {
+            oldSchema,
+            newSchema,
+            oldColumn,
+            newColumn,
+            dialect,
+            compareForeignKeys,
+        }));
+        if (matchIndex >= 0) {
+            const [newColumn] = pendingNew.splice(matchIndex, 1);
+            renameCandidates.push({
+                from: oldColumn,
+                to: newColumn,
+            });
+        }
+    }
+    const oldRemain = oldOnly.filter((column) => !renameCandidates.find((candidate) => candidate.from === column));
+    const newRemain = newOnly.filter((column) => !renameCandidates.find((candidate) => candidate.to === column));
+    return {
+        renameCandidates,
+        oldRemain,
+        newRemain,
+    };
+}
+function cloneIndex(index) {
+    return {
+        ...index,
+        attributes: index.attributes.map((attr) => ({
+            ...attr,
+        })),
+        config: index.config ? {
+            ...index.config,
+        } : undefined,
+        __originNames: index.__originNames ? [...index.__originNames] : undefined,
+    };
+}
+function buildIndexList(indexes) {
+    return (indexes || []).map(cloneIndex);
+}
+function buildIndexNameVariants(name, options) {
+    const variants = new Set([name]);
+    const pending = [name];
+    const prefixes = [options?.currentActualName, options?.targetKey].filter(Boolean);
+    while (pending.length > 0) {
+        const current = pending.shift();
+        prefixes.forEach((prefix) => {
+            if (current.startsWith(`${prefix}_`)) {
+                const stripped = current.slice(prefix.length + 1);
+                if (!variants.has(stripped)) {
+                    variants.add(stripped);
+                    pending.push(stripped);
+                }
+            }
+        });
+    }
+    return variants;
+}
+function areIndexNamesCompatible(oldIndex, newIndex, oldOptions, newOptions) {
+    if (oldIndex.name === newIndex.name) {
+        return true;
+    }
+    const newVariants = buildIndexNameVariants(newIndex.name, newOptions);
+    for (const variant of buildIndexNameVariants(oldIndex.name, oldOptions)) {
+        if (newVariants.has(variant)) {
+            return true;
+        }
+    }
+    return false;
+}
+function findCompatibleIndexMatch(oldIndex, newIndexes, matchedNewIndexes, oldOptions, newOptions) {
+    const aliasCandidates = [];
+    for (let i = 0; i < newIndexes.length; i++) {
+        if (matchedNewIndexes.has(i)) {
+            continue;
+        }
+        const newIndex = newIndexes[i];
+        if (oldIndex.name === newIndex.name) {
+            return i;
+        }
+        if (areIndexNamesCompatible(oldIndex, newIndex, oldOptions, newOptions)) {
+            aliasCandidates.push(i);
+        }
+    }
+    if (aliasCandidates.length === 1) {
+        return aliasCandidates[0];
+    }
+    return undefined;
+}
+function pickEquivalentIndexRenameCandidates(oldIndexes, newIndexes) {
+    const renameCandidates = [];
+    const pendingNew = [...newIndexes];
+    for (const oldIndex of oldIndexes) {
+        const matchIndex = pendingNew.findIndex((newIndex) => areIndexesEquivalent(oldIndex, newIndex));
+        if (matchIndex >= 0) {
+            const [newIndex] = pendingNew.splice(matchIndex, 1);
+            renameCandidates.push({
+                oldIndex,
+                newIndex,
+            });
+        }
+    }
+    const oldRemain = oldIndexes.filter((index) => !renameCandidates.find((candidate) => candidate.oldIndex === index));
+    const newRemain = newIndexes.filter((index) => !renameCandidates.find((candidate) => candidate.newIndex === index));
+    return {
+        renameCandidates,
+        oldRemain,
+        newRemain,
+    };
+}
+function getForeignKeyMap(table, tableDef, fullSchema, adapter) {
+    return adapter.getForeignKeys(table, tableDef, fullSchema);
+}
+function hasExplicitIndexOrigin(index) {
+    return !!index.__originName || !!index.__originNames?.length;
+}
+function buildMigrationPlan(currentSchema, targetSchema, adapter, options = {}) {
+    // planner 的核心算法分两步：
+    // 1. 先按“建表 / 改表 / 删表”收集变更语义；
+    // 2. 再把 SQL 按依赖关系重新分桶，避免 schema 遍历顺序影响最终执行顺序。
+    const largeTableRowThreshold = options.largeTableRowThreshold || 100000;
+    const compareForeignKeys = options.compareForeignKeys !== false;
+    const buckets = createSqlBuckets();
+    const plan = {
+        currentSchema,
+        targetSchema,
+        prepareSql: [],
+        forwardSql: [],
+        onlineSql: [],
+        manualSql: [],
+        backwardSql: [],
+        warnings: [],
+        renameCandidates: [],
+        summary: createEmptySummary(),
+        tableChanges: [],
+    };
+    const tableChanges = new Map();
+    const currentTables = buildTableMap(currentSchema, adapter);
+    const matchedCurrentTables = new Set();
+    plan.prepareSql.push(...adapter.buildPrepareSql(currentSchema, targetSchema));
+    Object.keys(targetSchema).forEach((table) => {
+        const targetDef = targetSchema[table];
+        const tableName = adapter.getTableName(table, targetDef);
+        const normalized = adapter.normalizeIdentifier(tableName);
+        const currentEntry = currentTables.get(normalized);
+        if (!currentEntry) {
+            // 新表先记录完整语义；真正的 FK SQL 会延后到 forwardForeignKeys 桶，
+            // 这样可以保证它一定落在所有 CREATE TABLE 之后。
+            const tableChange = ensureTableChange(plan, tableChanges, table, tableName, 'create');
+            const changePlan = adapter.buildNewTablePlan(table, targetDef);
+            const changePlanSql = getChangePlanSql(changePlan);
+            collectMeta(plan, changePlan, tableChange);
+            Object.entries(targetDef.attributes || {}).forEach(([column, attr]) => {
+                recordAddedColumn(tableChange, column, attr, changePlanSql, {
+                    schema: targetSchema,
+                    dialect: adapter.dialect,
+                    compareForeignKeys,
+                });
+            });
+            (targetDef.indexes || []).forEach((index) => {
+                recordAddedIndex(tableChange, index, changePlanSql);
+            });
+            Object.values(getForeignKeyMap(table, targetDef, targetSchema, adapter)).forEach((foreignKey) => {
+                recordAddedForeignKey(tableChange, foreignKey, changePlanSql);
+            });
+            buckets.forwardTables.push(...(changePlan.forwardSql || []));
+            buckets.forwardForeignKeys.push(...(changePlan.deferredForwardSql || []));
+            return;
+        }
+        matchedCurrentTables.add(normalized);
+        // 已存在表按“列 -> 索引 -> FK”的顺序规划，
+        // 这样后面的索引和约束总是基于列已经收敛后的结构。
+        const tableChange = ensureTableChange(plan, tableChanges, table, tableName, 'alter');
+        const oldAttrs = currentEntry.tableDef.attributes || {};
+        const newAttrs = targetDef.attributes || {};
+        const oldAttrNames = Object.keys(oldAttrs);
+        const newAttrNames = Object.keys(newAttrs);
+        const oldOnly = oldAttrNames.filter((name) => !newAttrs[name]);
+        const newOnly = newAttrNames.filter((name) => !oldAttrs[name]);
+        const renameResult = pickRenameCandidates(tableName, oldAttrs, newAttrs, oldOnly, newOnly, currentSchema, targetSchema, adapter.dialect, compareForeignKeys);
+        renameResult.renameCandidates.forEach(({ from, to }) => {
+            const renamePlan = adapter.buildRenamePlan(tableName, from, to, oldAttrs[from], newAttrs[to]);
+            const renamePlanSql = getChangePlanSql(renamePlan);
+            collectMeta(plan, renamePlan, tableChange);
+            recordRenamedColumn(tableChange, from, to, oldAttrs[from], newAttrs[to], renamePlanSql, {
+                oldSchema: currentSchema,
+                newSchema: targetSchema,
+                dialect: adapter.dialect,
+                compareForeignKeys,
+                reason: renamePlan.renameCandidates?.[0]?.reason || '检测到等价字段，建议按重命名处理',
+            });
+        });
+        oldAttrNames
+            .filter((name) => !!newAttrs[name])
+            .forEach((column) => {
+            const classification = classifyAttributeChange(oldAttrs[column], newAttrs[column], {
+                oldSchema: currentSchema,
+                newSchema: targetSchema,
+                column,
+                dialect: adapter.dialect,
+                compareForeignKeys,
+            });
+            const changePlan = adapter.buildColumnPlan(tableName, column, oldAttrs[column], newAttrs[column], classification);
+            const changePlanSql = getChangePlanSql(changePlan);
+            collectMeta(plan, changePlan, tableChange);
+            if (classification.mode !== 'none') {
+                recordChangedColumn(tableChange, column, oldAttrs[column], newAttrs[column], changePlanSql, {
+                    oldSchema: currentSchema,
+                    newSchema: targetSchema,
+                    dialect: adapter.dialect,
+                    compareForeignKeys,
+                    reason: classification.reason,
+                });
+            }
+            buckets.forwardColumns.push(...(changePlan.forwardSql || []));
+            buckets.backwardColumns.push(...(changePlan.backwardSql || []));
+        });
+        renameResult.newRemain.forEach((column) => {
+            const classification = classifyAttributeChange(undefined, newAttrs[column], {
+                newSchema: targetSchema,
+                column,
+                dialect: adapter.dialect,
+                compareForeignKeys,
+            });
+            const changePlan = adapter.buildColumnPlan(tableName, column, undefined, newAttrs[column], classification);
+            const changePlanSql = getChangePlanSql(changePlan);
+            collectMeta(plan, changePlan, tableChange);
+            recordAddedColumn(tableChange, column, newAttrs[column], changePlanSql, {
+                schema: targetSchema,
+                dialect: adapter.dialect,
+                compareForeignKeys,
+                reason: classification.reason,
+            });
+            buckets.forwardColumns.push(...(changePlan.forwardSql || []));
+            buckets.backwardColumns.push(...(changePlan.backwardSql || []));
+        });
+        renameResult.oldRemain.forEach((column) => {
+            const classification = classifyAttributeChange(oldAttrs[column], undefined, {
+                oldSchema: currentSchema,
+                column,
+                dialect: adapter.dialect,
+                compareForeignKeys,
+            });
+            const changePlan = adapter.buildColumnPlan(tableName, column, oldAttrs[column], undefined, classification);
+            const changePlanSql = getChangePlanSql(changePlan);
+            collectMeta(plan, changePlan, tableChange);
+            recordRemovedColumn(tableChange, column, oldAttrs[column], changePlanSql, {
+                schema: currentSchema,
+                dialect: adapter.dialect,
+                compareForeignKeys,
+            });
+            buckets.forwardColumns.push(...(changePlan.forwardSql || []));
+            buckets.backwardColumns.push(...(changePlan.backwardSql || []));
+        });
+        const oldIndexMatchOptions = {
+            currentActualName: currentEntry.actualName,
+            targetKey: table,
+        };
+        const newIndexMatchOptions = {
+            currentActualName: tableName,
+            targetKey: table,
+        };
+        const oldIndexes = buildIndexList(currentEntry.tableDef.indexes);
+        const newIndexes = buildIndexList(targetDef.indexes);
+        const matchedOldIndexes = new Set();
+        const matchedNewIndexes = new Set();
+        oldIndexes.forEach((oldIndex, oldIndexPosition) => {
+            const matchedNewPosition = findCompatibleIndexMatch(oldIndex, newIndexes, matchedNewIndexes, oldIndexMatchOptions, newIndexMatchOptions);
+            if (matchedNewPosition === undefined) {
+                return;
+            }
+            const newIndex = newIndexes[matchedNewPosition];
+            matchedOldIndexes.add(oldIndexPosition);
+            matchedNewIndexes.add(matchedNewPosition);
+            if (areIndexesEquivalent(oldIndex, newIndex)) {
+                if (hasExplicitIndexOrigin(oldIndex)) {
+                    const renamePlan = adapter.buildRenameIndexPlan(tableName, table, oldIndex, newIndex, {
+                        isNewTable: false,
+                        tableStats: options.currentTableStats?.[tableName],
+                        largeTableRowThreshold,
+                    });
+                    const renamePlanSql = getChangePlanSql(renamePlan);
+                    collectMeta(plan, renamePlan, tableChange);
+                    if (hasSqlInAnyCategory(renamePlanSql)) {
+                        recordRenamedIndex(tableChange, oldIndex, newIndex, renamePlanSql);
+                    }
+                    buckets.forwardIndexes.push(...(renamePlan.forwardSql || []));
+                    buckets.backwardIndexes.push(...(renamePlan.backwardSql || []));
+                }
+                return;
+            }
+            const changePlan = adapter.buildIndexPlan(tableName, table, oldIndex, newIndex, {
+                isNewTable: false,
+                tableStats: options.currentTableStats?.[tableName],
+                largeTableRowThreshold,
+            });
+            const changePlanSql = getChangePlanSql(changePlan);
+            collectMeta(plan, changePlan, tableChange);
+            recordChangedIndex(tableChange, oldIndex, newIndex, changePlanSql);
+            buckets.forwardIndexes.push(...(changePlan.forwardSql || []));
+            buckets.backwardIndexes.push(...(changePlan.backwardSql || []));
+        });
+        const indexRenameResult = pickEquivalentIndexRenameCandidates(oldIndexes.filter((_, index) => !matchedOldIndexes.has(index)), newIndexes.filter((_, index) => !matchedNewIndexes.has(index)));
+        indexRenameResult.renameCandidates.forEach(({ oldIndex, newIndex }) => {
+            const renamePlan = adapter.buildRenameIndexPlan(tableName, table, oldIndex, newIndex, {
+                isNewTable: false,
+                tableStats: options.currentTableStats?.[tableName],
+                largeTableRowThreshold,
+            });
+            const renamePlanSql = getChangePlanSql(renamePlan);
+            collectMeta(plan, renamePlan, tableChange);
+            if (hasSqlInAnyCategory(renamePlanSql)) {
+                recordRenamedIndex(tableChange, oldIndex, newIndex, renamePlanSql);
+            }
+            buckets.forwardIndexes.push(...(renamePlan.forwardSql || []));
+            buckets.backwardIndexes.push(...(renamePlan.backwardSql || []));
+        });
+        indexRenameResult.oldRemain.forEach((oldIndex) => {
+            const changePlan = adapter.buildIndexPlan(tableName, table, oldIndex, undefined, {
+                isNewTable: false,
+                tableStats: options.currentTableStats?.[tableName],
+                largeTableRowThreshold,
+            });
+            const changePlanSql = getChangePlanSql(changePlan);
+            collectMeta(plan, changePlan, tableChange);
+            recordRemovedIndex(tableChange, oldIndex, changePlanSql);
+            buckets.forwardIndexes.push(...(changePlan.forwardSql || []));
+            buckets.backwardIndexes.push(...(changePlan.backwardSql || []));
+        });
+        indexRenameResult.newRemain.forEach((newIndex) => {
+            const changePlan = adapter.buildIndexPlan(tableName, table, undefined, newIndex, {
+                isNewTable: false,
+                tableStats: options.currentTableStats?.[tableName],
+                largeTableRowThreshold,
+            });
+            const changePlanSql = getChangePlanSql(changePlan);
+            collectMeta(plan, changePlan, tableChange);
+            recordAddedIndex(tableChange, newIndex, changePlanSql);
+            buckets.forwardIndexes.push(...(changePlan.forwardSql || []));
+            buckets.backwardIndexes.push(...(changePlan.backwardSql || []));
+        });
+        if (compareForeignKeys) {
+            const oldForeignKeys = getForeignKeyMap(currentEntry.key, currentEntry.tableDef, currentSchema, adapter);
+            const newForeignKeys = getForeignKeyMap(table, targetDef, targetSchema, adapter);
+            const foreignKeyNames = Array.from(new Set([
+                ...Object.keys(oldForeignKeys),
+                ...Object.keys(newForeignKeys),
+            ]));
+            foreignKeyNames.forEach((name) => {
+                const oldForeignKey = oldForeignKeys[name];
+                const newForeignKey = newForeignKeys[name];
+                if (oldForeignKey && newForeignKey && isObjectEqual(oldForeignKey, newForeignKey)) {
+                    return;
+                }
+                const changePlan = adapter.buildForeignKeyPlan(tableName, oldForeignKey, newForeignKey, false);
+                const changePlanSql = getChangePlanSql(changePlan);
+                collectMeta(plan, changePlan, tableChange);
+                if (!oldForeignKey && newForeignKey) {
+                    recordAddedForeignKey(tableChange, newForeignKey, changePlanSql);
+                }
+                else if (oldForeignKey && !newForeignKey) {
+                    recordRemovedForeignKey(tableChange, oldForeignKey, changePlanSql);
+                }
+                else {
+                    recordChangedForeignKey(tableChange, oldForeignKey, newForeignKey, changePlanSql);
+                }
+                buckets.forwardForeignKeys.push(...(changePlan.forwardSql || []));
+                buckets.backwardForeignKeys.push(...(changePlan.backwardSql || []));
+            });
+        }
+    });
+    const removedTables = [];
+    currentTables.forEach((entry, normalized) => {
+        if (!matchedCurrentTables.has(normalized)) {
+            removedTables.push(entry);
+        }
+    });
+    // 删除表也分两轮：先删依赖约束，再删表本体。
+    // backward 方向需要和 forward 相反，否则很容易被 FK 依赖卡住。
+    removedTables.forEach((entry) => {
+        const tableChange = ensureTableChange(plan, tableChanges, entry.key, entry.actualName, 'drop');
+        const foreignKeys = getForeignKeyMap(entry.key, entry.tableDef, currentSchema, adapter);
+        Object.values(foreignKeys).forEach((foreignKey) => {
+            const changePlan = adapter.buildForeignKeyPlan(entry.actualName, foreignKey, undefined, false);
+            const changePlanSql = getChangePlanSql(changePlan);
+            collectMeta(plan, changePlan, tableChange);
+            recordRemovedForeignKey(tableChange, foreignKey, changePlanSql);
+            buckets.backwardForeignKeys.push(...(changePlan.backwardSql || []));
+        });
+    });
+    removedTables.forEach((entry) => {
+        const tableChange = ensureTableChange(plan, tableChanges, entry.key, entry.actualName, 'drop');
+        const changePlan = adapter.buildDropTablePlan(entry.actualName);
+        const changePlanSql = getChangePlanSql(changePlan);
+        collectMeta(plan, changePlan, tableChange);
+        Object.entries(entry.tableDef.attributes || {}).forEach(([column, attr]) => {
+            recordRemovedColumn(tableChange, column, attr, changePlanSql, {
+                schema: currentSchema,
+                dialect: adapter.dialect,
+                compareForeignKeys,
+            });
+        });
+        (entry.tableDef.indexes || []).forEach((index) => {
+            recordRemovedIndex(tableChange, index, changePlanSql);
+        });
+        buckets.backwardTables.push(...(changePlan.backwardSql || []));
+    });
+    // 最终 SQL 不按遍历顺序输出，而是按依赖桶统一回放。
+    // forward 方向是“表 -> 列 -> 索引 -> FK”，backward 方向则严格反过来。
+    plan.forwardSql.push(...buckets.forwardTables, ...buckets.forwardColumns, ...buckets.forwardIndexes, ...buckets.forwardForeignKeys);
+    plan.backwardSql.push(...buckets.backwardForeignKeys, ...buckets.backwardIndexes, ...buckets.backwardColumns, ...buckets.backwardTables);
+    plan.tableChanges = plan.tableChanges.filter(hasTableChange);
+    return plan;
+}