RoomDatabase.Builder

open class RoomDatabase.Builder<T : RoomDatabase>


Builder for RoomDatabase.

Parameters
<T : RoomDatabase>

The type of the abstract database class.

Summary

Public functions

open RoomDatabase.Builder<T>

Adds an auto migration spec to the builder.

open RoomDatabase.Builder<T>

Adds a Callback to this database.

open RoomDatabase.Builder<T>
addMigrations(vararg migrations: Migration)

Adds a migration to the builder.

open RoomDatabase.Builder<T>
addTypeConverter(typeConverter: Any)

Adds a type converter instance to this database.

open RoomDatabase.Builder<T>

Disables the main thread query check for Room.

open T

Creates the databases and initializes it.

open RoomDatabase.Builder<T>
createFromAsset(databaseFilePath: String)

Configures Room to create and open the database using a pre-packaged database located in the application 'assets/' folder.

open RoomDatabase.Builder<T>
createFromAsset(
    databaseFilePath: String,
    callback: RoomDatabase.PrepackagedDatabaseCallback
)

Configures Room to create and open the database using a pre-packaged database located in the application 'assets/' folder.

open RoomDatabase.Builder<T>
createFromFile(databaseFile: File)

Configures Room to create and open the database using a pre-packaged database file.

open RoomDatabase.Builder<T>
createFromFile(
    databaseFile: File,
    callback: RoomDatabase.PrepackagedDatabaseCallback
)

Configures Room to create and open the database using a pre-packaged database file.

open RoomDatabase.Builder<T>

Configures Room to create and open the database using a pre-packaged database via an InputStream.

open RoomDatabase.Builder<T>
createFromInputStream(
    inputStreamCallable: Callable<InputStream>,
    callback: RoomDatabase.PrepackagedDatabaseCallback
)

Configures Room to create and open the database using a pre-packaged database via an InputStream.

open RoomDatabase.Builder<T>

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.

open RoomDatabase.Builder<T>

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

open RoomDatabase.Builder<T>
fallbackToDestructiveMigrationFrom(vararg startVersions: Int)

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

open RoomDatabase.Builder<T>

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

open RoomDatabase.Builder<T>

Sets the database factory.

open RoomDatabase.Builder<T>
@ExperimentalRoomApi
setAutoCloseTimeout(
    autoCloseTimeout: @IntRange(from = 0) Long,
    autoCloseTimeUnit: TimeUnit
)

Enables auto-closing for the database to free up unused resources.

open RoomDatabase.Builder<T>

Sets the journal mode for this database.

open RoomDatabase.Builder<T>

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.

open RoomDatabase.Builder<T>
setQueryCallback(
    queryCallback: RoomDatabase.QueryCallback,
    executor: Executor
)

Sets a QueryCallback to be invoked when queries are executed.

open RoomDatabase.Builder<T>

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

open RoomDatabase.Builder<T>

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

Public functions

addAutoMigrationSpec

Added in 2.4.0
open fun addAutoMigrationSpec(autoMigrationSpec: AutoMigrationSpec): RoomDatabase.Builder<T>

Adds an auto migration spec to the builder.

Parameters
autoMigrationSpec: AutoMigrationSpec

The auto migration object that is annotated with AutoMigrationSpec and is declared in an AutoMigration annotation.

Returns
RoomDatabase.Builder<T>

This builder instance.

addCallback

Added in 2.0.0
open fun addCallback(callback: RoomDatabase.Callback): RoomDatabase.Builder<T>

Adds a Callback to this database.

Parameters
callback: RoomDatabase.Callback

The callback.

Returns
RoomDatabase.Builder<T>

This builder instance.

addMigrations

Added in 2.0.0
open fun addMigrations(vararg migrations: Migration): RoomDatabase.Builder<T>

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
vararg migrations: Migration

The migration object that can modify the database and to the necessary changes.

Returns
RoomDatabase.Builder<T>

This builder instance.

addTypeConverter

Added in 2.3.0
open fun addTypeConverter(typeConverter: Any): RoomDatabase.Builder<T>

