📚 课程目录第4章多表关联迁移与字段重命名

多表关联迁移与字段重命名：迁移中处理外键约束、表重命名、字段重命名的最佳实践

原理：外键依赖下的结构变更冲突

当数据库涉及多张具有外键关联的表时，表重命名与字段重命名不能孤立执行。SQLite 的外键机制在迁移过程中会阻止对父表或子表的破坏性操作（如 DROP TABLE、ALTER TABLE RENAME 等），直接执行会导致 FOREIGN KEY constraint failed 错误。核心矛盾在于：外键约束要求在修改时保持引用完整性，而重命名本质上是一个“先删后建”的过程。因此多表关联迁移必须遵循“先拆约束、再改结构、后重建约束”的基调。

  关键认知：Room 的 Migration 本质是逐条执行 SQL 的脚本容器，不自动处理外键依赖。开发者必须在 Migration 内部显式管理 PRAGMA foreign_keys 状态，并按照正确的顺序操作表，否则迁移会在第一条违反外键的 DDL 上崩溃。

实现流程：三阶段递进式迁移

针对多表关联迁移，推荐采用三阶段递进式策略，确保外键约束在合适的时机被禁用、操作、重建。

阶段一（准备）：分析新旧版本差异，建立表名映射与字段映射矩阵；使用 PRAGMA foreign_keys = OFF 临时禁用外键约束。
阶段二（执行）：按依赖顺序从叶子表到根表依次执行 CREATE TABLE ... AS SELECT 或 CREATE + INSERT + DROP + ALTER RENAME 完成表重命名与字段重命名。
阶段三（重建）：重新创建所有外键约束、索引、触发器；使用 PRAGMA foreign_keys = ON 恢复约束检查；执行完整性验证。

代码实现：Room Migration 实战

以下示例演示从版本 2 迁移到版本 3，同时处理 User→Customer 表重命名、orderNumber→purchaseCode 字段重命名以及外键重建。注意迁移中事务与 PRAGMA 的配合。

@Database(version = 3, entities = {Customer.class, Purchase.class}, exportSchema = true)
public class AppDatabase extends RoomDatabase {
    // DAO 声明...
}

static final Migration MIGRATION_2_3 = new Migration(2, 3) {
    @Override
    public void migrate(@NonNull SupportSQLiteDatabase database) {
        // 阶段一：禁用外键约束，避免操作顺序冲突
        database.execSQL("PRAGMA foreign_keys = OFF");

        // 阶段二：执行多表迁移
        // 2.1 创建新表 Customer（替代 User），字段 userName → customerName
        database.execSQL(
            "CREATE TABLE Customer (" +
            "    id INTEGER PRIMARY KEY NOT NULL," +
            "    customerName TEXT NOT NULL," +
            "    age INTEGER NOT NULL" +
            ")"
        );
        database.execSQL(
            "INSERT INTO Customer (id, customerName, age) " +
            "SELECT id, userName, age FROM User"
        );

        // 2.2 创建新表 Purchase（替代 Order），字段重命名 + 外键调整
        database.execSQL(
            "CREATE TABLE Purchase (" +
            "    id INTEGER PRIMARY KEY NOT NULL," +
            "    customerId INTEGER NOT NULL," +
            "    purchaseCode TEXT NOT NULL," +
            "    total REAL NOT NULL," +
            "    FOREIGN KEY (customerId) REFERENCES Customer(id)" +
            ")"
        );
        database.execSQL(
            "INSERT INTO Purchase (id, customerId, purchaseCode, total) " +
            "SELECT id, userId, orderNumber, amount FROM Order"
        );

        // 2.3 删除旧表（必须先删除子表 Order，再删除主表 User）
        database.execSQL("DROP TABLE IF EXISTS Order");
        database.execSQL("DROP TABLE IF EXISTS User");

        // 阶段三：重建外键索引（可选但推荐）并恢复约束
        database.execSQL("CREATE INDEX IF NOT EXISTS idx_purchase_customer ON Purchase(customerId)");
        database.execSQL("PRAGMA foreign_keys = ON");
    }
};

⚠️ 顺序敏感：删除旧表时必须先删子表（持有外键的表），再删父表。如果先删除 User（父表），SQLite 会因 Order 中残留的外键引用而抛出异常。事务中可以依赖 PRAGMA foreign_keys = OFF 暂时绕过，但保持正确的 DDL 顺序仍然是好习惯。

字段映射矩阵：在设计阶段必须对齐

迁移前应整理出完整的字段映射表，避免因名称错位导致数据丢失或类型转换异常。

旧表.字段	新表.字段	转换规则	注意事项
User.userName	Customer.customerName	直接映射	字段重命名，类型不变
User.age	Customer.age	直接映射	字段名未变化
Order.userId	Purchase.customerId	直接映射 + 外键重定向	外键目标表从 User 变为 Customer
Order.orderNumber	Purchase.purchaseCode	字段重命名	业务含义不变，仅命名规范调整
Order.amount	Purchase.total	字段重命名	数据类型仍为 REAL

调试策略：事务回滚与完整性验证

多表关联迁移的调试重点在于验证数据行数、外键引用和字段值三个维度。建议在 Migration 内部加入校验 SQL，并在测试环境中模拟全量数据迁移。

