Room

Room 持續性程式庫透過 SQLite 提供抽象層,可提升資料庫存取的穩固性,同時充分發揮 SQLite 的效用。
最近更新時間 穩定版 候選版 Beta 版 Alpha 版
2023 年 11 月 29 日 2.6.1 - - -

宣告依附元件

如要新增 Room 的依附元件,您必須將 Google Maven 存放區新增至專案中。詳情請參閱「Google 的 Maven 存放區」一節。

Room 依附元件包括測試 Room 遷移作業Room RxJava

在應用程式或模組的 build.gradle 檔案中,新增您需要的構件依附元件:

Groovy

dependencies {
    def room_version = "2.6.1"

    implementation "androidx.room:room-runtime:$room_version"
    annotationProcessor "androidx.room:room-compiler:$room_version"

    // To use Kotlin annotation processing tool (kapt)
    kapt "androidx.room:room-compiler:$room_version"
    // To use Kotlin Symbol Processing (KSP)
    ksp "androidx.room:room-compiler:$room_version"

    // optional - RxJava2 support for Room
    implementation "androidx.room:room-rxjava2:$room_version"

    // optional - RxJava3 support for Room
    implementation "androidx.room:room-rxjava3:$room_version"

    // optional - Guava support for Room, including Optional and ListenableFuture
    implementation "androidx.room:room-guava:$room_version"

    // optional - Test helpers
    testImplementation "androidx.room:room-testing:$room_version"

    // optional - Paging 3 Integration
    implementation "androidx.room:room-paging:$room_version"
}

Kotlin

dependencies {
    val room_version = "2.6.1"

    implementation("androidx.room:room-runtime:$room_version")
    annotationProcessor("androidx.room:room-compiler:$room_version")

    // To use Kotlin annotation processing tool (kapt)
    kapt("androidx.room:room-compiler:$room_version")
    // To use Kotlin Symbol Processing (KSP)
    ksp("androidx.room:room-compiler:$room_version")

    // optional - Kotlin Extensions and Coroutines support for Room
    implementation("androidx.room:room-ktx:$room_version")

    // optional - RxJava2 support for Room
    implementation("androidx.room:room-rxjava2:$room_version")

    // optional - RxJava3 support for Room
    implementation("androidx.room:room-rxjava3:$room_version")

    // optional - Guava support for Room, including Optional and ListenableFuture
    implementation("androidx.room:room-guava:$room_version")

    // optional - Test helpers
    testImplementation("androidx.room:room-testing:$room_version")

    // optional - Paging 3 Integration
    implementation("androidx.room:room-paging:$room_version")
}

若要瞭解如何使用 KAPT 外掛程式,請參閱 KAPT 說明文件

若要瞭解如何使用 KSP 外掛程式,請參閱 KSP 快速入門說明文件

如要進一步瞭解如何使用 Kotlin 擴充功能,請參閱 ktx 說明文件

如要進一步瞭解依附元件,請參閱「新增建構依附元件」一文。

針對非 Android 程式庫 (僅使用 Java 或 Kotlin 的 Gradle 模組),您可以選擇透過 androidx.room:room-common 使用 Room 註解。

設定編譯器選項

Room 提供以下註解處理工具選項。

room.schemaLocation directory
支援將資料庫結構定義匯出至指定目錄中的 JSON 檔案。詳情請參閱「Room 遷移作業」。
room.incremental boolean
啟用 Gradle 漸進式註解處理工具。預設值為 true
room.generateKotlin boolean
產生 Kotlin 來源檔案,而非 Java。需要 KSP。預設值為 false。詳情請參閱 2.6.0 版的注意事項。

使用 Room Gradle 外掛程式

在 Room 2.6.0 以上版本中,您可以使用 Room Gradle 外掛程式設定 Room 編譯器的選項。外掛程式會設定專案,讓產生結構定義 (編譯工作的輸出內容且用於自動遷移的輸出內容) 正確設定為具有可重現及可快取的建構作業。

如要新增外掛程式,請在頂層 Gradle 建構檔案中定義外掛程式及其版本。

Groovy

plugins {
    id 'androidx.room' version "$room_version" apply false
}

Kotlin

plugins {
    id("androidx.room") version "$room_version" apply false
}

在模組層級 Gradle 建構檔案中,套用外掛程式,並使用 room 擴充功能。

Groovy

plugins {
    id 'androidx.room'
}

android {
    ...
    room {
        schemaDirectory "$projectDir/schemas"
    }
}

Kotlin

plugins {
    id("androidx.room")
}

android {
    ...
    room {
        schemaDirectory("$projectDir/schemas")
    }
}

使用 Room Gradle 外掛程式時必須設定 schemaDirectory。這會設定 Room 編譯器、各種編譯工作及其後端 (javac、KAPT、KSP),以將結構定義檔案輸出至變種版本的資料夾,例如 schemas/flavorOneDebug/com.package.MyDatabase/1.json。請在存放區中簽到,以便用於驗證和自動遷移。

部分選項無法在所有版本的 Room Gradle 外掛程式中設定,即使 Room 編譯器支援這些選項也一樣。下表列出每個選項,以及支援使用 room 擴充功能設定該選項的 Room Gradle 外掛程式版本。如果您的版本較低,或系統尚未支援這個選項,您可以改用註解處理工具選項

選項 自版本以來
room.schemaLocation (必填) 2.6.0
room.incremental -
room.generateKotlin -

使用註解處理工具選項

如果您未使用 Room Gradle 外掛程式,或者您的外掛程式版本不支援所需的選項,您可以使用註解處理工具選項設定 Room,如「新增建構依附元件」一文所述。指定註解選項的方式取決於您是否針對 Room 使用 KSP 或 KAPT。

Groovy

// For KSP
ksp {
    arg("option_name", "option_value")
    // other otions...
}

// For javac and KAPT
android {
    ...
    defaultConfig {
        ...
        javaCompileOptions {
            annotationProcessorOptions {
                arguments += [
                    "option_name":"option_value",
                    // other options...
                    ]
            }
        }
    }
}

Kotlin

// For KSP
ksp {
    arg("option_name", "option_value")
    // other options...
}

// For javac and KAPT
android {
    ...
    defaultConfig {
        ...
        javaCompileOptions {
            annotationProcessorOptions {
                arguments += mapOf(
                    "option_name" to "option_value",
                    // other options...
                )
            }
        }
    }
}

由於 room.schemaLocation 是目錄而非原始類型,因此新增這個選項時,必須使用 CommandLineArgumentsProvider,讓 Gradle 在執行最新的檢查時知道該目錄。遷移 Room 資料庫會顯示提供結構定義位置的 CommandLineArgumentsProvider 完整實作。

意見回饋:

您的意見可協助我們改善 Jetpack。如果您發現新問題,或是有改進這個程式庫的建議,請告訴我們。回報新問題前,請先查看這個程式庫的現有問題。只要按一下星號按鈕,即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 文件

2.6 版

2.6.1 版

2023 年 11 月 29 日

發布 androidx.room:room-*:2.6.1查看 2.6.1 版的修訂項

修正錯誤

  • 已解決產生的程式碼中,EntityCursorConverter 中 Double 資料欄的預設值設為 0 而非 0.0 的問題。該功能也納入了 Float 類型欄類似的邊緣案例修正方法。(Id75f5b/304584179)
  • 現在起,從 PagingSource 載入擲回的例外狀況會以含有 Throwable 的 LoadResult.Error LoadStateUpdate 傳播。此錯誤狀態可透過 PagingDataAdapter.loadStateFlow(Views)LazyPagingItems.loadState(Compose) 觀察。請注意,這標示著過往載入錯誤的行為變更,其中會以觸發負載的 dao 方法擲回的例外狀況顯示。(I93887b/302708983)

2.6.0 版

2023 年 10 月 18 日

發布 androidx.room:room-*:2.6.0查看 2.6.0 版的修訂項

自 2.5.0 版以來的重要變更

  • Room KSP 現已提供啟用 Kotlin 程式碼產生功能 (或「Kotlin CodeGen」) 的選項。(4297ec0)。如要在 Room 中開啟 Kotlin CodeGen,請將 room.generateKotlin 選項名稱新增至 KSP 的處理器選項。如要進一步瞭解如何傳遞 KSP 的處理器選項,請參閱 KSP 說明文件

注意:使用 Kotlin CodeGen 時,請務必注意,系統已新增額外限制。系統不允許使用抽象屬性做為 Kotlin CodeGen 的 DAO getter 或 DAO 查詢,建議改為改寫為函式,以免發生屬性值不可變動且有固定儲存結果的誤報。新增了另一項限制,是 Kotlin CodeGen 的 Room 不再允許可為空值集合傳回類型。

警告:使用 Kotlin CodeGen 時,您可能會發現專案對是否可為空值設定嚴格。在 Kotlin CodeGen 中,類型引數的是否可為空值相當重要,在 Java 中則通常會忽略。舉例來說,假設您有 `Flow<foo\>` 傳回類型,且資料表為空白。在 Java CodeGen 中,這不會造成任何問題,但在 Kotlin CodeGen 中,您將會收到錯誤訊息。如要避免這種情況,您必須使用 `Flow<foo?\>`,並假設發出的空值。</foo?\></foo\>

  • 為 Room Gradle 外掛程式新增的構件 (ID:androidx.room) 已新增至 Room 中,解決透過 Gradle 註解處理工具選項提供結構定義輸入和輸出內容的各種問題。詳情請參閱 Room 2.6.0-alpha02 版本資訊
  • Room 實體中的值類別現在支援 KSP。(4194095)。
  • Room 現在支援 DAO 函式中的巢狀地圖傳回類型。(I13f48203008711)

