Room数据库现状盘点：整理现有实体、DAO、数据库版本及迁移历史

迁移的第一步不是写代码，而是对当前Room数据库做完整审计。本章从实体、DAO、版本号和迁移历史四个维度，建立一份可执行的现状清单，为后续迁移提供精确的输入数据。

2.1 现有实体（Entity）清单

以典型笔记类应用为例，现有Room数据库包含三个实体：User、Note、Tag，并存在一对多与多对多关联。

2.2 DAO接口分析

当前DAO层定义了核心数据操作模式。所有操作均通过以下三个DAO暴露：

• UserDao – 用户查询、注册、更新个人资料、统计笔记数量。
• NoteDao – 笔记的CRUD、按用户分页查询、全文搜索（基于 LIKE）。
• TagDao – 标签管理、按笔记ID查询标签、批量添加/删除关联。

关键DAO方法签名示例（NoteDao）：

@Dao
interface NoteDao {
    @Query("SELECT * FROM notes WHERE userId = :userId ORDER BY updatedAt DESC")
    fun getNotesByUser(userId: Long): Flow<List<Note>>

    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insertNote(note: Note): Long

    @Update
    suspend fun updateNote(note: Note)

    @Delete
    suspend fun deleteNote(note: Note)

    @Query("SELECT * FROM notes WHERE title LIKE '%' || :query || '%' OR content LIKE '%' || :query || '%'")
    fun searchNotes(query: String): Flow<List<Note>>
}

2.3 数据库版本号与迁移历史

当前数据库版本为 5，Room.databaseBuilder 的版本声明如下：

@Database(entities = [User::class, Note::class, Tag::class, NoteTagCrossRef::class],
          version = 5,
          exportSchema = true)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
    abstract fun noteDao(): NoteDao
    abstract fun tagDao(): TagDao
}

迁移历史共经历4次版本升级（1→5）：

对应的 Migration 对象示例（版本4→5）：

val MIGRATION_4_5 = object : Migration(4, 5) {
    override fun migrate(database: SupportSQLiteDatabase) {
        database.execSQL(
            "CREATE VIRTUAL TABLE notes_fts USING fts4(content="notes", title, content)"
        )
        database.execSQL(
            "INSERT INTO notes_fts(docid, title, content) " +
            "SELECT noteId, title, content FROM notes"
        )
        // 创建触发器保持同步
        database.execSQL(
            "CREATE TRIGGER IF NOT EXISTS notes_ai AFTER INSERT ON notes " +
            "BEGIN INSERT INTO notes_fts(docid, title, content) " +
            "VALUES (new.noteId, new.title, new.content); END"
        )
        // ... 省略 UPDATE / DELETE 触发器
    }
}

2.4 数据库现状结构图

2.5 迁移准备清单

基于以上盘点，整理出迁移前必须完成的准备项：

1. 导出当前Schema – 在 build.gradle 中开启 exportSchema = true，获取 AppDatabase_Impl.java 中的SQL创建语句，作为旧数据结构的唯一权威参照。
2. 备份生产数据库 – 对现有SQLite文件（app_database.db）做完整快照，存储在安全目录或云端。
3. 编写数据读取器 – 在DataStore迁移前，先用Room的 @Query 将所有实体数据全量读入内存（分批读取防OOM），并转为扁平化的DataStore模型。
4. 确认迁移策略 – 如果选择 fallbackToDestructiveMigration()，必须确保用户数据已有备份；建议使用自定义 Migration 对版本5→6（虚拟过渡版本）做数据导出。
5. 标记关联字段 – 对于 NoteTagCrossRef 这类关联表，决定在DataStore中是拆成独立列表还是嵌入到Note对象的 tagIds: List<Long> 字段中。推荐后者以减少多数据源同步问题。