androidx.room

Kotlin |Java

Interfaces

`PooledConnection`	A wrapper of `SQLiteConnection` that belongs to a connection pool and is safe to use in a coroutine.	Cmn
`RoomDatabaseConstructor`	Defines a class that can instantiate the Room generated implementation of an 'abstract' `Database` annotated `RoomDatabase` definition.	Cmn
`RoomOpenDelegateMarker`	Marker interface for Room's code generated delegate.	Cmn
`TransactionScope`	A `PooledConnection` with an active transaction capable of performing nested transactions.	Cmn
`Transactor`	A `PooledConnection` that can perform transactions.	Cmn

Classes

`DatabaseConfiguration`	Configuration class for a `RoomDatabase`.	Cmn N
`InvalidationTracker`	The invalidation tracker keeps track of tables modified by queries and notifies its created `Flow`s about such modifications.	Cmn N
`MultiInstanceInvalidationService`	A `Service` for remote invalidation among multiple `InvalidationTracker` instances.	android
`RoomDatabase`	Base class for all Room databases.	Cmn N
`RoomDatabase.Builder`	Builder for `RoomDatabase`.	Cmn N
`RoomDatabase.Callback`	Callback for `RoomDatabase`	Cmn N
`RoomDatabase.MigrationContainer`	A container to hold migrations.	Cmn N
`RoomRawQuery`	A query with an argument binding function.	Cmn
`RoomWarnings`	The list of warnings that are produced by Room.	Cmn
`RxRoom`		android

Exceptions

EmptyResultSetException

Thrown by Room when the query in a io.reactivex.Single DAO method needs to return a result but the returned result from the database is empty.

android

Objects

`FtsOptions`	Available option values that can be used with `Fts3`&`Fts4`.	Cmn
`Room`	Entry point for building and initializing a `RoomDatabase`.	Cmn android N

Annotations