2.6.0-rc01 版

2023 年 9 月 20 日

發布 androidx.room:room-*:2.6.0-rc01查看 2.6.0-rc01 版的修訂項

2.6.0-beta01 版

2023 年 8 月 23 日

發布 androidx.room:room-*:2.6.0-beta01查看 2.6.0-beta01 版的修訂項

修正錯誤

  • 在更新/插入期間擲回 2067 SQLITE_CONSTRAINT_UNIQUE 例外狀況時,處理特殊案例 SQLite 例外狀況,更新/插入應執行更新。(If2849b/243039555)

2.6.0-alpha03 版

2023 年 8 月 9 日

發布 androidx.room:room-*:2.6.0-alpha03查看 2.6.0-alpha03 版的修訂項

新功能

  • Room 現在支援 DAO 函式中的巢狀地圖傳回類型。(I13f48203008711)

API 變更

  • 已建立名為 @MapColumn 的新類型註解,以取代現已淘汰的 @MapInfo。對於 @MapInfo 註解中提供的每個資料欄名稱 (keyColumnName 和/或 valueColumnName),您必須使用 columnName 宣告 @MapColumn 註解,並在 DAO 函式的傳回類型中,對被參照的特定類型引數 (對應鍵或值) 使用註解。這是因為 @MapColumn 註解會直接用於 DAO 函式傳回類型中的類型引數,而非 @MapInfo 等函式本身。詳情請參閱 @MapColumn 說明文件。(Ib0305b/203008711)
  • 更新 API 檔案,為相容性抑制加上註解 (I8e87ab/287516207)
  • Room Gradle 外掛程式 API 已更新為不一定需要每個變化版本的設定。也就是說,這個外掛程式無需建立多個目錄,就能接受所有變化版本的全域位置,因此更靈活地可供手動設定變種版本或建構類型結構定義,同時保有外掛程式的優勢 (可重現和可快取的建構)。(I09d6fb/278266663)

修正錯誤

  • 已修正 QueryInterceptorStatement 中潛在的記憶體流失安全漏洞。(I193d1)。
  • 修正 QueryInterceptorDatabase execSQL() 函式中的錯誤行為。(Iefdc8)。

2.6.0-alpha02 版

2023 年 6 月 21 日

發布 androidx.room:room-*:2.6.0-alpha02查看 2.6.0-alpha02 版的修訂項

Room Gradle 外掛程式

這個新版本包含 Room Gradle 外掛程式 (ID 為 androidx.room) 的新成果,解決了在 Room 中透過 Gradle 註解處理工具選項提供結構定義輸入和輸出內容的各種問題。Room Gradle 外掛程式會設定專案,以產生用於自動遷移作業的結構定義,並正確設為編譯工作輸出內容,具有可重現及快取的建構作業。這個外掛程式提供的 DSL 可用來設定基本結構定義位置:

room {
    schemaDirectory("$projectDir/schemas/")
}

接著,外掛程式會設定 Room 編譯器、各種編譯工作及其後端 (javac、KAPT、KSP),將結構定義檔案輸出至各變種資料夾,例如 schemas/flavorOneDebug/com.package.MyDatabase/1.json。像平常一樣,這些檔案會在存放區中進行檢查,以便用於驗證及自動遷移。遷移至使用外掛程式 (而非註解處理工具選項) 時,必須將現有的結構定義檔案複製到由外掛程式建立的變種版本目錄,這項作業必須手動完成。日後我們也將更新 developers.android.com 中的結構定義說明文件,並在外掛程式穩定的情況下更新,因此請試用看看。

API 變更

  • RoomDatabase.QueryCallback 已定義為功能介面,可使用 SAM 轉換功能。(Iab8eab/281008549)

修正錯誤

  • 將 Room 來源從 Java 遷移至 Kotlin 後,在 Robolectric 中將資料庫執行個體化時會發生的問題。(Ic053cb/274924903)

2.6.0-alpha01 版

2023 年 3 月 22 日

發布 androidx.room:room-*:2.6.0-alpha01查看 2.6.0-alpha01 版的修訂項

新功能

  • 針對 KSP 的 Room 支援值類別。Room 現在可以支援實體中的值類別。(4194095)。
  • 現在可在 Room 中啟用 Kotlin 程式碼產生功能(或「Kotlin CodeGen」) (4297ec0)。如要在 Room 中開啟 Kotlin CodeGen,請將 room.generateKotlin 選項名稱新增至 KSP 的處理器選項。如要進一步瞭解如何傳遞 KSP 的處理器選項,請參閱 KSP 說明文件

注意:使用 Kotlin CodeGen 時,請務必注意,系統已新增額外限制。系統不允許使用抽象屬性做為 Kotlin CodeGen 的 DAO getter 或 DAO 查詢,建議改為改寫為函式,以免發生屬性值不可變動且有固定儲存結果的誤報。新增了另一項限制,是 Kotlin CodeGen 的 Room 不再允許可為空值集合傳回類型。

警告:使用 Kotlin CodeGen 時,您可能會發現專案對是否可為空值設定嚴格。在 Kotlin CodeGen 中,類型引數的是否可為空值相當重要,在 Java 中則通常會忽略。舉例來說,假設您有 `Flow<foo\>` 傳回類型,且資料表為空白。在 Java CodeGen 中,這不會造成任何問題,但在 Kotlin CodeGen 中,您將會收到錯誤訊息。如要避免這種情況,您必須使用 `Flow<foo?\>`,並假設發出的空值。</foo?\></foo\>

API 變更

  • 防止無意義的 DAO 方法傳回類型使用可為空值集合。(I777dcb/253271782b/259426907)
  • 新增 API,以建立發出無效追蹤器變更的 Flow。如果要建立需要回應資料庫異動的串流,這個 API 就能派上用場。(I8c790b/252899305)

修正錯誤

  • 禁止在 Kotlin 程式碼 gen 中使用抽象屬性做為 DAO getter 或 DAO 查詢,而是應將其改寫為函式,以免發生屬性值不可變動且有固定儲存結果的誤解。(If6a13b/127483380b/257967987)

2.5.2 版本

2.5.2 版本

2023 年 6 月 21 日

發布 androidx.room:room-*:2.5.2查看 2.5.2 版的修訂項

修正錯誤

  • 修正 kotlinx-metadata-jvm 不相容的問題。(386d5c)。
  • 修正在 Robolectric 測試中使用 Room 時擲回錯誤的問題。(f79beab/274924903)

2.5.1 版

2.5.1 版

2023 年 3 月 22 日

發布 androidx.room:room-*:2.5.12.5.1 版包含此連結所列的修訂項目。

修正錯誤

  • 如果資料庫已開啟,請避免檢查 FrameworkSQLiteHelper 中的資料庫父項目錄。(5de86b8)。
  • 檢查資料庫是否已開啟時,請使用 isOpenInternal 檢查。(e91fb35)。
  • Room 的 acquireTransactionThread() 現已支援改善接收案例的處理功能。(219f98b)。在暫停交易期間,Room 會使用交易執行工具的執行緒,在當中啟動事件迴圈,並將暫停的資料庫作業分派給該執行緒,使其全都封裝至交易協同程式內。交易執行緒通常與啟動交易的程序不同,但在某些情況下,這些執行緒應該都相同。為了處理這類重試情況,withTransaction() 已被重構,不再依賴控制工作,而是會在交易執行緒的 runBlocking 中執行暫停交易區塊。

2.5.0 版

2.5.0 版

2023 年 2 月 22 日

發布 androidx.room:room-paging-guava:2.5.0androidx.room:room-paging-rxjava2:2.5.0androidx.room:room-paging-rxjava3:2.5.0查看 2.5.0 版的修訂項

2.5.0 版

2023 年 1 月 11 日

發布 androidx.room:room-*:2.5.02.5.0 版包含此連結所列的修訂項目。

自 2.4.0 版本以來的重要異動

  • 所有 room-runtime 來源均已從 Java 轉換為 Kotlin。請注意,如果程式庫轉換為 Kotlin 格式,進而導致程式碼採用 Kotlin 格式,那麼您可能會遇到來源不相容的問題。舉例來說,在 InvalidationTracker 中,您現在必須在 Observer 宣告 onInvalidate(),類型參數才會是 Set,而不是 MutableSet。這正是一項眾所皆知的來源不相容異動。此外,某些 getter 方法會轉換成需要在 Kotlin 檔案上具有屬性存取語法的屬性。如果發生任何不相容的問題,請回報錯誤。
  • 新增捷徑註解 @Upsert,在沒有獨特性衝突時嘗試插入實體,或是在發生衝突時更新實體。(I7aaabb/241964353)
  • 在 Room Paging 中新增了 room-paging-rxjava2room-paging-rxjava3room-paging-guava 這三個 room-paging 構件以提供支援。
  • 新增了可在 @MapInfo 中 (Icc4b5) 提供鍵值資料表名稱以消除歧義的 API。

2.5.0-rc01 版本

2022 年 12 月 7 日

發布 androidx.room:room-*:2.5.0-rc012.5.0-rc01 版包含此連結所列的修訂項目。

  • 這個版與 2.5.0-beta02 相同。

2.5.0-beta02 版

2022 年 11 月 9 日