Adds a type converter instance to this database.

Parameters
typeConverter: Any

The converter. It must be an instance of a class annotated with ProvidedTypeConverter otherwise Room will throw an exception.

Returns
RoomDatabase.Builder<T>

This builder instance.

allowMainThreadQueries

Added in 2.0.0
open fun allowMainThreadQueries(): RoomDatabase.Builder<T>

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
RoomDatabase.Builder<T>

This builder instance.

build

Added in 2.0.0
open fun build(): T

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.

createFromAsset

Added in 2.2.0
open fun createFromAsset(databaseFilePath: String): RoomDatabase.Builder<T>

Configures Room to create and open the database using a pre-packaged database located in the application 'assets/' folder.

Room does not open the pre-packaged database, instead it copies it into the internal app database folder and then opens it. The pre-packaged database file must be located in the "assets/" folder of your application. For example, the path for a file located in "assets/databases/products.db" would be "databases/products.db".

The pre-packaged database schema will be validated. It might be best to create your pre-packaged database schema utilizing the exported schema files generated when Database.exportSchema is enabled.

This method is not supported for an in memory database Builder.

Parameters
databaseFilePath: String

The file path within the 'assets/' directory of where the database file is located.

Returns
RoomDatabase.Builder<T>

This builder instance.

createFromAsset

Added in 2.3.0
open fun createFromAsset(
    databaseFilePath: String,
    callback: RoomDatabase.PrepackagedDatabaseCallback
): RoomDatabase.Builder<T>

Configures Room to create and open the database using a pre-packaged database located in the application 'assets/' folder.

Room does not open the pre-packaged database, instead it copies it into the internal app database folder and then opens it. The pre-packaged database file must be located in the "assets/" folder of your application. For example, the path for a file located in "assets/databases/products.db" would be "databases/products.db".

The pre-packaged database schema will be validated. It might be best to create your pre-packaged database schema utilizing the exported schema files generated when Database.exportSchema is enabled.

This method is not supported for an in memory database Builder.

Parameters
databaseFilePath: String

The file path within the 'assets/' directory of where the database file is located.

callback: RoomDatabase.PrepackagedDatabaseCallback

The pre-packaged callback.

Returns
RoomDatabase.Builder<T>

This builder instance.

createFromFile

Added in 2.2.0
open fun createFromFile(databaseFile: File): RoomDatabase.Builder<T>

Configures Room to create and open the database using a pre-packaged database file.

Room does not open the pre-packaged database, instead it copies it into the internal app database folder and then opens it. The given file must be accessible and the right permissions must be granted for Room to copy the file.

The pre-packaged database schema will be validated. It might be best to create your pre-packaged database schema utilizing the exported schema files generated when Database.exportSchema is enabled.

The Callback.onOpen method can be used as an indicator that the pre-packaged database was successfully opened by Room and can be cleaned up.

This method is not supported for an in memory database Builder.

Parameters
databaseFile: File

The database file.

Returns
RoomDatabase.Builder<T>

This builder instance.

createFromFile

Added in 2.3.0
open fun createFromFile(
    databaseFile: File,
    callback: RoomDatabase.PrepackagedDatabaseCallback
): RoomDatabase.Builder<T>

Configures Room to create and open the database using a pre-packaged database file.

Room does not open the pre-packaged database, instead it copies it into the internal app database folder and then opens it. The given file must be accessible and the right permissions must be granted for Room to copy the file.

The pre-packaged database schema will be validated. It might be best to create your pre-packaged database schema utilizing the exported schema files generated when Database.exportSchema is enabled.

The Callback.onOpen method can be used as an indicator that the pre-packaged database was successfully opened by Room and can be cleaned up.

This method is not supported for an in memory database Builder.

Parameters
databaseFile: File

The database file.

callback: RoomDatabase.PrepackagedDatabaseCallback

The pre-packaged callback.

Returns
RoomDatabase.Builder<T>

This builder instance.

createFromInputStream

Added in 2.3.0
open fun createFromInputStream(inputStreamCallable: Callable<InputStream>): RoomDatabase.Builder<T>

