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

RoomDatabase

public abstract class RoomDatabase
extends Object

java.lang.Object
   ↳ 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.

See also:

Summary

Nested classes

class RoomDatabase.Builder<T extends RoomDatabase>

Builder for RoomDatabase. 

class RoomDatabase.Callback

Callback for RoomDatabase. 

enum RoomDatabase.JournalMode

Journal modes for SQLite database. 

class RoomDatabase.MigrationContainer

A container to hold migrations. 

class RoomDatabase.PrepackagedDatabaseCallback

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

This callback will be invoked after the pre-package DB is copied but before Room had a chance to open it and therefore before the RoomDatabase.Callback methods are invoked. 

interface RoomDatabase.QueryCallback

Callback interface for when SQLite queries are executed. 

Fields

protected SupportSQLiteDatabase mDatabase

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

Public constructors

RoomDatabase()

Creates a RoomDatabase.

Public methods

void beginTransaction()

This method is deprecated. Use runInTransaction(Runnable)

abstract void clearAllTables()

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

void close()

Closes the database if it is already open.

SupportSQLiteStatement compileStatement(String sql)

Wrapper for SupportSQLiteDatabase.compileStatement(String).

void endTransaction()

This method is deprecated. Use runInTransaction(Runnable)

InvalidationTracker getInvalidationTracker()

Returns the invalidation tracker for this database.

SupportSQLiteOpenHelper getOpenHelper()

Returns the SQLite open helper used by this database.

Executor getQueryExecutor()
Executor getTransactionExecutor()
<T> T getTypeConverter(Class<T> klass)

Gets the instance of the given Type Converter.

boolean inTransaction()

Returns true if current thread is in a transaction.

void init(DatabaseConfiguration configuration)

Called by Room when it is initialized.

boolean isOpen()

Returns true if database connection is open and initialized.

Cursor query(String query, Object[] args)

Convenience method to query the database with arguments.

Cursor query(SupportSQLiteQuery query, CancellationSignal signal)

Wrapper for SupportSQLiteDatabase.query(SupportSQLiteQuery).

Cursor query(SupportSQLiteQuery query)

Wrapper for SupportSQLiteDatabase.query(SupportSQLiteQuery).

<V> V runInTransaction(Callable<V> body)

Executes the specified Callable in a database transaction.

void runInTransaction(Runnable body)

Executes the specified Runnable in a database transaction.

void setTransactionSuccessful()

This method is deprecated. Use runInTransaction(Runnable)

Protected methods

abstract InvalidationTracker createInvalidationTracker()

Called when the RoomDatabase is created.

abstract SupportSQLiteOpenHelper createOpenHelper(DatabaseConfiguration config)

Creates the open helper to access the database.

Map<Class<?>, List<Class<?>>> getRequiredTypeConverters()

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.

void internalInitInvalidationTracker(SupportSQLiteDatabase db)

Called by the generated code when database is open.

Inherited methods

Fields

mDatabase

protected SupportSQLiteDatabase mDatabase

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

Set by the generated open helper.

Public constructors

RoomDatabase

public 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

public void beginTransaction ()

This method is deprecated.
Use runInTransaction(Runnable)

Wrapper for SupportSQLiteDatabase.beginTransaction().

clearAllTables

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.

close

public void close ()

Closes the database if it is already open.

compileStatement

public SupportSQLiteStatement compileStatement (String sql)

Wrapper for SupportSQLiteDatabase.compileStatement(String).

Parameters
sql String: The query to compile.
Returns
SupportSQLiteStatement The compiled query.

endTransaction

public void endTransaction ()

This method is deprecated.
Use runInTransaction(Runnable)

Wrapper for SupportSQLiteDatabase.endTransaction().

getInvalidationTracker

public InvalidationTracker getInvalidationTracker ()

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

getOpenHelper

public SupportSQLiteOpenHelper getOpenHelper ()

Returns the SQLite open helper used by this database.

Returns
SupportSQLiteOpenHelper The SQLite open helper used by this database.

getQueryExecutor

public Executor getQueryExecutor ()

Returns
Executor The Executor in use by this database for async queries.

getTransactionExecutor

public Executor getTransactionExecutor ()

Returns
Executor The Executor in use by this database for async transactions.

getTypeConverter

public T getTypeConverter (Class<T> klass)

Gets the instance of the given Type Converter.

Parameters
klass Class: 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.

init

public void init (DatabaseConfiguration configuration)

Called by Room when it is initialized.

Parameters
configuration DatabaseConfiguration: The database configuration.

isOpen

public boolean isOpen ()

Returns true if database connection is open and initialized.

Returns
boolean true if the database connection is open, false otherwise.

query

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

Convenience method to query the database with arguments.

Parameters
query String: The sql query
args Object: The bind arguments for the placeholders in the query
Returns
Cursor A Cursor obtained by running the given query in the Room database.

query

public Cursor query (SupportSQLiteQuery query, 
                CancellationSignal signal)

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.
Returns
Cursor Result of the query.

query

public Cursor query (SupportSQLiteQuery query)

Wrapper for SupportSQLiteDatabase.query(SupportSQLiteQuery).

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

runInTransaction

public V runInTransaction (Callable<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
body Callable: The piece of code to execute.
Returns
V The value returned from the Callable.

runInTransaction

public void runInTransaction (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
body Runnable: The piece of code to execute.

setTransactionSuccessful

public void setTransactionSuccessful ()

This method is deprecated.
Use runInTransaction(Runnable)

Wrapper for SupportSQLiteDatabase.setTransactionSuccessful().

Protected methods

createInvalidationTracker

protected abstract InvalidationTracker createInvalidationTracker ()

Called when the RoomDatabase is created.

This is already implemented by the generated code.

Returns
InvalidationTracker Creates a new InvalidationTracker.

createOpenHelper

protected abstract SupportSQLiteOpenHelper createOpenHelper (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
config DatabaseConfiguration: The configuration of the Room database.
Returns
SupportSQLiteOpenHelper A new SupportSQLiteOpenHelper to be used while connecting to the database.

getRequiredTypeConverters

protected Map<Class<?>, List<Class<?>>> getRequiredTypeConverters ()

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.

Returns
Map<Class<?>, List<Class<?>>> Creates a map that will include all required type converters for this database.

internalInitInvalidationTracker

protected void internalInitInvalidationTracker (SupportSQLiteDatabase db)

Called by the generated code when database is open.

You should never call this method manually.

Parameters
db SupportSQLiteDatabase: The database instance.