1. 数据库版本概念与迁移场景

1.1 版本号理解

Room 使用 整型版本号 标识数据库 Schema。每次在 @Database 注解中声明的 version 值改变，Room 自动触发迁移流程。版本号必须严格递增，低版本代表旧 Schema，高版本代表新 Schema。

@Database(
    entities = [User::class, Task::class],
    version = 3,
    exportSchema = true
)
abstract class AppDatabase : RoomDatabase() { … }

1.2 迁移触发条件

当 APP 启动时，Room 检测到 当前数据库版本 < 目标版本 且存在合法 Migration 对象时，自动执行迁移。若不存在对应 Migration，则 抛出 IllegalStateException 并强制用户卸载重装（默认 FallbackToDestructiveMigration 除外）。

• 版本不匹配：设备上数据库 version ≠ 代码中 version。
• Migration 缺失：未注册从旧版到新版的 Migration 实例。
• 降级禁止：Room 不支持降级，必须卸载重装或使用 destructive 回退。

1.3 常见业务场景

1.4 迁移流程全景图

1.5 代码与 API 要点

在 Room 中注册迁移的典型做法如下：

val MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(database: SupportSQLiteDatabase) {
        database.execSQL("ALTER TABLE User ADD COLUMN age INTEGER NOT NULL DEFAULT 0")
    }
}

val MIGRATION_2_3 = object : Migration(2, 3) {
    override fun migrate(database: SupportSQLiteDatabase) {
        database.execSQL("CREATE TABLE Task (id INTEGER PRIMARY KEY, name TEXT)")
    }
}

Room.databaseBuilder(context, AppDatabase::class.java, "mydb")
    .addMigrations(MIGRATION_1_2, MIGRATION_2_3)
    .build()

1.6 调试与验证

开启 Room 调试日志可实时查看迁移 SQL：

adb shell setprop log.tag.Room VERBOSE
# 或使用 RoomDatabase.Builder 的 enableMultiInstanceInvalidation() 配合日志

建议在单元测试中编写 MigrationTestHelper 验证迁移正确性：

@RunWith(AndroidJUnit4::class)
class MigrationTest {
    private val helper = MigrationTestHelper(
        InstrumentationRegistry.getInstrumentation(),
        AppDatabase::class.java.canonicalName,
        FrameworkSQLiteOpenHelperFactory()
    )

    @Test
    fun migrate1to2() {
        val db = helper.createDatabase("testdb", 1)
        db.execSQL("INSERT INTO User (id, name) VALUES (1, 'test')")
        val migratedDb = helper.runMigrationsAndValidate("testdb", 2, true, MIGRATION_1_2)
        // 校验新列 age 存在且默认为0
    }
}

1.7 常见错误与稳定性优化