【Jetpack】使用 Room 中的 Migration 升级数据库 ( 修改 Entity 实体类 | 创建 Migration 迁移类 | 修改数据库版本 )

在进行 Android 开发时，我们经常会使用到本地数据库来存储数据。在应用程序的发展过程中，很可能需要修改我们的实体类，这意味着我们需要升级数据库以反映这些更改。在使用 Room 数据库时，我们可以使用 Migration 来实现数据库升级。

当我们需要修改 实体类(Eentity) 的数据模型时，如何创建 Migration 迁移类，以及如何修改数据库版本来反映这些更改。

修改 Entity 实体类

在使用 Room 数据库时，我们定义的实体类用于映射表的结构。当我们需要修改实体类的数据模型时，我们需要创建 Migration 迁移类来实现数据库升级，以便合并这些更改。

例如，假设我们有以下 User 实体类：

@Entity(tableName = "user")
data class User(
    @PrimaryKey(autoGenerate = true) val id: Int,
    val name: String,
    val age: Int
)

现在，我们需要向 User 实体类中添加一些属性，如下所示：

@Entity(tableName = "user")
data class User(
    @PrimaryKey(autoGenerate = true) val id: Int,
    val name: String,
    val age: Int,
    val email: String,
    val phone: String
)

由于我们已经在应用程序中使用了 User 实体类，因此我们不能简单地修改它，而是需要创建一个 Migration 迁移类以实现数据库升级。

创建 Migration 迁移类

为了使数据库升级流程更加灵活和可靠，我们使用 Room 数据库提供的 Migration 类来定义数据库升级。我们可以使用 Migration 类来追踪数据库结构的更改，并对数据库的新版本执行迁移操作。从 Room 2.2.0 版本起，我们还可以将迁移代码嵌入在 @Database 注解中的 fallbackToDestructiveMigration 属性中，但是这种方法将从底层重新创建数据库，所有数据都将丢失，因此我们仅在遇到无法执行迁移操作的情况下使用这种方法。

为了创建 Migration 迁移类，我们需要扩展 Room 的 Migration 类。在创建 Migration 迁移类时，我们需要指定当前版本号和升级后的版本号，并实现 migrate 函数，该函数用于指定数据库升级时要执行的操作。在本例中，我们需要为 User 实体类添加 email 和 phone 属性，因此我们将在迁移类中添加这些属性。

示例代码如下：

val MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(database: SupportSQLiteDatabase) {
        // 添加 email 属性
        database.execSQL("ALTER TABLE user ADD COLUMN email TEXT")
        
        // 添加 phone 属性
        database.execSQL("ALTER TABLE user ADD COLUMN phone TEXT")
    }
}

在这个示例中，我们创建了一个名为 MIGRATION_1_2 的迁移类，它将当前数据库版本号 1 升级到版本号 2。在 migrate 函数中，我们使用 SQL 命令向 user 表格添加 email 和 phone 属性。

修改数据库版本

完成 Migration 迁移类后，我们需要将其应用于实际的 Room 数据库，以便在数据库升级时使用。

要将 Migration 迁移类应用于 Room 数据库中，我们只需将其添加到 Room 数据库构建器中即可。在创建 Room 数据库时，我们可以调用 addMigrations 函数，并将 Migration 迁移类实例作为参数传递。示例代码如下：

@Database(entities = [User::class], version = 2)
abstract class MyAppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao

    companion object {
        @Volatile
        private var INSTANCE: MyAppDatabase? = null

        fun getDatabase(context: Context): MyAppDatabase {
            val tempInstance = INSTANCE
            if (tempInstance != null) {
                return tempInstance
            }
            synchronized(this) {
                val instance = Room.databaseBuilder(
                    context.applicationContext,
                    MyAppDatabase::class.java,
                    "my_database"
                )
                    .addMigrations(MIGRATION_1_2)
                    .build()
                INSTANCE = instance
                return instance
            }
        }
    }
}

在这个示例中，我们将 Migration 迁移类 MIGRATION_1_2 添加到 MyAppDatabase 构建器中，以使其在数据库升级时起作用。我们将数据库版本号设置为 2，这意味着我们需要执行迁移操作才能将现有的数据库升级到此版本。

代码示例

下面是使用 Migration 来修改 User 实体类的完整示例代码：

@Entity(tableName = "user")
data class User(
    @PrimaryKey(autoGenerate = true) val id: Int,
    val name: String,
    val age: Int,
    val email: String,
    val phone: String
)

val MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(database: SupportSQLiteDatabase) {
        // 添加 email 属性
        database.execSQL("ALTER TABLE user ADD COLUMN email TEXT")
        
        // 添加 phone 属性
        database.execSQL("ALTER TABLE user ADD COLUMN phone TEXT")
    }
}

@Database(entities = [User::class], version = 2)
abstract class MyAppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao

    companion object {
        @Volatile
        private var INSTANCE: MyAppDatabase? = null

        fun getDatabase(context: Context): MyAppDatabase {
            val tempInstance = INSTANCE
            if (tempInstance != null) {
                return tempInstance
            }
            synchronized(this) {
                val instance = Room.databaseBuilder(
                    context.applicationContext,
                    MyAppDatabase::class.java,
                    "my_database"
                )
                    .addMigrations(MIGRATION_1_2)
                    .build()
                INSTANCE = instance
                return instance
            }
        }
    }
}

在这个示例中，我们定义了一个 User 实体类，并创建了 Migration 迁移类 MIGRATION_1_2，用于将数据库版本从 1 升级到 2。我们修改了 User 实体类的数据模型，将其添加了 email 和 phone 属性。在创建 MyAppDatabase 数据库时，我们使用 Room 数据库的 addMigrations 函数将 Migration 迁移类添加到数据库构建器中，以便在升级数据库时起作用。

结论

在使用 Room 数据库时，我们经常需要升级数据库以反映实体类的更改。本文介绍了使用 Migration 来创建迁移类，使我们能够在数据库升级时执行必要的操作，如向表格添加新列或删除旧列等。在使用 Room 数据库时，请务必谨慎处理数据库版本和 Migration 迁移类，以避免数据丢失和应用程序崩溃等问题的发生。通过理解本文中的示例代码，您现在应该具备足够的知识来创建和应用 Migration 迁移类，以实现数据库的升级操作。