`AutoMigration`	Declares an automatic migration on a Database.	Cmn
`BuiltInTypeConverters`	Flags to turn on/off extra type converters provided by Room.	Cmn
`ColumnInfo`	Allows specific customization about the column associated with this field.	Cmn
`ColumnInfo.Collate`		Cmn
`ColumnInfo.SQLiteTypeAffinity`	The SQLite column type constants that can be used in typeAffinity()	Cmn
`ConstructedBy`	Defines the `androidx.room.RoomDatabaseConstructor` that will instantiate the Room generated implementation of the annotated `Database`.	Cmn android N
`Dao`	Marks the class as a Data Access Object.	Cmn
`Database`	Marks a class as a `androidx.room.RoomDatabase`.	Cmn
`DatabaseView`	Marks a class as an SQLite view.	Cmn
`Delete`	Marks a method in a `Dao` annotated class as a delete method.	Cmn
`DeleteColumn`	Repeatable annotation declaring the deleted columns in the `AutoMigration.to` version of an auto migration.	Cmn android
`DeleteColumn.Entries`	Container annotation for the repeatable annotation `DeleteColumn`.	android
`DeleteTable`	Repeatable annotation declaring the deleted tables in the `AutoMigration.to` version of an auto migration.	Cmn android
`DeleteTable.Entries`	Container annotation for the repeatable annotation `DeleteTable`.	android
`Embedded`	Marks a field of an `Entity` or POJO to allow nested fields (i.e. fields of the annotated field's class) to be referenced directly in the SQL queries.	Cmn
`Entity`	Marks a class as an entity.	Cmn
`ExperimentalRoomApi`	APIs marked with ExperimentalRoomApi are experimental and may change.	android
`ForeignKey`	Declares a foreign key on another `Entity`.	Cmn
`ForeignKey.Action`	Constants definition for values that can be used in `onDelete` and `onUpdate`.	Cmn
`Fts3`	Marks an `Entity` annotated class as a FTS3 entity.	Cmn
`Fts4`	Marks an `Entity` annotated class as a FTS4 entity.	Cmn
`Ignore`	Ignores the marked element from Room's processing logic.	Cmn
`Index`	Declares an index on an `Entity`. see: SQLite Index Documentation	Cmn
`Insert`	Marks a method in a `Dao` annotated class as an insert method.	Cmn
`Junction`	Declares a junction to be used for joining a relationship.	Cmn
`MapColumn`	Declares which column is used to build a map or multimap return value in a `Dao` query method.	Cmn
`MapInfo`	This annotation is deprecated. Use @MapColumn instead.	Cmn
`OnConflictStrategy`	Set of conflict handling strategies for various {@link Dao} methods.	Cmn
`PrimaryKey`	Marks a field in an `Entity` as the primary key.	Cmn
`ProvidedAutoMigrationSpec`	Marks a class as an auto migration spec that will be provided to Room at runtime.	Cmn
`ProvidedTypeConverter`	Marks a class as a type converter that will be provided to Room at runtime.	Cmn
`Query`	Marks a method in a `Dao` annotated class as a query method.	Cmn
`RawQuery`	Marks a method in a `Dao` annotated class as a raw query method where you can pass the query as a `androidx.room.RoomRawQuery` or androidx.sqlite.db.SupportSQLiteQuery.	Cmn
`Relation`	A convenience annotation which can be used in a POJO to automatically fetch relation entities.	Cmn
`RenameColumn`	Repeatable annotation declaring the renamed columns in the `AutoMigration.to` version of an auto migration.	Cmn android
`RenameColumn.Entries`	Container annotation for the repeatable annotation `RenameColumn`.	android
`RenameTable`	Repeatable annotation declaring the renamed tables in the new version of an auto migration.	Cmn android
`RenameTable.Entries`	Container annotation for the repeatable annotation `RenameTable`.	android
`RewriteQueriesToDropUnusedColumns`	When present, `RewriteQueriesToDropUnusedColumns` annotation will cause Room to rewrite your `Query` methods such that only the columns that are used in the response are queried from the database.	Cmn
`SkipQueryVerification`	Skips database verification for the annotated element.	Cmn
`Transaction`	Marks a method in a `Dao` class as a transaction method.	Cmn
`TypeConverter`	Marks a method as a type converter.	Cmn
`TypeConverters`	Specifies additional type converters that Room can use.	Cmn
`Update`	Marks a method in a `Dao` annotated class as an update method.	Cmn
`Upsert`	Marks a method in a `Dao` annotated class as an upsert (insert or update) method.	Cmn

Enums

`BuiltInTypeConverters.State`	Control flags for built in converters.	Cmn
`FtsOptions.MatchInfo`		Cmn
`FtsOptions.Order`		Cmn
`Index.Order`		Cmn
`RoomDatabase.JournalMode`	Journal modes for SQLite database.	Cmn N
`Transactor.SQLiteTransactionType`	Transaction types.	Cmn

Extension functions summary

`suspend R`	`<R : Any?> Transactor.deferredTransaction(block: suspend TransactionScope<R>.() -> R)` Performs a `SQLiteTransactionType.DEFERRED` within the `block`.	Cmn
`suspend R`	`<R : Any?> Transactor.exclusiveTransaction(block: suspend TransactionScope<R>.() -> R)` Performs a `SQLiteTransactionType.EXCLUSIVE` within the `block`.	Cmn
`suspend Unit`	`PooledConnection.execSQL(sql: String)` Executes a single SQL statement that returns no values.	Cmn
`suspend R`	`<R : Any?> Transactor.immediateTransaction(block: suspend TransactionScope<R>.() -> R)` Performs a `SQLiteTransactionType.IMMEDIATE` within the `block`.	Cmn
`Flow<Set<String>>`	`RoomDatabase.invalidationTrackerFlow( vararg tables: String, emitInitialState: Boolean )` This function is deprecated. Replaced by equivalent API in InvalidationTracker.	android
`suspend R`	`<R : Any?> RoomDatabase.useReaderConnection(block: suspend (Transactor) -> R)` Acquires a READ connection, suspending while waiting if none is available and then calling the `block` to use the connection once it is acquired.	Cmn
`suspend R`	`<R : Any?> RoomDatabase.useWriterConnection(block: suspend (Transactor) -> R)` Acquires a WRITE connection, suspending while waiting if none is available and then calling the `block` to use the connection once it is acquired.	Cmn
`suspend R`	`<R : Any?> RoomDatabase.withTransaction(block: suspend () -> R)` Calls the specified suspending `block` in a database transaction.	android

Extension functions

deferredTransaction

Cmn

Artifact: androidx.room:room-runtime

View Source

suspend fun <R : Any?> Transactor.deferredTransaction(block: suspend TransactionScope<R>.() -> R): R

Performs a SQLiteTransactionType.DEFERRED within the block.

exclusiveTransaction

Cmn

Artifact: androidx.room:room-runtime

View Source

suspend fun <R : Any?> Transactor.exclusiveTransaction(block: suspend TransactionScope<R>.() -> R): R

Performs a SQLiteTransactionType.EXCLUSIVE within the block.

execSQL

Cmn

Artifact: androidx.room:room-runtime

View Source

Added in 2.7.0-alpha11

suspend fun PooledConnection.execSQL(sql: String): Unit

Executes a single SQL statement that returns no values.

immediateTransaction

Cmn

Artifact: androidx.room:room-runtime

View Source

suspend fun <R : Any?> Transactor.immediateTransaction(block: suspend TransactionScope<R>.() -> R): R

Performs a SQLiteTransactionType.IMMEDIATE within the block.

invalidationTrackerFlow

android

Artifact: androidx.room:room-runtime

View Source

fun RoomDatabase.invalidationTrackerFlow(
    vararg tables: String,
    emitInitialState: Boolean = true
): Flow<Set<String>>

Creates a Flow that listens for changes in the database via the InvalidationTracker and emits sets of the tables that were invalidated.

The Flow will emit at least one value, a set of all the tables registered for observation to kick-start the stream unless emitInitialState is set to false.

If one of the tables to observe does not exist in the database, this functions throws an IllegalArgumentException.

The returned Flow can be used to create a stream that reacts to changes in the database:

fun getArtistTours(from: Date, to: Date): Flow<Map<Artist, TourState>> {
  return db.invalidationTrackerFlow("Artist").map { _ ->
    val artists = artistsDao.getAllArtists()
    val tours = tourService.fetchStates(artists.map { it.id })
    associateTours(artists, tours, from, to)
  }
}

Parameters
`vararg tables: String`	The name of the tables or views to observe.
`emitInitialState: Boolean = true`	Set to `false` if no initial emission is desired. Default value is `true`.

useReaderConnection

Cmn

Artifact: androidx.room:room-runtime

View Source

suspend fun <R : Any?> RoomDatabase.useReaderConnection(block: suspend (Transactor) -> R): R

Acquires a READ connection, suspending while waiting if none is available and then calling the block to use the connection once it is acquired. A RoomDatabase will have one or more READ connections. The connection to use in the block is an instance of Transactor that provides the capabilities for performing nested transactions.

Using the connection after block completes is prohibited.

The connection will be confined to the coroutine on which block executes, attempting to use the connection from a different coroutine will result in an error.

If the current coroutine calling this function already has a confined connection, then that connection is used.

A connection is a limited resource and should not be held for more than it is needed. The best practice in using connections is to avoid executing long-running computations within the block. If a caller has to wait too long to acquire a connection a SQLiteException will be thrown due to a timeout.

Parameters
`block: suspend (Transactor) -> R`	The code to use the connection.

Throws
`androidx.sqlite.SQLiteException`	when the database is closed or a thread confined connection needs to be upgraded or there is a timeout acquiring a connection.

See also
`useWriterConnection`

useWriterConnection

Cmn

Artifact: androidx.room:room-runtime

View Source

suspend fun <R : Any?> RoomDatabase.useWriterConnection(block: suspend (Transactor) -> R): R

Acquires a WRITE connection, suspending while waiting if none is available and then calling the block to use the connection once it is acquired. A RoomDatabase will have only one WRITE connection. The connection to use in the block is an instance of Transactor that provides the capabilities for performing nested transactions.

Using the connection after block completes is prohibited.

The connection will be confined to the coroutine on which block executes, attempting to use the connection from a different coroutine will result in an error.

If the current coroutine calling this function already has a confined connection, then that connection is used as long as it isn't required to be upgraded to a writer. If an upgrade is required then a SQLiteException is thrown.

Parameters
`block: suspend (Transactor) -> R`	The code to use the connection.

Throws
`androidx.sqlite.SQLiteException`	when the database is closed or a thread confined connection needs to be upgraded or there is a timeout acquiring a connection.

See also
`useReaderConnection`

withTransaction

android

Artifact: androidx.room:room-runtime

View Source

suspend fun <R : Any?> RoomDatabase.withTransaction(block: suspend () -> R): R

Calls the specified suspending block in a database transaction. The transaction will be marked as successful unless an exception is thrown in the suspending block or the coroutine is cancelled.

Room will only perform at most one transaction at a time, additional transactions are queued and executed on a first come, first serve order.

Performing blocking database operations is not permitted in a coroutine scope other than the one received by the suspending block. It is recommended that all Dao function invoked within the block be suspending functions.

The internal dispatcher used to execute the given block will block an utilize a thread from Room's transaction executor until the block is complete.