Room 中的数据库迁移

2022/05/27 17:54
阅读数 115

在以往的数据库升级中,每当数据库 schema 发生变化时,开发者都必须实现 Migration 类,并将实际变化告知 Room,需要开发者编写和执行复杂的 SQL 查询。不过从2.4.0-alpha01 版本开始,Room 库里新加入了自动迁移的功能,这让数据库迁移的实现变得更简单。

现在,使用自动迁移功能,您就可以指定从哪个版本迁移到哪个版本了。Room 可以针对不是很复杂的情况自动生成迁移程序,例如添加或删除列、创建新的数据库表。但是在模棱两可的场景下,Room 则需要一些帮助。开发者可以提供具体的规范——比如重命名或删除列/数据库表——基于此,Room 将为您生成并运行迁移动作。接下来让我们一起看一些例子,以及具体的运行表现吧!

1,在自动迁移中加入自动元素

举例来说,我们需要在数据库中的一个表中新添加一列,并将数据库从版本 1 升级到版本 2。那么我们就需要更新 @Database 注解为其递增版本号,并添加从版本 1 到 2 的自动迁移,代码如下。

/* Copyright 2020 Google LLC.  
   SPDX-License-Identifier: Apache-2.0 */

@Database(
-   version = 1,
+   version = 2,
    entities = [ Doggos.class ],
+   autoMigrations = [
+         AutoMigration (from = 1, to = 2)
+     ]
  )
abstract class DoggosDatabase : RoomDatabase { }

每当数据库版本再次改变时,您只需更新 autoMigrations 列表,添加一个新的AutoMigration即可。

/* Copyright 2020 Google LLC.  
   SPDX-License-Identifier: Apache-2.0 */

@Database(
-   version = 2,
+   version = 3,
    entities = [ Doggos.class ],
    autoMigrations = [
       AutoMigration (from = 1, to = 2),
+      AutoMigration (from = 2, to = 3)
     ]
  )
abstract class DoggosDatabase : RoomDatabase { }

针对在 @Database schema 中声明的实体,如添加新列或表,更新主键、外键或索引,或更改列的默认值,Room 会自动检测出这些变化,不需要额外介入。

需要注意的是: 从实现层面来说,Room 的自动迁移依赖于所生成的数据库 schema,因此在使用 autoMigrations 时,请确保 @Database 中的 exportSchema 选项为 true。否则将导致错误: Cannot create auto-migrations when export schema is OFF。

2,自动迁移需要帮助时

Room 的自动迁移无法检测到数据库上执行的所有可能的变化,因此有时候它们需要一些帮助。举一个常见的例子,Room 没办法检测到一个数据库表或列是否被重命名或者被删除。在这种情况下,Room 会抛出一个编译错误,并要求您实现 AutoMigrationSpec。此类允许您指定做出更改的类型,实现一个 AutoMigrationSpec 并使用以下一项或多项来注解:

  • @DeleteTable(tableName)
  • @RenameTable(fromTableName, toTableName)
  • @DeleteColumn(tableName, columnName)
  • @RenameColumn(tableName, fromColumnName, toColumnName)

举个例子,假设我们将 Doggos 的数据库表重命名为 GoodDoggos。Room 无法检测到我们是新建了这个表并删除了 Doggos 表,还是重命名了它以及要保留所有的值。那么此时,我们就需要使用RenameTable注解进行标识。

/* Copyright 2020 Google LLC.  
   SPDX-License-Identifier: Apache-2.0 */

@Database(
   version = 2,
   entities = [ GoodDoggos.class ],
   autoMigrations = [
        AutoMigration (
            from = 1, 
            to = 2,
            spec = DoggosDatabase.DoggosAutoMigration::class
       )
    ]
)
abstract class DoggosDatabase : RoomDatabase {   
  @RenameTable(fromTableName = "Doggos", toTableName = "GoodDoggos")
    class DoggosAutoMigration: AutoMigrationSpec {   }
}

3,何时使用迁移功能

针对手动迁移数据库 (manually handle migrations),Room 从 1.0 版本开始就提供了 Migration 类。每当您要更改复杂的数据库 Schema 时,您就得使用这个类。举例来说,假如我们决定将数据库中的一个表拆分成两个不同的表,Room 无法检测到拆分的执行过程,也不能自动检测到需要移动的数据。因此这个时候,您需要实现一个 Migration 类,并通过 addMigrations() 的方法将其添加至 databaseBuilder() 中。

/* Copyright 2020 Google LLC.  
   SPDX-License-Identifier: Apache-2.0 */

val MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(database: SupportSQLiteDatabase) {
        ...
    }
}

Room.databaseBuilder(applicationContext, DoggosDatabase::class.java, "doggos-database")
    .addMigrations(MIGRATION_1_2,)
    .build()

4,组合使用迁移与自动迁移

Room 允许将迁移与自动迁移结合起来使用。比如说,从版本 1 迁移到版本 2 可以通过 Migration来完成,版本 2 迁移到 3 则可以使用自动迁移。如果您在同一个版本上同时定义了 Migration 和自动迁移,那么只有 Migration 会生效。

在底层实现上,自动迁移会构建一个 Migration 类,因此 这篇文章 详细提到的迁移逻辑依然适用。TL;DR: 当数据库被首次访问时,Room 会检查当前的数据库版本是否与 @Database 中定义的版本不同。如是,Room 会寻找出从此到彼的迁移路径,届时会连续地执行迁移操作。

5,测试自动迁移

可以通过 MigrationTestHelper 的测试规则来测试自动迁移,并与使用 Migration 类相同的方式调用 helper.runMigrationsAndValidate()。

参考链接:https://developer.android.google.cn/training/data-storage/room/migrating-db-versions

本文同步分享在 博客“xiangzhihong8”(CSDN)。
如有侵权,请联系 support@oschina.cn 删除。
本文参与“OSC源创计划”,欢迎正在阅读的你也加入,一起分享。

展开阅读全文
加载中
点击引领话题📣 发布并加入讨论🔥
0 评论
0 收藏
0
分享
返回顶部
顶部