房間

宣告依附元件

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

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

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

dependencies {
    val room_version = "2.6.1"

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

    // If this project uses any Kotlin source, use Kotlin Symbol Processing (KSP)
    // See Add the KSP plugin to your project
    ksp("androidx.room:room-compiler:$room_version")

    // If this project only uses Java source, use the Java annotationProcessor
    // No additional plugins are necessary
    annotationProcessor("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")
}

dependencies {
    def room_version = "2.6.1"

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

    // If this project uses any Kotlin source, use Kotlin Symbol Processing (KSP)
    // See KSP Quickstart to add KSP to your build
    ksp "androidx.room:room-compiler:$room_version"

    // If this project only uses Java source, use the Java annotationProcessor
    // No additional plugins are necessary
    annotationProcessor "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"
}

如要進一步瞭解如何使用 KAPT 外掛程式，請參閱 KAPT 說明文件。

如要進一步瞭解如何使用 KSP 外掛程式，請參閱 KSP 快速入門說明文件。

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

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

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

設定編譯器選項

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

使用 Room Gradle 外掛程式

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

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

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

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

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

plugins {
    id 'androidx.room'
}

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

plugins {
    id("androidx.room")
}

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

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

雖然 Room 編譯器支援部分選項，但並非所有版本的 Room Gradle 外掛程式都能設定這些選項。下表列出各個選項，並顯示 Room Gradle 外掛程式版本，該版本新增了使用 room 擴充功能設定該選項的支援功能。如果您使用的版本較低，或是系統尚未支援該選項，可以改用註解處理器選項。

使用註解處理工具選項

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

// 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...
                    ]
            }
        }
    }
}

// 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.7 版

2.7.0-alpha11 版

2024 年 10 月 30 日

發布 androidx.room:room-*:2.7.0-alpha11。2.7.0-alpha11 版包含這些修訂版本。

API 變更

• 請再次查看新加入的 convertRows() 方法簽章，將其設為可接收房間分頁 RawRoomQuery 的暫停函式。(Ie57b5、b/369136627)。

修正錯誤

• 修正了在 Room Paging 中，當 @Relation 與 PagingSource 搭配使用時，會產生無效程式碼的問題。

2.7.0-alpha10 版

2024 年 10 月 16 日

發布 androidx.room:room-*:2.7.0-alpha10。2.7.0-alpha10 版包含這些修訂項目。

API 變更

• 建立內部 ByteArrayWrapper 類別，以便在非 Android 和非 JVM 平台中支援與 ByteBuffer 的關係。(I75543、b/367205685)。
• 新增 SQLiteStatement.getColumnType() 和各種 SQLITE_DATA_* 結果常數，即可擷取資料欄的資料類型。(I1985c、b/369636251)。

2.7.0-alpha09 版

2024 年 10 月 2 日

發布 androidx.room:room-*:2.7.0-alpha09。2.7.0-alpha09 版包含這些修訂項目。

修正錯誤

• 修正 room-paging 的 KMP 實作問題，該問題會因在讀取連線上啟動寫入交易而導致 Error code: 8, message: attempt to write a readonly database。(b/368380988)。

2.7.0-alpha08 版

2024 年 9 月 18 日

發布 androidx.room:room-*:2.7.0-alpha08。2.7.0-alpha08 版包含這些修訂項目。

新功能

• room-paging 構件已遷移至與 KMP 相容的版本。(Ib8756、b/339934824)
• API invalidationTrackerFlow() 已通用化為第一方 API InvalidationTracker.createFlow()，現在可用於 KMP 專案中的非 Android 來源集。(I1fbfa、(I8fb29)、b/329291639、b/329315924)。

API 變更

• Room 中所有使用 Cursor 一詞的警告和錯誤訊息都已移除或取代，因為 Cursor 不再是 Room 的 KMP 版本中使用的正確通用字詞。(Id8cd9、b/334087492)

修正錯誤

• 已修正 Room KMP 會嘗試針對非 JVM 平台使用 UUID 發出程式碼的問題。(b/362994709)。
• 修正在搭配 Compose Multiplatform 使用 KMP 專案時，使用 Room Gradle 外掛程式時會導致錯誤，例如「無法變更設定的屬性...」這類錯誤。(b/343408758)

2.7.0-alpha07 版

2024 年 8 月 21 日

