Room 数据库迁移：让本地数据升级更稳

很多 Android 应用都会把使用者设置、缓存、离线内容或业务草稿放在本地数据库里。功能早期，表结构通常很简单；产品迭代几轮后就会遇到新增字段、拆表、合表、索引调整、默认值补齐等问题。

如果这些变化没有迁移方案。使用者一升级 App 就可能遇到崩溃、数据丢失，或者页面展示一堆不符合预期的旧数据。Room 的迁移能力就是为了解决这类问题：既保留 SQLite 的可控性，又让版本升级过程更容易测试和管理。

为什么 Room 需要迁移

Room 会根据 @Database 中的版本号管理数据库结构。当应用安装后设备上会保存某个版本的数据库文件。下一次 App 升级，如果代码里的数据库版本号变大。Room 就需要知道如何把旧结构升级到新结构。

举个简单例子，原来的使用者表只有 id 和 name

@Entity
data class UserEntity(
@PrimaryKey val id: Long,val name: String
)

后来业务需要展示头像。于是新增 avatarUrl 字段：

@Entity
data class UserEntity(
@PrimaryKey val id: Long,val name: String,val avatarUrl: String
)

这时如果只是修改实体类并提高数据库版本，Room 并不知道旧设备上的 user 表应该如何新增列。没有迁移逻辑时常见结果是启动时报错：

A migration from 1 to 2 was required but not found.

这不是 Room 麻烦，而是在提醒你：线上使用者的数据不能靠猜。

最小可用迁移

Room 的迁移通过 Migration 定义，主要是写清楚从旧版本到新版本要执行哪些 SQL。

val MIGRATION_1_2 = object : Migration {
override fun migrate {
db.execSQL(
"ALTER TABLE user ADD COLUMN avatarUrl TEXT NOT NULL DEFAULT ''"
)
}
}

接下来在创建数据库时注册：

val database = Room.databaseBuilder(
context。AppDatabase::class.java,"app.db"
)
.addMigrations
.build

痛点提示：新增非空字段时必须给默认值。因为旧表里已经有历史数据，数据库需要知道这些旧行的 avatarUrl 应该填什么。如果直接新增 TEXT NOT NULL 但不写 DEFAULT。迁移通常会失败，导致线上崩溃。老实说，

迁移不只是加字段

真实项目里迁移经常比新增一列更复杂。常见场景包括的观点是，

• 再看新增表。用 CREATE TABLE 建表，并补充必要索引。
• 至于新增索引，用 Create INDEX) 调整查询性能。
• 说到字段改名。SQLite 对部分结构修改支持有限，通常需要建新表、拷贝数据、删旧表、重命名。
• 字段类型调整的观点是。一样建议通过临时表完成，顺便做数据清洗。
• 再看表拆分。先创建新表，再从旧表中按规则迁移数据。

痛点示例：If you rename a column without proper migration,app will crash on launch for users who already have data.

例如把 User` 表里的昵称字段从 Name` 改成 `Nickname``,更稳的做法是创建新表并拷贝：

val MIGRATION_2_3 = object : Migration {
override fun migrate {
db.execSQL("""
CREATE TABLE user_new (
id INTEGER NOT NULL。nickname TEXT NOT NULL,avatarUrl TEXT NOT NULL DEFAULT '',PRIMARY KEY
)
""".trimIndent)
db.execSQL("""
INSERT INTO user_new
SELECT id,name,avatarUrl FROM user
""".trimIndent)
db.execSQL
db.execSQL
}
}

This approach looks longer than a simple ALTER but guarantees that new schema is exactly what you defined and that data mapping is explicit.

自动迁移适合什么场景？

The AutoMigration feature can handle straightforward structural changes such as adding tables or columns.

@Database(
entities =,version = 4,autoMigrations =
)
abstract class AppDatabase : RoomDatabase

Pain point:If you rely on AutoMigration for a column rename or a non‑trivial data transformation。Room will silently skip it and your app may end up with corrupted or missing data.

• Simplify addition of tables/columns → AutoMigration works.
• If business logic changes → write manual migration.
• If data is critical → manual migration + thorough testing.

fallbackToDestructiveMigration 要慎用

Room.databaseBuilder
.fallbackToDestructiveMigration
.build

This method instantly drops existing DB when a migration path is missing. It’s fine for demo apps or pure‑cache databases but **dangerous** for any business‑critical data.

• If data can be re‑fetched from server → destructive migration might be acceptable.
• If data includes drafts,offline content or local state → NEVER use destructive migration.
• If you’re unsure → treat it as non‑recoverable and avoid it.

Pain point:The “quick fix” of using destructive migration often hides a deeper problem – you’re losing users’ unsynced work without even realizing it.

迁移测试怎么写？

@RunWith
class AppDatabaseMigrationTest {
再看@get，Rule
val helper = MigrationTestHelper(
InstrumentationRegistry.getInstrumentation,AppDatabase::class.java.canonicalName,FrameworkSQLiteOpenHelperFactory
)
@Test
fun migrateFrom1To2 {
// Create old version database
helper.createDatabase.apply {
execSQL VALUES ")
close
}
// Run migrations & validate schema
val db = helper.runMigrationsAndValidate(
"test.db",2,true。MIGRATION_1_2
)
// Verify data after migration
val cursor = db.query
assertThat).isTrue
assertThat).isEqualTo
cursor.close
}
}

• This test confirms that table structure matches what Room expects after migration.
• The test also ensures that historic rows receive correct default values .
• You must also test *cross‑version* paths because users may skip intermediate releases .

项目落地建议

• Pain point:You often see migrations scattered across multiple files making m hard to audit.

object DatabaseMigrations {
val MIGRATION_1_2 = object : Migration {…}
val MIGRATION_2_3 = object : Migration { …}
// Add new migrations here only – never modify existing ones!val ALL = arrayOf(
MIGRATION_1_2,MIGRATION_2_3
)
}

Create DB with a single registration point:

Room.databaseBuilder
.addMigrations
.build

Avoid rushing version bumps. Before touching an entity or DAO ask yourself three questions:

• ① This structural change affect existing users?
• ② Do old rows need default values / cleaning / moving?说起来，
• ③ Have I added a migration test covering upgrade from every older version?

If any answer is “not sure”,pause version bump. Fixing a broken migration after release is far more expensive than delaying a feature flag.

常见踩坑

只改实体类。不写迁移

This is most typical issue. The entity reflects new schema while devices still hold an old one – leading to “migration required but not found” crashes at launch.

新增非空字段忘记默认值

If you add a NOT NULL column without DEFAULT SQLite cannot populate existing rows and will abort upgrade.

测试只覆盖全新安装

A fresh install only proves that creating a brand‑new DB works;it does **not** guarantee that upgrading an existing DB works. Always start tests from an older schema file.

直接修改历史迁移

Migrations that have already shipped must never be changed. Users who already applied m would end up with divergent schemas. Instead add a new subsequent migration to fix any mistake.

过度依赖破坏性迁移

Caching layers can tolerate destructive migrations;business layers cannot. Treat destructive migrations as “last resort” and document *** y are safe in each case.

小结

The key to stable Room migrations isn’t memorizing APIs – it’s adopting an attitude: ** local database is a contract with every installed user**. You must protect both new installs and upgrades of existing users.

• A clear version map .
• A deterministic SQL script for each step .
• A complete migration chain covering all possible upgrade paths.
• A suite of MigrationTestHelper tests that run on CI.

---