// 在 migrate() 方法末尾加入调试校验（仅 debug 构建）
if (BuildConfig.DEBUG) {
    // 1. 行数校验
    long userCount = database.query("SELECT COUNT(*) FROM User").getCount();
    long customerCount = database.query("SELECT COUNT(*) FROM Customer").getCount();
    if (userCount != customerCount) {
        throw new IllegalStateException(
            "User→Customer 行数不匹配: " + userCount + " vs " + customerCount
        );
    }

    // 2. 外键引用校验：Purchase.customerId 必须在 Customer 中存在
    Cursor cursor = database.query(
        "SELECT p.id FROM Purchase p " +
        "LEFT JOIN Customer c ON p.customerId = c.id " +
        "WHERE c.id IS NULL"
    );
    if (cursor.getCount() > 0) {
        throw new IllegalStateException("存在孤立的外键引用，请检查数据");
    }
    cursor.close();
}

💡 部署建议：在正式发布前，使用 @Database(exportSchema = true) 导出迁移历史，通过 Room 的 MigrationTestHelper 编写 Instrumented Test，覆盖版本 2→3 的完整迁移路径。测试应包含边界数据（如空表、含 NULL 值的字段、重复外键等）。

常见错误与解决方案

错误现象	根本原因	解决方案
`FOREIGN KEY constraint failed`	在启用外键约束时尝试删除父表，或插入数据违反引用完整性	在 DROP TABLE 前执行 `PRAGMA foreign_keys = OFF`；数据迁移后执行完整性校验
迁移后查询返回 0 行	`INSERT INTO ... SELECT` 中字段顺序或别名不匹配导致写入失败	使用 `SELECT *` 结合字段映射表验证；在调试模式打印受影响行数
`no such table: Customer`	Room 的实体注解中 `tableName` 未同步更新，或 Migration 中 DDL 拼写错误	检查 `@Entity(tableName = ...)` 与 Migration 中 CREATE TABLE 的表名一致
迁移耗时过长导致 ANR	未将多个 DDL/DML 包裹在单个事务中，或未使用批量插入	Room 的 Migration 默认在事务中运行；但 `execSQL` 不会自动启用事务，建议显式添加 `BEGIN TRANSACTION`/`END TRANSACTION`
外键重建后性能下降	重建外键后未重新创建索引，导致 JOIN 查询全表扫描	迁移完成后执行 `CREATE INDEX IF NOT EXISTS` 重建所有外键索引

性能与稳定性优化

多表关联迁移涉及大量 DDL 和数据搬移，在数据量较大时需要考虑以下优化手段：

显式事务包裹：Room Migration 本身运行在事务中，但如果需要在迁移中执行多次 execSQL，建议用 BEGIN IMMEDIATE TRANSACTION 确保原子性，避免中途崩溃导致部分迁移生效。
批量写入 vs 逐行写入：对于万级以上数据，INSERT INTO ... SELECT 是最高效的方式；避免使用逐行 ContentValues 插入。
索引延迟创建：先插入数据，再创建索引和外键约束，比先建约束再插入数据快 2～5 倍（减少约束检查开销）。
临时禁用同步 I/O：在迁移开始前执行 PRAGMA synchronous = OFF，迁移结束后恢复 PRAGMA synchronous = FULL（适用于可容忍极端情况下数据丢失的场景）。
监控迁移耗时：使用 android.os.Trace 或自定义计时器，在 migrate() 方法首尾记录耗时，便于定位慢 SQL。

// 高数据量下的优化迁移模板
database.execSQL("PRAGMA foreign_keys = OFF");
database.execSQL("PRAGMA synchronous = OFF");
database.execSQL("PRAGMA journal_mode = WAL");

database.execSQL("BEGIN IMMEDIATE TRANSACTION");
try {
    // 阶段二：CREATE + INSERT + DROP（此处省略具体 SQL）
    database.execSQL("CREATE TABLE Customer ...");
    database.execSQL("INSERT INTO Customer SELECT ... FROM User");
    database.execSQL("DROP TABLE IF EXISTS Order");
    database.execSQL("DROP TABLE IF EXISTS User");
    // 阶段三：先建索引，后建外键
    database.execSQL("CREATE INDEX idx_purchase_customer ON Purchase(customerId)");
    database.execSQL("END TRANSACTION");
} catch (Exception e) {
    database.execSQL("ROLLBACK");
    throw new MigrationException("迁移失败", e);
} finally {
    database.execSQL("PRAGMA foreign_keys = ON");
    database.execSQL("PRAGMA synchronous = FULL");
}

💡 稳定性底线：始终为 Migration 编写对应的降级回滚脚本（虽然 Room 不支持自动回滚，但可以在 fallbackToDestructiveMigration 开启前，手动备份旧表数据）。对于关键生产环境，建议采用“影子表”策略：先创建新表，双写一段时间，确认稳定后再删除旧表。

  核心要诀：多表关联迁移的成败取决于三个顺序——外键禁用顺序（先关后开）、表操作顺序（先建后删，先子后父）、约束重建顺序（先索引后外键）。在 Room 的 Migration 中保持这三个顺序，即可安全完成表重命名与字段重命名的复合迁移。