發布 androidx.room:room-*:2.7.0-alpha07。2.7.0-alpha07 版包含這些修訂項目。

新功能

• Room Gradle 外掛程式現在會自動將匯出的結構定義新增至 Android 檢測工具測試資源來源，以便 MigrationTestHelper 使用。

修正錯誤

• 修正了 RoomDatabaseConstructor 產生的「actual」在 initialize 函式中缺少「actual」修飾符的問題，如果該函式也已在「expect」宣告中覆寫。(359631627)。
• 修正了 RoomDatabaseConstructor 產生的「actual」值與「expect」宣告的顯示設定不符的問題。(358138953)。

2.7.0-alpha06 版

2024 年 8 月 7 日

發布 androidx.room:room-*:2.7.0-alpha06。2.7.0-alpha06 版包含這些修訂項目。

API 變更

• 變更 KMP 專案中 RoomDatabase 的例項化設定。

由於 Kotlin 2.0 編譯模型，參照名為 instantiateImpl() 的待產生函式策略不再可行。我們推出了兩個新的 API (@ConstructedBy 和 RoomDatabaseConstructor)，取代 instantiateImpl() 策略。新策略如下：

1. 定義實作 RoomDatabaseConstructor 的預期物件

     expect object MyDatabaseCtor : RoomDatabaseConstructor<MyDatabase>
   

2. 使用 @ConstructedBy 將物件連結至 @Database 宣告

     @Database(...)
     @ConstructedBy(MyDatabaseCtor::class) // NEW
     abstract class MyDatabase : RoomDatabase
   

3. 建立新的資料庫執行個體，但未傳遞工廠引數

     fun createNewDatabase(path: String) =
       Room.databaseBuilder<AppDatabase>(name = path)
         .setDriver(BundledSQLiteDriver())
         .setQueryCoroutineContext(Dispatchers.IO)
         .build()
   

修正 b/316978491、b/338446862 和 b/342905180

• 在 Room KMP 中支援 @RawQuery，方法是新增名為 RoomRawQuery 的新 API，該 API 與 SupportSQLiteQuery 類似，可保留原始 SQL 字串，並提供將引數繫結至陳述式的函式。@RawQuery 註解函式現在可接受 RoomRawQuery 做為單一參數。(Iea844、b/330586815)。
• 新增可接受 CoroutineContext 的 setQueryCallback() 超載。(Id66ff、b/309996304)。
• 新增對 linuxArm64 Kotlin Multiplatform 目標的支援 (I139d3，b/338268719)

修正錯誤

• 修正問題：Room 會在非 Android 目標中不正確產生對 recursiveFetchArrayMap 的呼叫。(710c36、b/352482325)。
• 修正在 KMP 專案中，Room 有時會擲回「嘗試連線逾時」異常值的問題。(fa72d0、b/347737870)
• 修正自動遷移作業中的問題，該問題會在其他資料表變更其結構定義以符合新外鍵之前，過早檢查外鍵。(7672c0、b/352085724)。

2.7.0-alpha05 版

2024 年 7 月 10 日

發布 androidx.room:room-*:2.7.0-alpha05。2.7.0-alpha05 版包含這些修訂項目。

API 變更

• 已將 SQLiteKt 重新命名為 SQLite，並將 BundledSQLiteKt 重新命名為 BundledSQLite。(I8b501)。

修正錯誤

• 修正錯誤：使用 AndroidSQLiteDriver 時，RoomDatabase 會發生死結或連線逾時錯誤。

2.7.0-alpha04 版

2024 年 6 月 12 日

發布 androidx.room:room-*:2.7.0-alpha04。2.7.0-alpha04 版包含這些修訂版本。

修正錯誤

• 修正了以下問題：在 DAO 中定義多重對應傳回類型時，Room 的註解處理工具會產生不相容的 KMP 程式碼。(b/340983093)
• 修正了以下問題：如果 @Database 註解類別沒有套件，Room 就無法找到產生的資料庫實作項目。(b/342097292)
• 修正了啟用自動關閉和多重執行個體無效功能時，當資料庫因閒置而自動關閉時，有時會導致 ConcurrentModificationException 的問題。

2.7.0-alpha03 版

2024 年 5 月 29 日

發布 androidx.room:room-*:2.7.0-alpha03。2.7.0-alpha03 版包含這些修訂項目。

修正錯誤

