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 |
Builder<T>
|
addMigrations(Migration... migrations)
Adds a migration to the builder. |
Builder<T>
|
addTypeConverter(Object typeConverter)
Adds a type converter instance to this database. |
Builder<T>
|
allowMainThreadQueries()
Disables the main thread query check for Room. |
T
|
build()
Creates the databases and initializes it. |
Builder<T>
|
createFromAsset(String databaseFilePath, RoomDatabase.PrepackagedDatabaseCallback callback)
Configures Room to create and open the database using a pre-packaged database located in the application 'assets/' folder. |
Builder<T>
|
createFromAsset(String databaseFilePath)
Configures Room to create and open the database using a pre-packaged database located in the application 'assets/' folder. |
Builder<T>
|
createFromFile(File databaseFile)
Configures Room to create and open the database using a pre-packaged database file. |
Builder<T>
|
createFromFile(File databaseFile, RoomDatabase.PrepackagedDatabaseCallback callback)
Configures Room to create and open the database using a pre-packaged database file. |
Builder<T>
|
createFromInputStream(Callable<InputStream> inputStreamCallable, RoomDatabase.PrepackagedDatabaseCallback callback)
Configures Room to create and open the database using a pre-packaged database via an
|
Builder<T>
|
createFromInputStream(Callable<InputStream> inputStreamCallable)
Configures Room to create and open the database using a pre-packaged database via an
|
Builder<T>
|
enableMultiInstanceInvalidation()
Sets whether table invalidation in this instance of |
Builder<T>
|
fallbackToDestructiveMigration()
Allows Room to destructively recreate database tables if |
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 |
Builder<T>
|
openHelperFactory(SupportSQLiteOpenHelper.Factory factory)
Sets the database factory. |
Builder<T>
|
setAutoCloseTimeout(long autoCloseTimeout, TimeUnit autoCloseTimeUnit)
Enables auto-closing for the database to free up unused resources. |
Builder<T>
|
setJournalMode(RoomDatabase.JournalMode journalMode)
Sets the journal mode for this database. |
Builder<T>
|
setQueryCallback(RoomDatabase.QueryCallback queryCallback, Executor executor)
Sets a |
Builder<T>
|
setQueryExecutor(Executor executor)
Sets the |
Builder<T>
|
setTransactionExecutor(Executor executor)
Sets the |
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 RoomDatabase.Builder instance.
|
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 RoomDatabase.Builder instance.
|
addTypeConverter
public Builder<T> addTypeConverter (Object typeConverter)
Adds a type converter instance to this database.
Parameters | |
---|---|
typeConverter |
Object : The converter. It must be an instance of a class annotated with
ProvidedTypeConverter otherwise Room will throw an exception. |
Returns | |
---|---|
Builder<T> |
This RoomDatabase.Builder instance.
|
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 RoomDatabase.Builder instance.
|
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. |
createFromAsset
public Builder<T> createFromAsset (String databaseFilePath, RoomDatabase.PrepackagedDatabaseCallback callback)
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 RoomDatabase.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 | |
---|---|
Builder<T> |
This RoomDatabase.Builder instance.
|
createFromAsset
public Builder<T> createFromAsset (String databaseFilePath)
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 RoomDatabase.Builder
.
Parameters | |
---|---|
databaseFilePath |
String : The file path within the 'assets/' directory of where the
database file is located. |
Returns | |
---|---|
Builder<T> |
This RoomDatabase.Builder instance.
|
createFromFile
public Builder<T> createFromFile (File databaseFile)
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 RoomDatabase.Callback.onOpen(SupportSQLiteDatabase)
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 RoomDatabase.Builder
.
Parameters | |
---|---|
databaseFile |
File : The database file. |
Returns | |
---|---|
Builder<T> |
This RoomDatabase.Builder instance.
|
createFromFile
public Builder<T> createFromFile (File databaseFile, RoomDatabase.PrepackagedDatabaseCallback callback)
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 RoomDatabase.Callback.onOpen(SupportSQLiteDatabase)
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 RoomDatabase.Builder
.
Parameters | |
---|---|
databaseFile |
File : The database file. |
callback |
RoomDatabase.PrepackagedDatabaseCallback : The pre-packaged callback. |
Returns | |
---|---|
Builder<T> |
This RoomDatabase.Builder instance.
|
createFromInputStream
public Builder<T> createFromInputStream (Callable<InputStream> inputStreamCallable, RoomDatabase.PrepackagedDatabaseCallback callback)
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 RoomDatabase.Callback.onOpen(SupportSQLiteDatabase)
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 RoomDatabase.Builder
.
Parameters | |
---|---|
inputStreamCallable |
Callable : 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(Executor) . 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 | |
---|---|
Builder<T> |
This RoomDatabase.Builder instance.
|
createFromInputStream
public Builder<T> createFromInputStream (Callable<InputStream> inputStreamCallable)
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 RoomDatabase.Callback.onOpen(SupportSQLiteDatabase)
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 RoomDatabase.Builder
.
Parameters | |
---|---|
inputStreamCallable |
Callable : 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(Executor) . 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 | |
---|---|
Builder<T> |
This RoomDatabase.Builder 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 RoomDatabase.Builder instance.
|
fallbackToDestructiveMigration
public Builder<T> fallbackToDestructiveMigration ()
Allows Room to destructively recreate database tables if Migration
s 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 Migration
s on the database.
If it cannot find the set of Migration
s 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 | |
---|---|
Builder<T> |
This RoomDatabase.Builder instance. |
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 Migration
s 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 RoomDatabase.Builder instance.
|
fallbackToDestructiveMigrationOnDowngrade
public Builder<T> fallbackToDestructiveMigrationOnDowngrade ()
Allows Room to destructively recreate database tables if Migration
s are not
available when downgrading to old schema versions.
Returns | |
---|---|
Builder<T> |
This RoomDatabase.Builder instance. |
See also:
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 RoomDatabase.Builder instance.
|
setAutoCloseTimeout
public Builder<T> setAutoCloseTimeout (long autoCloseTimeout, TimeUnit autoCloseTimeUnit)
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
.
All configuration should happen in your RoomDatabase.Callback.onOpen(SupportSQLiteDatabase)
callback so it is re-applied every time the database is re-opened. Note that the
RoomDatabase.Callback.onOpen(SupportSQLiteDatabase)
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 reopened 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
build()
.
Parameters | |
---|---|
autoCloseTimeout |
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 | |
---|---|
Builder<T> |
This RoomDatabase.Builder instance
|
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 RoomDatabase.Builder instance.
|
setQueryCallback
public Builder<T> setQueryCallback (RoomDatabase.QueryCallback queryCallback, Executor executor)
Sets a RoomDatabase.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 | |
---|---|
Builder<T> |
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 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, 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.
Parameters | |
---|---|
executor |
Executor |
Returns | |
---|---|
Builder<T> |
This RoomDatabase.Builder instance. |
See also:
setTransactionExecutor
public Builder<T> setTransactionExecutor (Executor executor)
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, 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.
Parameters | |
---|---|
executor |
Executor |
Returns | |
---|---|
Builder<T> |
This RoomDatabase.Builder instance. |
See also: