Room

声明依赖项

如需添加 Room 的依赖项，您必须将 Google Maven 制品库添加到项目中。如需了解详情，请参阅 Google 的 Maven 制品库。

Room 的依赖项包括测试 Room 迁移和 Room RxJava。

在应用或模块的 build.gradle 文件中添加所需工件的依赖项：

dependencies {
    val room_version = "2.7.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.7.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 文档。

如需详细了解依赖项，请参阅添加 build 依赖项。

或者，对于非 Android 库（即仅支持 Java 或 Kotlin 的 Gradle 模块），您可以依赖 androidx.room:room-common 来使用 Room 注解。

配置编译器选项

Room 具有以下注解处理器选项。

使用 Room Gradle 插件

在 Room 2.6.0 及更高版本中，您可以使用 Room Gradle 插件为 Room 编译器配置选项。该插件会配置项目，以便正确配置生成的架构（编译任务的输出，用于自动迁移），以便获得可重现且可缓存的 build。

如需添加该插件，请在顶级 Gradle build 文件中定义该插件及其版本。

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

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

在模块级 Gradle build 文件中，应用该插件并使用 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 Gradle 插件中配置，即使 Room 编译器支持这些选项也是如此。下表列出了每个选项，并显示了添加了使用 room 扩展程序配置该选项的支持的 Room Gradle 插件版本。如果您的版本较低，或者该选项尚不受支持，您可以改用注释处理器选项。

使用注解处理器选项

如果您未使用 Room Gradle 插件，或者您所需的选项不受您所用插件版本的支持，则可以使用注解处理器选项配置 Room，如添加 build 依赖项中所述。您指定注解选项的方式取决于您是使用 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。如果您发现了新问题，或对此库有任何改进建议，请告诉我们。创建新问题前，请先查看此库中的现有问题。您可以点击星标按钮，为现有问题投票。

创建新问题

如需了解详情，请参阅问题跟踪器文档。

版本 2.7

版本 2.7.1

2025 年 4 月 23 日

发布了 androidx.room:room-*:2.7.1。版本 2.7.1 包含这些提交内容。

bug 修复

• 修复了提供的类型转换器验证期间的 IndexOutOfBoundsException bug。(b/409804755)。
• 当 SQLiteDriver 使用 Room 进行配置时，支持 RoomDatabase.runInTransaction()。(b/408364828)。

版本 2.7.0

2025 年 4 月 9 日

发布了 androidx.room:room-*:2.7.0。版本 2.7.0 包含这些提交内容。

自 2.6.0 以来的重要变更

• Kotlin Multiplatform (KMP) 支持：在此版本中，Room 已重构为 Kotlin Multiplatform (KMP) 库。目前支持的平台包括 Android、iOS、JVM（桌面版）、原生 Mac 和原生 Linux。如需详细了解如何开始使用 Room KMP，请参阅 Room KMP 官方文档。作为 KMP 支持的一部分，Room 还可以使用 SQLiteDriver 进行配置。如需了解如何将现有应用迁移到驱动程序 API 和 Room KMP，请参阅迁移文档。
• 如果通过 KSP 进行处理，则默认开启 Kotlin Code Generation on KSP。对于 KAPT 或仅使用 Java 的项目，Room 仍会生成 Java 源代码。
• Kotlin 2.0 和 KSP2：Room 现在以 Kotlin 语言 2.0 为目标平台，并且要求项目也使用 Kotlin 2.0 和等同或更高版本的语言进行编译。还添加了对 KSP2 的支持，建议在将 Room 与 Kotlin 2.0 或更高版本搭配使用时使用 KSP2。

版本 2.7.0-rc03

2025 年 3 月 26 日

发布了 androidx.room:room-*:2.7.0-rc03。版本 2.7.0-rc03 包含这些提交内容。

bug 修复

• 在执行 Room 阻塞 API（包括阻塞 DAO 函数）期间线程被中断时，不再抛出 InterruptedException (b/400584611)。
• 重新实现了 Room 的连接池，以尝试缓解 SQLException: Error code: 5, message: Timed out attempting to acquire a reader connection. 和类似问题 (b/380088809)。

版本 2.7.0-rc02

2025 年 3 月 12 日

发布了 androidx.room:room-*:2.7.0-rc02。版本 2.7.0-rc02 包含这些提交内容。

bug 修复

• 修复了自动迁移无法正确处理 FTS 表中新列的问题。（b/348227770、Ic53f3）
• 修复了通过 KSP 处理非 JVM 源代码时因 NullPointerException 而导致的 Room 编译器崩溃问题。（b/396607230、I693c9）
• 修复了以下问题：Room 在使用写入器连接结束时不会使表失效。（b/340606803、I73ef6）

版本 2.7.0-rc01

2025 年 2 月 26 日

发布了 androidx.room:room-*:2.7.0-rc01。版本 2.7.0-rc01 包含这些提交内容。

bug 修复

• 修复了 Room 不会在初始数据库连接中设置 busy_timeout 导致 SQLException: Error code: 5, message: database is locked 问题的问题（I93208、b/380088809）。
• 修复了 Room 编译器中的一个问题，该问题会导致在 Kotlin 2.1.x 和 KSP1 上处理原生源代码集（例如 iOS）时 KSP 处理器崩溃 (I883b8、b/396607230)。

版本 2.7.0-beta01

2025 年 2 月 12 日

发布了 androidx.room:room-*:2.7.0-beta01。版本 2.7.0-beta01 包含这些提交内容。

bug 修复

• 修复了 RoomDatabase.inTransaction() 在不应打开已关闭的数据库时打开该数据库的问题，并且如果数据库已关闭，则应快速返回 false (b/325432967)。
• 修复了使用 Kotlin 内嵌 / 值类处理 DAO 函数时 Room 编译器中发生的崩溃 (IllegalArgumentException: not a valid name) 问题 (b/388299754)。
• 在 room-runtime 的 JVM 工件中添加 Proguard 规则，以免系统移除生成的数据库实现的默认构造函数，因为 Room 的默认初始化会使用该构造函数（b/392657750）。

版本 2.7.0-alpha13

2025 年 1 月 29 日

发布了 androidx.room:room-*:2.7.0-alpha13。版本 2.7.0-alpha13 包含这些提交内容。

API 变更

• Room 现在以 Kotlin 语言 2.0 为目标平台，并且要求项目也使用 Kotlin 2.0 及等同或更高语言版本进行编译。（I8efb0、b/315461431、b/384600605）

bug 修复

• 修复了以下问题：在 Android 中使用简单名称（而非路径），并且数据库文件解析路径不在应用的数据目录中时，Room KMP 数据库构建器会出现问题。（I83315、b/377830104）
• 修复了 Room Gradle 插件存在的问题，该问题会导致在 Android 项目中配置架构输入和输出：property 'inputDirectory' is final and cannot be changed any further. (1dbb4c, b/376071291)
• 在 Room Gradle 插件中添加了对 KSP2 的支持，修复了插件未正确设置架构目录的问题。（Iec3c4、b/379159770）

外部贡献

• 修复了 Room 分页集成导致刷新的初始键过于靠近列表末尾时界面跳转的问题。感谢 Eva！（I2abbe、b/389729367）

版本 2.7.0-alpha12

2024 年 12 月 11 日

发布了 androidx.room:room-*:2.7.0-alpha12。版本 2.7.0-alpha12 包含这些提交内容。

API 变更

• 添加了实验性 API RoomDatabase.Builder.setInMemoryTrackingMode()，用于配置 Room 是否将使用内存表进行失效跟踪。（I2a9b2、b/185414040）

bug 修复

• 破坏性迁移现在会丢弃视图，以确保重新创建这些视图，从而使 allowDestructiveMigrationForAllTables 处于开启状态（KMP 默认值）时的行为与处于关闭状态时的现有行为保持一致。0a3e83、b/381518941

版本 2.7.0-alpha11

2024 年 10 月 30 日

发布了 androidx.room:room-*:2.7.0-alpha11。版本 2.7.0-alpha11 包含这些提交内容。

API 变更

• 重新访问新添加的 convertRows() 方法签名，将其设为接收用于房间分页的 RawRoomQuery 的挂起函数。（Ie57b5、b/369136627）

bug 修复

• 修复了 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 包含这些提交内容。

bug 修复

• 修复了 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 变更

• 由于 Cursor 不再是 Room 的 KMP 版本中适用的准确通用术语，因此 Room 中使用 Cursor 一词的所有警告和错误消息均已移除或替换。（Id8cd9、b/334087492）

bug 修复

• 修复了 Room KMP 会尝试针对非 JVM 平台使用 UUID 发出代码的问题。(b/362994709)
• 修复了 Room Gradle 插件存在的问题，该问题会导致在包含 Compose Multiplatform 的 KMP 项目中使用时出现“无法更改配置的属性...在其被锁定以进行更改后”等错误。(b/343408758)

版本 2.7.0-alpha07

2024 年 8 月 21 日

发布了 androidx.room:room-*:2.7.0-alpha07。版本 2.7.0-alpha07 包含这些提交内容。

新功能

• Room Gradle 插件现在会自动将导出的架构添加到 Android 插桩测试资源源中，以便 MigrationTestHelper 可以使用它们。

bug 修复

• 修复了以下问题：如果在“expect”声明中也替换了 initialize 函数，则 RoomDatabaseConstructor 的生成“actual”会在 initialize 函数中缺少“actual”修饰符。(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 对象

     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

• 添加了一个名为 RoomRawQuery 的新 API，该 API 在保留原始 SQL 字符串方面与 SupportSQLiteQuery 类似，并添加了一个用于将参数绑定到语句的函数，以便在 Room KMP 中支持 @RawQuery。@RawQuery 注解的函数现在可以接受 RoomRawQuery 作为其单个参数。（Iea844、b/330586815）
• 添加了可接受 CoroutineContext 的 setQueryCallback() 过载。（Id66ff、b/309996304）
• 添加了对 linuxArm64 Kotlin 多平台目标的支持 (I139d3、b/338268719)

bug 修复

• 修复了以下问题：Room 会在非 Android 目标平台中错误地生成对 recursiveFetchArrayMap 的调用。（710c36、b/352482325）
• 修复了以下问题：Room 有时会在 KMP 项目中抛出有关“尝试连接超时”的异常。（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)

bug 修复

• 修复了以下 bug：使用 AndroidSQLiteDriver 时，RoomDatabase 会死锁或因连接超时而出错。

版本 2.7.0-alpha04

2024 年 6 月 12 日

发布了 androidx.room:room-*:2.7.0-alpha04。版本 2.7.0-alpha04 包含这些提交内容。

bug 修复

• 修复了以下问题：在 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 包含这些提交内容。

bug 修复

• 修复了与 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 包含这些提交内容。

bug 修复

• 修复了各种 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 进行处理，则默认开启 Kotlin Code Generation on KSP。对于 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 的执行器或协程上下文进行配置，但不能同时使用这两者。
• 添加了一个用于使用 SQLite 驱动程序配置 Room 的 API：RoomDatabase.Builder.setDriver()。如需详细了解 SQLite Driver API，请参阅 SQLite KMP 文档
• 添加了用于从驱动程序 API 访问底层 SQLiteConnection 的 API：RoomDatabase.useReaderConnection 和 RoomDatabase.useWriterConnection。
• 与 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 已与其所有 API 合并到 androidx.room:room-runtime，该工件现在为空。请将其从依赖项列表中移除。

版本 2.6

版本 2.6.1

2023 年 11 月 29 日

发布了 androidx.room:room-*:2.6.1。版本 2.6.1 中包含这些提交内容。

bug 修复

• 解决了生成的代码中存在的问题，即 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 以来的重要变更

• Room KSP 现在提供用于启用 Kotlin 代码生成（或“Kotlin CodeGen”）的选项。(4297ec0)。如需在 Room 中启用 Kotlin CodeGen，请将 room.generateKotlin 选项名称添加到 KSP 的处理器选项中。如需详细了解如何为 KSP 传递处理器选项，请参阅 KSP 文档。

注意：使用 Kotlin CodeGen 时，请务必注意，系统添加了额外的限制。在 Kotlin CodeGen 中，不允许将抽象属性作为 DAO Getter 或 DAO 查询，而应将其重写为函数，以避免错误地认为属性值是不可变的且具有固定的存储结果。添加的另一项限制是，Room 不再允许 Kotlin CodeGen 使用可为 null 的集合返回类型。

警告：使用 Kotlin CodeGen 时，您可能会发现项目在可为 null 性方面更为严格。在 Kotlin CodeGen 中，类型参数的可为 null 性非常重要，而在 Java 中，这通常会被忽略。例如，假设您有一个 `Flow<foo\>` 返回类型，并且表格为空。在 Java CodeGen 中，这不会导致任何问题，但在 Kotlin CodeGen 中，您会收到错误。为避免出现这种情况，您需要使用 `Flow<foo?\>`，假设发出了 null。</foo?\></foo\>

• 我们已向 Room 添加了 ID 为 androidx.room 的 Room Gradle 插件新工件，这解决了 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 中包含这些提交内容。

bug 修复

• 处理在更新/插入期间遇到的特殊情况 SQLite 异常。如果在更新/插入期间抛出 2067 SQLITE_CONSTRAINT_UNIQUE 异常，更新/插入应执行更新。（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 函数的返回类型中对被引用的特定类型参数（Map 的键或值）使用该注解。这是因为 @MapColumn 注解直接用于 DAO 函数的返回值类型中的类型参数，而不是用于函数本身（如 @MapInfo）。如需了解详情，请参阅 @MapColumn 文档。（Ib0305、b/203008711）
• 更新了 API 文件，以便为兼容性抑制添加注解。（I8e87a、b/287516207）
• Room Gradle 插件 API 已更新，不再总是需要按变体进行配置。这意味着，该插件可以接受所有变体的全局位置，而无需创建多个目录，从而实现更顺畅的迁移，但同时又足够灵活，可以手动配置变种或 build 类型架构，同时保留插件的优势（可重现且可缓存的 build）。（I09d6f、b/278266663）

bug 修复

• 修复了 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 插件会配置项目，以便用于自动迁移且是编译任务输出的生成架构得到正确配置，以便构建可重现且可缓存的 build。该插件提供了一个 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）

bug 修复

• 解决了从 Java 迁移到 Kotlin 的 Room 源代码后，在 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 现在能够支持实体中的值类。(4194095)
• 现在可以在 Room (4297ec0) 中启用 Kotlin 代码生成（或“Kotlin CodeGen”）。如需在 Room 中启用 Kotlin CodeGen，请将 room.generateKotlin 选项名称添加到 KSP 的处理器选项中。如需详细了解如何为 KSP 传递处理器选项，请参阅 KSP 文档。

注意：使用 Kotlin CodeGen 时，请务必注意，系统添加了额外的限制。在 Kotlin CodeGen 中，不允许将抽象属性作为 DAO Getter 或 DAO 查询，而应将其重写为函数，以避免错误地认为属性值是不可变的且具有固定的存储结果。添加的另一项限制是，Room 不再允许 Kotlin CodeGen 使用可为 null 的集合返回类型。

警告：使用 Kotlin CodeGen 时，您可能会发现项目在可为 null 性方面更为严格。在 Kotlin CodeGen 中，类型参数的可为 null 性非常重要，而在 Java 中，这通常会被忽略。例如，假设您有一个 `Flow<foo\>` 返回类型，并且表格为空。在 Java CodeGen 中，这不会导致任何问题，但在 Kotlin CodeGen 中，您会收到错误。为避免出现这种情况，您需要使用 `Flow<foo?\>`，假设发出了 null。</foo?\></foo\>

API 变更

• 防止在 DAO 方法返回值类型中无意义地使用可为 null 的集合。（I777dc、b/253271782、b/259426907）
• 添加了一个 API，用于创建会发出失效跟踪器更改的流程。该 API 非常适合创建需要对数据库更改做出响应的流。（I8c790、b/252899305）

bug 修复

• 禁止在 Kotlin 代码生成中将抽象属性用作 DAO Getter 或 DAO 查询，而应将其重写为函数，以避免错误地认为属性值是不可变的，并且具有固定的存储结果。（If6a13、b/127483380、b/257967987）

Version 2.5.2

Version 2.5.2

2023 年 6 月 21 日

发布了 androidx.room:room-*:2.5.2。版本 2.5.2 中包含这些提交内容。

bug 修复

• 修复了与 kotlinx-metadata-jvm 的不兼容问题。(386d5c)
• 修复了导致 Room 在 Robolectric 测试中使用时抛出错误的问题。（f79bea、b/274924903）

版本 2.5.1

版本 2.5.1

2023 年 3 月 22 日

发布了 androidx.room:room-*:2.5.1。版本 2.5.1 中包含这些提交内容。

bug 修复

• 如果数据库已打开，请避免在 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 文件使用属性访问语法的属性。如果存在任何严重的不兼容问题，请提交 bug。
• 添加了新的快捷方式注解 @Upsert，它会尝试在没有唯一性冲突时插入实体或者在存在冲突时更新该实体。（I7aaab、b/241964353）
• 添加了新的 Room Paging 制品 room-paging-rxjava2、room-paging-rxjava3 和 room-paging-guava，以支持 Room Paging。
• 添加了 API，用于在 @MapInfo 中提供消除歧义的键和值表名称 (Icc4b5)

版本 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）

bug 修复

• 修复了影子表错误地导出到架构 .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）

bug 修复

• 现在，在检查自动迁移外键约束条件期间，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-rxjava2、room-paging-rxjava3 和 room-paging-guava，以支持 Room Paging。（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 类型的参数。

• 添加了 API，用于在 @MapInfo 中提供消除歧义的键和值表名称 (Icc4b5)
• 修复了源代码兼容性问题，以重新允许在属性 getter 中使用 @Ignore。(Ifc2fb)

bug 修复

• 重复的列分辨率启发式算法。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）
• 添加了用于多进程锁定的 API，支持在 FrameworkSQLite* 级别使用，以保护多进程首次数据库创建和迁移。（Ied267、b/193182592）

bug 修复

• 添加了对 Kotlin 源代码中内部属性的支持。这是 Room 中的细微行为变更，会在将函数作为 getter/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 中包含这些提交内容。

bug 修复

• 修复了导致 Room 无法在 Kotlin 1.7 中识别挂起函数的问题 (b/236612358)

版本 2.4.2

版本 2.4.2

2022 年 2 月 23 日

发布了 androidx.room:room-*:2.4.2。版本 2.4.2 中包含这些提交内容。

bug 修复

• 修复了以下问题：因使用 -Xjvm-default=all 或等效项进行编译，而导致在为 Dao @Transaction 挂起函数生成代码时，主体会生成默认接口方法。(Ia4ce5)
• 修复了 Room 为 Array<ByteArray> 返回类型查询方法生成代码的 bug。（If086e、b/213789489）

版本 2.4.1

版本 2.4.1

2022 年 1 月 12 日

发布了 androidx.room:room-*:2.4.1。版本 2.4.1 中包含这些提交内容。

bug 修复

• 添加了对 Kotlin 源代码中内部属性的支持。这是 Room 中的细微行为变更，会在将函数作为 getter/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 中包含这些提交内容。

新功能

• 将 Room 对 KSP 的依赖项更新为 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）

bug 修复

• 我们添加了新的 TypeConverter 分析器，可将类型中的是否可为 null 信息纳入考虑范围。由于此信息仅在 KSP 中可用，因此在默认情况下，该分析器仅在 KSP 中开启。如果引起任何问题，您可以通过将 room.useNullAwareTypeAnalysis=false 传递到注解处理器来关闭该分析器。如果发生这种情况，请提交 bug，因为将来我们会移除该标志。对于这个新的 TypeConverter 分析器，我们建议您仅提供接收非 null 值的 TypeConverter，因为新分析器能够通过 null 检查来封装此类 TypeConverter。请注意，这对使用 KAPT 或 Java 作为注解处理器（与 KSP 不同）的用户没有任何影响，其类型中没有可为 null 性信息。（Ia88f9、b/193437407）
• 修复了以下 bug：当 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 中包含这些提交内容。

bug 修复

• 修复了当同一自动迁移中的其他表格也具有同名的新列时，自动迁移不添加新列的问题。（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 变更

• 在 TypeConverters 注解中添加了一个新属性，以便开发者停用内置 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-paging 设为结合使用 Paging3 与 Room 时的必要制品。(Ieaffe)

bug 修复

• 修复了当查询包含映射键中某一列的 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")
  }
  

bug 修复

• 修复了自动迁移中与处理外键违规相关的问题。(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 期间所用的相同方式自动添加自动迁移。

bug 修复

• 修复了 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。这样一来，依赖项注入框架就可以在需要复杂的依赖项时提供这些规范。

bug 修复

• 修复了无法正确重新创建 @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-alpha01。版本 2.4.0-alpha01 中包含这些提交内容。

新功能

• 自动迁移：Room 现在提供一个 API，用于在每次导出架构时自动生成迁移。为了告知 Room 应该生成自动迁移，可以使用新属性 @Database#autoMigrations 来声明自动迁移的来源和目标版本。当 Room 需要获取有关表和列重命名或删除方式的额外信息时，@AutoMigration 注解可以声明包含此类输入信息的规范类。如需了解详情，请参阅 @AutoMigration 文档。

bug 修复

• 修复了以下问题：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 以来的重要变更

• 内置 Enum 支持：现在，如果系统未提供任何类型转换器，Room 将默认使用“枚举 - 字符串”双向类型转换器。如果已存在适用于枚举的类型转换器，Room 将优先使用该转换器，而不使用默认转换器。
• 查询回调：现在，Room 提供了一个通用 callback API RoomDatabase.QueryCallback，此 API 会在即将执行查询时用到，它对登录调试 build 非常有用。可通过 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 现在支持为返回值类型为 androidx.paging.PagingSource 且带 @Query 注解的方法生成实现。

版本 2.3.0-rc01

2021 年 3 月 24 日

发布了 androidx.room:room-*:2.3.0-rc01。版本 2.3.0-rc01 中包含这些提交内容。

bug 修复

• 修复了导致 Room 创建的协程流查询无法在挂起的 withTransaction 块中使用的问题。(I797bf)

版本 2.3.0-beta03

2021 年 3 月 10 日

发布了 androidx.room:room-*:2.3.0-beta03。版本 2.3.0-beta03 中包含这些提交内容。

新功能

• 添加了对 KSP 的增量编译支持。（I031c1、b/176453350）

bug 修复

• 修复了在主线程上创建 PagingSource 会触发 ANR 的 bug。（I42b74、b/181221318）
• 将 @ExperimentalRoomApi 可见性修复为公开，而不是软件包私有。(b/181356119)

外部贡献

• 允许 Room 在同时带有 @Query 和 @SkipQueryVerification 注解的 DAO 方法中接受 POJO 返回类型。Room 会尽可能将查询结果转换为 POJO 返回类型，具体方式与带有 @RawQuery 注解的 DAO 方法的转换方式相同。非常感谢“Markus Riegel | hey@marcorei.com”做出的贡献。(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() 启用。对于具有多个数据库的应用，此功能非常有用。

bug 修复

• 修复了以下问题：具有多个 @Update 或 @Delete 方法（使用不同的冲突策略）的 Dao 方法会生成只使用其中一种策略的代码，实际导致已定义的策略遭到忽略。（/I0b90d、b/176138543）

版本 2.3.0-alpha04

2020 年 12 月 16 日

发布了 androidx.room:room-*:2.3.0-alpha04。版本 2.3.0-alpha04 中包含这些提交内容。

新功能

• 现在，Room 提供了一个通用 callback API RoomDatabase.QueryCallback，此 API 会在即将执行查询时用到，对登录调试 build 非常有用。可通过 RoomDatabase.Builder#setQueryCallback() 设置此回调。（Iaa513、b/174478034、b/74877608）
• 现在，如果系统未提供任何类型转换器，Room 将默认使用“枚举 - 字符串”双向类型转换器。如果已存在适用于枚举的类型转换器，Room 将优先使用该转换器，而不使用默认转换器。(b/73132006)

已知问题

• 如果单向读取类型转换器已存在，在转换为枚举类型时，Room 可能会意外使用内置的“字符串 - 枚举”转换器，这可能不符合预期。这是个已知问题，可通过将内置转换器改为双向转换器来解决这个问题。请参阅：b/175707691

bug 修复

• 修复了以下问题：在较新版本的 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-alpha03。版本 2.3.0-alpha03 中包含这些提交内容。

新功能

• Room 现在拥有相关 API，可提供类型转换器的实例，以便应用可以控制其初始化。如需标记将提供给 Room 的类型转换器，请使用新的注释 @ProvidedTypeConverter。感谢 mzgreen yairobbe@gmail.com。（Ie4fa5、b/121067210）

• Room 现在拥有相关 API，可使用从输入信息流中读取的预打包数据库创建数据库。因此，这可以处理使用 Gzip 压缩预打包数据库等情况。感谢 Ahmed El-Helw ahmedre@gmail.com（3e6792、b/146911060）

API 变更

• 向 @ForeignKey 注解添加了缺失的目标，防止其在 @Entity 注解之外使用。(Iced1e)

• RoomDatabase.java 中的字段 mCallbacks 现已隐藏。（d576cb、b/76109329）

bug 修复

• 更新了 TypeConverter 文档，现在明确指出 TypeConverter 只能用于转换列/字段，而不能转换行。（I07c56、b/77307836）

• 更新了 DaoProcessor，修复了 Dao 中具有含 Kotlin“基元”的通用超类型时出现的编译器错误。（Ice6bb、b/160258066）

• 更新了添加/移除 Observer 各方法的文档，现在对线程处理进行了明确说明（Ifd1d9、b/153948821）

• 修复了 Room 无法正确验证声明了 rowid 列的 FTS 表的问题。（d62ebc、b/145858914）

外部贡献

• 修复了与土耳其语相关的语言区域大小写问题（5746e3、b/68159494）

• 为避免在 Android Lollipop 上出现问题，将 RoomDatabase 中的 ConcurrentHashMap 替换为 Collections.synchronizedMap()（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 现在支持为返回值类型为 androidx.paging.PagingSource 的 @Query 注释方法生成实现。

  @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 提供的列冲突解决方案。

bug 修复

• 修复了 Room 无法正确检测用于启用增量注解处理器的 JDK 版本的 bug。感谢 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.6。版本 2.2.6 中包含这些提交内容。

bug 修复

• 修复了以下问题：在较新版本的 JDK 中，Room 会错误地停用增量注解处理。(b/171387388)

版本 2.2.5

版本 2.2.5

2020 年 3 月 18 日

发布了 androidx.room:room-*:2.2.5。版本 2.2.5 中包含这些提交内容。

bug 修复

• 使 MultiInstanceInvalidationService 实现了 directBootAware。感谢“Mygod contact-git@mygod.be”对此做出的贡献 (b/148240967)
• 修复了一个 bug，该 bug 会在已启用多实例失效且数据库包含 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 中包含这些提交内容。

bug 修复

• 修复了挂起事务时存在的问题，之前如果在事务实际启动前快速取消协程，事务将会发生死锁问题。(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 中包含以下提交内容。

bug 修复

• 修复了以下 bug：Room 无法验证未完成任何迁移并且包含旧版哈希（其架构中带有索引）的数据库。(b/139306173)

版本 2.2.2

版本 2.2.2

2019 年 11 月 20 日

发布了 androidx.room:room-*:2.2.2。版本 2.2.2 中包含这些提交内容。

bug 修复

• 修复了收集超过 999 行的一对一关系会导致 Room 返回 null 相关项的 bug。(b/143105450)

版本 2.2.1

版本 2.2.1

2019 年 10 月 23 日

发布了 androidx.room:room-*:2.2.1。版本 2.2.1 中包含这些提交内容。

bug 修复

• 修复了在编译器选项 expandProjection 开启时 Room 错误地发出 CURSOR_MISMATCH 警告的 bug。(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。当预填充的数据库文件在 APK 的资源文件夹中时，应使用 createFromAsset()；而当该文件在任意位置时，应使用 createFromFile()。这些 API 的用法会改变破坏性迁移的行为，因此在回退迁移期间，Room 将尝试重新复制预填充的数据库（如果有），否则它的回退方法是直接丢弃后再重新创建所有表。b/62185732
• 架构默认值：@ColumnInfo 现在具有一个新属性 defaultValue，该属性可用于指定列的默认值。默认值是数据库架构的一部分，如果指定了默认值，将在迁移期间对默认值进行验证。b/64088772
• 多对多关系：@Relation 现在具有一个新属性 associateBy，它带来一个新注解 @Junction，用于声明需要通过联结表（也称为“联接表”）满足的关系。b/69201917
• 一对一关系：POJO 字段中用于注解的 @Relation 的类型必须为 List 或 Set 的限制已解除，实际上允许表示单值关系。b/62905145
• 目标实体：DAO 注解 @Insert、@Update 和 @Delete 现在具有一个新属性 targetEntity，可用于指定要采用 DAO 方法的目标表。这样一来，这些 DAO 方法的参数就可以是任意 POJO，这些 POJO 将被解释为部分实体。实际上，这会允许部分插入、删除和更新。b/127549506
• 协程流：现在，@Query DAO 方法的返回值类型可以为 Flow<T>。如果查询中的观察表已失效，返回的流将重新发出一组新值。声明具有 Channel<T> 返回类型的 DAO 函数是错误的做法，Room 建议您使用 Flow，然后使用相邻函数将 Flow 转换为 Channel。b/130428884
• Gradle 增量注解处理器：Room 现在是 Gradle 隔离注解处理器，您可通过处理器选项 room.incremental 启用增量功能。如需了解详情，请参阅 Room 编译器选项。如果您遇到任何问题，请点击此处提交 bug。我们计划在将来的稳定版中默认启用增量功能。b/112110217
• 展开投影：添加了一个新的实验性编译器选项 room.expandProjection，它会使 Room 重写查询，从而使星形投影仅包含返回类型 POJO 中的列。例如，假设某个 DAO 方法带有 @Query("SELECT * FROM Song") 注释，它将返回一个名为 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。点击此处可查看此版本中包含的提交内容。

bug 修复

• 修复了协程流查询在一段时间后将停止重新发出新值的 bug。(b/139175786)
• 修复了 Room 在打开自 Room 1.0 以来未经过迁移的数据库时不会接受旧架构哈希代码，使得因架构无效而导致运行时崩溃的 bug。(b/139306173)

版本 2.2.0-alpha02

2019 年 8 月 7 日

发布了 androidx.room:room-*:2.2.0-alpha02。点击此处可查看此版本中包含的提交内容。

新功能

• 协程流：现在，@Query DAO 方法的返回值类型可以为 Flow<T>。如果查询中的观察表已失效，返回的流将重新发出一组新值。声明具有 Channel<T> 返回类型的 DAO 函数是错误的做法，Room 建议您使用 Flow，然后使用相邻函数将 Flow 转换为 Channel。b/130428884
• 展开投影：添加了一个新的实验性编译器选项 room.expandProjection，它会使 Room 重写查询，从而使星形投影仅包含返回类型 POJO 中的列。例如，假设某个 DAO 方法带有 @Query("SELECT * FROM Song") 注释，它将返回一个名为 SongIdAndTitle 且仅包含两个字段的 POJO。在这种情况下，Room 会将查询重写为 SELECT id, title FROM Song，以便获取符合返回类型的最小列集。这样会从本质上消除当查询返回的额外列与返回类型 POJO 中的任何字段都不匹配时出现的 CURSOR_MISMATCH 警告。
• onDestructiveMigrate 是向 RoomDatabase.Callback 添加的一个新 callback API，在 Room 破坏性地迁移数据库时使用。b/79962330

bug 修复

• 修复了在字段受保护时 Room 使用方法作为字段 setter 生成不正确代码的 bug。b/136194628
• 修复了导致 InvalidationTracker 在多实例失效已启用而失效服务已终止的情况下在第二个进程中抛出 NPE 的 bug。b/137454915
• 修复了以下 bug：Room 无法正确识别带有 @RawQuery 注解的继承挂起函数的返回值类型。b/137878827
• 相关键的类型为 BLOB 时，为 @Relation 更新了生成的代码，以使用可比较的 ByteBuffer。b/137881998
• 修复了 Room 指出用作 @Insert、@Update 和 @Delete 的部分实体参数的 POJO 缺少 setter 的错误。b/138664463
• 修复了相应实体类用于某些 DAO 方法时 Room 通过 @Entity 指出忽略的列缺少 getter 和 setter 的 bug。b/138238182
• 修复了 Room 在使用重用的参数执行查询时无法将指定的绑定 args 正确转换为位置 args，从而导致运行时异常的 bug。b/137254857

版本 2.2.0-alpha01

2019 年 7 月 10 日

新功能

• 预打包的数据库：RoomDatabase.Builder 中现在有两个新的 API，用于在给定已填充的数据库文件的情况下创建 RoomDatabase。当预填充的数据库文件在 APK 的资源文件夹中时，应使用 createFromAsset()；而当该文件在任意位置时，应使用 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
• 一对一关系：POJO 字段中用于注解的 @Relation 的类型必须为 List 或 Set 的限制已解除，实际上允许表示单值关系。b/62905145
• 目标实体：DAO 注解 @Insert、@Update 和 @Delete 现在具有一个新属性 targetEntity，可用于指定要采用 DAO 方法的目标表。这样一来，这些 DAO 方法的参数就可以是任意 POJO，这些 POJO 将被解释为部分实体。实际上，这会允许部分插入、删除和更新。b/127549506
• Gradle 增量注解处理器：Room 现在是 Gradle 隔离注解处理器，您可通过处理器选项 room.incremental 启用增量功能。如需了解详情，请参阅 Room 编译器选项。如果您遇到任何问题，请点击此处提交 bug。我们计划在将来的稳定版中默认启用增量功能。b/112110217

bug 修复

• 如果在查询完成之前处置了查询的 Rx 流，Room 不再将 EmptySetResultException 传播到全局错误处理程序。b/130257475
• 修复了带有 @RawQuery 注解的 DAO 挂起函数没有返回值类型时 Room 会显示不正确的错误消息的 bug。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 以及包含 INSERT、DELETE 或 UPDATE 语句的 @Query 注解的 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 日

bug 修复

• 修复了由于已设置 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 { } 封装容器。

bug 修复

• 修复了 Room 针对包含集合类型参数的 Kotlin DAO 函数无法匹配 TypeConverter 的错误。b/122066791

版本 2.1.0-alpha06

2019 年 3 月 22 日

API/行为变更

• 异步事务查询现已序列化，因此 Room 不会使用多个线程来执行数据库事务。添加了 RoomDatabase.Builder.setTransactionExecutor(Executor)，用于配置要对事务使用的执行程序。
• RoomDatabase.runInTransaction(Callable) 不再将受检异常封装到 RuntimeExceptions 中。b/128623748

bug 修复

• 修复了同时添加了内容表和外部 FTS 内容表的观察器时失效跟踪器停止观察内容表的 bug。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。

bug 修复

• 修复了所用分词器的类型为 SIMPLE 时丢弃分词器参数的 bug。b/125427014
• 修复了以下 bug：Room 无法正确识别包含类型为内部类的参数的挂起函数。b/123767877
• 修复了延迟的 @Query（包含 INSERT、UPDATE 或 DELETE 语句）DAO 方法急切地在主线程中准备查询的 bug。b/123695593
• 修复了 Room 为某些挂起函数生成的代码不正确的各种错误。b/123466702 和 b/123457323
• 修复了以下 bug：在生成的代码中无法正确抑制方法的废弃用法。b/117602586
• 将 Room 的 androidx.sqlite 依赖项更新为 1.0.2，该版本修复了相关问题，能够正确处理损坏的数据库。b/124476912

已知问题

• Room 2.1.0-alpha05 依赖于 kotlinx-metadata-jvm 制品，但 Maven 中央制品库中当前不提供该制品 (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
• 通过 @Deprecated 废弃了 OnConflictStrategy.FAIL 和 OnConflictStrategy.ROLLBACK，因为它们的行为与 Android 当前的 SQLite 绑定不符。b/117266738

bug 修复

• 修复了 DAO 方法是挂起函数时 Room 无法正确使用返回值类型的 TypeConverter 的 bug。b/122988159
• 修复了 Room 将继承的挂起函数错误地识别为非挂起函数的 bug。b/122902595
• 修复了 @Embedded 字段在父类中但在多个子类中使用时 Room 生成不正确代码的 bug。b/121099048
• 修复了在 beginTransaction() 和 endTransaction() 之间调用 DAO 挂起函数时数据库死锁的问题。b/120854786

版本 2.1.0-alpha03

2018 年 12 月 4 日

API 变更

• @Fts3/@Fts4 中的 FTS tokenizer 现在接受字符串而不是枚举。这允许 Room 使用自定义分词器。内置分词器仍在 FtsOptions 中定义为字符串常量。b/119234881

新功能

• 协程：DAO 方法现在可以是挂起函数。为了在 Room 中支持挂起函数，发布了一个新的制品，即 room-coroutines。b/69474692
• 带有 @Insert、@Delete 或 @Update 注解的 DAO 方法现在支持 ListenableFuture 作为返回值类型。b/119418331

bug 修复

• 修复了 Room 错误地尝试在 @Entity 的 ignoredColumns 属性中查找包含列的构造函数的 bug。b/119830714
• 修复了 Room 在其生成的实现中不将 DAO 方法参数标记为最终参数的 bug。b/118015483
• 修复了在报告包含特殊符号的查询出现错误时 Room 处理器会崩溃的 bug。b/119520136
• 修复了 Room 拒绝其他各种 Collection 实现作为 IN 表达式的参数的 bug。b/119884035
• 修复了当永久观察导致 Room 不再发出新数据时，从 Room 返回的 LiveData 会进行垃圾回收的 bug。b/74477406
• 更新了 RoomDatabase 的闭锁以减少锁争用。b/117900450

版本 2.1.0-alpha02

2018 年 10 月 30 日

新功能

• 在 @Relation 中添加了对引用 @DatabaseView 的支持。b/117680932

bug 修复

• 修复了在从 Rx 返回类型进行订阅和处理时 Room 会在主线程中执行磁盘 I/O 的 bug。b/117201279
• 修复了 Room 无法为 Kotlin 实体类中的字段找到合适的类型转换器的 bug。b/111404868
• 修复了 Room 为包含没有参数的 Kotlin 默认方法的 DAO 接口实现生成不正确代码的 bug。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。Room 注释 @PrimaryKey、@ColumnInfo、@Embedded 和 @Relation 现在可以在自动值注释类的抽象方法中声明。请注意，这些注解还必须附带 @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/行为变更

• 现通过 @Deprecated 废弃了 RoomDatabase 中的 mCallback 和 mDatabase，它们将在 Room 的下一主要版本中移除。b/76109329

bug 修复

• 修复了 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 和数据库实现现在是最终实现

bug 修复

• 在“找不到字段的 getter”错误中指定类/字段名称 b/73334503
• 修复了 RoomOpenHelper 与较低版本的 Room 的向后兼容性问题 b/110197391

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 无法正确处理迁移后初始化的 bug b/79362399

版本 1.1.0

版本 1.1.0-beta3

2018 年 4 月 19 日

bug 修复

• 修复了当 Kotlin POJO 引用使用 Java 定义的关系实体时出现的编译错误 b/78199923

版本 1.1.0-beta2

2018 年 4 月 5 日

bug 修复

• 修复了 Room Rx Single 和 Maybe 实现中的一个关键 bug，该 bug 会提前回收查询，导致在向返回的 Single 或 Maybe 实例添加多个观察器时出现问题。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。

bug 修复

• [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（如果尚未切换）。

bug 修复

• 改进了对 Kotlin Kapt 类型的支持。b/69164099
• 字段的顺序不再使架构无效。b/64290754