從 SQLite 遷移至 Room

與直接使用 SQLite API 相比，Room 永久性程式庫具備許多優點：

• SQL 查詢的編譯時間驗證
• 透過便利的註解，盡量減少樣板程式碼重複且容易出錯的情況
• 簡化的資料庫遷移路徑

如果您的應用程式並非使用 SQLite 的 Room 實作項目，請參閱本頁的說明，瞭解如何遷移至 Room。如果 Room 是您在應用程式中使用的第一個 SQLite 實作項目，請參閱「使用 Room 將資料儲存在本機資料庫」一文，瞭解基本用法。

遷移步驟

如要將 SQLite 實作項目遷移至 Room，請執行下列步驟。如果您的 SQLite 實作項目使用大型資料庫或複雜的查詢，建議您逐步遷移至 Room。如要進一步瞭解逐步遷移策略，請參閱「逐步遷移作業」一節的相關說明。

更新依附元件

如要在應用程式中使用 Room，您必須在應用程式的 build.gradle 檔案中加入適用的依附元件。如要進一步瞭解 Room 依附元件，請參閱「設定」。

將模型類別更新為資料實體

Room 會使用資料實體來代表資料庫中的資料表。每個實體類別代表一個資料表，並提供代表該資料表內所有資料欄的屬性。請按照下列步驟，將現有模型類別更新為 Room 實體：

1. 使用 @Entity 為類別宣告加上註解，以表示此為 Room 實體。您可以視需要使用 tableName 屬性來表示產生的資料表應使用與類別不同的名稱。
2. 使用 @PrimaryKey 為主鍵屬性加上註解。
3. 如果產生的資料表中有任何資料欄的名稱應與對應屬性的名稱不同，請使用 @ColumnInfo 為屬性加上註解，並將 name 屬性設為正確的資料欄名稱。
4. 如果類別含有您不想保留在資料庫中的屬性，請使用 @Ignore 為這些屬性加上註解，以表示 Room 不應在對應資料表中為這些屬性建立資料欄。
5. 如果類別有多個建構函式，請使用 @Ignore 將所有其他建構函式加上註解，指出 Room 應使用哪一個建構函式。

@Entity(tableName = "users")
data class User(
    @PrimaryKey @ColumnInfo(name = "userid") val id: String,
    @ColumnInfo(name = "username") val userName: String?,
    @ColumnInfo(name = "last_update") val date: Date?,
)
SqliteRoomMigrationSnippets.kt

建立 DAO

Room 會使用資料存取物件 (DAO) 定義存取資料庫的函式。請按照「使用 Room DAO 存取資料」一文中的操作說明，將現有查詢函式替換成 DAO。

建立資料庫類別

Room 的實作項目是使用資料庫類別來管理資料庫的執行個體。您的資料庫類別應擴充 RoomDatabase，並參照您所定義的所有實體和 DAO。

@Database(entities = [User::class], version = 2)
@ColumnTypeConverters(DateConverter::class)
abstract class UsersDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
}
SqliteRoomMigrationSnippets.kt

定義遷移路徑

由於資料庫版本編號有異動，您必須定義 Migration 物件來保留現有資料庫資料。如果資料庫結構定義沒有變更，這項遷移作業可以是空白的。

val MIGRATION_1_2 = object : Migration(1, 2) {
    override suspend fun migrate(connection: SQLiteConnection) {
        // Empty implementation, because the schema isn't changing.
    }
}
SqliteRoomMigrationSnippets.kt

如要進一步瞭解 Room 中的資料庫遷移路徑，請參閱「遷移資料庫」一文。

更新資料庫的例項建立作業

定義資料庫類別和遷移路徑後，您可以使用 Room.databaseBuilder 建立套用遷移路徑的資料庫執行個體：

val db =
    Room.databaseBuilder<UsersDatabase>(applicationContext, "database-name")
        .addMigrations(MIGRATION_1_2)
        .build()
SqliteRoomMigrationSnippets.kt

測試實作成果

請務必測試新的 Room 實作成果：

• 請按照「測試遷移作業」一文中的操作說明，測試資料庫遷移作業。
• 請按照「測試資料庫」一文中的操作說明，測試 DAO 函式。

逐步遷移作業

如果應用程式使用大型複雜的資料庫，可能無法一次將應用程式全部遷移至 Room。不過，您可以第一步先選擇實作資料實體和 Room 資料庫，稍後再將查詢函式遷移至 DAO。

如要實作漸進式遷移，請使用 androidx.room3:room3-sqlite-wrapper 構件中的 roomDatabase.getSupportWrapper 擴充功能函式，取得 SupportSQLiteDatabase 相容性包裝函式。這個包裝函式可讓您使用 Android SQLite API，對 Room 管理的資料庫執行 Android 樣式的直接 SQL 查詢：

// Get SupportSQLiteDatabase wrapper
val legacyDb = roomDatabase.getSupportWrapper()
legacyDb.execSQL("INSERT INTO users ...")
SqliteRoomMigrationSnippets.kt