發布 androidx.room:room-*:2.5.0-beta022.5.0-beta02 版包含此連結所列的修訂項目。

API 變更

  • 修正將查詢引數從不變 (Array<Any?>) 擷取到逆變 (Array<out Any?>) 的各種 API,以符合 Java 的陣列行為。(b/253531073)

2.5.0-beta01 版本

2022 年 10 月 5 日

發布 androidx.room:room-*:2.5.0-beta012.5.0-beta01 版包含此連結所列的修訂項目。

API 變更

  • 將支援 @Upsert 的最低版本限制為 API 16。這是因為您無法在舊版 API 中識別主鍵限制衝突。(I5f67fb/243039555)

修正錯誤

  • 修正問題,其中陰影表格錯誤地匯出至結構定義的 .json 檔案,並造成這些檔案毀損。(I4f83bb/246751839)

2.5.0-alpha03 版本

2022 年 8 月 24 日

發布 androidx.room:room-*:2.5.0-alpha032.5.0-alpha03 版包含此連結所列的修訂項目。

新功能

  • 新增捷徑註解 @Upsert,在沒有獨特性衝突時嘗試插入實體,或是在發生衝突時更新實體。(I7aaabb/241964353)

修正錯誤

  • 在自動遷移外鍵限制檢查期間,Room 現在會擲回 SQLiteConstraintException,而不是 IllegalStateException。(I328dd)
  • 修正 getOpenHelpergetQueryExecutorgetTransactionExecutor 的 getter / 屬性與 Kotlin 來源不相容的變更。(Iad0ac)

2.5.0-alpha02 版本

2022 年 6 月 1 日

發布 androidx.room:room-*:2.5.0-alpha022.5.0-alpha02 版包含此連結所列的修訂項目。

新功能

