androidx.room


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

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

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

Performs a SQLiteTransactionType.DEFERRED within the block.

exclusiveTransaction

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

Performs a SQLiteTransactionType.EXCLUSIVE within the block.

execSQL

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

Executes a single SQL statement that returns no values.

immediateTransaction

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

Performs a SQLiteTransactionType.IMMEDIATE within the block.

invalidationTrackerFlow

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

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.

useWriterConnection

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.

withTransaction

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.