Google is committed to advancing racial equity for Black communities. See how.

RoomDatabase

abstract class RoomDatabase
kotlin.Any
   ↳ androidx.room.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.

Summary

Nested classes
open

Builder for RoomDatabase.
abstract

Callback for RoomDatabase.

Journal modes for SQLite database.
open

A container to hold migrations.
abstract

Callback for Builder#createFromAsset(String), Builder#createFromFile(File) and Builder#createFromInputStream(Callable)

Public constructors

Creates a RoomDatabase.
Public methods
open Unit

Wrapper for SupportSQLiteDatabase#beginTransaction().
abstract Unit

Deletes all rows from all the tables that are registered to this database as Database#entities().
open Unit

Closes the database if it is already open.
open SupportSQLiteStatement!
compileStatement(@NonNull sql: String)

Wrapper for SupportSQLiteDatabase#compileStatement(String).
open Unit

Wrapper for SupportSQLiteDatabase#endTransaction().
open InvalidationTracker

Returns the invalidation tracker for this database.
open SupportSQLiteOpenHelper

Returns the SQLite open helper used by this database.
open Executor

open Executor

open T?
getTypeConverter(@NonNull klass: Class<T>)

Gets the instance of the given Type Converter.
open Boolean

Returns true if current thread is in a transaction.
open Unit
init(@NonNull configuration: DatabaseConfiguration)

Called by Room when it is initialized.
open Boolean

Returns true if database connection is open and initialized.
open Cursor
query(@NonNull query: String, @Nullable args: Array<Any!>?)

Convenience method to query the database with arguments.
open Cursor
query(@NonNull query: SupportSQLiteQuery)

Wrapper for SupportSQLiteDatabase#query(SupportSQLiteQuery).
open Cursor
query(@NonNull query: SupportSQLiteQuery, @Nullable signal: CancellationSignal?)

Wrapper for SupportSQLiteDatabase#query(SupportSQLiteQuery).
open Unit
runInTransaction(@NonNull body: Runnable)

Executes the specified Runnable in a database transaction.
open V
runInTransaction(@NonNull body: Callable<V>)

Executes the specified Callable in a database transaction.
open Unit

Wrapper for SupportSQLiteDatabase#setTransactionSuccessful().
Protected methods
abstract InvalidationTracker

Called when the RoomDatabase is created.
abstract SupportSQLiteOpenHelper

Creates the open helper to access the database.
open MutableMap<Class<*>!, MutableList<Class<*>!>!>

Returns a Map of String -> List<Class> where each entry has the `key` as the DAO name and `value` as the list of type converter classes that are necessary for the database to function.
open Unit

Called by the generated code when database is open.
Extension functions
From androidx.room
suspend R
RoomDatabase.withTransaction(block: suspend () -> R)

Calls the specified suspending block in a database transaction.
Properties
SupportSQLiteDatabase!

Set by the generated open helper.

Public constructors

<init>

RoomDatabase()

Creates a RoomDatabase.

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

Public methods

beginTransaction

open fun beginTransaction(): Unit

Deprecated: Use runInTransaction(Runnable)

Wrapper for SupportSQLiteDatabase#beginTransaction().

