RoomDatabase.Builder

public final class RoomDatabase.Builder<T extends RoomDatabase>

Builder for RoomDatabase.

Parameters
<T extends RoomDatabase>

The type of the abstract database class.

Summary

Public methods
final @NonNull RoomDatabase.Builder<@NonNull T>

Adds an auto migration spec instance to the builder.
final @NonNull RoomDatabase.Builder<@NonNull T>

Adds a Callback to this database.
final @NonNull RoomDatabase.Builder<@NonNull T>

Adds a migration to the builder.
final @NonNull RoomDatabase.Builder<@NonNull T>

Adds a type converter instance to the builder.
final @NonNull T

Creates the database and initializes it.
final @NonNull RoomDatabase.Builder<@NonNull T>
fallbackToDestructiveMigration(boolean dropAllTables)

Allows Room to destructively recreate database tables if Migrations that would migrate old database schemas to the latest schema version are not found.
final @NonNull RoomDatabase.Builder<@NonNull T>
fallbackToDestructiveMigrationFrom(
    boolean dropAllTables,
    int startVersions
)

Informs Room that it is allowed to destructively recreate database tables from specific starting schema versions.
final @NonNull RoomDatabase.Builder<@NonNull T>

Allows Room to destructively recreate database tables if Migrations are not available when downgrading to old schema versions.
final @NonNull RoomDatabase.Builder<@NonNull T>

Sets the SQLiteDriver implementation to be used by Room to open database connections.
final @NonNull RoomDatabase.Builder<@NonNull T>

Sets the journal mode for this database.
final @NonNull RoomDatabase.Builder<@NonNull T>

Sets the CoroutineContext that will be used to execute all asynchronous queries and tasks, such as Flow emissions and InvalidationTracker notifications.

Public methods

addAutoMigrationSpec

Added in 2.4.0
public final @NonNull RoomDatabase.Builder<@NonNull T> addAutoMigrationSpec(@NonNull AutoMigrationSpec autoMigrationSpec)

Adds an auto migration spec instance to the builder.

Parameters
@NonNull AutoMigrationSpec autoMigrationSpec

The auto migration object that is annotated with ProvidedAutoMigrationSpec and is declared in an AutoMigration annotation.
Returns
@NonNull RoomDatabase.Builder<@NonNull T>

This builder instance.

addCallback

Added in 2.0.0
public final @NonNull RoomDatabase.Builder<@NonNull T> addCallback(@NonNull RoomDatabase.Callback callback)

Adds a Callback to this database.

Parameters
@NonNull RoomDatabase.Callback callback

The callback.
Returns
@NonNull RoomDatabase.Builder<@NonNull T>

This builder instance.

addMigrations

Added in 2.0.0
public final @NonNull RoomDatabase.Builder<@NonNull T> addMigrations(@NonNull 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.

A migration can handle more than 1 version (e.g. if you have a faster path to choose when going from 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
@NonNull Migration migrations

The migration objects that modify the database schema with the necessary changes for a version change.
Returns
@NonNull RoomDatabase.Builder<@NonNull T>

This builder instance.

addTypeConverter

Added in 2.3.0
public final @NonNull RoomDatabase.Builder<@NonNull T> addTypeConverter(@NonNull Object typeConverter)

Adds a type converter instance to the builder.

Parameters
@NonNull Object typeConverter

The converter instance that is annotated with ProvidedTypeConverter.
Returns
@NonNull RoomDatabase.Builder<@NonNull T>

This builder instance.

build

Added in 2.0.0
public final @NonNull T build()

Creates the database and initializes it.

Returns
@NonNull T

A new database instance.
Throws
kotlin.IllegalArgumentException

if the builder was misconfigured.

fallbackToDestructiveMigration

Added in 2.7.0-alpha01
public final @NonNull RoomDatabase.Builder<@NonNull T> fallbackToDestructiveMigration(boolean dropAllTables)

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 tables instead of crashing.

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

Parameters
boolean dropAllTables

Set to true if all tables should be dropped during destructive migration including those not managed by Room. Recommended value is true as otherwise Room could leave obsolete data when table names or existence changes between versions.
Returns
@NonNull RoomDatabase.Builder<@NonNull T>

This builder instance.

fallbackToDestructiveMigrationFrom

Added in 2.7.0-alpha01
public final @NonNull RoomDatabase.Builder<@NonNull T> fallbackToDestructiveMigrationFrom(
    boolean dropAllTables,
    int startVersions
)

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

This functionality is the same 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 via addMigrations. If a version passed to this method is found as a starting or ending version in a Migration, an exception will be thrown.

Parameters
boolean dropAllTables

Set to true if all tables should be dropped during destructive migration including those not managed by Room. Recommended value is true as otherwise Room could leave obsolete data when table names or existence changes between versions.
int startVersions

The set of schema versions from which Room should use a destructive migration.
Returns
@NonNull RoomDatabase.Builder<@NonNull T>

This builder instance.

fallbackToDestructiveMigrationOnDowngrade

Added in 2.7.0-alpha01
public final @NonNull RoomDatabase.Builder<@NonNull T> fallbackToDestructiveMigrationOnDowngrade(boolean dropAllTables)

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

For details, see Builder.fallbackToDestructiveMigration.

Parameters
boolean dropAllTables

Set to true if all tables should be dropped during destructive migration including those not managed by Room. Recommended value is true as otherwise Room could leave obsolete data when table names or existence changes between versions.
Returns
@NonNull RoomDatabase.Builder<@NonNull T>

This builder instance.

setDriver

Added in 2.7.0-alpha01
public final @NonNull RoomDatabase.Builder<@NonNull T> setDriver(@NonNull SQLiteDriver driver)

Sets the SQLiteDriver implementation to be used by Room to open database connections.

Parameters
@NonNull SQLiteDriver driver

The driver
Returns
@NonNull RoomDatabase.Builder<@NonNull T>

This builder instance.

setJournalMode

Added in 2.0.0
public final @NonNull RoomDatabase.Builder<@NonNull T> setJournalMode(@NonNull RoomDatabase.JournalMode journalMode)

Sets the journal mode for this database.

The value is ignored if the builder is for an 'in-memory database'. The journal mode should be consistent across multiple instances of RoomDatabase for a single SQLite database file.

The default value is JournalMode.WRITE_AHEAD_LOGGING.

Parameters
@NonNull RoomDatabase.JournalMode journalMode

The journal mode.
Returns
@NonNull RoomDatabase.Builder<@NonNull T>

This builder instance.

setQueryCoroutineContext

Added in 2.7.0-alpha01
public final @NonNull RoomDatabase.Builder<@NonNull T> setQueryCoroutineContext(@NonNull CoroutineContext context)

Sets the CoroutineContext that will be used to execute all asynchronous queries and tasks, such as Flow emissions and InvalidationTracker notifications.

If no CoroutineDispatcher is present in the context then this function will throw an IllegalArgumentException

Parameters
@NonNull CoroutineContext context

The context
Returns
@NonNull RoomDatabase.Builder<@NonNull T>

This Builder instance
Throws
kotlin.IllegalArgumentException

if the context has no CoroutineDispatcher