Room

Room 持久性库在 SQLite 的基础上提供了一个抽象层,让用户能够在充分利用 SQLite 的强大功能的同时,获享更强健的数据库访问机制。如需了解详情,请参阅参考文档

声明依赖项

要添加 Room 的依赖项,您必须将 Google Maven 代码库添加到项目中。请阅读 Google 的 Maven 代码库了解详情。

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

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

    dependencies {
      def room_version = "2.2.0-rc01"

      implementation "androidx.room:room-runtime:$room_version"
      annotationProcessor "androidx.room:room-compiler:$room_version" // For Kotlin use kapt instead of annotationProcessor

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

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

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

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

如需了解如何使用 Kotlin 扩展程序,请参阅 ktx 文档

如需详细了解依赖项,请参阅添加编译依赖项

配置编译器选项

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

  • room.schemaLocation:配置并启用将数据库架构导出到给定目录中的 JSON 文件的功能。如需了解详情,请参阅 Room 迁移
  • room.incremental:启用 Gradle 增量注解处理器。
  • room.expandProjection:配置 Room 以重写查询,使其顶部星形投影在展开后仅包含 DAO 方法返回类型中定义的列。

以下代码段举例说明了如何配置这些选项:

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

版本 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 在打开自 Room 1.0 以来未经过迁移的数据库时不会接受旧架构哈希代码,从而因架构无效而导致运行时崩溃的错误。(b/139306173)

版本 2.2.0-alpha02

2019 年 8 月 7 日

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

新功能

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

问题修复

  • 修复了在字段受保护时 Room 使用方法作为字段 setter 生成的代码不正确的错误。 b/136194628
  • 修复了导致 InvalidationTracker 在多实例失效已启用而失效服务已终止的情况下在第二个进程中抛出 NPE 的错误。 b/137454915
  • 修复了 Room 无法正确识别带有 @RawQuery 注解的继承的暂停函数的返回类型的错误。 b/137878827
  • 相关键的类型为 BLOB 时,为 @Relation 更新了生成的代码,以使用可比较的 ByteBufferb/137881998
  • 修复了 Room 指出用作 @Insert@Update@Delete 的部分实体参数的 POJO 缺少 setter 的错误。 b/138664463
  • 修复了相应实体类用于某些 DAO 方法时 Room 通过 @Entity 指出忽略的列缺少 getter 和 setter 的错误。 b/138238182
  • 修复了 Room 在使用重用的参数执行查询时无法将指定的绑定 args 正确转换为位置 args 从而导致运行时异常的错误。 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
  • 一对一关系:带有 @Relation 注解且类型为 ListSet 的 POJO 字段中的限制已解除,实际上允许表示单值关系。 b/62905145
  • 目标实体:DAO 注解 @Insert@Update@Delete 现在具有一个新属性 targetEntity,可用于指定 DAO 方法应当作用于的目标表。这样一来,这些 DAO 方法的参数就可以是任意 POJO,这些 POJO 将被解释为部分实体。实际上,这允许部分插入、删除和更新。 b/127549506
  • Gradle 增量注解处理器:Room 现在是 Gradle 隔离注解处理器,您可通过处理器选项 room.incremental 启用增量功能。如需了解详情,请参阅 Room 编译器选项。如果您遇到任何问题,请点击此处提交错误。我们计划在将来的稳定版中默认启用增量功能。 b/112110217

问题修复

  • 如果在查询完成之前处置了查询的 Rx 流,Room 不再将 EmptySetResultException 传播到全局错误处理程序。 b/130257475
  • 修复了带有 @RawQuery 注解的 DAO 暂停函数没有返回类型时 Room 会显示不正确的错误消息的错误。 b/134303897
  • Room 将不再生成具有原始类型的 DAO 适配器。 b/135747255

版本 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 以及包含 INSERTDELETEUPDATE 语句的 @Query 注解的 DAO 方法现在支持 Rx 返回类型 CompletableSingleMaybe 以及 Guava 的返回类型 ListenableFuture,并且它们也可以是暂停函数。
  • enableMultiInstanceInvalidationRoomDatabase.Builder 中的一个新 API,可使用同一数据库文件在 RoomDatabase 的多个实例中启用失效。
  • fallbackToDestructiveMigrationOnDowngradeRoomDatabase.Builder 中的一个新 API,可在发生降级时自动重新创建数据库。
  • ignoredColumns@Entity 注解中的一个新 API,可用于按名称列出忽略的字段。
  • 现在,Room 将在数据类中正确使用 Kotlin 的主要构造函数,这样就无需将属性声明为 vars

版本 2.1.0-rc01

2019 年 5 月 29 日

问题修复

  • 修复了由于已设置 temp_store 配置而可能发生的 Room 初始化错误。 b/132602198
  • 修复了向使用 SQLite 3.27.0 及更高版本的用户发出的双引号用法警告。 b/131712640
  • 修复了并行执行多项失效检查时 InvalidationTracker 会导致崩溃的错误。 b/133457594

版本 2.1.0-beta01

2019 年 5 月 7 日

发布了 androidx.room 2.1.0-beta01,该版本与 2.1.0-alpha07 相比没有变化。要查看此版本中包含的提交内容,请点击此处

版本 2.1.0-alpha07

2019 年 4 月 25 日

API/行为更改

  • 扩展函数 RoomDatabase.withTransaction 已更改,不再将包含 CoroutineScope 的函数块当作接收器。这样可以防止跳过并发运行事务块中的内容所需的额外 coroutineScope { } 封装容器。

问题修复

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

版本 2.1.0-alpha06

2019 年 3 月 22 日

API/行为更改

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

问题修复

  • 修复了同时添加了内容表和外部 FTS 内容表的观察者时失效跟踪器将停止观察内容表的错误。 b/128508917
  • 更新了 Room 的 SQLite 语法,使其与 SQLite 3.24.0 相符。 b/110883668

版本 2.1.0-alpha05

2019 年 3 月 13 日

新功能

  • 通过扩展函数 RoomDatabase.withTransaction,您可以在协程内安全地执行数据库事务。room-ktx 工件中提供了 Room 扩展函数以及协程支持。
  • 带有 @Transaction 注解的非抽象 DAO 方法现在可以是暂停函数。b/120241587

API/行为更改

  • 按照与其他 androidx 工件相同的命名方式,工件 room-coroutines 已重命名为 room-ktx
  • RoomDatabase 中的 beginTransactionsetTransactionSuccessfulendTransaction 已弃用,取而代之的是 runInTransactionroom-ktx 扩展函数 withTransaction

问题修复

  • 修复了所用分词器的类型为 SIMPLE 时丢弃分词器参数的错误。b/125427014
  • 修复了 Room 无法正确识别包含类型为内部类的参数的暂停函数的错误。b/123767877
  • 修复了延迟的 @Query(包含 INSERTUPDATEDELETE 语句)DAO 方法急切地在主线程中准备查询的错误。b/123695593
  • 修复了 Room 为某些暂停函数生成的代码不正确的各种错误。b/123466702b/123457323
  • 修复了在生成的代码中无法正确抑制方法的废弃用法的错误。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(包含 INSERTUPDATEDELETE 语句)注解的 DAO 方法现在可以返回异步类型 SingleMaybleCompletableListenableFuture。此外,它们也可以是暂停函数。b/120227284

API/行为更改

  • 如果带有 @Transaction 注解的非抽象 DAO 方法返回异步类型(如 SingleMaybleCompletableLiveDataListenableFuture),Room 现在会抛出错误。由于事务受线程限制,因此 Room 目前无法开始和结束与可能在不同线程中执行查询的函数相关的事务。b/120109336
  • OnConflictStrategy.FAILOnConflictStrategy.ROLLBACK 已通过 @Deprecated 注解弃用,因为它们的行为与 Android 当前的 SQLite 绑定不符。b/117266738

问题修复

  • 修复了 DAO 方法是暂停函数时 Room 无法正确使用返回类型的 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 现在接受字符串而不是枚举。这允许 Room 使用自定义分词器。内置分词器仍在 FtsOptions 中定义为字符串常量。b/119234881

新功能

  • 协程:DAO 方法现在可以是暂停函数。为了在 Room 中支持暂停函数,发布了一个新的工件,即 room-coroutinesb/69474692
  • 带有 @Insert@Delete@Update 注解的 DAO 方法现在支持 ListenableFuture 作为返回类型。b/119418331

问题修复

  • 修复了 Room 错误地尝试在 @EntityignoredColumns 属性中查找包含列的构造函数的错误。b/119830714
  • 修复了 Room 在其生成的实现中不将 DAO 方法参数标记为最终参数的问题。b/118015483
  • 修复了在报告包含特殊符号的查询出现错误时 Room 的处理器会崩溃的问题。b/119520136
  • 修复了 Room 拒绝其他各种 Collection 实现作为 IN 表达式的参数的错误。b/119884035
  • 修复了当永久观察导致 Room 不再发出新数据时从 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
  • 修复了 Room 为包含没有参数的 Kotlin 默认方法的 DAO 接口实现生成的代码不正确的错误。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 返回类型 CompletableSingle<T>Maybe<T>b/63317956
  • 带有 @Relation 注解的不可变类型:Room 以前要求带有 @Relation 注解的字段可设置,但现在它们可以是构造函数参数。
  • enableMultiInstanceInvalidation:是 RoomDatabase.Builder 中的一个新 API,可使用同一数据库文件在 RoomDatabase 的多个实例中启用失效。这种多实例失效机制也适用于多个进程。b/62334005
  • fallbackToDestructiveMigrationOnDowngrade:是 RoomDatabase.Builder 中的一个新 API,可在发生降级时自动重新创建数据库。b/110416954
  • ignoredColumns:是 @Entity 注解中的一个新 API,可用于按名称列出忽略的字段。对于忽略实体上继承的字段很有用。b/63522075

API/行为更改

  • RoomDatabase 中的 mCallbackmDatabase 现已通过 @Deprecated 注解弃用,将在 Room 的下一主要版本中移除。b/76109329

问题修复

  • 修复了 Room 无法从损坏的数据库正确恢复或在初始化期间出现错误迁移的两个问题。b/111504749b/111519144
  • 现在,Room 将在数据类中正确使用 Kotlin 的主要构造函数,这样就无需将字段声明为 varsb/105769985

版本 2.0.0-beta01

2018 年 7 月 2 日

API/行为更改

  • 添加了 RoomDatabase.Builder.setQueryExecutor() 以允许自定义查询运行位置
  • 添加了 RxJava2 Observable 支持
  • 生成的 DAO 和数据库实现现在是最终实现

问题修复

  • 在“找不到字段的 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

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-beta3

2018 年 4 月 19 日

问题修复

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

版本 1.1.0-beta2

2018 年 4 月 5 日

问题修复

  • 修复了 Room 的 Rx SingleMaybe 实现中的一个关键错误,该错误将提前回收查询,导致在向返回的 SingleMaybe 实例添加多个观察者时出现问题。 b/76031240

  • 如果在事务内调用 [RoomDatabase.clearAllTables][ref-clearAllTables],它不会对数据库执行 VACUUM 操作。 b/77235565

版本 1.1.0-beta1

2018 年 3 月 21 日

API 更改

  • 根据 API 审核反馈,@RawQuery 不再接受将 String 作为查询参数传递。您需要使用 [SupportSQLiteQuery][ref-SupportSQLiteQuery](要轻松创建具有参数支持的 [SupportSQLiteQuery][ref-SupportSQLiteQuery] 实例,请参阅 [SimpleSQLiteQuery][ref-SimpleSQLiteQuery])。
  • RoomDatabase.Builder 的 [fallbackToDestructiveMigrationFrom][ref-fallbackToDestructiveMigrationFrom] 方法现在接受 vararg int 而不是 vararg Integer

问题修复

  • [RoomDatabase.clearAllTables][ref-clearAllTables] 现在通过设置 WAL 检查点和对数据库执行 VACUUM 操作,尝试将空间返还给操作系统。
  • [@RawQuery][ref-RawQuery] 现在接受 observedEntities 属性的任何 Pojo,前提是该 Pojo 通过其 Embedded 字段或 Relation 引用一个或多个实体。 b/74041772
  • Paging:Room 的 DataSource 实现现在可以正确处理多表依赖项(如关系和连接)。以前,这些将无法触发新结果,或者可能无法编译。 b/74128314

版本 1.1.0-alpha1

2018 年 1 月 22 日

新功能

  • RawQuery:这一新 API 允许 @Dao 方法接收 SQL 作为查询参数 b/62103290b/71458963
  • 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