clearAllTables

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

    close

    open fun close(): Unit

    Closes the database if it is already open.

    compileStatement

    open fun compileStatement(@NonNull sql: String): SupportSQLiteStatement!

    Wrapper for SupportSQLiteDatabase#compileStatement(String).

    Parameters
    sql String: The query to compile.
    Return
    SupportSQLiteStatement! The compiled query.

    endTransaction

    open fun endTransaction(): Unit

    Deprecated: Use runInTransaction(Runnable)

    Wrapper for SupportSQLiteDatabase#endTransaction().

    getInvalidationTracker

    @NonNull open fun getInvalidationTracker(): InvalidationTracker

    Returns the invalidation tracker for this database.

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

    Return
    InvalidationTracker The invalidation tracker for the database.

    getOpenHelper

    @NonNull open fun getOpenHelper(): SupportSQLiteOpenHelper

    Returns the SQLite open helper used by this database.

    Return
    SupportSQLiteOpenHelper The SQLite open helper used by this database.

    getQueryExecutor

    @NonNull open fun getQueryExecutor(): Executor
    Return
    Executor The Executor in use by this database for async queries.

    getTransactionExecutor

    @NonNull open fun getTransactionExecutor(): Executor
    Return
    Executor The Executor in use by this database for async transactions.

    getTypeConverter

    @Nullable open fun <T : Any!> getTypeConverter(@NonNull klass: Class<T>): T?

    Gets the instance of the given Type Converter.

    Parameters
    klass Class<T>: The Type Converter class.
    <T> The type of the expected Type Converter subclass.
    Return
    T? An instance of T if it is provided in the builder.

    inTransaction

    open fun inTransaction(): Boolean

    Returns true if current thread is in a transaction.

    Return
    Boolean True if there is an active transaction in current thread, false otherwise.

    init

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

    Called by Room when it is initialized.

    Parameters
    configuration DatabaseConfiguration: The database configuration.

    isOpen

    open fun isOpen(): Boolean

    Returns true if database connection is open and initialized.

    Return
    Boolean true if the database connection is open, false otherwise.

    query

    @NonNull open fun query(
        @NonNull query: String, 
        @Nullable args: Array<Any!>?
    ): Cursor

    Convenience method to query the database with arguments.

    Parameters
    query String: The sql query
    args Array<Any!>?: The bind arguments for the placeholders in the query
    Return
    Cursor A Cursor obtained by running the given query in the Room database.

    query

    @NonNull open fun query(@NonNull query: SupportSQLiteQuery): Cursor

    Wrapper for SupportSQLiteDatabase#query(SupportSQLiteQuery).

    Parameters
    query SupportSQLiteQuery: The Query which includes the SQL and a bind callback for bind arguments.
    Return
    Cursor Result of the query.

    query

    @NonNull open fun query(
        @NonNull query: SupportSQLiteQuery, 
        @Nullable signal: CancellationSignal?
    ): Cursor

    Wrapper for SupportSQLiteDatabase#query(SupportSQLiteQuery).

    Parameters
    query SupportSQLiteQuery: The Query which includes the SQL and a bind callback for bind arguments.
    signal CancellationSignal?: The cancellation signal to be attached to the query.
    Return
    Cursor Result of the query.

    runInTransaction

    open fun runInTransaction(@NonNull 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.

    Parameters
    body Runnable: The piece of code to execute.

    runInTransaction

    open fun <V : Any!> runInTransaction(@NonNull 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.

    Parameters
    body Callable<V>: The piece of code to execute.
    <V> The type of the return value.
    Return
    V The value returned from the Callable.

    setTransactionSuccessful

    open fun setTransactionSuccessful(): Unit

    Deprecated: Use runInTransaction(Runnable)

    Wrapper for SupportSQLiteDatabase#setTransactionSuccessful().

    Protected methods

    createInvalidationTracker

    @NonNull protected abstract fun createInvalidationTracker(): InvalidationTracker

    Called when the RoomDatabase is created.

    This is already implemented by the generated code.

    Return
    InvalidationTracker Creates a new InvalidationTracker.

    createOpenHelper

    @NonNull protected abstract 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.

    Parameters
    config DatabaseConfiguration!: The configuration of the Room database.
    Return
    SupportSQLiteOpenHelper A new SupportSQLiteOpenHelper to be used while connecting to the database.

    getRequiredTypeConverters

    @NonNull protected open fun getRequiredTypeConverters(): MutableMap<Class<*>!, MutableList<Class<*>!>!>

    Returns a Map of String -> List<Class> where each entry has the `key` as the DAO name and `value` as the list of type converter classes that are necessary for the database to function.

    This is implemented by the generated code.

    Return
    MutableMap<Class<*>!, MutableList<Class<*>!>!> Creates a map that will include all required type converters for this database.

    internalInitInvalidationTracker

    protected open fun internalInitInvalidationTracker(@NonNull db: SupportSQLiteDatabase): Unit

    Called by the generated code when database is open.

    You should never call this method manually.

    Parameters
    db SupportSQLiteDatabase: The database instance.

    Properties

    mDatabase

    protected var mDatabase: SupportSQLiteDatabase!

    Deprecated: Will be hidden in the next release.

    Set by the generated open helper.