Room

Room 持續性資料庫是 SQLite 提供的抽象層,讓您在充分運用 SQLiteg 的強大效能時,也能順暢且穩定地存取資料庫。
最近更新時間 穩定版 候選版 Beta 版 Alpha 版
2022 年 8 月 24 日 2.4.3 - - 2.5.0-alpha03

宣告依附元件

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

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

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

Groovy

dependencies {
    def room_version = "2.4.3"

    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:2.5.0-alpha03"
}

Kotlin

dependencies {
    val room_version = "2.4.3"

    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:2.5.0-alpha03")
}

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

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

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

設定編譯器選項

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

  • room.schemaLocation:設定及啟用將資料庫結構定義匯出至指定目錄內的 JSON 檔。如需詳細資訊,請參閱 Room 遷移作業
  • room.incremental:啟用 Gradle 增量註解處理工具。
  • room.expandProjection:設定 Room 以改寫查詢,藉由擴充頂層星號投射,僅納入 DAO 方法傳回類型中所定義的資料欄。

下列程式碼片段示範如何設定這些選項:

Groovy

android {
    ...
    defaultConfig {
        ...
        javaCompileOptions {
            annotationProcessorOptions {
                arguments += [
                    "room.schemaLocation":"$projectDir/schemas".toString(),
                    "room.incremental":"true",
                    "room.expandProjection":"true"]
            }
        }
    }
}

Kotlin

android {
    ...
    defaultConfig {
        ...
        javaCompileOptions {
            annotationProcessorOptions {
                arguments += mapOf(
                    "room.schemaLocation" to "$projectDir/schemas",
                    "room.incremental" to "true",
                    "room.expandProjection" to "true"
                )
            }
        }
    }
}

意見回饋

您的意見可協助我們改善 Jetpack。發現新的問題或有改善這個程式庫的想法時,請告訴我們。建立新的問題之前,請先查看這個程式庫中的現有問題。只要按一下星號按鈕,即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 說明文件

2.5.0 版本

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)、(I96c25b/206859668)

    注意:由於程式庫轉換為 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 變更

  • @RemoveUnusedColumns 是全新的便捷註解,可讓 Room 重寫查詢中的「*」投影,以便讓系統移除結果中未使用的資料欄。
  • 處理器選項 room.expandProjection 現已淘汰。使用 @RemoveUnusedColumns 取代 Room 藉由星號投影最佳化查詢。請注意,關於包含 @Embedded 欄位的傳回類型,@RemoveUnusedColumn 並不會取代 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
  • 修正了含有 INSERTUPDATEDELETE 陳述式的延遲執行 @Query DAO 方法在主執行緒中急切準備查詢的問題。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 中參照 @DatabaseView 的支援機制。b/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 註解欄位必須可供設定,但現在可以是建構函式參數。
  • enableMultiInstanceInvalidation:這是 RoomDatabase.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 和資料庫實作現已定案

修正錯誤

  • 在「找不到欄位的 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