Configures Room to create and open the database using a pre-packaged database via an InputStream.

This is useful for processing compressed database files. Room does not open the pre-packaged database, instead it copies it into the internal app database folder, and then open it. The InputStream will be closed once Room is done consuming it.

The pre-packaged database schema will be validated. It might be best to create your pre-packaged database schema utilizing the exported schema files generated when Database.exportSchema is enabled.

The Callback.onOpen method can be used as an indicator that the pre-packaged database was successfully opened by Room and can be cleaned up.

This method is not supported for an in memory database Builder.

Parameters
inputStreamCallable: Callable<InputStream>

A callable that returns an InputStream from which to copy the database. The callable will be invoked in a thread from the Executor set via setQueryExecutor. The callable is only invoked if Room needs to create and open the database from the pre-package database, usually the first time it is created or during a destructive migration.

Returns
RoomDatabase.Builder<T>

This builder instance.

createFromInputStream

Added in 2.3.0
open fun createFromInputStream(
    inputStreamCallable: Callable<InputStream>,
    callback: RoomDatabase.PrepackagedDatabaseCallback
): RoomDatabase.Builder<T>

Configures Room to create and open the database using a pre-packaged database via an InputStream.

This is useful for processing compressed database files. Room does not open the pre-packaged database, instead it copies it into the internal app database folder, and then open it. The InputStream will be closed once Room is done consuming it.

The pre-packaged database schema will be validated. It might be best to create your pre-packaged database schema utilizing the exported schema files generated when Database.exportSchema is enabled.

The Callback.onOpen method can be used as an indicator that the pre-packaged database was successfully opened by Room and can be cleaned up.

This method is not supported for an in memory database Builder.

Parameters
inputStreamCallable: Callable<InputStream>

A callable that returns an InputStream from which to copy the database. The callable will be invoked in a thread from the Executor set via setQueryExecutor. The callable is only invoked if Room needs to create and open the database from the pre-package database, usually the first time it is created or during a destructive migration.

callback: RoomDatabase.PrepackagedDatabaseCallback

The pre-packaged callback.

Returns
RoomDatabase.Builder<T>

This builder instance.

enableMultiInstanceInvalidation

Added in 2.1.0
open fun enableMultiInstanceInvalidation(): RoomDatabase.Builder<T>

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
RoomDatabase.Builder<T>

This builder instance.

fallbackToDestructiveMigration

Added in 2.0.0
open fun fallbackToDestructiveMigration(): RoomDatabase.Builder<T>

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.

If the database was create from an asset or a file then Room will try to use the same file to re-create the database, otherwise 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
RoomDatabase.Builder<T>

This builder instance.

fallbackToDestructiveMigrationFrom

Added in 2.0.0
open fun fallbackToDestructiveMigrationFrom(vararg startVersions: Int): RoomDatabase.Builder<T>

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

Parameters
vararg startVersions: Int

The set of schema versions from which Room should use a destructive migration.

Returns
RoomDatabase.Builder<T>

This builder instance.

fallbackToDestructiveMigrationOnDowngrade

Added in 2.1.0
open fun fallbackToDestructiveMigrationOnDowngrade(): RoomDatabase.Builder<T>

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

For details, see Builder.fallbackToDestructiveMigration.

Returns
RoomDatabase.Builder<T>

This builder instance.

openHelperFactory

Added in 2.0.0
open fun openHelperFactory(factory: SupportSQLiteOpenHelper.Factory?): RoomDatabase.Builder<T>

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

Parameters
factory: SupportSQLiteOpenHelper.Factory?

The factory to use to access the database.

Returns
RoomDatabase.Builder<T>

This builder instance.

setAutoCloseTimeout

Added in 2.3.0
@ExperimentalRoomApi
open fun setAutoCloseTimeout(
    autoCloseTimeout: @IntRange(from = 0) Long,
    autoCloseTimeUnit: TimeUnit
): RoomDatabase.Builder<T>

