RoomDatabase

Base class for all Room databases. All classes that are annotated with Database must extend this class.

RoomDatabase provides direct access to the underlying database implementation but you should prefer using Dao classes.

See also
Database

Summary

Nested types

Builder for RoomDatabase.
abstract class RoomDatabase.Callback

Callback for RoomDatabase

Journal modes for SQLite database.

A container to hold migrations.

Public constructors
Cmn
N

Public functions
Unit

Closes the database.
Cmn
N

Protected functions
abstract InvalidationTracker

Creates the invalidation tracker
Cmn
N

Public properties
InvalidationTracker

The invalidation tracker for this database.
Cmn
N

Extension functions
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

Public constructors

RoomDatabase

Cmn
Added in 2.0.0
RoomDatabase()

RoomDatabase

N
Added in 2.0.0
RoomDatabase()

Public functions

close

Cmn N
Added in 2.0.0
fun close(): Unit

Closes the database.

Once a RoomDatabase is closed it should no longer be used.

Protected functions

createInvalidationTracker

Cmn N
Added in 2.0.0
protected abstract fun createInvalidationTracker(): InvalidationTracker

Creates the invalidation tracker

An implementation of this function is generated by the Room processor. Note that this method is called when the RoomDatabase is initialized.

Returns
InvalidationTracker

A new invalidation tracker.

Public properties

invalidationTracker

Cmn N
Added in 2.0.0
val invalidationTracker: InvalidationTracker

The invalidation tracker for this database.

You can use the invalidation tracker to get notified when certain tables in the database are modified.

Returns
InvalidationTracker

The invalidation tracker for the database.

Extension functions

invalidationTrackerFlow

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