Room数据库空库时迁移未执行问题求助

核心原因 #

Room的Migration迁移逻辑仅在数据库已存在且版本号低于目标版本时触发。如果是全新安装的空数据库，Room会直接根据@Database注解中的entities生成建表语句，不会触发任何迁移流程——这就是你看不到迁移日志的根本原因。

解决方案 #

要覆盖空数据库的初始填充需求，需要结合Room的RoomDatabase.Callback来处理首次创建场景，同时保留原有的迁移逻辑：

1. 区分首次创建与迁移场景

重写Callback的onCreate方法，该方法会在数据库首次创建完成后执行，刚好适配空数据库的填充需求：

// 定义数据库回调
val dbCallback = object : RoomDatabase.Callback() {
    override fun onCreate(db: SupportSQLiteDatabase) {
        super.onCreate(db)
        // 在这里执行读取应用私有文件夹并填充数据库的逻辑
        // 注意：耗时操作需切换到后台线程，避免阻塞数据库创建线程
    }
}

// 构建数据库时同时传入迁移逻辑和回调
val appDb = Room.databaseBuilder(context, AppDatabase::class.java, "app_database")
    .addMigrations(MIGRATION_X_Y) // 保留原有的迁移逻辑
    .addCallback(dbCallback)
    .build()

2. 统一复用填充逻辑

如果迁移和首次创建的填充逻辑一致，可以抽成通用方法，分别在迁移和回调中调用：

// 抽离通用的数据库填充逻辑
private fun populateDatabase(db: SupportSQLiteDatabase) {
    // 读取私有文件夹、插入数据的通用代码
}

// 原有的迁移逻辑
val MIGRATION_X_Y = object : Migration(X, Y) {
    override fun migrate(db: SupportSQLiteDatabase) {
        populateDatabase(db)
        // 其他迁移操作（如修改表结构、新增表）
    }
}

// 处理首次创建的回调
val dbCallback = object : RoomDatabase.Callback() {
    override fun onCreate(db: SupportSQLiteDatabase) {
        super.onCreate(db)
        populateDatabase(db)
    }
}

3. 关键注意事项

• onCreate在数据库创建的线程执行，耗时操作必须用线程池或协程切换到后台，避免ANR。
• 不要混淆onCreate和onOpen：onOpen每次打开数据库都会触发，适合做状态检查，而初始数据填充用onCreate更稳妥，避免重复插入。
• 如果后续升级数据库版本，首次安装的新用户仍会走onCreate逻辑，无需修改迁移代码。

内容的提问来源于stack exchange，提问作者Davidbrcz