Enables auto-closing for the database to free up unused resources. The underlying database will be closed after it's last use after the specified autoCloseTimeout has elapsed since its last usage. The database will be automatically re-opened the next time it is accessed.

Auto-closing is not compatible with in-memory databases since the data will be lost when the database is auto-closed.

Also, temp tables and temp triggers will be cleared each time the database is auto-closed. If you need to use them, please include them in your callback RoomDatabase.Callback.onOpen.

All configuration should happen in your RoomDatabase.Callback.onOpen callback so it is re-applied every time the database is re-opened. Note that the RoomDatabase.Callback.onOpen will be called every time the database is re-opened.

The auto-closing database operation runs on the query executor.

The database will not be re-opened if the RoomDatabase or the SupportSqliteOpenHelper is closed manually (by calling RoomDatabase.close or SupportSQLiteOpenHelper.close. If the database is closed manually, you must create a new database using RoomDatabase.Builder.build.

Parameters
autoCloseTimeout: @IntRange(from = 0) Long

the amount of time after the last usage before closing the database. Must greater or equal to zero.

autoCloseTimeUnit: TimeUnit

the timeunit for autoCloseTimeout.

Returns
RoomDatabase.Builder<T>

This builder instance.

setJournalMode

Added in 2.0.0
open fun setJournalMode(journalMode: RoomDatabase.JournalMode): RoomDatabase.Builder<T>

Sets the journal mode for this database.

This value is ignored if the builder is initialized with Room.inMemoryDatabaseBuilder.

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

The default value is JournalMode.AUTOMATIC.

Parameters
journalMode: RoomDatabase.JournalMode

The journal mode.

Returns
RoomDatabase.Builder<T>

This builder instance.

setMultiInstanceInvalidationServiceIntent

Added in 2.4.0
@ExperimentalRoomApi
open fun setMultiInstanceInvalidationServiceIntent(
    invalidationServiceIntent: Intent
): RoomDatabase.Builder<T>

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 and need to point to the same MultiInstanceInvalidationService.

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.

Parameters
invalidationServiceIntent: Intent

Intent to bind to the MultiInstanceInvalidationService.

Returns
RoomDatabase.Builder<T>

This builder instance.

setQueryCallback

Added in 2.3.0
open fun setQueryCallback(
    queryCallback: RoomDatabase.QueryCallback,
    executor: Executor
): RoomDatabase.Builder<T>

Sets a QueryCallback to be invoked when queries are executed.

The callback is invoked whenever a query is executed, note that adding this callback has a small cost and should be avoided in production builds unless needed.

A use case for providing a callback is to allow logging executed queries. When the callback implementation logs then it is recommended to use an immediate executor.

Parameters
queryCallback: RoomDatabase.QueryCallback

The query callback.

executor: Executor

The executor on which the query callback will be invoked.

Returns
RoomDatabase.Builder<T>

This builder instance.

setQueryExecutor

Added in 2.0.0
open fun setQueryExecutor(executor: Executor): RoomDatabase.Builder<T>

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 both the query executor and transaction executor are unset, then a default Executor will be used. The default Executor allocates and shares threads amongst Architecture Components libraries. If the query executor is unset but a transaction executor was set setTransactionExecutor, then the same Executor will be used for queries.

For best performance the given Executor should be bounded (max number of threads is limited).

The input Executor cannot run tasks on the UI thread.

Returns
RoomDatabase.Builder<T>

This builder instance.

setTransactionExecutor

Added in 2.1.0
open fun setTransactionExecutor(executor: Executor): RoomDatabase.Builder<T>

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

When both the transaction executor and query executor are unset, then a default Executor will be used. The default Executor allocates and shares threads amongst Architecture Components libraries. If the transaction executor is unset but a query executor was set using setQueryExecutor, then the same Executor will be used for transactions.

If the given Executor is shared then it should be unbounded to avoid the possibility of a deadlock. Room will not use more than one thread at a time from this executor since only one transaction at a time can be executed, other transactions will be queued on a first come, first serve order.

The input Executor cannot run tasks on the UI thread.

Returns
RoomDatabase.Builder<T>

This builder instance.