Room
Latest Update | Stable Release | Release Candidate | Beta Release | Alpha Release |
---|---|---|---|---|
October 2, 2024 | 2.6.1 | - | - | 2.7.0-alpha09 |
Declaring dependencies
To add a dependency on Room, you must add the Google Maven repository to your project. Read Google's Maven repository for more information.
Dependencies for Room include testing Room migrations and Room RxJava
Add the dependencies for the artifacts you need in the build.gradle
file for
your app or module:
Groovy
dependencies { def room_version = "2.6.1" implementation "androidx.room:room-runtime:$room_version" annotationProcessor "androidx.room:room-compiler:$room_version" // To use Kotlin annotation processing tool (kapt) kapt "androidx.room:room-compiler:$room_version" // To use Kotlin Symbol Processing (KSP) ksp "androidx.room:room-compiler:$room_version" // optional - RxJava2 support for Room implementation "androidx.room:room-rxjava2:$room_version" // optional - RxJava3 support for Room implementation "androidx.room:room-rxjava3:$room_version" // optional - Guava support for Room, including Optional and ListenableFuture implementation "androidx.room:room-guava:$room_version" // optional - Test helpers testImplementation "androidx.room:room-testing:$room_version" // optional - Paging 3 Integration implementation "androidx.room:room-paging:$room_version" }
Kotlin
dependencies { val room_version = "2.6.1" implementation("androidx.room:room-runtime:$room_version") annotationProcessor("androidx.room:room-compiler:$room_version") // To use Kotlin annotation processing tool (kapt) kapt("androidx.room:room-compiler:$room_version") // To use Kotlin Symbol Processing (KSP) ksp("androidx.room:room-compiler:$room_version") // optional - Kotlin Extensions and Coroutines support for Room implementation("androidx.room:room-ktx:$room_version") // optional - RxJava2 support for Room implementation("androidx.room:room-rxjava2:$room_version") // optional - RxJava3 support for Room implementation("androidx.room:room-rxjava3:$room_version") // optional - Guava support for Room, including Optional and ListenableFuture implementation("androidx.room:room-guava:$room_version") // optional - Test helpers testImplementation("androidx.room:room-testing:$room_version") // optional - Paging 3 Integration implementation("androidx.room:room-paging:$room_version") }
For information on using the KAPT plugin, see the KAPT documentation.
For information on using the KSP plugin, see the KSP quick-start documentation.
For information on using Kotlin extensions, see the ktx documentation.
For more information about dependencies, see Add Build Dependencies.
Optionally, for non-Android libraries (i.e. Java or Kotlin only Gradle modules)
you can depend on androidx.room:room-common
to use Room annotations.
Configuring Compiler Options
Room has the following annotation processor options.
room.schemaLocation |
directory
Enables exporting database schemas into JSON files in the given directory. See Room Migrations for more information. |
room.incremental |
boolean
Enables Gradle incremental annotation processor. Default value is true .
|
room.generateKotlin |
boolean
Generate Kotlin source files instead of Java. Requires KSP. Default value is false .
See version 2.6.0 notes for more details.
|
Use the Room Gradle Plugin
With Room version 2.6.0 and higher, you can use the Room Gradle Plugin to configure options for the Room compiler. The plugin configures the project such that generated schemas (which are an output of the compile tasks and are consumed for auto-migrations) are correctly configured to have reproducible and cacheable builds.
To add the plugin, in your top-level Gradle build file, define the plugin and its version.
Groovy
plugins { id 'androidx.room' version "$room_version" apply false }
Kotlin
plugins { id("androidx.room") version "$room_version" apply false }
In the module-level Gradle build file, apply the plugin and use the room
extension.
Groovy
plugins { id 'androidx.room' } android { ... room { schemaDirectory "$projectDir/schemas" } }
Kotlin
plugins { id("androidx.room") } android { ... room { schemaDirectory("$projectDir/schemas") } }
Setting a schemaDirectory
is required when using the Room Gradle Plugin. This
will configure the Room compiler and the various compile tasks and its backends
(javac, KAPT, KSP) to output schema files into flavored folders, for example
schemas/flavorOneDebug/com.package.MyDatabase/1.json
. These files should be
checked into the repository to be used for validation and auto-migrations.
Some options cannot be configured in all versions of the Room Gradle Plugin,
even though they are supported by the Room compiler. The table below lists each
option and shows the version of the Room Gradle Plugin that added support for
configuring that option using the room
extension. If your version is lower,
or if the option is not supported yet, you can use
annotation processor options instead.
Option | Since version |
---|---|
room.schemaLocation (required) |
2.6.0 |
room.incremental |
- |
room.generateKotlin |
- |
Use annotation processor options
If you aren't using the Room Gradle Plugin, or if the option you want isn't supported by your version of the plugin, you can configure Room using annotation processor options, as described in Add build dependencies. How you specify annotation options depends on whether you use KSP or KAPT for Room.
Groovy
// For KSP ksp { arg("option_name", "option_value") // other otions... } // For javac and KAPT android { ... defaultConfig { ... javaCompileOptions { annotationProcessorOptions { arguments += [ "option_name":"option_value", // other options... ] } } } }
Kotlin
// For KSP ksp { arg("option_name", "option_value") // other options... } // For javac and KAPT android { ... defaultConfig { ... javaCompileOptions { annotationProcessorOptions { arguments += mapOf( "option_name" to "option_value", // other options... ) } } } }
Because room.schemaLocation
is a directory and not a primitive type, it is
necessary to use a CommandLineArgumentsProvider
when adding this option so
that Gradle knows about this directory when conducting up-to-date checks.
Migrate your Room database
shows a complete implementation of CommandLineArgumentsProvider
that provides
the schema location.
Feedback
Your feedback helps make Jetpack better. Let us know if you discover new issues or have ideas for improving this library. Please take a look at the existing issues in this library before you create a new one. You can add your vote to an existing issue by clicking the star button.
See the Issue Tracker documentation for more information.
Version 2.7
Version 2.7.0-alpha09
October 2, 2024
androidx.room:room-*:2.7.0-alpha09
is released. Version 2.7.0-alpha09 contains these commits.
Bug Fixes
- Fix an issue with the KMP implementation of
room-paging
that would cause anError code: 8, message: attempt to write a readonly database
due to starting a write transaction on a read connection. (b/368380988)
Version 2.7.0-alpha08
September 18, 2024
androidx.room:room-*:2.7.0-alpha08
is released. Version 2.7.0-alpha08 contains these commits.
New Features
- The
room-paging
artifacts have been migrated to be KMP compatible. (Ib8756, b/339934824) - The API
invalidationTrackerFlow()
has been commonized as a first-party API asInvalidationTracker.createFlow()
and is now available for non-Android source sets in KMP projects. (I1fbfa, (I8fb29), b/329291639, b/329315924)
API Changes
- All warnings and error messages in Room that use the word
Cursor
have been removed or replaced, asCursor
is no longer an accurate general term to use in the KMP version of Room. (Id8cd9, b/334087492)
Bug Fixes
- Fixed an issue where Room KMP would try to emit code using
UUID
for non-JVM platforms. (b/362994709) - Fixed an issue with the Room Gradle Plugin that would cause an error such as ‘Cannot change attributes of configuration … after it has been locked for mutation’ when being used in a KMP project with Compose Multiplatform. (b/343408758)
Version 2.7.0-alpha07
August 21, 2024
androidx.room:room-*:2.7.0-alpha07
is released. Version 2.7.0-alpha07 contains these commits.
New Features
- The Room Gradle Plugin will now automatically add the exported schemas into the Android Instrumentation Test resource sources so they can be used by the
MigrationTestHelper
.
Bug Fixes
- Fixed an issue with the generated ‘actual’ of the
RoomDatabaseConstructor
missing the ‘actual’ modifier in theinitialize
function if such function is also overridden in the ‘expect’ declaration. (359631627) - Fixed an issue with the generated ‘actual’ of the
RoomDatabaseConstructor
not matching the visibility of the ‘expect’ declaration. (358138953)
Version 2.7.0-alpha06
August 7, 2024
androidx.room:room-*:2.7.0-alpha06
is released. Version 2.7.0-alpha06 contains these commits.
API Changes
- Change the instantiation setup for a
RoomDatabase
in a KMP project.
Due to Kotlin 2.0 compilation model, the strategy of referencing a to-be-generated function, named instantiateImpl()
is longer viable. Two new APIs, @ConstructedBy
and RoomDatabaseConstructor
are introduced that replace the instantiateImpl()
strategy. The new strategy is as follow:
Define an expect object that implements
RoomDatabaseConstructor
expect object MyDatabaseCtor : RoomDatabaseConstructor<MyDatabase>
Link the object with the
@Database
declaration using@ConstructedBy
@Database(...) @ConstructedBy(MyDatabaseCtor::class) // NEW abstract class MyDatabase : RoomDatabase
Create a new database instance but without passing a factory argument
fun createNewDatabase(path: String) = Room.databaseBuilder<AppDatabase>(name = path) .setDriver(BundledSQLiteDriver()) .setQueryCoroutineContext(Dispatchers.IO) .build()
Fixes b/316978491, b/338446862, and b/342905180
- Support for
@RawQuery
in Room KMP by adding a new API calledRoomRawQuery
that is similar toSupportSQLiteQuery
in terms of holding into the raw SQL string and a function to bind arguments into a statement.@RawQuery
annotated functions can now accept aRoomRawQuery
as their single parameter. (Iea844, b/330586815) - Add an overload of
setQueryCallback()
that accepts aCoroutineContext
. (Id66ff, b/309996304) - Added support for
linuxArm64
Kotlin Multiplatform targets (I139d3, b/338268719)
Bug Fixes
- Fix an issue where Room would incorrectly generate a call to
recursiveFetchArrayMap
in non-Android targets. (710c36, b/352482325) - Fix an issue where sometimes Room would throw an exception about ‘Timed out attempting a connection’ in a KMP project. (fa72d0, b/347737870)
- Fix an issue in auto-migrations that would check for foreign keys too early before other tables changed their schemas to conform to the new foreign keys. (7672c0, b/352085724)
Version 2.7.0-alpha05
July 10, 2024
androidx.room:room-*:2.7.0-alpha05
is released. Version 2.7.0-alpha05 contains these commits.
API Changes
- Renamed
SQLiteKt
toSQLite
andBundledSQLiteKt
toBundledSQLite
. (I8b501)
Bug Fixes
- Fixed a bug where a
RoomDatabase
would deadlock or error out with a connection timeout when using theAndroidSQLiteDriver
.
Version 2.7.0-alpha04
June 12, 2024
androidx.room:room-*:2.7.0-alpha04
is released. Version 2.7.0-alpha04 contains these commits.
Bug Fixes
- Fixed an issue in Room’s annotation processor would generate incompatible KMP code when a multi-map return type was defined in a DAO. (b/340983093)
- Fixed an issue where Room would fail to find the generated database implementation if the
@Database
annotated class had no package. (b/342097292) - Fixed an issue where enabling auto-close and multi-instance invalidation would sometimes cause a
ConcurrentModificationException
when the database was auto-closed due to being idle.
Version 2.7.0-alpha03
May 29, 2024
androidx.room:room-*:2.7.0-alpha03
is released. Version 2.7.0-alpha03 contains these commits.
Bug Fixes
- Fix various issues regarding Kotlin 2.0 and KSP 2.0. Note that Kotlin 2.0 with KSP 2 support is not complete and the team is working on the various APIs and behavior changes in the new compiler. (b/314151707)
Version 2.7.0-alpha02
May 14, 2024
androidx.room:room-*:2.7.0-alpha02
is released. Version 2.7.0-alpha02 contains these commits.
Bug Fixes
- Fixed various KSP issues.
Version 2.7.0-alpha01
May 1, 2024
androidx.room:room-*:2.7.0-alpha01
is released. Version 2.7.0-alpha01 contains these commits.
New Features
- Kotlin Multiplatform (KMP) Support: In this release, Room has been refactored to become a Kotlin Multiplatform (KMP) library. Although there is still some work to be done, this release introduces a new version of Room where the majority of the functionality has been “common-ized” (made to be multiplatform). Current supported platforms are Android, iOS, JVM (Desktop), native Mac and native Linux. Any missing functionality in the newly supported platforms will be made “feature-complete” in upcoming Room releases.
For more information on how to get started using Room KMP, please refer to the official Room KMP documentation.
- Kotlin Code Generation on KSP has been turned ON by default if processing is done via KSP. For KAPT or Java only projects, Room will still generate Java sources.
API Changes
- An overload of
Room.databaseBuilder()
has been added that takes a lambda parameter that is meant to be used with a Room generated function to avoid using reflection when instantiating the generatedRoomDatabase
implementation. Example usage is:
Room.databaseBuilder<MyDatabase>(
context = appContext,
name = dbFilePath,
factory = { MyDatabase::class.instantiateImpl() }
)
- An API for configuring a Room with a
CoroutineContext
has been added to the builder:RoomDatabase.Builder.setQueryCoroutineContext
. Note that aRoomDatabase
can only be configured with either executors usingsetQueryExecutor
or with a Coroutine context but not both. - An API for configuring Room with a
SQLite
Driver has been added:RoomDatabase.Builder.setDriver()
. For more information about theSQLite
Driver API refer to the SQLite KMP documentation - APIs for accessing the underlying
SQLiteConnection
from driver APIs have been added:RoomDatabase.useReaderConnection
andRoomDatabase.useWriterConnection
. - Varios Room related callbacks now have an overloaded version that receive
SQLiteConnection
instead ofSupportSQLiteDatabase
. These are intended to be overridden when migrating to a KMP project. For more information about migrating Room usages in an Android app to a common KMP module refer to the migration guide. The callbacks are:Migration.migrate(SQLiteConnection)
AutoMigrationSpec.onPostMigrate(SQLiteConnection)
RoomDatabase.Callback.onCreate(SQLiteConnection)
RoomDatabase.Callback.onDestructiveMigration(SQLiteConnection)
RoomDatabase.Callback.onOpen(SQLiteConnection)
- The KTX artifact
androidx.room:room-ktx
has been merged toandroidx.room:room-runtime
along with all its APIs, the artifact is now blank. Please remove it from your dependency list.
Version 2.6
Version 2.6.1
November 29, 2023
androidx.room:room-*:2.6.1
is released. Version 2.6.1 contains these commits.
Bug Fixes
- Resolved issue in generated code where the default value for Double columns in
EntityCursorConverter
was being set to 0 instead of 0.0. A potential fix for a similar edge-case for Float type columns has also been included. (Id75f5, b/304584179) - Exceptions thrown from
PagingSource
loads will now be propagated as aLoadStateUpdate
ofLoadResult.Error
containing the Throwable. This error state is observable throughPagingDataAdapter.loadStateFlow(Views)
orLazyPagingItems.loadState(Compose)
. Note that this marks a behavioral change where in the past load errors will bubble up as an Exception thrown by the dao method that triggered the load. (I93887, b/302708983)
Version 2.6.0
October 18, 2023
androidx.room:room-*:2.6.0
is released. Version 2.6.0 contains these commits.
Important changes since 2.5.0
- The option to enable Kotlin code generation (or “Kotlin CodeGen”) is now available in Room KSP. (4297ec0). To turn on Kotlin CodeGen in Room, add the
room.generateKotlin
option name to your processor options for KSP. For more details on how to pass processor options for KSP, see the KSP documentation.
Note: When using Kotlin CodeGen, it is important to note that there are additional restrictions that have been added. Abstract properties as DAO getters or DAO queries in Kotlin CodeGen are disallowed, and instead expected to be rewritten as functions to avoid the false notion that the property value is immutable and has a fixed stored result. Another restriction that has been added is that Nullable collection return types are no longer allowed in Room for Kotlin CodeGen.
Warning: You may find that your projects are more strict in terms of nullability when using Kotlin CodeGen. In Kotlin CodeGen, the nullability of type arguments is important, wheras in Java this is mostly ignored. For example, let's say you have a `Flow
- The new artifact for the Room Gradle Plugin has been added to Room with the id
androidx.room
, which solves various existing issues in Room regarding having inputs and outputs of schemas via Gradle annotation processor options. For more details, refer to the Room Version 2.6.0-alpha02 release notes. - Value classes in Room Entities are now supported for KSP. (4194095)
- Nested Map return types in DAO functions are now supported in Room. (I13f48, 203008711)
Version 2.6.0-rc01
September 20, 2023
androidx.room:room-*:2.6.0-rc01
is released. Version 2.6.0-rc01 contains these commits.
Version 2.6.0-beta01
August 23, 2023
androidx.room:room-*:2.6.0-beta01
is released. Version 2.6.0-beta01 contains these commits.
Bug Fixes
- Handling the special case
SQLite
exception during upsert encountered when the2067 SQLITE_CONSTRAINT_UNIQUE
exception is thrown during an upsert, upsert should perform an update. (If2849, b/243039555)
Version 2.6.0-alpha03
August 9, 2023
androidx.room:room-*:2.6.0-alpha03
is released. Version 2.6.0-alpha03 contains these commits.
New Features
API Changes
- A new type annotation called
@MapColumn
has been created to replace@MapInfo
, which is now deprecated. For each column name (keyColumnName
,valueColumnName
, or both) provided in a@MapInfo
annotation, you will need to declare a@MapColumn
annotation with just thecolumnName
and use the annotation on the specific type argument that is being referenced (the key or value of the Map) in the return type of the DAO function. This is because the@MapColumn
annotation is used directly on the type argument within the return type of a DAO function, instead of on the function itself like@MapInfo
. For more information, please refer to the@MapColumn
documentation. (Ib0305, b/203008711) - Updated API files to annotate compatibility suppression (I8e87a, b/287516207)
- The Room Gradle plugin APIs have been updated to not always require per-variant configurations. This means that the plugin can accept a global location for all variants without creating multiple directories, enabling smoother migrations that but is also flexible enough to manually configure flavors or build type schemas while still retaining the benefits of the plugin (reproducible and cacheable builds). (I09d6f, b/278266663)
Bug Fixes
- Fixed potential memory leak vulnerability in
QueryInterceptorStatement
. (I193d1) - Fixed incorrect behavior in the
QueryInterceptorDatabase execSQL()
function. (Iefdc8)
Version 2.6.0-alpha02
June 21, 2023
androidx.room:room-*:2.6.0-alpha02
is released. Version 2.6.0-alpha02 contains these commits.
Room Gradle Plugin
This new release contains a new artifact for the Room Gradle Plugin with id androidx.room
, which solves various existing issues in Room regarding having inputs and outputs of schemas via Gradle annotation processor options. The Room Gradle Plugin configures the project such that generated schemas that are consumed for auto-migrations and are output of the compile tasks are correctly configured to have reproducible and cacheable builds. The plugin offers a DSL to configure the base schema location:
room {
schemaDirectory("$projectDir/schemas/")
}
The plugin will then configure the Room compiler and the various compile tasks and its backends (javac, KAPT, KSP) to output schema files into flavored folders, i.e. schemas/flavorOneDebug/com.package.MyDatabase/1.json
. As usual these files are checks-in into the repository to be used for validation and auto-migrations. Upon migrating to using the plugin instead of the annotation processor options the existing schema files must be copied to the generated flavor directories created by the plugin, this is a one-time migration operation that must be done manually. The schema documentation in developers.android.com will be updated in the future once feedback is addressed and the plugin reaches stable, so please give it a try.
API Changes
RoomDatabase.QueryCallback
has been defined as a functional interface to allow SAM conversion usages. (Iab8ea, b/281008549)
Bug Fixes
- Resolving issue arising when instantiating the database in Robolectric after the migration of Room sources from Java to Kotlin. (Ic053c, b/274924903)
Version 2.6.0-alpha01
March 22, 2023
androidx.room:room-*:2.6.0-alpha01
is released. Version 2.6.0-alpha01 contains these commits.
New Features
- Supporting value classes in Room for KSP. Room is now able to support value classes in Entities. (4194095)
- Kotlin code generation(or “Kotlin CodeGen”) can now be enabled in Room (4297ec0). To turn on Kotlin CodeGen in Room, add the
room.generateKotlin
option name to your processor options for KSP. For more details on how to pass processor options for KSP, see the KSP documentation.
Note: When using Kotlin CodeGen, it is important to note that there are additional restrictions that have been added. Abstract properties as DAO getters or DAO queries in Kotlin CodeGen are disallowed, and instead expected to be rewritten as functions to avoid the false notion that the property value is immutable and has a fixed stored result. Another restriction that has been added is that Nullable collection return types are no longer allowed in Room for Kotlin CodeGen.
Warning: You may find that your projects are more strict in terms of nullability when using Kotlin CodeGen. In Kotlin CodeGen, the nullability of type arguments is important, wheras in Java this is mostly ignored. For example, let's say you have a `Flow
API Changes
- Guarding against meaningless usage of nullable collections in DAO method return types. (I777dc, b/253271782, b/259426907)
- Add an API for creating a Flow that emits invalidation tracker changes. The API is useful for creating streams that need to react to database changes. (I8c790, b/252899305)
Bug Fixes
- Disallow abstract properties as DAO getters or DAO queries in Kotlin codegen, instead they should be rewritten as functions to avoid the false notion that the property value is immutable and has a fixed stored result. (If6a13, b/127483380, b/257967987)
Version 2.5.2
Version 2.5.2
June 21, 2023
androidx.room:room-*:2.5.2
is released. Version 2.5.2 contains these commits.
Bug Fixes
- Fix an incompatibility issue with the kotlinx-metadata-jvm. (386d5c)
- Fix an issue that causes Room to throw an error when being used in a Robolectric test. (f79bea, b/274924903)
Version 2.5.1
Version 2.5.1
March 22, 2023
androidx.room:room-*:2.5.1
is released. Version 2.5.1 contains these commits.
Bug Fixes
- Avoid checking the database parent directory in
FrameworkSQLiteHelper
if the database is already open. (5de86b8) - Use an
isOpenInternal
check when checking if the database is already open. (e91fb35) - Better handling of the reentrant case in Room's
acquireTransactionThread()
is now available. (219f98b). During a suspending transaction, Room uses a thread from the transaction executor, starts an event loop in it and dispatches suspending database operations to it so they are all encapsulated within the transaction coroutine. It is usually expected that the transaction thread is different from the one starting the transaction, but in some cases they are the same. To handle such reentrant cases thewithTransaction()
has been refactored to no longer rely on a control job and instead it will execute the suspending transaction block from within therunBlocking
in the transaction thread.
Version 2.5.0
Version 2.5.0
February 22, 2023
androidx.room:room-paging-guava:2.5.0
, androidx.room:room-paging-rxjava2:2.5.0
, and androidx.room:room-paging-rxjava3:2.5.0
are released. Version 2.5.0 contains these commits.
Version 2.5.0
January 11, 2023
androidx.room:room-*:2.5.0
is released. Version 2.5.0 contains these commits.
Important changes since 2.4.0
- All of
room-runtime
sources has been converted from Java to Kotlin. Note that you may encounter source incompatibility issues if your code is in Kotlin due to the library conversion to Kotlin. For example, a known source incompatible change is that inInvalidationTracker
you will now need to declareonInvalidate()
inObserver
to have a param of typeSet
and notMutableSet
. Moreover, certain getter methods were converted to properties requiring the property access syntax on Kotlin files. Please file a bug if there are any significant incompatibilities. - Added a new shortcut annotation,
@Upsert
, which attempts to insert an entity when there is no uniqueness conflict or update the entity if there is a conflict. (I7aaab, b/241964353) - New room-paging artifacts
room-paging-rxjava2
,room-paging-rxjava3
androom-paging-guava
have been added for support in Room Paging. - Added APIs for providing key and value tables names for disambiguation in
@MapInfo
(Icc4b5)
Version 2.5.0-rc01
December 7, 2022
androidx.room:room-*:2.5.0-rc01
is released. Version 2.5.0-rc01 contains these commits.
- This release is identical to
2.5.0-beta02
.
Version 2.5.0-beta02
November 9, 2022
androidx.room:room-*:2.5.0-beta02
is released. Version 2.5.0-beta02 contains these commits.
API Changes
- Fix various APIs that take query arguments from invariant (
Array<Any?>
) to contravariant (Array<out Any?>
) to match Java’s array behavior. (b/253531073)
Version 2.5.0-beta01
October 5, 2022
androidx.room:room-*:2.5.0-beta01
is released. Version 2.5.0-beta01 contains these commits.
API Changes
- Restrict the minimum version that supports
@Upsert
to be API 16. This is due to the inability to identity a primary key constraint conflict in older APIs. (I5f67f, b/243039555)
Bug Fixes
- Fixed an issue where shadow tables where incorrectly exported to the schema
.json
files, corrupting them. (I4f83b, b/246751839)
Version 2.5.0-alpha03
August 24, 2022
androidx.room:room-*:2.5.0-alpha03
is released. Version 2.5.0-alpha03 contains these commits.
New Features
- Added a new shortcut annotation,
@Upsert
, which attempts to insert an entity when there is no uniqueness conflict or update the entity if there is a conflict. (I7aaab, b/241964353)
Bug Fixes
- Room will now throw a
SQLiteConstraintException
instead of aIllegalStateException
during an auto-migration foreign key constraint check. (I328dd) - Fix a Kotlin source incompatible change for getter / properties of
getOpenHelper
,getQueryExecutor
andgetTransactionExecutor
. (Iad0ac)
Version 2.5.0-alpha02
June 1, 2022
androidx.room:room-*:2.5.0-alpha02
is released. Version 2.5.0-alpha02 contains these commits.
New Features
- New
room-paging
artifactsroom-paging-rxjava2
,room-paging-rxjava3
androom-paging-guava
have been added for support in Room Paging.(41a1d4,b/203666906),(eb6098,b/203666906),(1b9ae4,b/203666906)
API Changes
- All of
room-runtime
has been converted from Java to Kotlin. (If2069, b/206859668),(Ie4b55, b/206859668), (I697ee, b/206859668), (I96c25, b/206859668)Note: You may encounter source incompatibility issues due to the library conversion to Kotlin. If your code was in Kotlin and calling the old version of Room, the new version will need to handle these cases. For example, a known source incompatible change is that in
InvalidationTracker
you will now need to declareonInvalidate()
inObserver
to have a param of typeSet
and notMutableSet
. - Added APIs for providing key and value tables names for disambiguation in
@MapInfo
(Icc4b5) - Fix a source compatibility issue to re-allow
@Ignore
in property getters. (Ifc2fb)
Bug Fixes
- Duplicate column resolution heuristic algorithm. Room will now attempt to resolve ambiguous columns in a multimap query. This allows for JOINs with tables containing same-name tables to be correctly mapped to a result data object. (I4b444, b/201306012, b/212279118)
Version 2.5.0-alpha01
February 23, 2022
androidx.room:room-*:2.5.0-alpha01
is released. Version 2.5.0-alpha01 contains these commits.
API Changes
- Fixed an issue where Room
@IntDef
usage were not being enforced in Kotlin sources. (I75f41, b/217951311) - Fixed a source compatibility issue to re-allow
@Query
in property getters. (I0a09b) - Converted room-common from Java to Kotlin. (I69c48, b/206858235)
Note: You may encounter source incompatibility issues as some properties have been moved into companion objects during the library conversion to Kotlin. If your code was in Kotlin and calling the old version of Room, the new version will need the ".Companion" suffix when accessing these properties.
- Converted room-migration from Java to Kotlin. (I2724b, b/206858622)
- Converted
paging
related files inroom-runtime
from Java to Kotlin. (I82fc8, b/206859668) - Added API for multi-process lock and usage at the FrameworkSQLite* level, to protect multi-process 1st time database creation and migrations. (Ied267, b/193182592)
Bug Fixes
- Added support for internal properties in Kotlin sources.
This is a slight behavior change in Room where it will use the source
name of functions while matching them to properties as getters/setters
(previously, it was using JVM name of the function which is different
for internal functions/properties).
If you are using custom
@JvmName
annotations to match getters/setters to private properties, please double check the generated code after the update (If6531, b/205289020)
Version 2.4.3
Version 2.4.3
July 27, 2022
androidx.room:room-*:2.4.3
is released. Version 2.4.3 contains these commits.
Bug Fixes
- Fixed an issue that would cause Room to not recognize suspend functions in Kotlin 1.7 (b/236612358)
Version 2.4.2
Version 2.4.2
February 23, 2022
androidx.room:room-*:2.4.2
is released. Version 2.4.2 contains these commits.
Bug Fixes
- Fix an issue generating code for a Dao
@Transaction
suspend function with a body that generates a default interface method due to compilation with-Xjvm-default=all
or equivalent. (Ia4ce5) - Resolving a bug where Room generates code for a
Array<ByteArray>
return type query method. (If086e, b/213789489)
Version 2.4.1
Version 2.4.1
January 12, 2022
androidx.room:room-*:2.4.1
is released. Version 2.4.1 contains these commits.
Bug Fixes
- Added support for internal properties in Kotlin sources.
This is a slight behavior change in Room where it will use the source
name of functions while matching them to properties as getters/setters
(previously, it was using JVM name of the function which is different
for internal functions/properties).
If you are using custom
@JvmName
annotations to match getters/setters to private properties, please double check the generated code after the update (If6531, b/205289020)
Version 2.4.0
Version 2.4.0
December 15, 2021
androidx.room:room-*:2.4.0
is released. Version 2.4.0 contains these commits.
Important changes since 2.3.0
- Auto Migrations: Room now offers an API for automatically generating migrations as long as schemas are exported. To let Room know that it should generate an auto-migration a new property
@Database#autoMigrations
can be used to declare the versions to auto-migrate from and to. When Room needs additional information regarding tables and column renames or deletes, then the@AutoMigration
annotation can declare a specification class containing such inputs. See the@AutoMigration
documentation for more details. - Dependency Injection in Auto Migrations:
@ProvidedAutoMigrationSpec
is a new API for declaring that anAutoMigrationSpec
will be provided at runtime viaRoomDatabase.Builder#addAutoMigrationSpec()
. This allows for a dependency injection framework to provide such specs when they need complex dependencies. - Migration Test Helper Support for Auto Migrations: Room’s
MigrationTestHelper
was updated to support auto migrations by providing a new constructor API that receives the database class under test. This allows the helper to automatically add auto migrations the same way duringrunMigrationsAndValidate
. - Room-Paging Support:
androidx.room:room-paging
is released, providing native Paging 3.0 support for Room queries returningandroidx.paging.PagingSource
. - Relational Query Methods: Room now supports multimap return types
@Dao
methods, useful for JOIN statements. The supported types of multimaps areMap
,SparseArray
,LongSparseArray
, along with Guava'sImmutableMap
,ImmutableSetMultimap
andImmutableListMultimap
.
Version 2.4.0-rc01
December 1, 2021
androidx.room:room-*:2.4.0-rc01
is released. Version 2.4.0-rc01 contains these commits.
New Features
- Update Room’s dependency on KSP to
1.6.0-1.0.1
to support Kotlin 1.6
Version 2.4.0-beta02
November 17, 2021
androidx.room:room-*:2.4.0-beta02
is released. Version 2.4.0-beta02 contains these commits.
New Features
- We’ve added support for SparseArray and LongSparseArray in @MapInfo. (Ic91a2b/138910317)
Bug Fixes
- We've added a new TypeConverter analyzer that takes nullability information in types into account. As this information is only available in KSP, it is turned on by default only in KSP. If it causes any issues, you can turn it off by passing room.useNullAwareTypeAnalysis=false to the annotation processor. If that happens, please a file bug as this flag will be removed in the future. With this new TypeConverter analyzer, it is suggested to only provide non-null receiving TypeConverters as the new analyzer has the ability to wrap them with a null check. Note that this has no impact for users using KAPT or Java as the annotation processors (unlike KSP), don't have nullability information in types. (Ia88f9, b/193437407)
- Fix a bug where Room would fail to compile with a SQL error when an FTS entity declared to use the ICU tokenizer. (I00db9, b/201753224)
- Resolved issue in auto migrations regarding a new column added to an embedded Entity between versions. (I5fcb1b/193798291)
- We have resolved an issue regarding the relational query method return types in LEFT JOIN queries. With these changes, in the case where a 1-many mapping is present, the collection returned for a key will not include the invalid value object if it is not found in the cursor. If no valid values are found, then a key will be mapped to an empty collection. (Id5552b/201946438)
- Resolved the auto migration issue where SQLite keywords failed to be escaped in column names. (Idbed4b/197133152)
Version 2.4.0-beta01
October 13, 2021
androidx.room:room-*:2.4.0-beta01
is released. Version 2.4.0-beta01 contains these commits.
Bug Fixes
- Fixed an issue with auto-migrations not adding new columns when another table in the same auto-migration also had a new column with the same name. (Ia5db5, b/200818663)
- The PagingSource implementation generated by room-paging now
uses the
queryExecutor
passed throughRoomDatabase.Builder
, so it can be overridden, instead ofDispatchers.IO
previously. (Iae259)
Version 2.4.0-alpha05
September 29, 2021
androidx.room:room-*:2.4.0-alpha05
is released. Version 2.4.0-alpha05 contains these commits.
New Features
- Added a built-in type converter for UUID. (I671e8, b/73132006)
API Changes
Added a new property to the TypeConverters annotation to let developers disable built-in Enum and UUID converters. By default, these converters are on but you can disable them for a certain scope, or for the whole database. See TypeConverters documentation for details. (36ae9e, b/195413406)
Supporting non-POJO keys/values for Multimap return types in DAOs via the
@MapInfo
annotation. (I4d704)
@MapInfo
will be required when the key or value column of the map are from a single column. See example:
@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>
- Make
room-paging
a required artifact when using Paging3 with Room. (Ieaffe)
Bug Fixes
- Fix an issue where multimap queries results were not correctly ordered when the query contained an ORDER BY clause of a column from the map's key. (I6b887)
External Contribution
- Added new API to specify index order in @Index. Thanks to Nikita Zhelonkin. (I033fc)
Version 2.4.0-alpha04
July 21, 2021
androidx.room:room-*:2.4.0-alpha04
is released. Version 2.4.0-alpha04 contains these commits.
New Features
Room now supports multimap return types
@Dao
methods, useful for JOIN statements. The supported types of multimaps areMap
along with Guava'sImmutableMap
,ImmutableSetMultimap
andImmutableListMultimap
.The following are examples of multimap queries:
One-to-One Relation Map
@Query("SELECT * FROM Song JOIN Artist ON Song.artistId = Artist.artistId") fun getSongAndArtist(): Map<Song, Artist>
One-to-Many Relation Map (Standard multimap)
@Query("SELECT * FROM Artist JOIN Album ON Artist.id = Album.artistId") fun getArtistAndAlbums(): Map<Artist, List<Album>>
The multimap result can also be wrapped in the supported async return types, such as
LiveData
, Rx’sObservable
, or coroutinesFlow
.
Room-Paging
androidx.room:room-paging
is released, providing native Paging 3.0 support for Room queries returningandroidx.paging.PagingSource
.@Dao interface UserDao { @Query("SELECT * FROM users ORDER BY id ASC") fun loadUsers(): PagingSource<Int, User> }
This artifact replaces the
androidx.paging.PagingSource
implementation generated by Room with one built on top of Paging 3.0 APIs. The new PagingSource implementation parses keys differently, so any key manually supplied to Room’s PagingSource would need to account for this behavior change, including the initialKey passed via Pager’s constructor. Pages will start loading from theKey
withKey
being the first loaded item. This deviates from existing behavior whereLoadParams.Refresh.Key
is treated as the user's scroll position and items are loaded both before and after the key.The artifact is optional and opting out will fallback to existing support for Paging 3.0 that was introduced in Room 2.3. However, this artifact will become non-optional in future release for those using Room with Paging 3.0. To opt-in, add the new room-paging artifact to your classpath. If you are using Gradle, you can add the following snippet to your build.gradle:
dependency { implementation("androidx.room:room-paging:2.4.0-alpha04") }
Bug Fixes
- Fix an issue in auto migrations regarding handling foreign key violations. (b/190113935)
Version 2.4.0-alpha03
June 16, 2021
androidx.room:room-*:2.4.0-alpha03
is released. Version 2.4.0-alpha03 contains these commits.
API Changes
- Update Room’s
MigrationTestHelper
to support auto migrations by providing a new constructor API that receives the database class under test. This allows the helper to automatically add auto migrations the same way duringrunMigrationsAndValidate
.
Bug Fixes
Fixed an issue with Room’s SQLite native library to support Apple’s M1 chips. (b/174695268
Fixed an issue where Room would not error out when the return type of a @Transaction function was a Flow (I56ddd, b/190075899)
Fix an issue in auto migrations regarding indices. b/177673291
Dependency Updates
- Room’s KSP support now depends on KSP
1.5.10-1.0.0-beta01
. (1ecb11, b/160322705)
Version 2.4.0-alpha02
May 5, 2021
androidx.room:room-*:2.4.0-alpha02
is released. Version 2.4.0-alpha02 contains these commits.
API Changes
@ProvidedAutoMigrationSpec
is a new API for declaring that anAutoMigrationSpec
will be provided at runtime viaRoomDatabase.Builder#addAutoMigrationSpec()
. This allows for a dependency injection framework to provide such specs when they need complex dependencies.
Bug Fixes
- Fix an issue with auto migrations where
@DatabaseView
s where not being properly re-created.
External Contribution
- Fix an issue in Room’s
JournalMode.TRUNCATE
where theInvalidationTracker
callback was sometimes being invoked invalidly, too late, or not at all. Thanks toUli Bubenheimer | bubenheimer@users.noreply.github.com
(b/154040286)
Version 2.4.0-alpha01
April 21, 2021
androidx.room:room-*:2.4.0-alpha01
is released. Version 2.4.0-alpha01 contains these commits.
New Features
- Auto Migrations: Room now offers an API for automatically generating migrations as long as schemas are exported. To let Room know that it should generate an auto-migration a new property
@Database#autoMigrations
can be used to declare the versions to auto-migrate from and to. When Room needs additional information regarding tables and column renames or deletes, then the@AutoMigration
annotation can declare a specification class containing such inputs. See the@AutoMigration
documentation for more details.
Bug Fixes
- Fix an issue where
defaultValue
with extra parenthesis were being incorrectly validated by Room’s schema validation. b/182284899
Version 2.3.0
Version 2.3.0
April 21, 2021
androidx.room:room-*:2.3.0
is released. Version 2.3.0 contains these commits.
Important changes since 2.2.0
- Built-in Enum Support: Room will now default to using an Enum to String and vice versa type converter if none is provided. If a type converter for an enum already exists, Room will prioritize using it over the default one.
- Query Callback: Room now offers a general callback API RoomDatabase.QueryCallback, for when queries are about to execute, which can be useful for logging in debug builds. The callback can be set via
RoomDatabase.Builder#setQueryCallback()
. - Pre-packaged Improvement: Room now has APIs for creating a database using a pre-packaged database read from an input stream. This allows for cases such as when the pre-package database is gzipped.
- Provided Type Converters: Room now has APIs for providing instances of type converters such that the app can control their initialization. To mark a type converter that will be provided to Room use the new annotation @ProvidedTypeConverter.
- RxJava3 Support: Room now supports RxJava3 types. Similar to RxJava2 you can declare DAO methods whose return type are Flowable, Single, Maybe and Completable. Additionally a new artifact
androidx.room:room-rxjava3
is available to support RxJava3. - Paging 3.0 Support: Room will now support generating implementations for
@Query
annotated methods whose return type isandroidx.paging.PagingSource
.
Version 2.3.0-rc01
March 24, 2021
androidx.room:room-*:2.3.0-rc01
is released. Version 2.3.0-rc01 contains these commits.
Bug Fixes
- Fix an issue that prevented Coroutine Flow queries created by Room to be consumed in a suspending
withTransaction
block. (I797bf)
Version 2.3.0-beta03
March 10, 2021
androidx.room:room-*:2.3.0-beta03
is released. Version 2.3.0-beta03 contains these commits.
New Features
- Added incremental compilation support for KSP. (I031c1, b/176453350)
Bug Fixes
- Fixed a bug where creating PagingSource on the main thread could trigger an ANR. (I42b74, b/181221318)
- Fixed
@ExperimentalRoomApi
visibility to be public instead of package private. (b/181356119)
External Contribution
- Allow Room to accept a POJO return type in a
@Query
annotated DAO method when it is also annotated with@SkipQueryVerification
. Room will do a best-effort to convert the result of the query to the POJO return type the same way it is done for a@RawQuery
annotated DAO method. Thanks to ‘Markus Riegel | hey@marcorei.com’. (I45acb)
Version 2.3.0-beta02
February 18, 2021
androidx.room:room-*:2.3.0-beta02
is released. Version 2.3.0-beta02 contains these commits.
New Features
Room now has experimental support for Kotlin Symbol Processing KSP.
KSP is a replacement for KAPT to run annotation processors natively on the Kotlin compiler, significantly reducing build times.
To use Room with KSP, you can apply the KSP Gradle plugin and replace the
kapt
configuration in your build file withksp
. For example, instead ofkapt 'androidx.room:room-compiler:2.3.0-beta02'
useksp 'androidx.room:room-compiler:2.3.0-beta02'
. See the KSP documentation for more details.Note that since KSP is experimental, it is recommended to still use KAPT for production code. The reduction of build times is only applicable if there are no other processors that use KAPT. See b/160322705 for known issues.
Version 2.3.0-beta01
January 27, 2021
androidx.room:room-*:2.3.0-beta01
is released. Version 2.3.0-beta01 contains these commits.
New Features
- Auto Closable Databases: Room now has the ability to close databases that are not accessed after a given amount of time. This is an experimental feature and can be enabled by calling
RoomDatabase.Builder#setAutoCloseTimeout()
. This feature is useful for applications with multiple databases.
Bug Fixes
- Fix an issue where Dao methods with multiple
@Update
or@Delete
methods with different conflict strategies would generate code with only one of the strategies, effectively ignoring the defined one. (/I0b90d, b/176138543)
Version 2.3.0-alpha04
December 16, 2020
androidx.room:room-*:2.3.0-alpha04
is released. Version 2.3.0-alpha04 contains these commits.
New Features
- Room now offers a general callback API
RoomDatabase.QueryCallback
, for when queries are about to execute, which can be useful for logging in debug builds. The callback can be set viaRoomDatabase.Builder#setQueryCallback()
. (Iaa513, b/174478034, b/74877608) - Room will now default to using an Enum to String and vice versa type converter if none is provided. If a type converter for an enum already exists, Room will prioritize using it over the default one. (b/73132006)
Known Issue
- If a one-way type converter for reading already exists for the Enum, Room might accidentally use the built-in String to Enum converter which might not be desired. This is a known issue and can be fixed by making it a two-way converter. See: b/175707691
Bug Fixes
- Fixed an issue where Room would incorrectly disabled incremental annotation processing in newer JDK versions. (b/171387388)
- Fixed an issue with Room finding the generated class when multiple class loaders are used. Thanks for the fix ‘Serendipity | 892449346@qq.com’! (b/170141113)
- Fixed an issue where Room would generate incorrect code when a Kotlin
@Dao
had a base class whose generics are primitives in the JVM. (b/160258066)
External Contribution
- Room will now default to using
beginTransactionNonExclusive
if WAL mode is enabled and API is 16 or more. Thanks to ‘Ahmed I. Khalil | ahmedibrahimkhali@gmail.com’! (b/126258791)
Version 2.3.0-alpha03
October 14, 2020
androidx.room:room-*:2.3.0-alpha03
is released. Version 2.3.0-alpha03 contains these commits.
New Features
Room now has APIs for providing instances of type converters such that the app can control their initialization. To mark a type converter that will be provided to Room use the new annotation
@ProvidedTypeConverter
. Thanks to ‘mzgreen yairobbe@gmail.com’. (Ie4fa5, b/121067210)Room now has APIs for creating a database using a pre-packaged database read from an input stream. This allows for cases such as when the pre-package database is gzipped. Thanks to ‘Ahmed El-Helw ahmedre@gmail.com’ (3e6792, b/146911060)
API Changes
Added missing target to
@ForeignKey
annotation preventing its usage outside of the@Entity
annotation. (Iced1e)The field
mCallbacks
inRoomDatabase.java
is now hidden. (d576cb, b/76109329)
Bug Fixes
Update to TypeConverters documentation to clarify that TypeConverters can only be used to convert columns / fields and not rows. (I07c56, b/77307836)
Update to the DaoProcessor to fix compiler error on Dao with a generic super type with Kotlin "primitives". (Ice6bb, b/160258066)
Update add/remove observer methods documentation to clarify threading (Ifd1d9, b/153948821)
Fix an issue with Room incorrectly validating FTS tables that declared their rowid column. (d62ebc, b/145858914)
External Contributions
Fix upper/lowercase locale issues related to Turkish (5746e3), b/68159494
Replace the
ConcurrentHashMap
insideRoomDatabase
withCollections.synchronizedMap()
to avoid issues on Android Lollipop (d1cfc7, b/162431855)Add a onOpenPrepackagedDatabase callback for when a prepackaged DB is copied. (I1ba74, b/148934423)
Version 2.3.0-alpha02
July 22, 2020
androidx.room:room-*:2.3.0-alpha02
is released. Version 2.3.0-alpha02 contains these commits.
New Features
- RxJava3 Support: Room now supports RxJava3 types. Similar to RxJava2 you can declare DAO methods whose return type are Flowable, Single, Maybe and Completable. Additionally a new artifact
androidx.room:room-rxjava3
is available to support RxJava3. (b/152427884)
API Changes
- Declaring a
@TypeConverter
in Kotlin Object class is now supported. (b/151110764) - Room's incremental annotation processing option is now ON by default. (b/112110217)
Version 2.3.0-alpha01
June 10, 2020
androidx.room:room-*:2.3.0-alpha01
is released. Version 2.3.0-alpha01 contains these commits.
New Features
Paging 3.0 Support: Room will now support generating implementations for
@Query
annotated methods whose return type isandroidx.paging.PagingSource
.@Dao interface UserDao { @Query("SELECT * FROM users ORDER BY id ASC") fun pagingSource(): PagingSource<Int, User> }
API Changes
@RewriteQueriesToDropUnusedColumns
is a new convenient annotation that makes Room rewrite the ‘*’ projection in a query such that unused columns in the result are removed.- The processor option
room.expandProjection
is now deprecated. Use@RewriteQueriesToDropUnusedColumns
as a replacement for Room optimizing queries with star projections. Note that@RewriteQueriesToDropUnusedColumns
does not replace the column conflict solutionroom.expandProjection
offered with regards to return types that contained@Embedded
fields.
Bug Fixes
- Fixed a bug where Room would not correctly detect the JDK version used to enable incremental annotation processor. Thanks to Blaz Solar (me@blaz.solar) (b/155215201)
- Room now embeds its ANTLR dependency with the annotation processor to avoid version conflicts with other processors that also use ANTLR. (b/150106190)
Version 2.2.6
Version 2.2.6
December 16, 2020
androidx.room:room-*:2.2.6
is released. Version 2.2.6 contains these commits.
Bug Fixes
- Fixed an issue where Room would incorrectly disabled incremental annotation processing in newer JDK versions. (b/171387388)
Version 2.2.5
Version 2.2.5
March 18, 2020
androidx.room:room-*:2.2.5
is released. Version 2.2.5 contains these commits.
Bug Fixes
- Make
MultiInstanceInvalidationService
directBootAware. Thanks to ‘Mygod contact-git@mygod.be’ (b/148240967) - Fixed a bug that would cause a crash when multi-instance invalidation was enabled and the database contained a FTS entity. (b/148969394)
- Fixed an issue when loading the SQLite native libraries in the Room annotation processor that would cause the compiler to crash due to parallel compilations. (b/146217083)
Version 2.2.4
Version 2.2.4
February 19, 2020
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
, and androidx.room:room-testing:2.2.4
are released. Version 2.2.4 contains these commits.
Bug Fixes
- Fixed an issue with suspending transactions where they would deadlock if the coroutine was canceled quickly before the transaction actually started. (b/148181325)
- Fixed an issue with the @Generated being wrongly used when building with JDK 9. (b/146538330)
- Fixed an issue where Room would generate incorrect code when a DAO interface in Kotlin had a concrete function. (b/146825845)
Version 2.2.3
Version 2.2.3
December 18, 2019
androidx.room:room-*:2.2.3
is released. Version 2.2.3 contains these commits.
Bug fixes
- Fixed a bug where Room would fail to validate a database that had not gone through any migration and contained a legacy hash with indices in its schema. (b/139306173)
Version 2.2.2
Version 2.2.2
November 20, 2019
androidx.room:room-*:2.2.2
is released. Version 2.2.2 contains these commits.
Bug fixes
- Fixed a bug where collecting a one-to-one relationship with more than 999 rows would cause Room to return null relating items. (b/143105450)
Version 2.2.1
Version 2.2.1
October 23, 2019
androidx.room:room-*:2.2.1
is released. Version 2.2.1 contains these commits.
Bug fixes
- Fixed a bug where Room would incorrectly warn about
CURSOR_MISMATCH
with the compiler optionexpandProjection
turned ON. (b/140759491) - Added a retry mechanism for handling the missing native library used for verifying queries during compile time.
Version 2.2.0
Version 2.2.0
October 9, 2019
androidx.room:room-*:2.2.0
is released. Version 2.2.0 contains these commits.
Important changes since version 2.1.0
- Pre-packaged Database: Two new APIs in
RoomDatabase.Builder
are now available for creating aRoomDatabase
given an already populated database file.createFromAsset()
is for when the pre-populated database file is in the assets folder of the APK, whilecreateFromFile()
is for when the file is in an arbitrary location. The usages of these API change the behaviour of destructive migrations such that during a fallback migration, Room will try to re-copy the pre-populated database if available, otherwise it fallbacks to just dropping and re-creating all tables. b/62185732 - Schema Default Values:
@ColumnInfo
now has a new propertydefaultValue
that can be used to specify the default value of a column. Default values are part of a database schema and will be validated during migrations if specified. b/64088772 - Many-to-Many Relations:
@Relation
now has a new propertyassociateBy
, that takes in a new annotation@Junction
, used to declare a relation that needs to be satisfied via a junction table (also known as a join table). b/69201917 - One-to-One Relations: The restriction in POJO fields annotated with
@Relation
to be of typeList
orSet
has been lifted, effectively allowing single-value relations to be represented. b/62905145 - Target Entity: The DAO annnotations
@Insert
,@Update
and@Delete
now has a new propertytargetEntity
, that allows specifying the target table the DAO method is meant to act on. This allows for the parameters of those DAO methods to be arbitrary POJOs which will be interpreted as partial entities. In practice, this allows partial inserts, deletes and updates. b/127549506 - Coroutines Flow:
@Query
DAO methods can now be of return typeFlow<T>
. The returned Flow will re-emit a new set of values if the observing tables in the query are invalidated. Declaring a DAO function with aChannel<T>
return type is an error, Room instead encourages you to useFlow
and then use the neighboring functions to convert theFlow
into aChannel
. b/130428884 - Gradle Incremental Annotation Processor: Room is now a Gradle isolating
annotation processor and incrementability can be enabled via the processor
option
room.incremental
. See Room Compiler Options for more information. If you encounter any issues please file a bug here. We plan to enable incrementability by default in a future, stable version. b/112110217 - Expanding Projections: A new experimental compiler option
room.expandProjection
was added that causes Room to rewrite a query with a star projection to only contain the columns in the returning type POJO. For example, for a DAO method with@Query("SELECT * FROM Song")
that returns a POJO namedSongIdAndTitle
with only two fields. Then Room will rewrite the query toSELECT id, title FROM Song
such that the minimum set of columns to satisfy the return type are fetched. This essentially eliminates theCURSOR_MISMATCH
warning that is presented when the query returns extra columns that do not match any field in the returning POJO type.
Version 2.2.0-rc01
September 5, 2019
androidx.room:room:2.2.0-rc01
is released. The commits included in this version can be found here.
No public changes since Room 2.2.0-beta01
.
Version 2.2.0-beta01
August 22, 2019
androidx.room:room-*:2.2.0-beta01
is released. The commits included in this version can be found here.
Bug fixes
- Fixed a bug where a Coroutine Flow query would stop reemitting new values after a certain time. (b/139175786)
- Fixed a bug where Room would not accept a legacy schema hash code while opening a database that had not gone a migration since Room 1.0, causing a runtime crash due to invalid schema. (b/139306173)
Version 2.2.0-alpha02
August 7, 2019
androidx.room:room-*:2.2.0-alpha02
is released. The commits included in this version can be found here.
New Features
- Coroutines Flow:
@Query
DAO methods can now be of return typeFlow<T>
. The returned Flow will re-emit a new set of values if the observing tables in the query are invalidated. Declaring a DAO function with aChannel<T>
return type is an error, Room instead encourages you to useFlow
and then use the neighboring functions to convert theFlow
into aChannel
. b/130428884 - Expanding Projections: A new experimental compiler option
room.expandProjection
was added that causes Room to rewrite a query with a star projection to only contain the columns in the returning type POJO. For example, for a DAO method with@Query("SELECT * FROM Song")
that returns a POJO namedSongIdAndTitle
with only two fields. Then Room will rewrite the query toSELECT id, title FROM Song
such that the minimum set of columns to satisfy the return type are fetched. This essentially eliminates theCURSOR_MISMATCH
warning that is presented when the query returns extra columns that do not match any field in the returning POJO type. onDestructiveMigrate
is a new callback API added toRoomDatabase.Callback
for when Room destructively migrates a database. b/79962330
Bug Fixes
- Fixed a bug where Room would generate incorrect code using a method as field setter when the field is protected. b/136194628
- Fixed a bug that caused the InvalidationTracker to throw a NPE in a second process when multi-instance invalidation was enabled and the invalidation Service was killed. b/137454915
- Fixed a bug where Room would not correctly identify the return type of an
inherited suspend function annotated with
@RawQuery
. b/137878827 - Updated the generated code for
@Relation
when the relating key is of type BLOB to use aByteBuffer
that is comparable. b/137881998 - Fixed a bug where Room would complain about missing setters on POJOs used as
partial entity parameters of
@Insert
,@Update
and@Delete
. b/138664463 - Fixed a bug where Room would complain about missing getters & setters for an
ignored column via
@Entity
when the entity class was used in certain DAO methods. b/138238182 - Fixed a bug where Room would not correctly convert named binding args to positional args causing a runtime exception when executing a query with re-used parameters. b/137254857
Version 2.2.0-alpha01
July 10, 2019
New Features
- Pre-packaged Database: Two new APIs in
RoomDatabase.Builder
are now available for creating aRoomDatabase
given an already populated database file.createFromAsset()
is for when the pre-populated database file is in the assets folder of the APK, whilecreateFromFile()
is for when the file is in an arbitrary location. The usages of these API change the behaviour of destructive migrations such that during a fallback migration, Room will try to re-copy the pre-populated database if available, otherwise it fallbacks to just dropping and re-creating all tables. b/62185732 - Schema Default Values:
@ColumnInfo
now has a new propertydefaultValue
that can be used to specify the default value of a column. Default values are part of a database schema and will be validated during migrations if specified. b/64088772Note: If your database schema already has default values, such as those added via
ALTER TABLE x ADD COLUMN y INTEGER NOTNULL DEFAULT z
, and you decide to define default values via@ColumnInfo
to the same columns, then you might need to provide a migration to validate the unaccounted default values. See Room Migrations for more information. - Many-to-Many Relations:
@Relation
now has a new propertyassociateBy
, that takes in a new annotation@Junction
, used to declare a relation that needs to be satisfied via a junction table (also known as a join table). b/69201917 - One-to-One Relations: The restriction in POJO fields annotated with
@Relation
to be of typeList
orSet
has been lifted, effectively allowing single-value relations to be represented. b/62905145 - Target Entity: The DAO annnotations
@Insert
,@Update
and@Delete
now has a new propertytargetEntity
, that allows specifying the target table the DAO method is meant to act on. This allows for the parameters of those DAO methods to be arbitrary POJOs which will be interpreted as partial entities. In practice, this allows partial inserts, deletes and updates. b/127549506 - Gradle Incremental Annotation Processor: Room is now a Gradle isolating
annotation processor and incrementability can be enabled via the processor
option
room.incremental
. See Room Compiler Options for more information. If you encounter any issues please file a bug here. We plan to enable incrementability by default in a future, stable version. b/112110217
Bug Fixes
- Room will no longer propagate the
EmptySetResultException
to the global error handler when the Rx stream of a query has been disposed before the query is complete. b/130257475 - Fixed a bug where Room would show an incorrect error message when a suspend
DAO function annotated with
@RawQuery
didn't have a return type. b/134303897 - Room will no longer generate DAO adapters with raw types. b/135747255
Version 2.1.0
Version 2.1.0
June 13, 2019
Room 2.1.0 is released with no changes from 2.1.0-rc01
. The commits included in the version can be found here.
Important changes since 2.0.0
- FTS: Room now supports entities with a mapping
FTS3 or FTS4 table. Classes annotated with
@Entity
can now be additionally annotated with@Fts3
or@Fts4
to declare a class with a mapping full-text search table. FTS options for further customization are available via the annotation’s methods. - Views: Room now supports declaring a class as a stored query, also known
as a view, using the
@DatabaseView
annotation. - Couroutines: DAO methods can now be suspend functions. Include
room-ktx
in your dependencies to take advantage of this functionality. The ktx artifact also provides the extension functionRoomDatabase.withTransaction
for performing database transactions within a coroutine. - Auto Value: Room now supports declaring
AutoValue
annotated classes as entities and POJOs. The Room annotations
@PrimaryKey
,@ColumnInfo
,@Embedded
and@Relation
can now be declared in an auto value annotated class’s abstract methods. Note that these annotation must also be accompanied by@CopyAnnotations
for Room to properly understand them. - Additional Async Support: DAO methods annotated with
@Insert
,@Delete
or@Update
, along with@Query
containingINSERT
,DELETE
orUPDATE
statements, now support Rx return typesCompletable
,Single
,Maybe
, and Guava's return typeListenableFuture
, and they can also be suspend functions. enableMultiInstanceInvalidation
is a new API inRoomDatabase.Builder
to enable invalidation across multiple instances of RoomDatabase using the same database file.fallbackToDestructiveMigrationOnDowngrade
is a new API inRoomDatabase.Builder
to automatically re-create the database if a downgrade happens.ignoredColumns
is a new API in the@Entity
annotation that can be used to list ignored fields by name.- Room will now properly use Kotlin’s primary constructor in data classes
avoiding the need to declare the properties as
vars
.
Version 2.1.0-rc01
May 29, 2019
Bug Fixes
- Fixed a Room initialization error that might occur due to an already setup temp_store configuration. b/132602198
- Fixed a double quote usage warning for users with SQLite 3.27.0 and above. b/131712640
- Fixed a bug where the InvalidationTracker would cause a crash when multiple invalidation checks would occur in parallel. b/133457594
Version 2.1.0-beta01
May 7, 2019
androidx.room 2.1.0-beta01
is released with no changes from 2.1.0-alpha07. The commits included in this version can be found here.
Version 2.1.0-alpha07
April 25, 2019
API / Behavior Changes
- The extension function
RoomDatabase.withTransaction
has been changed to no longer take a function block with aCoroutineScope
as receiver. This prevents skipping the additionalcoroutineScope { }
wrapper required to run things in the transaction block concurrently.
Bug Fixes
- Fixed a bug where Room would fail to match a TypeConverter for a Kotlin DAO function containing a parameter of Collection type. b/122066791
Version 2.1.0-alpha06
March 22, 2019
API / Behavior Changes
- Async transaction queries are now serialized such that Room will not use
more than one thread for executing database transactions.
RoomDatabase.Builder.setTransactionExecutor(Executor)
was added to allow configuring the executor to be used for transactions. RoomDatabase.runInTransaction(Callable)
will no longer wrap checked exceptions into RuntimeExceptions. b/128623748
Bug Fixes
- Fixed a bug where the invalidation tracker would stop observing a content table if observers for both the content table and an external content FTS table were added. b/128508917
- Updated Room's SQLite grammar to match SQLite 3.24.0. b/110883668
Version 2.1.0-alpha05
March 13, 2019
New Features
- The extension function
RoomDatabase.withTransaction
allows you to safely perform database transactions within a coroutine. Room extensions functions along with coroutines support are available in theroom-ktx
artifact. - Non-abstract DAO methods annotated with
@Transaction
can now be suspend functions. b/120241587
API / Behavior Changes
- The artifact
room-coroutines
has been renamed toroom-ktx
following the same naming as other androidx artifacts. beginTransaction
,setTransactionSuccessful
andendTransaction
inRoomDatabase
have been deprecated in favor ofrunInTransaction
and theroom-ktx
extension functionwithTransaction
.
Bug Fixes
- Fixed a bug where tokenizer arguments were being dropped if the tokenizer used was SIMPLE. b/125427014
- Fixed a bug where Room would fail to correctly identify suspending functions with parameters whos type were an inner class. b/123767877
- Fixed a bug where deferred
@Query
DAO method withINSERT
,UPDATE
orDELETE
statements were eagerly preparing the query in the main thread. b/123695593 - Fixed various bugs where Room would generate incorrect code for certain suspend functions. b/123466702 and b/123457323
- Fixed a bug where deprecated usage of methods were not being correctly suppressed in generated code. b/117602586
- Updated Room dependency of androidx.sqlite to 1.0.2 which contain fixes for correctly handling corrupted databases. b/124476912
Known Issues
- Room 2.1.0-alpha05 depends on the
kotlinx-metadata-jvm
artifact which is not currently available in Maven Central (KT-27991). This dependency can be resolved by addingmaven { url "https://kotlin.bintray.com/kotlinx/" }
to your project repositories.
Version 2.1.0-alpha04
January 25, 2019
New Features
- DAO methods annotated with
@Query
containingINSERT
,UPDATE
orDELETE
statements can now return async typesSingle
,Mayble
,Completable
andListenableFuture
. Additionally they can also be suspend functions. b/120227284
API / Behavior Changes
- Room will now throw an error if a non-abstract DAO method annotated with
@Transaction
returns an async type such asSingle
,Mayble
,Completable
,LiveData
orListenableFuture
. Since transactions are thread confined it is currently impossible for Room to begin and end a transaction around a function that may peform queries in different threads. b/120109336 OnConflictStrategy.FAIL
andOnConflictStrategy.ROLLBACK
have been@Deprecated
since they do not behave as intended with Android's current SQLite bindings. b/117266738
Bug Fixes
- Fixed a bug where Room wouldn't correctly use the TypeConverter of a return type if the DAO method was a suspend function. b/122988159
- Fixed a bug where Room would incorrectly identify inherited suspend functions as non-suspending. b/122902595
- Fixed a bug where Room would generate incorrect code when an
@Embedded
field was in a parent class and used in multiple child classes. b/121099048 - Fixed an issue where the database would deadlock when invoking DAO suspend functions between a
beginTransaction()
andendTransaction()
. b/120854786
Version 2.1.0-alpha03
December 4, 2018
API Changes
- The FTS
tokenizer
in@Fts3
/@Fts4
now takes a String instead of an Enum. This allows custom tokenizers to be used by Room. Built-in tokenizers are still defined inFtsOptions
as string constants. b/119234881
New Features
- Couroutines: DAO methods can now be suspend functions. To support suspend functions in Room a new artifact has been released,
room-coroutines
. b/69474692 - DAO methods annotated with
@Insert
,@Delete
or@Update
now supportListenableFuture
as return type. b/119418331
Bug Fixes
- Fixed a bug where Room would incorrectly attempt to find a constructor with columns in the
ignoredColumns
property of@Entity
. b/119830714 - Fixed a bug where Room would not mark DAO method parameters as final in their generated implementation. b/118015483
- Fixed a bug where Room's processor would crash when reporting an error on a query with special symbols. b/119520136
- Fixed a bug where Room would decline other various
Collection
implementations as arguments of anIN
expression. b/119884035 - Fixed a bug where LiveData returned from Room would get garbage collected when observed forever causing it to no longer emit new data. b/74477406
- Updated
RoomDatabase
's close lock to reduce lock contention. b/117900450
Version 2.1.0-alpha02
October 30, 2018
New Features
- Added support for referencing a
@DatabaseView
in a@Relation
. b/117680932
Bug Fixes
- Fixed a bug where Room would perform disk I/O in the main thread when subscribing and disposing from an Rx return type. b/117201279
- Fixed a bug where Room would fail to find an appropriate type converter for a field in a Kotlin entity class. b/111404868
- Fixed a bug where Room would generate incorrect code for a
DAO
interface implementation containing a Kotlin default method that has no arguments. b/117527454 - Updated Room's SQLite grammar parser, fixing a performance issue that would cause long build times. b/117401230
Version 2.1.0-alpha01
October 8, 2018
New Features
- FTS: Room now supports entities with a mapping FTS3 or FTS4 table. Classes annotated with
@Entity
can now be additionally annotated with@Fts3
or@Fts4
to declare a class with a mapping full-text search table. FTS options for further customization are available via the annotation’s methods. b/62356416 - Views: Room now supports declaring a class as a stored query, also known as a view using the @DatabaseView annotation. b/67033276
- Auto Value: Room now supports declaring AutoValue annotated classes as entities and POJOs. The Room annotations
@PrimaryKey
,@ColumnInfo
,@Embedded
and@Relation
can now be declared in an auto value annotated class’ abstract methods. Note that these annotation must also be accompanied by@CopyAnnotations
for Room to properly understand them. b/62408420 - Additional Rx Return Types Support: DAO methods annotated with
@Insert
,@Delete
or@Update
now support Rx return typesCompletable
,Single<T>
andMaybe<T>
. b/63317956 - Immutable Types with
@Relation
: Room previously required@Relation
annotated fields to be settable but now they can be constructor parameters. enableMultiInstanceInvalidation
: Is a new API inRoomDatabase.Builder
to enable invalidation across multiple instances of RoomDatabase using the same database file. This multi-instance invalidation mechanism also works across multiple processes. b/62334005fallbackToDestructiveMigrationOnDowngrade
: Is a new API inRoomDatabase.Builder
to automatically re-create the database if a downgrade happens. b/110416954ignoredColumns
: Is a new API in the@Entity
annotation that can be used to list ignored fields by name. Useful for ignoring inherited fields on an entity. b/63522075
API / Behavior Changes
mCallback
andmDatabase
inRoomDatabase
are now@Deprecated
and will be removed in the next major version of Room. b/76109329
Bug Fixes
- Fixed two issues where Room wouldn’t properly recover from a corrupted database or a bad migration during initialization. b/111504749 and b/111519144
- Room will now properly use Kotlin’s primary constructor in data classes avoiding the need to declare the fields as
vars
. b/105769985
Version 2.0.0
Version 2.0.0
October 1, 2018
androidx.room 2.0.0
is released with no changes from 2.0.0-rc01.
Version 2.0.0-rc01
September 20, 2018
androidx.room 2.0.0-rc01
is released with no changes from 2.0.0-beta01.
Version 2.0.0-beta01
July 2, 2018
API / Behavior Changes
- Added
RoomDatabase.Builder.setQueryExecutor()
to allow customization of where queries are run - Added RxJava2
Observable
support - Generated DAO and Database implementations are now final
Bug Fixes
- Specify class/field name in "cannot find getter for field" error b/73334503
- Fixed RoomOpenHelper backwards compatibility with older versions of Room b/110197391
Pre-AndroidX Dependencies
For the pre-AndroidX versions of Room, include these dependencies:
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"
}
Version 1.1.1
Version 1.1.1
June 19, 2018
Room 1.1.1
is identical to Room 1.1.1-rc1
.
Version 1.1.1-rc1
May 16, 2018
We highly
recommend using Room 1.1.1-rc1
instead of 1.1.0
if you are using migrations.
Fixed a bug where Room would not handle post migration initialization properly b/79362399
Version 1.1.0
Version 1.1.0-beta3
April 19, 2018
Bug Fixes
- Fix compilation error when a Kotlin POJO references a relation entity that was defined in Java b/78199923
Version 1.1.0-beta2
April 5, 2018
Bug Fixes
Fixed a critical bug in Room's Rx
Single
andMaybe
implementations where it would recycle the query ahead of time, causing problems if you add more than 1 observer to the returnedSingle
orMaybe
instancces. b/76031240[RoomDatabase.clearAllTables][ref-clearAllTables] will not
VACUUM
the database if it is called inside a transaction. b/77235565
Version 1.1.0-beta1
March 21, 2018
API Changes
- Based on API Review feedback,
@RawQuery
does not accept passing aString
as the query parameter anymore. You need to use [SupportSQLiteQuery][ref-SupportSQLiteQuery]. (see [SimpleSQLiteQuery][ref-SimpleSQLiteQuery] to easily create an instance of [SupportSQLiteQuery][ref-SupportSQLiteQuery] with argument support). - RoomDatabase.Builder's [fallbackToDestructiveMigrationFrom][ref-fallbackToDestructiveMigrationFrom] method now accepts
vararg int
instead ofvararg Integer
.
Bug Fixes
- [RoomDatabase.clearAllTables][ref-clearAllTables] now tries to return space back to the operating system by setting a WAL checkpoint and
VACUUM
ing the database. - [
@RawQuery
][ref-RawQuery] now accepts any Pojo for theobservedEntities
property as long as the Pojo references to one or more entities via itsEmbedded
fields orRelation
s. b/74041772 - Paging: Room’s DataSource implementation now correctly handles multi-table dependencies (such as relations, and joins). Previously these would fail to trigger new results, or could fail to compile. b/74128314
Version 1.1.0-alpha1
January 22, 2018
New Features
RawQuery
: This new API allows@Dao
methods to receive the SQL as a query parameter b/62103290, b/71458963fallBackToDestructiveMigrationsFrom
: This new API inRoomDatabase.Builder
allows for finer grained control over from which starting schema versions destructive migrations are allowed (as compared to fallbackToDestructiveMigration) b/64989640- Room now only supports newer Paging APIs (alpha-4+), dropping support for the deprecated
LivePagedListProvider
. To use the new Room alpha, you’ll need to use pagingalpha-4
or higher, and switch fromLivePagedListProvider
toLivePagedListBuilder
if you haven’t already.
Bug Fixes
- Improved support for Kotlin Kapt types. b/69164099
- Order of fields do not invalidate schema anymore. b/64290754