androidx.room

---

Kotlin |Java

Common/AllAndroid/JVMNative/C/iOS

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

This function is deprecated.
Replaced by equivalent API in InvalidationTracker.

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.

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