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.

Callback for Builder.createFromAsset, Builder.createFromFile and Builder.createFromInputStream

Public functions
abstract Unit

Deletes all rows from all the tables that are registered to this database as Database.entities.
android
Unit

Closes the database.
Cmn
android
N
open Unit

Called by Room when it is initialized.
android

Protected functions
abstract InvalidationTracker

Creates the invalidation tracker
Cmn
android
N

Public properties
InvalidationTracker

The invalidation tracker for this database.
Cmn
android
N

Extension functions
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.withReadTransaction(block: suspend TransactionScope<R>.() -> R)

Acquire a READ connection and start a Transactor.SQLiteTransactionType.DEFERRED transaction to execute the given block within the transaction.
Cmn
suspend R
<R : Any?> RoomDatabase.withWriteTransaction(block: suspend TransactionScope<R>.() -> R)

Acquire a WRITE connection and start a Transactor.SQLiteTransactionType.IMMEDIATE transaction to execute the given block within the transaction.
Cmn
ERROR CLASS: Symbol not found for SupportSQLiteDatabase

Gets a new SupportSQLiteDatabase implementation that is backed by a RoomDatabase for compatibility with existing usages of SupportSQLiteDatabase.
android

Public functions

clearAllTables

android
Added in 3.0.0-alpha01
@WorkerThread
abstract fun clearAllTables(): Unit

Deletes all rows from all the tables that are registered to this database as Database.entities.

This does NOT reset the auto-increment value generated by PrimaryKey.autoGenerate.

After deleting the rows, Room will set a WAL checkpoint and run VACUUM. This means that the data is completely erased. The space will be reclaimed by the system if the amount surpasses the threshold of database file size.

See SQLite documentation for details. FileFormat

close

Cmn android N
Added in 3.0.0-alpha01
fun close(): Unit

Closes the database.

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

init

android
Added in 3.0.0-alpha01
@CallSuper
open fun init(configuration: DatabaseConfiguration): Unit

Called by Room when it is initialized.

Parameters
configuration: DatabaseConfiguration

The database configuration.
Throws
IllegalArgumentException

if initialization fails.

Protected functions

createInvalidationTracker

Cmn android N
Added in 3.0.0-alpha01
protected abstract fun createInvalidationTracker(): InvalidationTracker

Creates the invalidation tracker

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

Returns
InvalidationTracker

A new invalidation tracker.

Public properties

invalidationTracker

Cmn android N
Added in 3.0.0-alpha01
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

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

withReadTransaction

Cmn 
suspend fun <R : Any?> RoomDatabase.withReadTransaction(block: suspend TransactionScope<R>.() -> R): R

Acquire a READ connection and start a Transactor.SQLiteTransactionType.DEFERRED transaction to execute the given block within the transaction.

This function is a shorthand of:

roomDatabase.useReaderConnection { it.withTransaction(DEFERRED) { block() } }

withWriteTransaction

Cmn 
suspend fun <R : Any?> RoomDatabase.withWriteTransaction(block: suspend TransactionScope<R>.() -> R): R

Acquire a WRITE connection and start a Transactor.SQLiteTransactionType.IMMEDIATE transaction to execute the given block within the transaction.

This function is a shorthand of:

roomDatabase.useWriterConnection { it.withTransaction(IMMEDIATE) { block() } }

getSupportWrapper

android 
fun RoomDatabase.getSupportWrapper(): ERROR CLASS: Symbol not found for SupportSQLiteDatabase

Gets a new SupportSQLiteDatabase implementation that is backed by a RoomDatabase for compatibility with existing usages of SupportSQLiteDatabase.