• 修正 Kotlin 2.0 和 KSP 2.0 的各種問題。請注意，支援 KSP 2 的 Kotlin 2.0 尚未完成，團隊正在處理新編譯器中的各種 API 和行為變更。(b/314151707)。

2.7.0-alpha02 版

2024 年 5 月 14 日

發布 androidx.room:room-*:2.7.0-alpha02。2.7.0-alpha02 版包含這些修訂版本。

修正錯誤

• 修正各種 KSP 問題。

2.7.0-alpha01 版

2024 年 5 月 1 日

發布 androidx.room:room-*:2.7.0-alpha01。2.7.0-alpha01 版本包含這些修訂版本。

新功能

• Kotlin Multiplatform (KMP) 支援：在這個版本中，Room 已重構為 Kotlin Multiplatform (KMP) 程式庫。雖然仍有待完成的工作，但這個版本推出了新版 Room，其中大部分功能已「通用化」(可用於多個平台)。目前支援的平台包括 Android、iOS、JVM (電腦版)、原生 Mac 和原生 Linux。在即將支援的平台中，任何缺少的功能都會在即將推出的 Room 版本中「功能完整」。

如要進一步瞭解如何開始使用 Room KMP，請參閱 Room KMP 官方說明文件。

• 如果透過 KSP 進行處理，則 KSP 上的 Kotlin 程式碼生成功能預設為「開啟」。針對僅限 KAPT 或 Java 的專案，Room 仍會產生 Java 來源。

API 變更

• 我們已新增 Room.databaseBuilder() 超載，該超載會採用 lambda 參數，並與 Room 產生的函式搭配使用，以便在例項化產生的 RoomDatabase 實作時避免使用反射。使用方式範例如下：

Room.databaseBuilder<MyDatabase>(
    context = appContext,
    name = dbFilePath,
    factory =  { MyDatabase::class.instantiateImpl() }
)

• 已將使用 CoroutineContext 設定 Room 的 API 新增至建構工具：RoomDatabase.Builder.setQueryCoroutineContext。請注意，RoomDatabase 只能使用 setQueryExecutor 執行緒或 Coroutine 執行緒設定，兩者皆不可同時使用。
• 已新增透過 SQLite 驅動程式設定 Room 的 API：RoomDatabase.Builder.setDriver()。如要進一步瞭解 SQLite Driver API，請參閱 SQLite KMP 說明文件
• 新增了 RoomDatabase.useReaderConnection 和 RoomDatabase.useWriterConnection 這兩個 API，可從驅動程式 API 存取底層 SQLiteConnection。
• Varios Room 相關回呼現在有超載版本，可接收 SQLiteConnection 而非 SupportSQLiteDatabase。這些值會在遷移至 KMP 專案時覆寫。如要進一步瞭解如何將 Android 應用程式中的 Room 用法遷移至常見的 KMP 模組，請參閱遷移指南。回呼如下：
  • Migration.migrate(SQLiteConnection)
  • AutoMigrationSpec.onPostMigrate(SQLiteConnection)
  • RoomDatabase.Callback.onCreate(SQLiteConnection)
  • RoomDatabase.Callback.onDestructiveMigration(SQLiteConnection)
  • RoomDatabase.Callback.onOpen(SQLiteConnection)
• KTX 構件 androidx.room:room-ktx 已與 androidx.room:room-runtime 的所有 API 合併，構件現為空白。請從依附元件清單中移除此項目。

2.6 版本

2.6.1 版

2023 年 11 月 29 日

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

修正錯誤

• 解決產生程式碼中的問題，在 EntityCursorConverter 中，Double 資料欄的預設值會設為 0 而非 0.0。我們也針對類似的邊緣情況 (浮點型欄) 提供可能的修正方式。(Id75f5、b/304584179)。
• 從 PagingSource 載入擲回的例外狀況，現在會以包含 Throwable 的 LoadResult.Error 的 LoadStateUpdate 形式傳播。您可以透過 PagingDataAdapter.loadStateFlow(Views) 或 LazyPagingItems.loadState(Compose) 觀察這個錯誤狀態。請注意，這項變更會導致行為變更，過去的載入錯誤會以例外狀況的形式傳遞，而這類例外狀況是由觸發載入的 dao 方法擲回。(I93887、b/302708983)。

2.6.0 版

2023 年 10 月 18 日

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

自 2.5.0 版以來的重要變更

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

