Room自动迁移失败求助：未正确处理实体问题

问题根源 #

Room 2.4+的自动迁移仅支持基础数据类型的列增减、重命名等简单操作，对于需要依赖TypeConverter的复杂类型（比如对象列表List<T>），自动迁移无法识别并生成对应的SQL逻辑，导致实际表中未创建目标列，触发迁移失败。

解决步骤 #

1. 手动编写Migration类 #

自动迁移搞不定复杂类型，必须手动实现迁移逻辑：

• 先升级数据库版本号（比如从version = 1改为version = 2）
• 创建Migration实例，在migrate()方法中执行ALTER TABLE语句添加列，列类型要和TypeConverter转换后的SQL类型匹配（比如列表转JSON字符串对应TEXT类型）
• 示例代码：

  val MIGRATION_1_2 = object : Migration(1, 2) {
      override fun migrate(database: SupportSQLiteDatabase) {
          // 假设实体类名为EntityName，新增列名为object_list，类型为TEXT
          database.execSQL("ALTER TABLE EntityName ADD COLUMN object_list TEXT")
      }
  }
  

• 在RoomDatabase的@Database注解中注册该Migration：

  @Database(
      entities = [EntityName::class],
      version = 2,
      // 如果之前有其他自动迁移可以保留，但优先使用手动Migration
      autoMigrations = [AutoMigration(from = 1, to = 2)],
      exportSchema = true
  )
  abstract class AppDatabase : RoomDatabase() {
      // DAO定义
  }
  

2. 确保TypeConverter配置正确 #

新增的对象列表字段必须绑定对应的TypeConverter，否则Room无法处理该列的序列化/反序列化：

• 编写TypeConverter类：

  class ListConverters {
      @TypeConverter
      fun fromObjectList(list: List<YourObject>): String {
          return Gson().toJson(list)
      }
  
      @TypeConverter
      fun toObjectList(json: String): List<YourObject> {
          return Gson().fromJson(json, object : TypeToken<List<YourObject>>() {}.type)
      }
  }
  

• 在实体类的目标字段上添加注解，或者在Database类上全局配置：

  // 实体类级别
  @Entity
  @TypeConverters(ListConverters::class)
  data class EntityName(
      @PrimaryKey val id: Int,
      val object_list: List<YourObject> // 新增的列表字段
  )
  
  // 或者Database全局级别
  @Database(
      entities = [EntityName::class],
      version = 2,
      typeConverters = [ListConverters::class],
      exportSchema = true
  )
  abstract class AppDatabase : RoomDatabase()
  

3. 验证迁移逻辑 #

• 开启exportSchema = true，Room会在app/schemas目录下生成数据库schema文件，对比新旧版本的schema，确认新增列的定义和手动Migration的SQL一致
• 测试时可以临时使用fallbackToDestructiveMigration()（仅用于测试，会清空数据），先确认实体和数据库的映射关系正常，再移除该配置并启用手动迁移

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