Join us on the livestream at Android Dev Summit on 7-8 November 2018, starting at 10AM PDT!

RoomDatabase.Builder

public static class RoomDatabase.Builder
extends Object

java.lang.Object
   ↳ androidx.room.RoomDatabase.Builder<T extends androidx.room.RoomDatabase>


Builder for RoomDatabase.

Summary

Public methods

Builder<T> addCallback(RoomDatabase.Callback callback)

Adds a RoomDatabase.Callback to this database.

Builder<T> addMigrations(Migration... migrations)

Adds a migration to the builder.

Builder<T> allowMainThreadQueries()

Disables the main thread query check for Room.

T build()

Creates the databases and initializes it.

Builder<T> enableMultiInstanceInvalidation()

Sets whether table invalidation in this instance of RoomDatabase should be broadcast and synchronized with other instances of the same RoomDatabase, including those in a separate process.

Builder<T> fallbackToDestructiveMigration()

Allows Room to destructively recreate database tables if Migrations that would migrate old database schemas to the latest schema version are not found.

Builder<T> fallbackToDestructiveMigrationFrom(int... startVersions)

Informs Room that it is allowed to destructively recreate database tables from specific starting schema versions.

Builder<T> fallbackToDestructiveMigrationOnDowngrade()

Allows Room to destructively recreate database tables if Migrations are not available when downgrading to old schema versions.

Builder<T> openHelperFactory(SupportSQLiteOpenHelper.Factory factory)

Sets the database factory.

Builder<T> setJournalMode(RoomDatabase.JournalMode journalMode)

Sets the journal mode for this database.

Builder<T> setQueryExecutor(Executor executor)

Sets the Executor that will be used to execute all non-blocking asynchronous queries and tasks, including LiveData invalidation, Flowable scheduling and ListenableFuture tasks.

Inherited methods

Public methods

addCallback

public Builder<T> addCallback (RoomDatabase.Callback callback)

Adds a RoomDatabase.Callback to this database.

Parameters
callback RoomDatabase.Callback: The callback.

Returns
Builder<T> this

addMigrations

public Builder<T> addMigrations (Migration... migrations)

Adds a migration to the builder.

Each Migration has a start and end versions and Room runs these migrations to bring the database to the latest version.

If a migration item is missing between current version and the latest version, Room will clear the database and recreate so even if you have no changes between 2 versions, you should still provide a Migration object to the builder.

A migration can handle more than 1 version (e.g. if you have a faster path to choose when going version 3 to 5 without going to version 4). If Room opens a database at version 3 and latest version is >= 5, Room will use the migration object that can migrate from 3 to 5 instead of 3 to 4 and 4 to 5.

Parameters
migrations Migration: The migration object that can modify the database and to the necessary changes.

Returns
Builder<T> this

allowMainThreadQueries

public Builder<T> allowMainThreadQueries ()

Disables the main thread query check for Room.

Room ensures that Database is never accessed on the main thread because it may lock the main thread and trigger an ANR. If you need to access the database from the main thread, you should always use async alternatives or manually move the call to a background thread.

You may want to turn this check off for testing.

Returns
Builder<T> this

build

public T build ()

Creates the databases and initializes it.

By default, all RoomDatabases use in memory storage for TEMP tables and enables recursive triggers.

Returns
T A new database instance.

enableMultiInstanceInvalidation

public Builder<T> enableMultiInstanceInvalidation ()

Sets whether table invalidation in this instance of RoomDatabase should be broadcast and synchronized with other instances of the same RoomDatabase, including those in a separate process. In order to enable multi-instance invalidation, this has to be turned on both ends.

This is not enabled by default.

This does not work for in-memory databases. This does not work between database instances targeting different database files.

Returns
Builder<T> this

fallbackToDestructiveMigration

public Builder<T> fallbackToDestructiveMigration ()

Allows Room to destructively recreate database tables if Migrations that would migrate old database schemas to the latest schema version are not found.

When the database version on the device does not match the latest schema version, Room runs necessary Migrations on the database.

If it cannot find the set of Migrations that will bring the database to the current version, it will throw an IllegalStateException.

You can call this method to change this behavior to re-create the database instead of crashing.

Note that this will delete all of the data in the database tables managed by Room.

To let Room fallback to destructive migration only during a schema downgrade then use fallbackToDestructiveMigrationOnDowngrade().

Returns
Builder<T> this

fallbackToDestructiveMigrationFrom

public Builder<T> fallbackToDestructiveMigrationFrom (int... startVersions)

Informs Room that it is allowed to destructively recreate database tables from specific starting schema versions.

This functionality is the same as that provided by fallbackToDestructiveMigration(), except that this method allows the specification of a set of schema versions for which destructive recreation is allowed.

Using this method is preferable to fallbackToDestructiveMigration() if you want to allow destructive migrations from some schema versions while still taking advantage of exceptions being thrown due to unintentionally missing migrations.

Note: No versions passed to this method may also exist as either starting or ending versions in the Migrations provided to addMigrations(Migration). If a version passed to this method is found as a starting or ending version in a Migration, an exception will be thrown.

Parameters
startVersions int: The set of schema versions from which Room should use a destructive migration.

Returns
Builder<T> this

fallbackToDestructiveMigrationOnDowngrade

public Builder<T> fallbackToDestructiveMigrationOnDowngrade ()

Allows Room to destructively recreate database tables if Migrations are not available when downgrading to old schema versions.

Returns
Builder<T> this

openHelperFactory

public Builder<T> openHelperFactory (SupportSQLiteOpenHelper.Factory factory)

Sets the database factory. If not set, it defaults to FrameworkSQLiteOpenHelperFactory.

Parameters
factory SupportSQLiteOpenHelper.Factory: The factory to use to access the database.

Returns
Builder<T> this

setJournalMode

public Builder<T> setJournalMode (RoomDatabase.JournalMode journalMode)

Sets the journal mode for this database.

This value is ignored if the builder is initialized with Room.inMemoryDatabaseBuilder(Context, Class).

The journal mode should be consistent across multiple instances of RoomDatabase for a single SQLite database file.

The default value is RoomDatabase.JournalMode.AUTOMATIC.

Parameters
journalMode RoomDatabase.JournalMode: The journal mode.

Returns
Builder<T> this

setQueryExecutor

public Builder<T> setQueryExecutor (Executor executor)

Sets the Executor that will be used to execute all non-blocking asynchronous queries and tasks, including LiveData invalidation, Flowable scheduling and ListenableFuture tasks.

When unset, a default Executor will be used. The default Executor allocates and shares threads amongst Architecture Components libraries.

The input Executor cannot run tasks on the UI thread.

Parameters
executor Executor

Returns
Builder<T> this