RoomDatabase

public abstract class 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
RoomDatabase.Builder

Builder for RoomDatabase.
RoomDatabase.Callback

Callback for RoomDatabase.
RoomDatabase.Companion
RoomDatabase.JournalMode

Journal modes for SQLite database.
RoomDatabase.MigrationContainer

A container to hold migrations.
RoomDatabase.PrepackagedDatabaseCallback

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

Callback interface for when SQLite queries are executed.

Public fields
@NonNull InvalidationTracker

The invalidation tracker for this database.
boolean

True if database connection is open and initialized.
final @NonNull ThreadLocal<@NonNull Integer>

Suspending transaction id of the current thread.

Protected fields
volatile final SupportSQLiteDatabase

This field is deprecated. Will be hidden in the next release.

Public constructors

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

Public methods
void

This method is deprecated. beginTransaction() is deprecated
abstract @WorkerThread void

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

Closes the database if it is already open.
@NonNull SupportSQLiteStatement

Wrapper for SupportSQLiteDatabase.compileStatement.
void

This method is deprecated. endTransaction() is deprecated
@NonNull SupportSQLiteOpenHelper

Returns the SQLite open helper used by this database.
@NonNull Executor
@NonNull Executor
T
<T extends Object> getTypeConverter(@NonNull Class<@NonNull T> klass)

Gets the instance of the given Type Converter.
boolean

Returns true if current thread is in a transaction.
@CallSuper void

Called by Room when it is initialized.
@NonNull Cursor
query(@NonNull String query, Object[] args)

Convenience method to query the database with arguments.
@NonNull Cursor

Wrapper for SupportSQLiteDatabase.query.
void

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

Executes the specified Callable in a database transaction.
void

This method is deprecated. setTransactionSuccessful() is deprecated

Protected methods
abstract @NonNull InvalidationTracker

Called when the RoomDatabase is created.
abstract @NonNull SupportSQLiteOpenHelper

Creates the open helper to access the database.
void

Called by the generated code when database is open.

Public fields

invalidationTracker

public @NonNull 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
@NonNull InvalidationTracker

The invalidation tracker for the database.

isOpen

public boolean isOpen

True if database connection is open and initialized.

Returns
boolean

true if the database connection is open, false otherwise.

suspendingTransactionId

public final @NonNull ThreadLocal<@NonNull Integer> suspendingTransactionId

Suspending transaction id of the current thread.

This id is only set on threads that are used to dispatch coroutines within a suspending database transaction.

Protected fields

mDatabase

volatile protected final SupportSQLiteDatabase mDatabase

Set by the generated open helper.

Public constructors

RoomDatabase

public final RoomDatabase()

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

Public methods

beginTransaction

public void beginTransaction()

Wrapper for SupportSQLiteDatabase.beginTransaction.

clearAllTables

@WorkerThread
public abstract void clearAllTables()

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

public void close()

Closes the database if it is already open.

compileStatement

public @NonNull SupportSQLiteStatement compileStatement(@NonNull String sql)

Wrapper for SupportSQLiteDatabase.compileStatement.

Parameters
@NonNull String sql

The query to compile.
Returns
@NonNull SupportSQLiteStatement

The compiled query.

endTransaction

public void endTransaction()

Wrapper for SupportSQLiteDatabase.endTransaction.

getOpenHelper

public @NonNull SupportSQLiteOpenHelper getOpenHelper()

Returns the SQLite open helper used by this database.

Returns
@NonNull SupportSQLiteOpenHelper

The SQLite open helper used by this database.

getQueryExecutor

public @NonNull Executor getQueryExecutor()
Returns
@NonNull Executor

The Executor in use by this database for async queries.

getTransactionExecutor

public @NonNull Executor getTransactionExecutor()
Returns
@NonNull Executor

The Executor in use by this database for async transactions.

getTypeConverter

public T <T extends Object> getTypeConverter(@NonNull Class<@NonNull T> klass)

Gets the instance of the given Type Converter.

Parameters
<T extends Object>

The type of the expected Type Converter subclass.
@NonNull Class<@NonNull T> klass

The Type Converter class.
Returns
T

An instance of T if it is provided in the builder.

inTransaction

public boolean inTransaction()

Returns true if current thread is in a transaction.

Returns
boolean

True if there is an active transaction in current thread, false otherwise.
See also
inTransaction

init

@CallSuper
public void init(@NonNull DatabaseConfiguration configuration)

Called by Room when it is initialized.

Parameters
@NonNull DatabaseConfiguration configuration

The database configuration.
Throws
kotlin.IllegalArgumentException

if initialization fails.

query

public @NonNull Cursor query(@NonNull String query, Object[] args)

Convenience method to query the database with arguments.

The sql query

Parameters
Object[] args

The bind arguments for the placeholders in the query
Returns
@NonNull Cursor

A Cursor obtained by running the given query in the Room database.

query

public @NonNull Cursor query(@NonNull SupportSQLiteQuery query, CancellationSignal signal)

Wrapper for SupportSQLiteDatabase.query.

The Query which includes the SQL and a bind callback for bind arguments.

Parameters
CancellationSignal signal

The cancellation signal to be attached to the query.
Returns
@NonNull Cursor

Result of the query.

runInTransaction

public void runInTransaction(@NonNull Runnable body)

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
@NonNull Runnable body

The piece of code to execute.

runInTransaction

public @NonNull V <V extends Object> runInTransaction(@NonNull Callable<@NonNull V> body)

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
<V extends Object>

The type of the return value.
@NonNull Callable<@NonNull V> body

The piece of code to execute.
Returns
@NonNull V

The value returned from the Callable.

setTransactionSuccessful

public void setTransactionSuccessful()

Wrapper for SupportSQLiteDatabase.setTransactionSuccessful.

Protected methods

createInvalidationTracker

protected abstract @NonNull InvalidationTracker createInvalidationTracker()

Called when the RoomDatabase is created.

This is already implemented by the generated code.

Returns
@NonNull InvalidationTracker

Creates a new InvalidationTracker.

createOpenHelper

protected abstract @NonNull SupportSQLiteOpenHelper createOpenHelper(@NonNull DatabaseConfiguration config)

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
@NonNull DatabaseConfiguration config

The configuration of the Room database.
Returns
@NonNull SupportSQLiteOpenHelper

A new SupportSQLiteOpenHelper to be used while connecting to the database.

internalInitInvalidationTracker

protected void internalInitInvalidationTracker(@NonNull SupportSQLiteDatabase db)

Called by the generated code when database is open.

You should never call this method manually.

Parameters
@NonNull SupportSQLiteDatabase db

The database instance.