createInBackground static method

QueryExecutor createInBackground(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,
  );
}