注意：使用 Kotlin CodeGen 時，請務必注意新增的額外限制。在 Kotlin CodeGen 中，系統不允許將抽象屬性做為 DAO getter 或 DAO 查詢，而是應將其重寫為函式，以免產生屬性值不可變動且具有固定儲存結果的錯誤觀念。另外，我們也新增了另一項限制，即 Room for Kotlin CodeGen 不再允許使用 Nullable 集合傳回類型。

警告：使用 Kotlin CodeGen 時，您可能會發現專案對「是否可為空值」設定更嚴格。在 Kotlin CodeGen 中，類型引數的是否可為空值很重要，但在 Java 中，這項資訊通常會遭到忽略。舉例來說，假設您有 `Flow<foo\>` 傳回類型，且表格為空白。在 Java CodeGen 中，這不會造成任何問題，但在 Kotlin CodeGen 中，您會收到錯誤。為避免這種情況，您需要使用 `Flow<foo?\>`，假設會傳送 null。</foo?\></foo\>

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

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 例外狀況，更新/插入應執行更新。(If2849、b/243039555)。

2.6.0-alpha03 版本

2023 年 8 月 9 日

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

新功能

• Room 現已支援 DAO 函式中的巢狀 Map 傳回類型。(I13f48、203008711)。

API 變更

