当您在应用中添加和更改功能时，需要修改 Room 实体类和底层数据库表以反映这些更改。如果应用更新更改了数据库架构，那么保留设备内置数据库中已有的用户数据就非常重要。
Room 同时支持以自动和手动方式进行的增量迁移。自动迁移适用于大多数基本架构更改，不过对于更复杂的更改，您可能需要手动定义迁移路径。
自动迁移
如需声明两个数据库版本之间的自动迁移，请将 @AutoMigration 注解添加到 @Database 中的 autoMigrations 属性：
Kotlin
// Database class before the version update. @Database( version = 1, entities = [User::class] ) abstract class AppDatabase : RoomDatabase() { ... } // Database class after the version update. @Database( version = 2, entities = [User::class], autoMigrations = [ AutoMigration (from = 1, to = 2) ] ) abstract class AppDatabase : RoomDatabase() { ... }
Java
// Database class before the version update. @Database( version = 1, entities = {User.class} ) public abstract class AppDatabase extends RoomDatabase { ... } // Database class after the version update. @Database( version = 2, entities = {User.class}, autoMigrations = { @AutoMigration (from = 1, to = 2) } ) public abstract class AppDatabase extends RoomDatabase { ... }
自动迁移规范
如果 Room 检测到架构更改不明确，并且无法在没有更多输入的情况下生成迁移计划，则会抛出编译时间错误并要求您实现 AutoMigrationSpec。这往往出现在迁移涉及以下情形之一时：
- 删除或重命名表。
- 删除或重命名列。
您可以使用 AutoMigrationSpec 为 Room 提供正确生成迁移路径所需的额外信息。定义一个在 RoomDatabase 类中实现 AutoMigrationSpec 的静态类，并为其添加以下一项或多项注解：
如需使用 AutoMigrationSpec 实现进行自动迁移，请在相应的 @AutoMigration 注解中设置 spec 属性：
Kotlin
@Database( version = 2, entities = [User::class], autoMigrations = [ AutoMigration ( from = 1, to = 2, spec = AppDatabase.MyAutoMigration::class ) ] ) abstract class AppDatabase : RoomDatabase() { @RenameTable(fromTableName = "User", toTableName = "AppUser") class MyAutoMigration : AutoMigrationSpec ... }
Java
@Database( version = 2, entities = {AppUser.class}, autoMigrations = { @AutoMigration ( from = 1, to = 2, spec = AppDatabase.MyAutoMigration.class ) } ) public abstract class AppDatabase extends RoomDatabase { @RenameTable(fromTableName = "User", toTableName = "AppUser") static class MyAutoMigration implements AutoMigrationSpec { } ... }
如果您的应用在自动化迁移完成后需要执行更多工作，您可以实现 onPostMigrate()。如果您在 AutoMigrationSpec 中实现此方法，Room 将在自动迁移完成后调用该方法。
手动迁移
如果迁移涉及复杂的架构更改，Room 可能无法自动生成适当的迁移路径。例如，如果您决定将表中的数据拆分到两个表中，Room 无法确定应如何执行此拆分。在这类情况下，您必须通过实现 Migration 类来手动定义迁移路径。
Migration 类会通过替换 Migration.migrate() 方法明确定义 startVersion 和 endVersion 之间的迁移路径。使用 addMigrations() 方法将您的 Migration 类添加到数据库构建器：
Kotlin
val MIGRATION_1_2 = object : Migration(1, 2) { override fun migrate(database: SupportSQLiteDatabase) { database.execSQL("CREATE TABLE `Fruit` (`id` INTEGER, `name` TEXT, " + "PRIMARY KEY(`id`))") } } val MIGRATION_2_3 = object : Migration(2, 3) { override fun migrate(database: SupportSQLiteDatabase) { database.execSQL("ALTER TABLE Book ADD COLUMN pub_year INTEGER") } } Room.databaseBuilder(applicationContext, MyDb::class.java, "database-name") .addMigrations(MIGRATION_1_2, MIGRATION_2_3).build()
Java
static final Migration MIGRATION_1_2 = new Migration(1, 2) { @Override public void migrate(SupportSQLiteDatabase database) { database.execSQL("CREATE TABLE `Fruit` (`id` INTEGER, " + "`name` TEXT, PRIMARY KEY(`id`))"); } }; static final Migration MIGRATION_2_3 = new Migration(2, 3) { @Override public void migrate(SupportSQLiteDatabase database) { database.execSQL("ALTER TABLE Book " + " ADD COLUMN pub_year INTEGER"); } }; Room.databaseBuilder(getApplicationContext(), MyDb.class, "database-name") .addMigrations(MIGRATION_1_2, MIGRATION_2_3).build();
定义迁移路径后，您可以对某些版本使用自动迁移，而对另一些版本使用手动迁移。如果您为同一版本同时定义了自动迁移和手动迁移，则 Room 会使用手动迁移。
测试迁移
迁移通常十分复杂，迁移定义错误可能会导致应用崩溃。为了保持应用的稳定性，请测试迁移。Room 提供了一个 room-testing Maven 工件，以协助完成自动和手动迁移的测试过程。为使此工件正常工作，您必须先导出数据库的架构。
导出架构
Room 可以在编译时将数据库的架构信息导出为 JSON 文件。导出的 JSON 文件代表数据库的架构历史记录。将这些文件存储在版本控制系统中，以便 Room 出于测试目的创建较旧版本的数据库，并支持自动生成迁移路径。
使用 Room Gradle 插件设置架构位置
如果您使用的是 Room 2.6.0 或更高版本，可以应用 Room Gradle 插件，并使用 room 扩展指定架构目录。
Groovy
plugins { id 'androidx.room' } room { schemaDirectory "$projectDir/schemas" } Kotlin
plugins { id("androidx.room") } room { schemaDirectory("$projectDir/schemas") } 如果您的数据库架构因变体、特性或 build 类型而异，您必须多次使用 schemaDirectory() 配置来指定不同的位置，每次使用时都将 variantMatchName 作为第一个实参。每项配置都可以通过与变体名称进行简单比较来匹配一个或多个变体。
请确保这些示例详尽无遗，涵盖所有变体。您还可以添加不含 variantMatchName 的 schemaDirectory()，以处理与任何其他配置都不匹配的变体。例如，在具有两个 build 方案（demo 和 full）和两个 build 类型（debug 和 release）的应用中，以下配置有效：
Groovy
room { // Applies to 'demoDebug' only schemaDirectory "demoDebug", "$projectDir/schemas/demoDebug" // Applies to 'demoDebug' and 'demoRelease' schemaDirectory "demo", "$projectDir/schemas/demo" // Applies to 'demoDebug' and 'fullDebug' schemaDirectory "debug", "$projectDir/schemas/debug" // Applies to variants that aren't matched by other configurations. schemaDirectory "$projectDir/schemas" } Kotlin
room { // Applies to 'demoDebug' only schemaDirectory("demoDebug", "$projectDir/schemas/demoDebug") // Applies to 'demoDebug' and 'demoRelease' schemaDirectory("demo", "$projectDir/schemas/demo") // Applies to 'demoDebug' and 'fullDebug' schemaDirectory("debug", "$projectDir/schemas/debug") // Applies to variants that aren't matched by other configurations. schemaDirectory("$projectDir/schemas") } 使用注解处理器选项设置架构位置
如果您使用的是 Room 2.5.2 或更低版本，或者您未使用 Room Gradle 插件，请使用 room.schemaLocation 注解处理器选项设置架构位置。
此目录中的文件用作某些 Gradle 任务的输入和输出。 为了确保增量 build 和缓存 build 的正确性和性能，您必须使用 Gradle 的 CommandLineArgumentProvider 来告知 Gradle 此目录。
首先，将下面的 RoomSchemaArgProvider 类复制到模块的 Gradle build 文件中。示例类中的 asArguments() 方法会将 room.schemaLocation=${schemaDir.path} 传递给 KSP。如果您使用的是 KAPT 和 javac，请将此值更改为 -Aroom.schemaLocation=${schemaDir.path}。
Groovy
class RoomSchemaArgProvider implements CommandLineArgumentProvider { @InputDirectory @PathSensitive(PathSensitivity.RELATIVE) File schemaDir RoomSchemaArgProvider(File schemaDir) { this.schemaDir = schemaDir } @Override Iterable<String> asArguments() { // Note: If you're using KAPT and javac, change the line below to // return ["-Aroom.schemaLocation=${schemaDir.path}".toString()]. return ["room.schemaLocation=${schemaDir.path}".toString()] } } Kotlin
class RoomSchemaArgProvider( @get:InputDirectory @get:PathSensitive(PathSensitivity.RELATIVE) val schemaDir: File ) : CommandLineArgumentProvider { override fun asArguments(): Iterable<String> { // Note: If you're using KAPT and javac, change the line below to // return listOf("-Aroom.schemaLocation=${schemaDir.path}"). return listOf("room.schemaLocation=${schemaDir.path}") } } 接下来，配置编译选项来使用 RoomSchemaArgProvider，并传入指定的架构目录：
Groovy
// For KSP, configure using KSP extension: ksp { arg(new RoomSchemaArgProvider(new File(projectDir, "schemas"))) } // For javac or KAPT, configure using android DSL: android { ... defaultConfig { javaCompileOptions { annotationProcessorOptions { compilerArgumentProviders( new RoomSchemaArgProvider(new File(projectDir, "schemas")) ) } } } } Kotlin
// For KSP, configure using KSP extension: ksp { arg(RoomSchemaArgProvider(File(projectDir, "schemas"))) } // For javac or KAPT, configure using android DSL: android { ... defaultConfig { javaCompileOptions { annotationProcessorOptions { compilerArgumentProviders( RoomSchemaArgProvider(File(projectDir, "schemas")) ) } } } } 测试单次迁移
测试迁移之前，先将 Room 中的 androidx.room:room-testing Maven 工件添加至测试依赖项中，并将所导出架构的位置添加为资源文件夹：
build.gradle
Groovy
android { ... sourceSets { // Adds exported schema location as test app assets. androidTest.assets.srcDirs += files("$projectDir/schemas".toString()) } } dependencies { ... androidTestImplementation "androidx.room:room-testing:2.7.2" }
Kotlin
android { ... sourceSets { // Adds exported schema location as test app assets. getByName("androidTest").assets.srcDir("$projectDir/schemas") } } dependencies { ... testImplementation("androidx.room:room-testing:2.7.2") }
测试软件包提供了可读取导出的架构文件的 MigrationTestHelper 类。该软件包还实现了 JUnit4 TestRule 接口，因此可以管理创建的数据库。
以下示例演示了针对单次迁移的测试：
Kotlin
@RunWith(AndroidJUnit4::class) class MigrationTest { private val TEST_DB = "migration-test" @get:Rule val helper: MigrationTestHelper = MigrationTestHelper( InstrumentationRegistry.getInstrumentation(), MigrationDb::class.java.canonicalName, FrameworkSQLiteOpenHelperFactory() ) @Test @Throws(IOException::class) fun migrate1To2() { var db = helper.createDatabase(TEST_DB, 1).apply { // Database has schema version 1. Insert some data using SQL queries. // You can't use DAO classes because they expect the latest schema. execSQL(...) // Prepare for the next version. close() } // Re-open the database with version 2 and provide // MIGRATION_1_2 as the migration process. db = helper.runMigrationsAndValidate(TEST_DB, 2, true, MIGRATION_1_2) // MigrationTestHelper automatically verifies the schema changes, // but you need to validate that the data was migrated properly. } }
Java
@RunWith(AndroidJUnit4.class) public class MigrationTest { private static final String TEST_DB = "migration-test"; @Rule public MigrationTestHelper helper; public MigrationTest() { helper = new MigrationTestHelper(InstrumentationRegistry.getInstrumentation(), MigrationDb.class.getCanonicalName(), new FrameworkSQLiteOpenHelperFactory()); } @Test public void migrate1To2() throws IOException { SupportSQLiteDatabase db = helper.createDatabase(TEST_DB, 1); // Database has schema version 1. Insert some data using SQL queries. // You can't use DAO classes because they expect the latest schema. db.execSQL(...); // Prepare for the next version. db.close(); // Re-open the database with version 2 and provide // MIGRATION_1_2 as the migration process. db = helper.runMigrationsAndValidate(TEST_DB, 2, true, MIGRATION_1_2); // MigrationTestHelper automatically verifies the schema changes, // but you need to validate that the data was migrated properly. } }
测试所有迁移
虽然可以测试单次增量迁移，但建议您添加一个测试，涵盖为应用的数据库定义的所有迁移。这有助于确保最近创建的数据库实例与遵循定义的迁移路径的旧实例之间不存在差异。
以下示例演示了针对所有定义的迁移的测试：
Kotlin
@RunWith(AndroidJUnit4::class) class MigrationTest { private val TEST_DB = "migration-test" // Array of all migrations. private val ALL_MIGRATIONS = arrayOf( MIGRATION_1_2, MIGRATION_2_3, MIGRATION_3_4) @get:Rule val helper: MigrationTestHelper = MigrationTestHelper( InstrumentationRegistry.getInstrumentation(), AppDatabase::class.java.canonicalName, FrameworkSQLiteOpenHelperFactory() ) @Test @Throws(IOException::class) fun migrateAll() { // Create earliest version of the database. helper.createDatabase(TEST_DB, 1).apply { close() } // Open latest version of the database. Room validates the schema // once all migrations execute. Room.databaseBuilder( InstrumentationRegistry.getInstrumentation().targetContext, AppDatabase::class.java, TEST_DB ).addMigrations(*ALL_MIGRATIONS).build().apply { openHelper.writableDatabase.close() } } }
Java
@RunWith(AndroidJUnit4.class) public class MigrationTest { private static final String TEST_DB = "migration-test"; @Rule public MigrationTestHelper helper; public MigrationTest() { helper = new MigrationTestHelper(InstrumentationRegistry.getInstrumentation(), AppDatabase.class.getCanonicalName(), new FrameworkSQLiteOpenHelperFactory()); } @Test public void migrateAll() throws IOException { // Create earliest version of the database. SupportSQLiteDatabase db = helper.createDatabase(TEST_DB, 1); db.close(); // Open latest version of the database. Room validates the schema // once all migrations execute. AppDatabase appDb = Room.databaseBuilder( InstrumentationRegistry.getInstrumentation().getTargetContext(), AppDatabase.class, TEST_DB) .addMigrations(ALL_MIGRATIONS).build(); appDb.getOpenHelper().getWritableDatabase(); appDb.close(); } // Array of all migrations. private static final Migration[] ALL_MIGRATIONS = new Migration[]{ MIGRATION_1_2, MIGRATION_2_3, MIGRATION_3_4}; }
妥善处理缺失的迁移路径
如果 Room 无法找到将设备上的一个现有数据库升级到当前版本的迁移路径，就会发生 IllegalStateException。在迁移路径缺失的情况下，如果丢失现有数据可以接受，请在创建数据库时调用 fallbackToDestructiveMigration() 构建器方法：
Kotlin
Room.databaseBuilder(applicationContext, MyDb::class.java, "database-name") .fallbackToDestructiveMigration() .build()
Java
Room.databaseBuilder(getApplicationContext(), MyDb.class, "database-name") .fallbackToDestructiveMigration() .build();
此方法会指示 Room 在需要执行没有定义迁移路径的增量迁移时，破坏性地重新创建应用的数据库表。