RoomDatabase

RoomDatabase()

You cannot create an instance of a database, instead, you should acquire it via #Room.databaseBuilder or #Room.inMemoryDatabaseBuilder.

open fun beginTransaction(): Unit

Wrapper for SupportSQLiteDatabase.beginTransaction.

@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

fun close(): Unit

Closes the database.

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

open fun compileStatement(sql: String): SupportSQLiteStatement

Wrapper for SupportSQLiteDatabase.compileStatement.

open fun endTransaction(): Unit

Wrapper for SupportSQLiteDatabase.endTransaction.

open fun <T : Any> getTypeConverter(klass: Class<T>): T?

Gets the instance of the given Type Converter.

open fun inTransaction(): Boolean

Wrapper for SupportSQLiteDatabase.inTransaction. Returns true if current thread is in a transaction.

@CallSuper
open fun init(configuration: DatabaseConfiguration): Unit

Called by Room when it is initialized.

open fun query(query: String, args: Array<Any?>?): Cursor

Convenience method to query the database with arguments.

open fun query(query: SupportSQLiteQuery, signal: CancellationSignal? = null): Cursor

Wrapper for SupportSQLiteDatabase.query.

open fun <V : Any?> runInTransaction(body: Callable<V>): V

Executes the specified Callable in a database transaction. The transaction will be marked as successful unless an exception is thrown in the Callable.

Room will only perform at most one transaction at a time.

If a SQLiteDriver is configured with this database, then it is best to use useWriterConnection along with immediateTransaction to perform transactional operations.

open fun runInTransaction(body: Runnable): Unit

Executes the specified Runnable in a database transaction. The transaction will be marked as successful unless an exception is thrown in the Runnable.

Room will only perform at most one transaction at a time.

If a SQLiteDriver is configured with this database, then it is best to use useWriterConnection along with immediateTransaction to perform transactional operations.

open fun setTransactionSuccessful(): Unit

Wrapper for SupportSQLiteDatabase.setTransactionSuccessful.

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.

protected open fun createOpenHelper(config: DatabaseConfiguration): SupportSQLiteOpenHelper

Creates the open helper to access the database. Generated class already implements this method. Note that this method is called when the RoomDatabase is initialized.

protected open fun internalInitInvalidationTracker(db: SupportSQLiteDatabase): Unit

Initialize invalidation tracker. Note that this method is called when the RoomDatabase is initialized and opens a database connection.

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.

open val isOpen: Boolean

True if database connection is open and initialized.

When Room is configured with RoomDatabase.Builder.setAutoCloseTimeout the database is considered open even if internally the connection has been closed, unless manually closed.

open val openHelper: SupportSQLiteOpenHelper

The SQLite open helper used by this database.

open val queryExecutor: Executor

The Executor in use by this database for async queries.

open val transactionExecutor: Executor

The Executor in use by this database for async transactions.

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

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.

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.

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.