createInBackground static method
- File file, {
- bool logStatements = false,
- bool cachePreparedStatements = _cacheStatementsByDefault,
- DatabaseSetup? setup,
- SqliteResolver sqlite3 = _NativeDelegate._defaultResolver,
- bool enableMigrations = true,
- IsolateSetup? isolateSetup,
- int readPool = _defaultReadPoolSize,
Creates a database storing its result in file
.
This method will create the same database as the default constructor of
the NativeDatabase class. It also behaves the same otherwise: The file
is created if it doesn't exist, logStatements
can be used to print
statements and setup
can be used to perform a one-time setup work when
the database is created.
The big distinction of this method is that the database is implicitly created on a background isolate, freeing up your main thread accessing the database from I/O work needed to run statements. When the database returned by this method is closed, the background isolate will shut down as well.
When readPool
is set to a number greater than zero, drift will spawn an
additional number of isolates only responsible for running read operations
(i.e. SELECT
statements) on the database.
Since the original isolate is used for writes, this causes readPool + 1
isolates to be spawned. While these isolates will only run statements on
demand and consume few resources otherwise, using a read pool is not
necessary for most applications. It can make sense to reduce load times in
applications issuing lots of reads at startup, especially if some of these
are known to be slow.
Please note that readPool
is only effective when enabling write-ahead
logging! In the default journaling mode used by sqlite3, concurrent
reads and writes are forbidden. To enable write-ahead logging, issue a
call to Database.execute
setting pragma journal_mode = WAL;
in
setup
.
The sqlite3
parameter can be used to provide a function responsible for
obtaining an instance of the Sqlite3
bindings drift will use to open the
database. This is particularly relevant for users interested in using
drift with the native assets SDK feature, see SqliteResolver for an
example.
Be aware that the functions setup
, isolateSetup
and sqlite3
, are
sent to other isolates and are executed there. Thus, they don't have
access to the same contents of global variables. Care must also be taken
to ensure that the functions don't capture state not meant to be sent
across isolates.
Implementation
static QueryExecutor createInBackground(
File file, {
bool logStatements = false,
bool cachePreparedStatements = _cacheStatementsByDefault,
DatabaseSetup? setup,
SqliteResolver sqlite3 = _NativeDelegate._defaultResolver,
bool enableMigrations = true,
IsolateSetup? isolateSetup,
int readPool = _defaultReadPoolSize,
}) {
return createBackgroundConnection(
file,
logStatements: logStatements,
setup: setup,
isolateSetup: isolateSetup,
enableMigrations: enableMigrations,
cachePreparedStatements: cachePreparedStatements,
readPool: readPool,
sqlite3: sqlite3,
);
}