• 我們已建立名為 @MapColumn 的新型別註解，取代現已淘汰的 @MapInfo。針對 @MapInfo 註解中提供的每個資料欄名稱 (keyColumnName、valueColumnName 或兩者皆是)，您必須宣告只包含 columnName 的 @MapColumn 註解，並在 DAO 函式的傳回類型中使用註解，參照 DAO 函式的傳回類型中所參照的特定類型引數 (Map 的鍵或值)。這是因為 @MapColumn 註解會直接用於 DAO 函式的傳回類型中的類型引數，而不是 @MapInfo 等函式本身。詳情請參閱 @MapColumn 說明文件。(Ib0305、b/203008711)
• 更新 API 檔案，以標註相容性抑制 (I8e87a、b/287516207)
• Room Gradle 外掛程式 API 已更新，因此不一定需要個別變化版本設定。這表示外掛程式可接受所有變化版本的全域位置，而無須建立多個目錄，這樣遷移作業就能更順暢，而且還能保有手動設定變種版本或建構類型結構定義的彈性，同時保有外掛程式的優勢 (可重現且可快取的版本)。(I09d6f、b/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 外掛程式

這個新版本包含 ID 為 androidx.room 的 Room Gradle 外掛程式新構件，該構件解決了 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 轉換用途。(Iab8ea、b/281008549)

修正錯誤

• 解決在將 Room 來源從 Java 遷移至 Kotlin 後，在 Robolectric 中將資料庫例項化時發生的問題。(Ic053c、b/274924903)。

2.6.0-alpha01 版本

2023 年 3 月 22 日

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

新功能

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

注意：使用 Kotlin CodeGen 時，請務必注意新增的額外限制。Kotlin CodeGen 禁止將抽象屬性當做 DAO getter 或 DAO 查詢，而是應將這類屬性改寫為函式，以避免出現屬性值不可變的誤解，且具有固定儲存的結果。另外，我們也新增了另一項限制，即 Kotlin CodeGen 的 Room 中不再允許使用 Nullable 集合傳回類型。

警告：使用 Kotlin CodeGen 時，您可能會發現專案在是否可為空值方面更加嚴格。在 Kotlin CodeGen 中，類型引數的是否可為空值很重要，但在 Java 中，這項資訊通常會遭到忽略。舉例來說，假設您有 `Flow<foo\>` 傳回類型，且表格為空白。在 Java CodeGen 中，這不會造成任何問題，但在 Kotlin CodeGen 中，您會收到錯誤。為避免這種情況，您必須使用 `Flow<foo?\>`，假設會傳送 null。</foo?\></foo\>

API 變更

• 避免在 DAO 方法傳回類型中使用無意義的 nullable 集合。(I777dc、b/253271782、b/259426907)。
• 新增 API，用於建立會傳送無效追蹤器變更的資料流。如果想建立必須回應資料庫變更的串流，這個 API 就非常實用。(I8c790、b/252899305)。

修正錯誤

• 在 Kotlin CodeGen 中，禁止使用抽象屬性做為 DAO Getter 或 DAO 查詢，應改為將其重寫為函式，以免產生屬性值不可變動且具有固定儲存結果的錯誤觀念。(If6a13、b/127483380、b/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 擲回錯誤的問題。(f79bea、b/274924903)。

2.5.1 版

2.5.1 版

2023 年 3 月 22 日

發布 androidx.room:room-*:2.5.1。2.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.0、androidx.room:room-paging-rxjava2:2.5.0 和 androidx.room:room-paging-rxjava3:2.5.0。2.5.0 版包含此連結所列的修訂項目。

2.5.0 版

2023 年 1 月 11 日

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

自 2.4.0 版本以來的重要異動

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

2.5.0-rc01 版本

2022 年 12 月 7 日

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

• 這個版與 2.5.0-beta02 相同。

2.5.0-beta02 版

2022 年 11 月 9 日

發布了 androidx.room:room-*:2.5.0-beta02。2.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-beta01。2.5.0-beta01 版包含此連結所列的修訂項目。

API 變更

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

修正錯誤

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

2.5.0-alpha03 版本

2022 年 8 月 24 日

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

新功能

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

修正錯誤

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

2.5.0-alpha02 版本

2022 年 6 月 1 日

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

新功能

• 在 Room Paging 中新增了 room-paging 構件 room-paging-rxjava2、room-paging-rxjava3 和 room-paging-guava 以提供支援。(41a1d4、b/203666906)、(eb6098、b/203666906)、(1b9ae4、b/203666906)

API 變更

• 所有 room-runtime 構件均已從 Java 轉換為 Kotlin。(If2069、b/206859668)、(Ie4b55、b/206859668)、(I697ee、b/206859668)、(I96c25、b/206859668)

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

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

修正錯誤

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

2.5.0-alpha01 版本

2022 年 2 月 23 日

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

API 變更

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

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

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

修正錯誤

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

2.4.3 版本

2.4.3 版本

2022 年 7 月 27 日

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

修正錯誤

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

2.4.2 版本

2.4.2 版本

2022 年 2 月 23 日

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

修正錯誤

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

2.4.1 版本

2.4.1 版本

2022 年 1 月 12 日

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

修正錯誤

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

2.4.0 版本

2.4.0 版本

2021 年 12 月 15 日

發布 androidx.room:room-*:2.4.0。2.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 陳述式很實用。支援的多重對應類型包括 Map、SparseArray、LongSparseArray，以及 Guava 的 ImmutableMap、ImmutableSetMultimap 和 ImmutableListMultimap。

2.4.0-rc01 版本

2021 年 12 月 1 日

發布 androidx.room:room-*:2.4.0-rc01。2.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-beta02。2.4.0-beta02 版包含此連結所列的修訂項目。

新功能

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

修正錯誤

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

2.4.0-beta01 版本

2021 年 10 月 13 日

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

修正錯誤

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

2.4.0-alpha05 版本

2021 年 9 月 29 日

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

新功能

• 新增了一個適用於 UUID 的內建類型轉換工具。(I671e8、b/73132006)

API 變更

• 在 TypeTransformers 註解中新增了一個屬性，讓開發人員停用內建的 Enum 和 UUID 轉換工具。這些轉換工具預設為開啟，但您可以針對特定範圍或整個資料庫將其停用。詳情請參閱 TypeConverters 說明文件。(36ae9e、b/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-alpha04。2.4.0-alpha04 版包含此連結所列的修訂項目。

新功能

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

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

  一對一關係對應

  @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-alpha03。2.4.0-alpha03 版包含此連結所列的修訂項目。

API 變更

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

修正錯誤

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

• 修正了以下問題：當 @Transaction 函式的傳回類型是 Flow 時，Room 就不會出錯 (I56ddd、b/190075899)

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

依附元件更新

• Room 的 KSP 支援現在依賴 KSP 1.5.10-1.0.0-beta01。(1ecb11、b/160322705)

2.4.0-alpha02 版本

2021 年 5 月 5 日

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

API 變更

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

修正錯誤

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

外部貢獻

• 修正 Room 的 JournalMode.TRUNCATE 中的一個問題，即有時無效，或是太晚或根本未叫用 InvalidationTracker 回呼的問題。歸功於 Uli Bubenheimer | [email protected] (b/154040286)

2.4.0-alpha01 版本

2021 年 4 月 21 日

發布了 androidx.room:room-*:2.4.0-alpha01。2.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.0。2.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-rc01。2.3.0-rc01 版包含此連結所列的修訂項目。

修正錯誤

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

2.3.0-beta03 版本

2021 年 3 月 10 日

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

新功能

• 新增了 KSP 的增量編譯支援。(I031c1、b/176453350)

修正錯誤

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

外部貢獻

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

2.3.0-beta02 版本

2021 年 2 月 18 日

發布了 androidx.room:room-*:2.3.0-beta02。2.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-beta01。2.3.0-beta01 版包含此連結所列的修訂項目。

新功能

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

修正錯誤

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

2.3.0-alpha04 版本

2020 年 12 月 16 日

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

新功能

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

已知問題

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

修正錯誤

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

外部貢獻

• 如果 WAL 模式已啟用且 API 級別為16 以上，Room 現在將預設使用 beginTransactionNonExclusive。非常非常感謝「Ahmed I. Khalil | [email protected]」！(b/126258791)

2.3.0-alpha03 版本

2020 年 10 月 14 日

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

新功能

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

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

API 變更

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

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

修正錯誤

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

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

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

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

外部貢獻

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

• 將 RoomDatabase 中的 ConcurrentHashMap 替換成 Collections.synchronizedMap()，以避免在 Android Lollipop 上出現問題 (d1cfc7、b/162431855)

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

2.3.0-alpha02 版

2020 年 7 月 22 日

發布了 androidx.room:room-*:2.3.0-alpha02。2.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-alpha01。2.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 ([email protected]) (b/155215201)
• Room 現在會將其 ANTLR 依附元件嵌入註解處理工具，以避免與其他處理 ANTLR 的處理工具發生衝突。(b/150106190)

2.2.6 版本

2.2.6 版本

2020 年 12 月 16 日

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

修正錯誤

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

2.2.5 版本

2.2.5 版本

2020 年 3 月 18 日

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

修正錯誤

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

2.2.4 版本

2.2.4 版本

2020 年 2 月 19 日

發布了 androidx.room:room-common:2.2.4、androidx.room:room-compiler:2.2.4、androidx.room:room-guava:2.2.4、androidx.room:room-ktx:2.2.4、androidx.room:room-migration:2.2.4、androidx.room:room-runtime:2.2.4、androidx.room:room-rxjava2:2.2.4 和 androidx.room:room-testing:2.2.4。2.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.3。2.2.3 版包含此連結所列的修訂項目。

修正錯誤

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

2.2.2 版本

2.2.2 版本

2019 年 11 月 20 日

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

修正錯誤

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

2.2.1 版本

2.2.1 版本

2019 年 10 月 23 日

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

修正錯誤

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

2.2.0 版本

2.2.0 版本

2019 年 10 月 9 日

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

自 2.1.0 版以來的重要異動

• 預先封裝的資料庫：RoomDatabase.Builder 中現在有兩個新的 API，可用於在指定已填入資料庫檔案的情況下建立 RoomDatabase。createFromAsset() 適合用於預先填入的資料庫檔案位於 APK 素材資源資料夾的情況，createFromFile() 則適合用於檔案位於任意位置的情況。這些 API 的使用情形會改變破壞性遷移作業的行為，因此在回退遷移作業期間，如有預先填入的資料庫，Room 會嘗試重新複製該資料庫，否則將回退改為直接刪除及重新建立所有資料表。b/62185732
• 結構定義預設值：@ColumnInfo 現在提供新的屬性 defaultValue，可用於指定資料欄的預設值。預設值是資料庫結構定義的一部分，如果指定了預設值，將會在遷移作業期間進行驗證。b/64088772
• 多對多關係：@Relation 現在提供新的屬性 associateBy，該屬性接受新的註解 @Junction，可用於宣告必須透過聯合資料表 (也稱為彙整資料表) 滿足的關係。b/69201917
• 一對一關係：針對包含 @Relation 註解的 POJO 欄位解除了類型必須設為 List 或 Set 的限制，有效支援單一值關係的表示方式。b/62905145
• 目標實體：DAO 註解 @Insert、@Update 和 @Delete 現在提供新的屬性 targetEntity，能夠指定 DAO 方法的執行目標資料表。如此一來，那些 DAO 方法的參數即成為任意 POJO，系統會將這些 POJO 解譯為部分實體。在實作中，這能夠讓使用者進行部分插入、刪除與更新。b/127549506
• 協同程式流程：@Query DAO 方法現在可以設為 Flow<T> 傳回類型。如果查詢中的觀察資料表無效，傳回的流程將重新發出一組新值。宣告 DAO 函式並將傳回類型設為 Channel<T> 將導致錯誤，Room 建議您改用 Flow，再使用相鄰的函式將 Flow 轉換成 Channel。b/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 轉換成 Channel。b/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 更新了產生的程式碼，以使用可比較的 ByteBuffer。b/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，可用於在指定已填入資料庫檔案的情況下建立 RoomDatabase。createFromAsset() 適合用於預先填入的資料庫檔案位於 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 欄位解除了類型必須設為 List 或 Set 的限制，有效支援單一值關係的表示方式。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 以及包含 @Query、INSERT、DELETE 或 UPDATE 陳述式的 DAO 方法，現在支援 Rx 傳回類型 Completable、Single、Maybe，以及 Guava 的傳回類型 ListenableFuture，還可以是暫停函式。
• enableMultiInstanceInvalidation 是 RoomDatabase.Builder 中的新 API，可讓多個使用同一個資料庫檔案的 RoomDatabase 執行個體失效。
• fallbackToDestructiveMigrationOnDowngrade 是 RoomDatabase.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 中的 beginTransaction、setTransactionSuccessful 和 endTransaction，並改用 runInTransaction 和 room-ktx 擴充函式 withTransaction。

修正錯誤

• 修正了所用權杖化工具為 SIMPLE 時捨棄權杖化工具引數的錯誤。b/125427014
• 修正了 Room 無法正確識別包含類型為內部類別參數的暫停函式的錯誤。b/123767877
• 修正了在主要執行緒中呼叫延遲執行的 @Query DAO 方法時，其所含 INSERT、UPDATE 或 DELETE 陳述式會立即準備查詢的錯誤。b/123695593
• 修正多項錯誤：Room 先前會針對特定暫停函式產生不正確的程式碼，現在這些錯誤已經修正。b/123466702 和 b/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 註解且含有 INSERT、UPDATE 或 DELETE 陳述式的 DAO 方法現在可傳回非同步類型 Single、Mayble、Completable 和 ListenableFuture。此外，這些方法也可以是暫停函式。b/120227284

API/行為變更

• 現在，如果加上 @Transaction 註解的非抽象 DAO 方法傳回 Single、Mayble、Completable、LiveData 或 ListenableFuture 等非同步類型，Room 會擲回錯誤。由於交易受執行緒限制，因此 Room 目前無法開始及結束與可能在不同執行緒中執行查詢的函數相關交易。b/120109336
• OnConflictStrategy.FAIL 和 OnConflictStrategy.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-coroutines。b/69474692
• 加上 @Insert、@Delete 或 @Update 註解的 DAO 方法現在支援 ListenableFuture 做為傳回類型。b/119418331

修正錯誤

• 修正錯誤：Room 會在 @Entity 的 ignoredColumns 屬性中嘗試尋找含有資料欄的建構函式。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 傳回類型 Completable、Single<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 中的 mCallback 和 mDatabase 現已淘汰 (@Deprecated)，並將在下一個 Room 的主要版本中移除。b/76109329

修正錯誤

• 修正了 Room 在初始化期間無法正確地從資料庫毀損或遷移無效錯誤中復原的兩個問題。b/111504749 和 b/111519144
• Room 現在會在資料類別中正確使用 Kotlin 的主要建構函式，而不必將這些欄位宣告為 vars。b/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 Single 和 Maybe 實作中提前回收查詢的重大錯誤；在該錯誤的影響下，如果您在傳回的 Single 或 Maybe 執行個體中加入超過 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/62103290、b/71458963
• fallBackToDestructiveMigrationsFrom：RoomDatabase.Builder 中的這個新的 API 可讓您精細掌控要從哪個起始結構定義版本允許破壞性遷移 (與 fallbackToDestructiveMigration 相比) b/64989640
• Room 現在僅支援新版 Paging API (alpha-4 以上版本)，不再支援已淘汰的 LivePagedListProvider。如要使用新的 Room Alpha 版，您需要使用 Paging alpha-4 以上版本，並從 LivePagedListProvider 切換至 LivePagedListBuilder (如果尚未這麼做的話)。

修正錯誤

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