Room 中的数据库自动迁移功能

Room 中的数据库自动迁移功能

在不同 Room 之间轻松移动数据库表

2.4.0-alpha01 版本开始,Room 库里新加入了自动迁移的功能,这让数据库迁移的实现变得更简单。以往每当您的数据库 schema 发生变化时,您都必须实现一个 Migration 类,并将实际变化告知 Room,且多数情况下均涉及编写和执行复杂的 SQL 查询。

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

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

举例来说,我们需要在数据库中的一个表中新添加一列,并将数据库从版本 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 列表,添加一个新的:

/* 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

当自动迁移需要帮助时

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

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

举个例子,假设我们将 Doggos 的数据库表重命名为 GoodDoggos。Room 无法检测到我们是新建了这个表并删除了 Doggos 表,还是重命名了它以及要保留所有的值。

/* 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 {   }
}

迁移 vs 自动迁移

何时使用迁移功能

针对手动迁移数据库 (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()

组合使用「迁移」与「自动迁移」

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

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

测试自动迁移

您可以通过 MigrationTestHelper 的测试规则来测试自动迁移,并与使用 Migration 类相同的方式调用 helper.runMigrationsAndValidate()。关于测试迁移的更多信息,欢迎您查看文档: 测试单次迁移

总结

自动迁移功能 (@Database 中的 autoMigration 参数) 可以让您轻松的应对数据库 Schema 变化。虽然 Room 能处理许多基本情况,但对于数据库表/列的删除或重命名来说,您仍需要实现一个 AutoMigrationSpec。针对其他情况,请继续使用 Migrations 来处理。

该功能现仍处于 alpha 状态,欢迎您通过 issue tracker 积极反馈,来帮助我们做得更好。

版权声明

禁止一切形式的转载-禁止商用-禁止衍生 申请授权

脉脉不得语
脉脉不得语
Zhengzhou Website
Android Developer | https://androiddevtools.cn and https://androidweekly.io WebMaster | GDG Zhengzhou Funder & Ex Organizer | http://Toast.show(∞) Podcast Host

你已经成功订阅到 Android 开发技术周报
太棒了!接下来,完成检验以获得全部访问权限 Android 开发技术周报
欢迎回来!你已经成功登录了。
Unable to sign you in. Please try again.
成功!您的帐户已完全激活,您现在可以访问所有内容。
Error! Stripe checkout failed.
Success! Your billing info is updated.
Error! Billing info update failed.