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

文章图片

在不同 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 来处理。
【Room 中的数据库自动迁移功能】该功能现仍处于 alpha 状态，欢迎您通过 issue tracker 积极反馈，来帮助我们做得更好。