Android：从旧版SQLite迁移至Room数据库遇attach相关问题求助

核心问题拆解 #

1. attach时的预写日志错误：本质是Room默认的WAL日志模式与旧数据库的日志模式冲突，或旧库存在隐性未释放的连接
2. detach时的数据库锁定：通常是迁移过程中事务未完成、WAL文件未执行checkpoint导致资源未释放

可行解决方案（无需修改Room日志模式为TRUNCATE） #

方案1：用Room事务包裹全流程+参数化SQL #

将attach、迁移、detach操作放在同一个Room事务中，由Room统一管理连接状态，同时用参数化SQL避免路径特殊字符和注入问题，确保操作原子性。

roomDb.runInTransaction {
    try {
        val legacyDbFile = File(fullLegacyDbPath)
        if (legacyDbFile.exists()) {
            // 参数化方式传入旧库路径，避免SQL注入和路径字符问题
            roomDb.execSQL("ATTACH DATABASE ? AS old_db", arrayOf(fullLegacyDbPath))
            // 执行自定义迁移SQL（根据schema差异调整字段映射）
            roomDb.execSQL("INSERT INTO new_table (col1, col2) SELECT old_col1, old_col2 FROM old_db.old_table")
            // 强制WAL checkpoint，释放旧库资源
            roomDb.execSQL("PRAGMA old_db.wal_checkpoint(FULL)")
            roomDb.execSQL("DETACH DATABASE old_db")
        }
    } catch (e: Exception) {
        // 异常处理：日志记录、回滚等
        e.printStackTrace()
    }
}

方案2：临时调整旧库日志模式（针对旧库用WAL的场景） #

如果旧数据库采用WAL模式，attach到Room的WAL连接时会触发日志模式切换冲突。可以临时将旧库改为DELETE模式，迁移完成后恢复原模式。

// 第一步：临时修改旧库日志模式
val legacyDb = SQLiteDatabase.openDatabase(fullLegacyDbPath, null, SQLiteDatabase.OPEN_READWRITE)
legacyDb.execSQL("PRAGMA journal_mode = DELETE")
legacyDb.close()

// 第二步：执行Room迁移操作
roomDb.runInTransaction {
    try {
        roomDb.execSQL("ATTACH DATABASE ? AS old_db", arrayOf(fullLegacyDbPath))
        roomDb.execSQL("INSERT INTO new_table SELECT * FROM old_db.old_table")
        roomDb.execSQL("PRAGMA old_db.wal_checkpoint(FULL)")
        roomDb.execSQL("DETACH DATABASE old_db")
    } catch (e: Exception) {
        e.printStackTrace()
    } finally {
        // 可选：恢复旧库原日志模式（如果之前是WAL）
        val legacyDbRestore = SQLiteDatabase.openDatabase(fullLegacyDbPath, null, SQLiteDatabase.OPEN_READWRITE)
        legacyDbRestore.execSQL("PRAGMA journal_mode = WAL")
        legacyDbRestore.close()
    }
}

方案3：用Room官方Migration类实现（最规范） #

使用Room提供的Migration类进行迁移，Room会自动管理数据库连接的生命周期和状态，避免手动操作的冲突问题，同时符合Room的设计规范。

// 定义迁移规则（从版本1到版本2，根据实际版本调整）
val MIGRATION_1_2 = object : Migration(1, 2) {
    override fun migrate(database: SupportSQLiteDatabase) {
        val fullLegacyDbPath = context.getDatabasePath("legacy.db").absolutePath
        val legacyDbFile = File(fullLegacyDbPath)
        if (legacyDbFile.exists()) {
            try {
                database.execSQL("ATTACH DATABASE ? AS old_db", arrayOf(fullLegacyDbPath))
                // 按需调整字段映射的迁移SQL
                database.execSQL("INSERT INTO new_entity (id, username) SELECT legacy_id, legacy_name FROM old_db.legacy_user")
                database.execSQL("PRAGMA old_db.wal_checkpoint(FULL)")
                database.execSQL("DETACH DATABASE old_db")
            } catch (e: Exception) {
                e.printStackTrace()
            }
        }
    }
}

// 在RoomDatabase实例中注册迁移
@Database(entities = [NewEntity::class], version = 2)
abstract class AppDatabase : RoomDatabase() {
    abstract fun newDao(): NewDao

    companion object {
        fun getInstance(context: Context): AppDatabase {
            return Room.databaseBuilder(context, AppDatabase::class.java, "new_db")
                .addMigrations(MIGRATION_1_2)
                .build()
        }
    }
}

关键注意事项 #

• 确保旧数据库未被任何其他进程/连接占用，迁移前关闭所有旧库的操作实例
• 迁移前备份旧数据库，避免数据丢失
• 针对大表迁移，可分批次执行INSERT...SELECT（比如加LIMIT/OFFSET），避免单次操作占用过多内存

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