API 變更

  • 所有 room-runtime 構件均已從 Java 轉換為 Kotlin。(If2069b/206859668)、(Ie4b55b/206859668)、(I697eeb/206859668、(I96c25、6159)

    注意:由於程式庫轉換為 Kotlin,您可能會遇到原始碼不相容的問題。如果程式碼原本是 Kotlin,且呼叫的 Room 也是舊版,新版本便需要處理不相容的情況。這類因為原始碼不相容而帶來的異動,一個大家都知道的例子就是:在 InvalidationTracker,您現在必須在 Observer 宣告 onInvalidate(),類型參數才會是 Set,而不是 MutableSet

  • 新增了可在 @MapInfo 中 (Icc4b5) 提供鍵值資料表名稱以消除歧義的 API。
  • 修正來源相容性問題,恢復允許 getter 屬性中的 @Ignore。(Ifc2fb)

修正錯誤

  • 重複的資料欄解析度經驗法則演算法。Room 現在將嘗試在多重對應查詢中解決引起歧義的資料欄。此點考慮到內含資料表的 JOIN,其中包含相同名稱的資料表將正確對應於結果資料物件。(I4b444b/201306012b/212279118)

2.5.0-alpha01 版本

2022 年 2 月 23 日

發布 androidx.room:room-*:2.5.0-alpha012.5.0-alpha01 版包含此連結所列的修訂項目。

API 變更

  • 修正了以下問題:無法在 Kotlin 來源中強制使用 Room @IntDef。(I75f41b/217951311)
  • 修正了來源相容性問題,恢復允許在 getter 屬性中使用 @Query。(I0a09b)
  • 將 room-common 從 Java 轉換至 Kotlin。(I69c48b/206858235)

    注意事項:由於某些屬性在程式庫轉換至 Kotlin 的過程已移至隨附物件中,因此您可能會遇到來源不相容的問題。如果程式碼原本是以 Kotlin 編寫並呼叫舊版的 Room,新版本必須加上「.Companion」後置字元,才能存取這些屬性。

  • 將 room-migration 從 Java 轉換至 Kotlin。(I2724bb/206858622)
  • room-runtime 中的 paging 相關檔案從 Java 轉換至 Kotlin。(I82fc8b/206859668)
  • 在 FrameworkSQLite* 層級新增用來鎖定多元處理程序的 API,這樣在首度同時建立及遷移資料庫時,可以避免發生多元處理程序競爭狀況。(Ied267b/193182592)

修正錯誤

  • 新增了針對 Kotlin 來源中內部屬性的支援。在 Room 中,這是輕微的行為變更,會在將函式作為 getters/setter 與屬性進行比對時使用函式的來源名稱 (之前,所使用的是函式的 JVM 名稱,而對內部函數/屬性,JVM 名稱有所不同)。如果您要使用自訂的 @JvmName 註解將 getter/setter 與私人屬性進行比對,請在更新後仔細檢查產生的程式碼 (If6531b/205289020)。

2.4.3 版本

2.4.3 版本

2022 年 7 月 27 日

發布 androidx.room:room-*:2.4.32.4.3 版包含此連結所列的修訂項目。

修正錯誤

  • 修正會導致 Room 無法辨識 Kotlin 1.7 中暫停函式的問題 (b/236612358)

2.4.2 版本

2.4.2 版本

2022 年 2 月 23 日

發布 androidx.room:room-*:2.4.22.4.2 版包含此連結所列的修訂項目。

修正錯誤

  • 修正因使用 -Xjvm-default=all 或同等程式碼進行編譯,而導致為 Dao @Transaction 暫停函式產生程式碼時,出現主體產生預設介面方法的問題。(Ia4ce5)
  • 解決 Room 因 Array<ByteArray> 傳回類型查詢方法產生程式碼的錯誤。(If086eb/213789489)

2.4.1 版本

2.4.1 版本

2022 年 1 月 12 日

發布了 androidx.room:room-*:2.4.12.4.1 版包含此連結所列的修訂項目。

修正錯誤

  • 新增了針對 Kotlin 來源中內部屬性的支援。在 Room 中,這是輕微的行為變更,會在將函式作為 getters/setter 與屬性進行比對時使用函式的來源名稱 (之前,所使用的是函式的 JVM 名稱,而對內部函數/屬性,JVM 名稱有所不同)。如果您要使用自訂的 @JvmName 註解將 getter/setter 與私人屬性進行比對,請在更新後仔細檢查產生的程式碼 (If6531b/205289020)。

2.4.0 版本

2.4.0 版本

2021 年 12 月 15 日

發布 androidx.room:room-*:2.4.02.4.0 版包含此連結所列的修訂項目。

2.3.0 版之後的重要變更

  • 自動遷移:Room 現在提供只要匯出結構定義即可自動產生遷移作業的 API。為了讓 Room 得知應該產生自動遷移作業,可以使用新屬性 @Database#autoMigrations 來宣告要自動遷移的來源和目標版本。當 Room 需要資料表和資料欄重新命名或刪除的額外相關資訊,@AutoMigration 註解可以宣告包含此類輸入內容的規格類別。如需詳細資訊,請參閱 @AutoMigration 說明文件。
  • 在自動遷移中插入依附元件@ProvidedAutoMigrationSpec 是一個新的 API,用於宣告將在執行階段透過 RoomDatabase.Builder#addAutoMigrationSpec() 提供 AutoMigrationSpec。如此一來,依附元件插入架構在需要複雜的依附元件時便可提供此類規格。
  • 遷移測試協助程式對自動遷移作業的支援:更新了 Room 的 MigrationTestHelper,提供新建構函式 API 接收測試中的該資料庫類別,即可支援自動遷移作業。如此一來,協助程式便能在 runMigrationsAndValidate 期間以相同方式自動新增自動遷移作業。
  • Room-Paging 支援:發布了 androidx.room:room-paging,為回傳 androidx.paging.PagingSource 的 Room 查詢提供原生的 Paging 3.0 支援。
  • 相關查詢方法:Room 現可支援多重對應傳回類型 @Dao 方法,對於 JOIN 陳述式很實用。支援的多重對應類型包括 MapSparseArrayLongSparseArray,以及 Guava 的 ImmutableMapImmutableSetMultimapImmutableListMultimap

2.4.0-rc01 版本

2021 年 12 月 1 日

發布 androidx.room:room-*:2.4.0-rc012.4.0-rc01 版包含此連結所列的修訂項目。

新功能

  • 將 KSP 中 Room 的依附元件更新為 1.6.0-1.0.1,以支援 Kotlin 1.6

2.4.0-beta02 版本

2021 年 11 月 17 日

發布 androidx.room:room-*:2.4.0-beta022.4.0-beta02 版包含此連結所列的修訂項目。

新功能

  • 我們在 @MapInfo 中新增對 SparseArray 和 LongSparseArray 的支援。(Ic91a2b/138910317)

修正錯誤

  • 我們新增了一個新的 TypeConverter 分析工具,可將類型中的是否可為空值資訊納入考量範圍。由於此資訊僅適用於 KSP,因此根據預設,在 KSP 中才能開啟該分析工具。如果造成任何問題,請將 room.useNullAwareTypeAnalysis=false 傳遞至註解處理工具,即可將其關閉。如果發生此狀況,請回報錯誤,我們日後會移除此標記項目。使用這個新的 TypeConverter 分析工具時,建議您僅提供非空值接收 TypeConverter,因為新的分析工具能透過空值檢查將其納入。請注意,這對於使用 KAPT 或 Java 作為註解處理工具 (不同於 KSP) 的使用者並無任何影響,因此類型中不含任何是否可為空值的資訊。(Ia88f9b/193437407)
  • 修正錯誤:當 FTS 實體宣告了使用 ICU 權杖化工具時,Room 無法進行編譯並出現 SQL 錯誤。(I00db9b/201753224)
  • 解決了各版本之間關於新增至嵌入實體新資料欄的自動遷移問題。(I5fcb1b/193798291)。
  • 我們解決了有關 LEFT JOIN 查詢中相關查詢方法傳回類型的問題。透過這些變更,在存在一對多的對應情況下,如果在游標中找不到無效值物件,則為某個鍵傳回的集合將不包括該物件。如果找不到任何有效值,系統就會將鍵對應到空集合。(Id5552b/201946438)
  • 解決了 SQLite 關鍵字無法在資料欄名稱中逸出的自動遷移問題。(Idbed4b/197133152)。

2.4.0-beta01 版本

2021 年 10 月 13 日

發布 androidx.room:room-*:2.4.0-beta012.4.0-beta01 版包含此連結所列的修訂項目。

修正錯誤

  • 修正了以下問題:當同一自動遷移作業中的其他表格也有同名的新資料欄時,自動遷移就不會新增資料欄。(Ia5db5b/200818663)
  • 由 Room-Paging 產生的 PagingSource 實作現在使用透過 RoomDatabase.Builder 傳遞的 queryExecutor,因此可被覆寫,取代了之前使用的 Dispatchers.IO。(Iae259)

2.4.0-alpha05 版本

2021 年 9 月 29 日

發布 androidx.room:room-*:2.4.0-alpha052.4.0-alpha05 版包含此連結所列的修訂項目。

新功能

API 變更

  • 在 TypeTransformers 註解中新增了一個屬性,讓開發人員停用內建的 Enum 和 UUID 轉換工具。這些轉換工具預設為開啟,但您可以針對特定範圍或整個資料庫將其停用。詳情請參閱 TypeConverters 說明文件。(36ae9eb/195413406)

  • 透過 @MapInfo 註解,支援在 DAO 中適用於多重對應傳回類型的非 POJO 鍵/值。(I4d704)

對應的鍵或值資料欄來自單欄時,就必須使用 @MapInfo。詳見範例如下:

@MapInfo(valueColumn = "songCount")
@Query("""
       SELECT *, COUNT(mSongId) as songCount
       FROM Artist JOIN Song ON Artist.artistName = Song.artist
       GROUP BY artistName
       """)
fun getArtistAndSongCounts(): Map<Artist, Integer>
  • 搭配 Room 一起使用 Paging3 時,請將 room-paging 設為必選構件。(Ieaffe)

修正錯誤

  • 修正以下問題:當查詢包含對應鍵中某一欄的 ORDER BY 子句時,多重對應查詢結果無法正確排序。(I6b887)

外部貢獻

  • 新增了用於在 @Index 中指定索引順序的 API。非常感謝 Nikita Zhelonkin。(I033fc)

2.4.0-alpha04 版本

2021 年 7 月 21 日

發布 androidx.room:room-*:2.4.0-alpha042.4.0-alpha04 版包含此連結所列的修訂項目。

新功能

  • Room 現可支援多重對應傳回類型 @Dao 方法,對於 JOIN 陳述式很實用。支援的多重對應類型包括 Map,以及 Guava 的 ImmutableMapImmutableSetMultimapImmutableListMultimap

    以下是多重對應查詢的範例:

    一對一關係對應

    @Query("SELECT * FROM Song JOIN Artist ON Song.artistId = Artist.artistId")
    fun getSongAndArtist(): Map<Song, Artist>
    

    一對多關係對應 (標準多重對應)

    @Query("SELECT * FROM Artist JOIN Album ON Artist.id = Album.artistId")
    fun getArtistAndAlbums(): Map<Artist, List<Album>>
    

    多重對應結果還可以納入支援的非同步傳回類型中,例如 LiveData、Rx 的 Observable 或協同程式 Flow

Room-Paging

  • 發布了 androidx.room:room-paging,可為傳回 androidx.paging.PagingSource 的 Room 查詢提供原生 Paging 3.0 支援。

    @Dao
    interface UserDao {
      @Query("SELECT * FROM users ORDER BY id ASC")
      fun loadUsers(): PagingSource<Int, User>
    }
    
  • 這個構件將 Room 所產生的 androidx.paging.PagingSource 實作項目替換為建構在 Paging 3.0 API 上的實作項目。新的 PagingSource 實作會以不同方式剖析鍵,因此手動提供到 Room PagingSource 的的任何鍵都必須考量此行為變更,包括透過 Pager 的建構函式傳遞的initialKey。頁面將從 Key 開始載入,因為 Key 是第一個載入的項目。這與現有行為不同,在現有行為中,LoadParams.Refresh.Key 被視為使用者的捲動位置,並且在鍵的前後都會載入項目。

  • 該構件為選用項目,選擇不採用將回退至在 Room 2.3 中所引入針對 Paging 3.0 的現有支援。不過,對於將 Room 與 Paging 3.0 搭配使用的使用者,此構件在未來版本中將變為非選用項目。如要選擇使用,請將新的 Room-Paging 構件新增至您的類別路徑中。如果您使用的是 Gradle,請將下列程式碼片段新增至 build.gradle 中:

    dependency {
      implementation("androidx.room:room-paging:2.4.0-alpha04")
    }
    

修正錯誤

  • 修正自動遷移作業中與處理外鍵違規相關的問題。(b/190113935)

2.4.0-alpha03 版本

2021 年 6 月 16 日

發布 androidx.room:room-*:2.4.0-alpha032.4.0-alpha03 版包含此連結所列的修訂項目。

API 變更

  • 更新 Room 的 MigrationTestHelper,提供可接收測試中資料庫類別的新建構函式 API,以支援自動遷移作業。如此一來,協助程式便能在 runMigrationsAndValidate 期間以相同方式自動新增自動遷移作業。

修正錯誤

  • 修正了 Room 的 SQLite 原生資料庫問題,以支援 Apple 的 M1 晶片。(b/174695268)

  • 修正了以下問題:當 @Transaction 函式的傳回類型是 Flow 時,Room 就不會出錯 (I56dddb/190075899)

  • 修正自動遷移作業中與索引相關的問題。b/177673291

依附元件更新

2.4.0-alpha02 版本

2021 年 5 月 5 日

發布 androidx.room:room-*:2.4.0-alpha022.4.0-alpha02 版包含此連結所列的修訂項目

API 變更

  • @ProvidedAutoMigrationSpec 是一個新 API,用於宣告在執行階段透過 RoomDatabase.Builder#addAutoMigrationSpec() 提供 AutoMigrationSpec。如此一來,依附元件插入架構在需要複雜的依附元件時便可提供此類規格。

修正錯誤

  • 修正導致無法正確重建 @DatabaseView 的自動遷移問題。

外部貢獻

  • 修正 Room 的 JournalMode.TRUNCATE 中的一個問題,即有時無效,或是太晚或根本未叫用 InvalidationTracker 回呼的問題。歸功於 Uli Bubenheimer | bubenheimer@users.noreply.github.com (b/154040286)

2.4.0-alpha01 版本

2021 年 4 月 21 日

發布 androidx.room:room-*:2.4.0-alpha012.4.0-alpha01 版包含此連結所列的修訂項目。

新功能

  • 自動遷移:Room 現在提供只要匯出結構定義即可自動產生遷移作業的 API。為了讓 Room 得知應該產生自動遷移作業,可以使用新屬性 @Database#autoMigrations 來宣告要自動遷移的來源和目標版本。當 Room 需要資料表和資料欄重新命名或刪除的額外相關資訊,@AutoMigration 註解可以宣告包含此類輸入內容的規格類別。詳情請參閱 @AutoMigration 說明文件。

修正錯誤

  • 修正 Room 的結構定義驗證機制誤讓含有多餘括號的 defaultValue 通過驗證的問題。b/182284899

2.3.0 版本

2.3.0 版本

2021 年 4 月 21 日

發布 androidx.room:room-*:2.3.02.3.0 版包含此連結所列的修訂項目。

自 2.2.0 版以來的重要變更

  • 內建列舉支援:如果系統未提供任何類型轉換工具,Room 現在將根據預設使用「列舉 - 字串」雙向類型轉換工具。如果適用於列舉的類型轉換工具已存在,Room 將優先使用該轉換器工具,而非預設轉換工具。
  • 查詢回呼:Room 現可提供一個通用回呼 API RoomDatabase.QueryCallback,適用於即將執行查詢時,對於登入偵錯版本會很實用。可以透過 RoomDatabase.Builder#setQueryCallback() 設定回呼。
  • 預先封裝的改善項目:Room 現在擁有相關 API,可使用透過輸入裝置串流讀取的預先封裝資料庫來建立資料庫。此做法可處理採用 gzip 格式壓縮的預先封裝資料庫等情況。
  • 提供的類型轉換工具:Room 現在擁有相關 API,可提供類型轉換工具的執行個體,以便應用程式能夠控制其初始化。如要標示將提供給 Room 的類型轉換工具,請使用新註解 @ProvidedTypeConverter。
  • RxJava3 支援:Room 現在支援 RxJava3 類型。與 RxJava2 類似,您可以宣告傳回類型為 Flowable、Single、Maybe 和 Completable 的 DAO 方法。此外,還可使用新構件 androidx.room:room-rxjava3 支援 RxJava3。
  • Paging 3.0 支援:Room 現在支援產生 @Query 註解方法 (傳回類型為 androidx.paging.PagingSource) 的導入作業。

2.3.0-rc01 版本

2021 年 3 月 24 日

發布 androidx.room:room-*:2.3.0-rc012.3.0-rc01 版包含此連結所列的修訂項目。

修正錯誤

  • 修正導致 Room 所建立的 Coroutine Flow (協同程式流程) 查詢無法在暫停的 withTransaction 區塊中使用的問題。(I797bf)

2.3.0-beta03 版本

2021 年 3 月 10 日

發布 androidx.room:room-*:2.3.0-beta032.3.0-beta03 版包含此連結所列的修訂項目。

新功能

修正錯誤

  • 修正了在主執行緒上建立 PagingSource 可能觸發 ANR 的錯誤 (I42b74b/181221318)。
  • @ExperimentalRoomApi 瀏覽權限修正為公開,而非套件私有 (b/181356119)。

外部貢獻

  • 當 Room 同時使用 @SkipQueryVerification 進行註解時,允許 Room 在 @Query 註解的 DAO 方法中接受 POJO 傳回類型。Room 會盡力將查詢結果轉換為 POJO 傳回類型,與針對 @RawQuery 註解的 DAO 方法採用相同的處理方式。非常感謝「MarkMark Riegel | Hey@marcorei.com」。(I45acb)

2.3.0-beta02 版本

2021 年 2 月 18 日

發布了 androidx.room:room-*:2.3.0-beta022.3.0-beta02 版包含此連結所列的修訂項目。

新功能

  • Room 現在實驗性支援 Kotlin Symbol Processing KSP

    KSP 用於取代 KAPT,能夠在 Kotlin 編譯器上以原生方式執行註解處理工具,並大幅縮短建構時間。

    如要將 Room 與 KSP 搭配使用,您可以套用 KSP Gradle 外掛程式,並將建構檔案中的 kapt 設定替換成 ksp。例如,使用 ksp 'androidx.room:room-compiler:2.3.0-beta02',而不使用 kapt 'androidx.room:room-compiler:2.3.0-beta02'。詳情請參閱 KSP 說明文件

    請注意,由於 KSP 尚處於實驗階段,因此建議仍將 KAPT 用於正式版程式碼。當不再有其他處理工具使用 KAPT 時,縮短建構時間才適用。如需瞭解已知問題,請參閱 b/160322705

2.3.0-beta01 版本

2021 年 1 月 27 日

發布 androidx.room:room-*:2.3.0-beta012.3.0-beta01 版包含此連結所列的修訂項目。

新功能

  • 「自動關閉資料庫」:Room 現在能夠關閉一段指定時間未存取的資料庫。這是一項實驗功能,透過呼叫 RoomDatabase.Builder#setAutoCloseTimeout() 即可啟用。對於擁有多個資料庫的應用程式,此功能很實用。

修正錯誤

  • 修正當 Dao 方法有多個 @Update@Delete 方法採用不同衝突策略時,產生的程式碼只會包含其中一種策略而有效忽略已定義策略的問題。(/I0b90db/176138543)。

2.3.0-alpha04 版本

2020 年 12 月 16 日

發布 androidx.room:room-*:2.3.0-alpha042.3.0-alpha04 版包含此連結所列的修訂項目。

新功能

  • Room 現可提供一個通用回呼 API RoomDatabase.QueryCallback,適用於即將執行查詢時,對於登入偵錯版本會很實用。可以透過 RoomDatabase.Builder#setQueryCallback() 設定回呼。(Iaa513b/174478034b/74877608)
  • 如果系統未提供任何類型轉換工具,Room 現在將根據預設使用「列舉 - 字串」雙向類型轉換工具。如果適用於列舉的類型轉換工具已存在,Room 將優先使用該轉換器工具,而非預設轉換工具。(b/73132006)

已知問題

  • 如果 Enum 已經有用於讀取的單向類型轉換工具,Room 可能會意外誤用內建的 String-Enum 轉換工具,這可能不合乎期待。這是個已知問題,可透過使其成為雙向轉換工具進行修正。請參閱:b/175707691

修正錯誤

  • 修正了以下問題:在較新的 JDK 版本中,Room 會誤停用增量註解處理作業。(b/171387388)
  • 修正了以下問題:使用多個類別載入器時,Room 會查找系統所產生類別。非常感謝「Serendipity | 892449346@qq.com」協助修正此問題!(b/170141113)
  • 修正了以下問題:當 Kotlin @Dao 含有泛型為 JVM 中基元的基礎類別時,Room 會產生不正確的程式碼。(b/160258066)

外部貢獻

  • 如果 WAL 模式已啟用且 API 級別為16 以上,Room 現在將預設使用 beginTransactionNonExclusive。非常非常感謝「Ahmed I. Khalil | ahmedibrahimkhali@gmail.com」!(b/126258791)

2.3.0-alpha03 版本

2020 年 10 月 14 日

發布 androidx.room:room-*:2.3.0-alpha032.3.0-alpha03 版包含此連結所列的修訂項目。

新功能

  • Room 現在擁有相關 API,可提供類型轉換工具的執行個體,以便應用程式能夠控制其初始化。如要標示將提供給 Room 的類型轉換工具,請使用新註解 @ProvidedTypeConverter。非常感謝「mzgreen yairobbe@gmail.com」。(Ie4fa5b/121067210)。

  • Room 現在擁有相關 API,可使用透過輸入裝置串流讀取的預先封裝資料庫來建立資料庫。此做法可處理採用 gzip 格式壓縮的預先封裝資料庫等情況。非常感謝「Ahmed El-Helw ahmedre@gmail.com」(3e6792b/146911060)

API 變更

  • 已將缺少的目標新增到 @ForeignKey 註解中,防止其用於 @Entity 註解以外。(Iced1e)

  • RoomDatabase.java 中的 mCallbacks 欄位現在處於隱藏狀態。(d576cbb/76109329)。

修正錯誤

  • 更新 TypeConverter 說明文件,澄清 TypeTransformer 只能用於轉換資料欄/欄位,而不適用於資料列。(I07c56b/77307836)

  • 更新為 DaoProcessor,修正使用包含 Kotlin「基元」的泛型超級類別時在 Dao 上出現的編輯器錯誤。(Ice6bbb/160258066)

  • 更新新增/移除觀測工具方法說明文件,澄清執行緒使用模式 (Ifd1d9b/153948821)

  • 修正 Room 無法正確驗證已宣告其 rowid 資料欄的 FTS 表格問題 (d62ebcb/145858914)。

外部貢獻

  • 修正與土耳其文相關的大小寫語言代碼問題 (5746e3)、b/68159494

  • RoomDatabase 中的 ConcurrentHashMap 替換成 Collections.synchronizedMap(),以避免在 Android Lollipop 上出現問題 (d1cfc7b/162431855)

  • 新增 onOpenPrepackagedDatabase 回呼,用於處理複製預先封裝的資料庫的情況。(I1ba74b/148934423)。

2.3.0-alpha02 版

2020 年 7 月 22 日

發布 androidx.room:room-*:2.3.0-alpha022.3.0-alpha02 版包含此連結所列的修訂項目。

新功能

  • RxJava3 支援:Room 現在支援 RxJava3 類型。與 RxJava2 類似,您可以宣告傳回類型為 Flowable、Single、Maybe 和 Completable 的 DAO 方法。此外,還可使用新構件 androidx.room:room-rxjava3 支援 RxJava3。(b/152427884)

API 變更

  • 現可支援在 Kotlin 物件類別中宣告 @TypeConverter (b/151110764)
  • Room 的漸進式註解處理選項現在預設為「開啟」(b/112110217)

2.3.0-alpha01 版本

2020 年 6 月 10 日

發布 androidx.room:room-*:2.3.0-alpha012.3.0-alpha01 版包含此連結所列的修訂項目

新功能

  • Paging 3.0 支援:Room 現在支援產生 @Query 註解方法 (傳回類型為 androidx.paging.PagingSource) 的導入作業。

    @Dao
    interface UserDao {
      @Query("SELECT * FROM users ORDER BY id ASC")
      fun pagingSource(): PagingSource<Int, User>
    }
    

API 變更

  • @RewriteQueriesToDropUnusedColumns 是全新的便捷註解,可讓 Room 重寫查詢中的「*」投影,如此一來,系統就能移除結果中未使用的欄。
  • 處理器選項 room.expandProjection 現已淘汰。使用 @RewriteQueriesToDropUnusedColumns 取代 Room 藉由星號投影最佳化查詢。請注意,關於包含 @Embedded 欄位的傳回類型,@RewriteQueriesToDropUnusedColumns 並不會取代 room.expandProjection 提供的資料欄衝突解決方案。

修正錯誤

  • 修正了 Room 無法正確偵測用於啟用增量註解處理工具的 JDK 版本問題。非常感謝 Blaz Solar (me@blaz.solar) (b/155215201)
  • Room 現在會將其 ANTLR 依附元件嵌入註解處理工具,以避免與其他處理 ANTLR 的處理工具發生衝突。(b/150106190)

2.2.6 版本

2.2.6 版本

2020 年 12 月 16 日

發布 androidx.room:room-*:2.2.62.2.6 版包含此連結所列的修訂項目。

修正錯誤

  • 修正了以下問題:在較新的 JDK 版本中,Room 會誤停用增量註解處理作業。(b/171387388)

2.2.5 版本

2.2.5 版本

2020 年 3 月 18 日

發布 androidx.room:room-*:2.2.52.2.5 版包含此連結所列的修訂項目。

修正錯誤

  • 使 MultiInstanceInvalidationService 成為 DirectBootAware。非常感謝「Mygod contact-git@mygod.be」(b/148240967)
  • 修正了已啟用多重執行個體無效且資料庫包含 FTS 實體時會導致當機的問題。(b/148969394)
  • 修正了以下問題:在 Room 註解處理工具中載入 SQLite 原生資料庫時,會導致編譯器因平行編譯而當機。(b/146217083)

2.2.4 版本

2.2.4 版本

2020 年 2 月 19 日

發布了 androidx.room:room-common:2.2.4androidx.room:room-compiler:2.2.4androidx.room:room-guava:2.2.4androidx.room:room-ktx:2.2.4androidx.room:room-migration:2.2.4androidx.room:room-runtime:2.2.4androidx.room:room-rxjava2:2.2.4androidx.room:room-testing:2.2.42.2.4 版包含此連結所列的修訂項目。

修正錯誤

  • 修正了暫停交易時出現的問題:如果在交易實際開始前快速取消了協同程式,交易會死結。(b/148181325)
  • 修正了使用 JDK 9 建構時誤用 @Generated 的問題 (b/146538330)
  • 修正了當 Kotlin 中的 DAO 介面有具體函式時,Room 會產生不正確程式碼的問題。(b/146825845)

2.2.3 版本

2.2.3 版本

2019 年 12 月 18 日

發布 androidx.room:room-*:2.2.32.2.3 版包含此連結所列的修訂項目

修正錯誤

  • 修正了以下錯誤:Room 無法驗證未經過任何遷移並在其架構中包含了帶有索引的舊版雜湊的資料庫。(b/139306173)

2.2.2 版本

2.2.2 版本

2019 年 11 月 20 日

發布了 androidx.room:room-*:2.2.22.2.2 版包含此連結所列的修訂項目

修正錯誤

  • 修正錯誤:Room 因為收集的一對一關係超過 999 列,而傳回空值相關項目 (b/143105450)。

2.2.1 版本

2.2.1 版本

2019 年 10 月 23 日

發布 androidx.room:room-*:2.2.12.2.1 版包含此連結所列的修訂項目。

修正錯誤

  • 修正了 Room 在編譯器選項 expandProjection 設為開啟時誤發出 CURSOR_MISMATCH 警告的錯誤。(b/140759491)
  • 新增了重試機制,用於處理編譯期間缺少驗證查詢所用原生資料庫的問題。

2.2.0 版本

2.2.0 版本

2019 年 10 月 9 日

發布了 androidx.room:room-*:2.2.02.2.0 版包含此連結所列的修訂項目

自 2.1.0 版以來的重要異動

  • 預先封裝的資料庫RoomDatabase.Builder 中現在有兩個新的 API,可用於在指定已填入資料庫檔案的情況下建立 RoomDatabasecreateFromAsset() 適合用於預先填入的資料庫檔案位於 APK 素材資源資料夾的情況,createFromFile() 則適合用於檔案位於任意位置的情況。這些 API 的使用情形會改變破壞性遷移作業的行為,因此在回退遷移作業期間,如有預先填入的資料庫,Room 會嘗試重新複製該資料庫,否則將回退改為直接刪除及重新建立所有資料表。b/62185732
  • 結構定義預設值@ColumnInfo 現在提供新的屬性 defaultValue,可用於指定資料欄的預設值。預設值是資料庫結構定義的一部分,如果指定了預設值,將會在遷移作業期間進行驗證。b/64088772
  • 多對多關係@Relation 現在提供新的屬性 associateBy,該屬性接受新的註解 @Junction,可用於宣告必須透過聯合資料表 (也稱為彙整資料表) 滿足的關係。b/69201917
  • 一對一關係:針對包含 @Relation 註解的 POJO 欄位解除了類型必須設為 ListSet 的限制,有效支援單一值關係的表示方式。b/62905145
  • 目標實體:DAO 註解 @Insert@Update@Delete 現在提供新的屬性 targetEntity,能夠指定 DAO 方法的執行目標資料表。如此一來,那些 DAO 方法的參數即成為任意 POJO,系統會將這些 POJO 解譯為部分實體。在實作中,這能夠讓使用者進行部分插入、刪除與更新。b/127549506
  • 協同程式流程@Query DAO 方法現在可以設為 Flow<T> 傳回類型。如果查詢中的觀察資料表無效,傳回的流程將重新發出一組新值。宣告 DAO 函式並將傳回類型設為 Channel<T> 將導致錯誤,Room 建議您改用 Flow,再使用相鄰的函式將 Flow 轉換成 Channelb/130428884
  • Gradle 增量註解處理工具:Room 現在是 Gradle 隔離註解處理工具,並可透過處理工具選項 room.incremental 啟用增量功能。詳情請參閱 Room 編譯器選項一文。如果遇到任何問題,請按一下 這裡 回報錯誤。我們計畫在日後的穩定版本中預設啟用增量功能。b/112110217
  • 展開式投影:新增了實驗性編譯器選項 room.expandProjection,讓 Room 改寫使用星號投影的查詢,僅納入傳回類型 POJO 中的資料欄。例如,如果是包含 @Query("SELECT * FROM Song") 的 DAO 方法,系統會傳回只有兩個欄位名稱為 SongIdAndTitle 的 POJO。在這種情況下,Room 會將查詢改寫為 SELECT id, title FROM Song,只擷取要滿足傳回類型所需的最低數量資料欄。這樣一來,即使查詢傳回的額外資料欄與 POJO 傳回類型中的所有欄位皆不相符,系統基本上也不會顯示 CURSOR_MISMATCH 警告。

2.2.0-rc01 版本

2019 年 9 月 5 日

發布了 androidx.room:room:2.2.0-rc01。您可以前往這裡查看這個版本包含的修訂項目。

自 Room 2.2.0-beta01 以來沒有公開的變更。

2.2.0-beta01 版本

2019 年 8 月 22 日

發布 androidx.room:room-*:2.2.0-beta01。您可以前往這裡查看這個版本包含的修訂項目。

修正錯誤

  • 修正錯誤:Coroutine Flow (協同程式流程) 查詢在一段特定時間後,就會停止重新發送新值 (b/139175786)。
  • 修正了以下錯誤:Room 開啟自 1.0 版本後便一直未進行遷移作業的資料庫時,不會接受舊版結構定義雜湊程式碼,因結構定義無效而導致執行階段停止運作。(b/139306173)

2.2.0-alpha02 版本

2019 年 8 月 7 日

發布 androidx.room:room-*:2.2.0-alpha02。您可以前往這裡查看這個版本包含的修訂項目。

新功能

  • 協同程式流程@Query DAO 方法現在可以設為 Flow<T> 傳回類型。如果查詢中的觀察資料表無效,傳回的流程將重新發出一組新值。宣告 DAO 函式並將傳回類型設為 Channel<T> 將導致錯誤,Room 建議您改用 Flow,再使用相鄰的函式將 Flow 轉換成 Channelb/130428884
  • 展開式投影:新增了實驗性編譯器選項 room.expandProjection,讓 Room 改寫使用星號投影的查詢,僅納入傳回類型 POJO 中的資料欄。例如,如果是包含 @Query("SELECT * FROM Song") 的 DAO 方法,系統會傳回只有兩個欄位名稱為 SongIdAndTitle 的 POJO。在這種情況下,Room 會將查詢改寫為 SELECT id, title FROM Song,只擷取要滿足傳回類型所需的最低數量資料欄。這樣一來,即使查詢傳回的額外資料欄與 POJO 傳回類型中的所有欄位皆不相符,系統基本上也不會顯示 CURSOR_MISMATCH 警告。
  • onDestructiveMigrate 是新增到 RoomDatabase.Callback 的回呼 API,用於處理在 Room 中破壞性地遷移資料庫的情況。b/79962330

修正錯誤

  • 修正了當欄位受到保護時,Room 產生的程式碼會誤將方法當做欄位 setter 使用的錯誤。b/136194628
  • 修正了當多實體作廢設定為啟用且作廢服務遭到終止時,InvalidationTracker 會在第二個程序中擲回 NPE 的錯誤。b/137454915
  • 修正錯誤:Room 無法正確識別所繼承暫停函式 (使用 @RawQuery 註解) 的傳回類型。b/137878827
  • 當相關鍵的類型為 BLOB 時,為 @Relation 更新了產生的程式碼,以使用可比較的 ByteBufferb/137881998
  • 修正了當使用 POJO 做為 @Insert@Update@Delete 的部分實體參數時,Room 會誤判 POJO 缺少 setter 的錯誤。b/138664463
  • 修正了在特定 DAO 方法中使用實體類別時,Room 會透過 @Entity 指出忽略的資料欄缺少 getter 和 setter 的錯誤。b/138238182
  • 修正了當執行的查詢含有重複使用的參數時,Room 無法正確將已命名的繫結引數轉換成位置引數,而導致執行階段發生例外狀況的錯誤。b/137254857

2.2.0-alpha01 版本

2019 年 7 月 10 日

新功能

  • 預先封裝的資料庫RoomDatabase.Builder 中現在有兩個新的 API,可用於在指定已填入資料庫檔案的情況下建立 RoomDatabasecreateFromAsset() 適合用於預先填入的資料庫檔案位於 APK 素材資源資料夾的情況,createFromFile() 則適合用於檔案位於任意位置的情況。這些 API 的使用情形會改變破壞性遷移作業的行為,因此在回退遷移作業期間,如有預先填入的資料庫,Room 會嘗試重新複製該資料庫,否則將回退改為直接刪除及重新建立所有資料表。b/62185732
  • 結構定義預設值@ColumnInfo 現在提供新的屬性 defaultValue,可用於指定資料欄的預設值。預設值是資料庫結構定義的一部分,如果指定了預設值,將會在遷移作業期間進行驗證。b/64088772

    注意事項:如果您的資料庫結構定義已設有預設值 (例如透過 ALTER TABLE x ADD COLUMN y INTEGER NOTNULL DEFAULT z 新增的值),而您決定透過 @ColumnInfo 針對相同資料欄定義預設值,您可能需要提供遷移程序來驗證未納入記錄的預設值。如需詳細資訊,請參閱 Room 遷移作業

  • 多對多關係@Relation 現在提供新的屬性 associateBy,該屬性接受新的註解 @Junction,可用於宣告必須透過聯合資料表 (也稱為彙整資料表) 滿足的關係。b/69201917
  • 一對一關係:針對包含 @Relation 註解的 POJO 欄位解除了類型必須設為 ListSet 的限制,有效支援單一值關係的表示方式。b/62905145
  • 目標實體:DAO 註解 @Insert@Update@Delete 現在提供新的屬性 targetEntity,能夠指定 DAO 方法的執行目標資料表。如此一來,那些 DAO 方法的參數即成為任意 POJO,系統會將這些 POJO 解譯為部分實體。在實作中,這能夠讓使用者進行部分插入、刪除與更新。b/127549506
  • Gradle 增量註解處理工具:Room 現在是 Gradle 隔離註解處理工具,並可透過處理工具選項 room.incremental 啟用增量功能。詳情請參閱 Room 編譯器選項一文。如果遇到任何問題,請按一下 這裡 回報錯誤。我們計畫在日後的穩定版本中預設啟用增量功能。b/112110217

修正錯誤

  • 當查詢的 Rx Stream 在查詢完成前即遭到棄置時,Room 不會再將 EmptySetResultException 套用到全域錯誤處理常式。b/130257475
  • 修正了當包含 @RawQuery 註解的暫停 DAO 函式缺少傳回類型時,Room 顯示的錯誤訊息不正確的錯誤。b/134303897
  • Room 將不再產生採用原始類型的 DAO 配接器。b/135747255

2.1.0 版本

2.1.0 版本

2019 年 6 月 13 日

發布了 Room 2.1.0,對比 2.1.0-rc01 無任何變更。您可以前往這裡查看這個版本包含的修訂項目。

自 2.0.0 版以來的重要異動

  • FTS:Room 現在支援具備 FTS3 或 FTS4 對應資料表的實體。使用 @Entity 註解的類別現在可以另外加上 @Fts3@Fts4 註解,以宣告含有對應全文搜尋資料表的類別。您可透過註解的方法取得進一步的自訂的 FTS 選項。
  • 檢視畫面:Room 現在支援使用 @DatabaseView 註解,將類別宣告為已儲存的查詢,也稱為 檢視畫面
  • 協同程式:DAO 方法現在可以是暫停函式。在依附元件中納入 room-ktx,即可使用這項功能。ktx 構件也提供擴充功能函式 RoomDatabase.withTransaction,用於在協同程式內執行資料庫交易。
  • 自動值:Room 現在支援將 AutoValue 註解的類別宣告為實體和 POJO。您現在可以透過自動值註解類別的抽象方法宣告 Room 註解 @PrimaryKey@ColumnInfo@Embedded@Relation。請注意,這些註解也必須附帶 @CopyAnnotations,以供 Room 正確解讀。
  • 其他非同步支援:加註 @Insert@Delete@Update 以及包含 @QueryINSERTDELETEUPDATE 陳述式的 DAO 方法,現在支援 Rx 傳回類型 CompletableSingleMaybe,以及 Guava 的傳回類型 ListenableFuture,還可以是暫停函式。
  • enableMultiInstanceInvalidationRoomDatabase.Builder 中的新 API,可讓多個使用同一個資料庫檔案的 RoomDatabase 執行個體失效。
  • fallbackToDestructiveMigrationOnDowngradeRoomDatabase.Builder 中的新 API,可在發生降級時自動重新建立資料庫。
  • ignoredColumns@Entity 註解中的新 API,可用於依名稱列出忽略的欄位。
  • 現在,Room 會在資料類別中正確地使用 Kotlin 的主要建構函式,無需將屬性宣告為 vars

2.1.0-rc01 版本

2019 年 5 月 29 日

修正錯誤

  • 修正了由於 temp_store 設定而可能發生的 Room 初始化錯誤。b/132602198
  • 修正了向 SQLite 3.27.0 以上版本使用者顯示雙引號用法的警告訊息。b/131712640
  • 修正了 InvalidationTracker 會在同時啟動多項無效檢查時導致當機的錯誤。b/133457594

2.1.0-beta01 版本

2019 年 5 月 7 日

發布 androidx.room 2.1.0-beta01,對比 2.1.0-alpha07 版本無任何變更。您可以前往這裡查看這個版本包含的修訂項目。

2.1.0-alpha07 版本

2019 年 4 月 25 日

API/行為變更

  • 變更了擴充功能函式 RoomDatabase.withTransaction,不再將包含 CoroutineScope 的函式區塊當做接收器。這樣可以略過在交易區塊中同時執行工作所需的額外 coroutineScope { } 包裝函式。

修正錯誤

  • 修正了 Room 無法為包含 Collection 類型參數的 Kotlin DAO 函式比對 TypeConverter 的錯誤。b/122066791

2.1.0-alpha06 版本

2019 年 3 月 22 日

API/行為變更

  • 非同步交易查詢現已序列化,因此 Room 不會使用多個執行緒來執行資料庫交易。新增了 RoomDatabase.Builder.setTransactionExecutor(Executor),可用於將執行程式設定為用於交易。
  • RoomDatabase.runInTransaction(Callable) 將不再把勾選的例外狀況納入至 RuntimeExceptions 中。b/128623748

修正錯誤

  • 修正了在同時新增內容資料表和外部內容 FTS 資料表觀測工具的情況下,作廢追蹤程式會停止觀察內容資料表的錯誤。b/128508917
  • 更新了 Room 的 SQLite 文法,使其與 SQLite 3.24.0 相符。b/110883668

2.1.0-alpha05 版本

2019 年 3 月 13 日

新功能

  • 擴充函式 RoomDatabase.withTransaction 可讓您在協同程式內安全地執行資料庫交易。room-ktx 構件中提供了 Room 擴充功能和協同程式支援。
  • 加註 @Transaction 的非抽象 DAO 方法現在可以是暫停函式。b/120241587

API/行為變更

  • 按照與其他 AndroidX 構件相同的命名方式,已將構件 room-coroutines 重新命名為 room-ktx
  • 淘汰了 RoomDatabase 中的 beginTransactionsetTransactionSuccessfulendTransaction,並改用 runInTransactionroom-ktx 擴充函式 withTransaction

修正錯誤

  • 修正了所用權杖化工具為 SIMPLE 時捨棄權杖化工具引數的錯誤。b/125427014
  • 修正了 Room 無法正確識別包含類型為內部類別參數的暫停函式的錯誤。b/123767877
  • 修正了在主要執行緒中呼叫延遲執行的 @Query DAO 方法時,其所含 INSERTUPDATEDELETE 陳述式會立即準備查詢的錯誤。b/123695593
  • 修正多項錯誤:Room 先前會針對特定暫停函式產生不正確的程式碼,現在這些錯誤已經修正。b/123466702b/123457323
  • 修正錯誤:未正確在產生的程式碼中抑制方法的淘汰用法。b/117602586
  • 將 Room 的 androidx.sqlite 依附元件更新為 1.0.2,其中修正了無法正確處理資料庫損毀的問題。b/124476912

已知問題

  • Room 2.1.0-alpha05 依賴於 Maven Central 中目前不支援的 kotlinx-metadata-jvm 構件 (KT-27991)。將 maven { url "https://kotlin.bintray.com/kotlinx/" } 新增至專案存放區,即可解析這項依附元件。

2.1.0-alpha04 版本

2019 年 1 月 25 日

新功能

  • 加上 @Query 註解且含有 INSERTUPDATEDELETE 陳述式的 DAO 方法現在可傳回非同步類型 SingleMaybleCompletableListenableFuture。此外,這些方法也可以是暫停函式。b/120227284

API/行為變更

  • 現在,如果加上 @Transaction 註解的非抽象 DAO 方法傳回 SingleMaybleCompletableLiveDataListenableFuture 等非同步類型,Room 會擲回錯誤。由於交易受執行緒限制,因此 Room 目前無法開始及結束與可能在不同執行緒中執行查詢的函數相關交易。b/120109336
  • OnConflictStrategy.FAILOnConflictStrategy.ROLLBACK 已淘汰 (@Deprecated),原因在於這兩者與 Android 現有 SQLite 繫結搭配使用時的行為與預期不符。b/117266738

修正錯誤

  • 修正了 Room 在 DAO 方法為暫停函式時,無法正確使用傳回類型 TypeConverter 的錯誤。b/122988159
  • 修正了 Room 將沿用的暫停函式誤認為非暫停函式的錯誤。b/122902595
  • 修正了當 @Embedded 欄位位於父項類別且用於多個子項類別時,Room 會產生不正確程式碼的錯誤。b/121099048
  • 修正了在 beginTransaction()endTransaction() 之間叫用 DAO 暫停函式時,資料庫會出現死結的問題。b/120854786

2.1.0-alpha03 版本

2018 年 12 月 4 日

API 變更

  • @Fts3/@Fts4 中的 FTS tokenizer 現在接受 String,而非 Enum。這樣一來,Room 就能使用自訂權杖化工具。內建權杖化工具仍會透過 FtsOptions 以字串常數定義。b/119234881

新功能

  • 協同程式:DAO 方法現在可以是暫停函式。為了支援 Room 的暫停函式,我們推出了新構件 room-coroutinesb/69474692
  • 加上 @Insert@Delete@Update 註解的 DAO 方法現在支援 ListenableFuture 做為傳回類型。b/119418331

修正錯誤

  • 修正錯誤:Room 會在 @EntityignoredColumns 屬性中嘗試尋找含有資料欄的建構函式。b/119830714
  • 修正錯誤:Room 先前在所產生的實作項目中不會將 DAO 方法參數標示為最終參數,現在這個錯誤已經修正。b/118015483
  • 修正錯誤:Room 處理工具先前針對含有特殊符號的查詢回報錯誤時會當機,現在這個錯誤已經修正。b/119520136
  • 修正了 Room 會拒絕使用其他各種 Collection 實作項目做為 IN 運算式引數的錯誤。b/119884035
  • 修正了 Room 傳回的 LiveData 在有觀測活動時會遭到垃圾收集處理而再也無法發出新資料的錯誤。b/74477406
  • 更新了 RoomDatabase 的鎖定機制,以減少鎖定動作爭用情形。b/117900450

2.1.0-alpha02 版本

2018 年 10 月 30 日

新功能

  • 開始支援在 @Relation 中參照 @DatabaseViewb/117680932

修正錯誤

  • 修正了從 Rx 傳回類型進行訂閱與棄置時,Room 會在主執行緒中執行磁碟 I/O 的錯誤。b/117201279
  • 修正了 Room 無法為 Kotlin 實體類別中的欄位找到適當類型轉換工具的錯誤。b/111404868
  • 修正了當 DAO 介面實作包含的 Kotlin 預設方法沒有引數時,Room 會產生錯誤程式碼的問題。b/117527454
  • 更新了 Room 的 SQLite 文法剖析器,修正導致建構時間過長的效能問題。b/117401230

2.1.0-alpha01 版本

2018 年 10 月 8 日

新功能

  • FTS:Room 現在支援具備 FTS3 或 FTS4 對應資料表的實體。使用 @Entity 註解的類別現在可以另外加上 @Fts3@Fts4 註解,以宣告含有對應全文搜尋資料表的類別。您可以透過註解的方法存取 FTS 的進階自訂選項。b/62356416
  • 檢視畫面:Room 現在支援使用 @DatabaseView 註解,將類別宣告為已儲存的查詢,也稱為檢視畫面b/67033276
  • 自動值:Room 現在支援將包含 AutoValue 註解的類別宣告為實體和 POJO。您現在可以透過自動值註解類別的抽象方法宣告 @PrimaryKey@ColumnInfo@Embedded@Relation 這些 Room 註解。請注意,這些註解也必須附上 @CopyAnnotations,這樣 Room 才能正確解讀註解。b/62408420
  • 其他 Rx 傳回類型支援:包含 @Insert@Delete@Update 註解的 DAO 方法現在支援 Rx 傳回類型 CompletableSingle<T>Maybe<T>b/63317956
  • 包含 @Relation 的不可變動類型:Room 先前要求 @Relation 註解欄位必須可供設定,但現在可以是建構函式參數。
  • enableMultiInstanceInvalidationRoomDatabase.Builder 中的新 API,可讓多個使用同一資料庫檔案的 RoomDatabase 執行個體失效。這項多執行個體撤銷機制也適用於多個程序。b/62334005
  • fallbackToDestructiveMigrationOnDowngrade:這是 RoomDatabase.Builder 中的新 API,可在發生降級時自動重新建立資料庫。b/110416954
  • ignoredColumns:這是 @Entity 註解中的新 API,可依名稱列出遭忽略的欄位。適合用於忽略特定實體的沿用欄位。b/63522075

API/行為變更

  • RoomDatabase 中的 mCallbackmDatabase 現已淘汰 (@Deprecated),並將在下一個 Room 的主要版本中移除。b/76109329

修正錯誤

  • 修正了 Room 在初始化期間無法正確地從資料庫毀損或遷移無效錯誤中復原的兩個問題。b/111504749b/111519144
  • Room 現在會在資料類別中正確使用 Kotlin 的主要建構函式,而不必將這些欄位宣告為 varsb/105769985

2.0.0 版本

2.0.0 版本

2018 年 10 月 1 日

發布了 androidx.room 2.0.0,且自 2.0.0-rc01 以來皆無異動。

2.0.0-rc01 版本

2018 年 9 月 20 日

發布了 androidx.room 2.0.0-rc01,對比 2.0.0-beta01 版本無任何變更。

2.0.0-beta01 版本

2018 年 7 月 2 日

API/行為變更

  • 新增了 RoomDatabase.Builder.setQueryExecutor(),以便自訂查詢執行位置
  • 新增了 RxJava2 Observable 支援
  • 原先產生的 DAO 和資料庫實作現已定案

修正錯誤

  • 指定「cannot find getter for field」(找不到欄位的 getter) 錯誤訊息中的類別/欄位名稱 b/73334503
  • 修正了 RoomOpenHelper 與 Room 較舊版本的回溯相容性問題 b/110197391

Pre-AndroidX 依附元件

使用 AndroidX 之前的 Room 版本時,請加入下列依附元件:

dependencies {
    def room_version = "1.1.1"

    implementation "android.arch.persistence.room:runtime:$room_version"
    annotationProcessor "android.arch.persistence.room:compiler:$room_version" // For Kotlin use kapt instead of annotationProcessor

    // optional - RxJava support for Room
    implementation "android.arch.persistence.room:rxjava2:$room_version"

    // optional - Guava support for Room, including Optional and ListenableFuture
    implementation "android.arch.persistence.room:guava:$room_version"

    // Test helpers
    testImplementation "android.arch.persistence.room:testing:$room_version"
}

1.1.1 版

1.1.1 版

2018 年 6 月 19 日

Room 1.1.1 與 Room 1.1.1-rc1 完全相同。

1.1.1-rc1 版本

2018 年 5 月 16 日 如要使用遷移作業,強烈建議您使用 Room 1.1.1-rc1,而非 1.1.0

修正了 Room 無法正確地處理遷移後初始化作業的問題 b/79362399

1.1.0 版本

1.1.0-beta3 版本

2018 年 4 月 19 日

修正錯誤

  • 修正當 Kotlin POJO 參照 Java 中定義的關聯實體時發生的編譯錯誤 b/78199923

1.1.0-beta2 版本

2018 年 4 月 5 日

修正錯誤

  • 修正了 Room 的 Rx SingleMaybe 實作中提前回收查詢的重大錯誤;在該錯誤的影響下,如果您在傳回的 SingleMaybe 執行個體中加入超過 1 個觀測工具,就會發生問題。b/76031240

  • [RoomDatabase.clearAllTables][ref-clearAllTables] 不會在交易中呼叫的情況下對資料庫執行 VACUUM 操作。b/77235565

1.1.0-beta1 版本

2018 年 3 月 21 日

API 變更

  • 根據 API 審查意見回饋,@RawQuery 不再接受傳遞 String 做為查詢參數。您需要使用 [SupportSQLiteQuery][ref-SupportSQLiteQuery]。如要輕鬆建立具有引數支援的 [SupportSQLiteQuery][ref-SupportSQLiteQuery] 執行個體,請見 [SimpleSQLiteQuery][ref-SimpleSQLiteQuery]。
  • RoomDatabase.Builder 的 [fallbackToDestructiveMigrationFrom][ref-fallbackToDestructiveMigrationFrom] 方法現在接受 vararg int,而不是 vararg Integer

修正錯誤

  • [RoomDatabase.clearAllTables][ref-clearAllTables] 現在會嘗試設定 WAL 檢查點並對資料庫執行 VACUUM 操作,將空間還給作業系統。
  • [@RawQuery][ref-RawQuery] 現在接受在 observedEntities 屬性中使用任何 Pojo,前提是 Pojo 透過其 Embedded 欄位或 Relation 參照了一或多個實體。b/74041772
  • Paging:Room 的 DataSource 實作現在能夠正確地處理多資料表依附元件 (例如關係和彙整項目)。先前,這些方法無法觸發新結果,或是可能無法編譯。b/74128314

1.1.0-alpha1 版本

2018 年 1 月 22 日

新功能

  • RawQuery:這個新的 API 允許 @Dao 方法接收 SQL 做為查詢參數 b/62103290b/71458963
  • fallBackToDestructiveMigrationsFromRoomDatabase.Builder 中的這個新的 API 可讓您精細掌控要從哪個起始結構定義版本允許破壞性遷移 (與 fallbackToDestructiveMigration 相比) b/64989640
  • Room 現在僅支援新版 Paging API (alpha-4 以上版本),不再支援已淘汰的 LivePagedListProvider。如要使用新的 Room Alpha 版,您需要使用 Paging alpha-4 以上版本,並從 LivePagedListProvider 切換至 LivePagedListBuilder (如果尚未這麼做的話)。

修正錯誤

  • 改善對 Kotlin Kapt 類型的支援。b/69164099
  • 欄位順序不會再使結構定義失效。b/64290754