OpenDatabaseOptions constructor

OpenDatabaseOptions({
  1. int? version,
  2. OnDatabaseConfigureFn? onConfigure,
  3. OnDatabaseCreateFn? onCreate,
  4. OnDatabaseVersionChangeFn? onUpgrade,
  5. OnDatabaseVersionChangeFn? onDowngrade,
  6. OnDatabaseOpenFn? onOpen,
  7. bool? readOnly = false,
  8. bool? singleInstance = true,
  9. bool? rollbackActiveTransactionOnOpen,
})

Open the database at a given path

version (optional) specifies the schema version of the database being opened. This is used to decide whether to call onCreate, onUpgrade, and onDowngrade. If specified, it must be a 32-bits integer greater than 0.

The optional callbacks are called in the following order:

  1. onConfigure
  2. onCreate or onUpgrade or onDowngrade
  3. onOpen

onConfigure is the first callback invoked when opening the database. It allows you to perform database initialization such as enabling foreign keys or write-ahead logging

If version is specified, onCreate, onUpgrade, and onDowngrade can be called. These functions are mutually exclusive — only one of them can be called depending on the context, although they can all be specified to cover multiple scenarios. They run in a transaction: use the database they receive directly (do not start a transaction) and await every call. The new version is saved when the callback completes.

onCreate is called if the database did not exist prior to calling openDatabase. You can use the opportunity to create the required tables in the database according to your schema. It is not called for an existing database: a schema change needs a new version handled in onUpgrade.

onUpgrade is called if either of the following conditions are met:

  1. onCreate is not specified
  2. The database already exists and version is higher than the last database version

In the first case where onCreate is not specified, onUpgrade is called with its OnDatabaseVersionChangeFn.oldVersion parameter as 0. In the second case, you can perform the necessary migration procedures to handle the differing schema

onDowngrade is called only when version is lower than the last database version. This is a rare case and should only come up if a newer version of your code has created a database that is then interacted with by an older version of your code. You should try to avoid this scenario

onOpen is the last optional callback to be invoked. It is called after the database version has been set and before openDatabase returns

When readOnly (false by default) is true, the database is opened in read-only mode: the file must exist and any write fails. The other parameters are not ignored: onConfigure and onOpen are still called, and if version is specified and differs from the version of the database, the migration callback is called and saving the new version fails, making the open fail. Don't specify version for a read-only database.

When singleInstance is true (the default), a single database instance is returned for a given path. Subsequent calls to openDatabase with the same path will return the same instance, and will discard all other parameters such as callbacks for that invocation. Closing the database closes it for every holder.

This also applies to the in-memory database (inMemoryDatabasePath, :memory:): opening it again without closing it returns the same instance (same data); once closed, the next open gives a new empty database. Set singleInstance to false to get a new private in-memory database at each open. Don't set it to false for a file: uri.

On the web (sqflite_common_ffi_web), singleInstance must be true for a persistent database, multiple connections to the same database file are not supported and an ArgumentError is thrown.

Experimental for sqflite plugin. When rollbackActiveTransactionOnOpen is true and singleInstance is true, any active transaction from another isolate is rolled back when opening the database.

This is useful when using the same database from multiple isolates. During hot restart, a transaction may still be active in another isolate, and rollback may be needed to reopen the database safely.

By default, this is true in debug mode and false in release mode. Before this option was added, rollback on open was always enabled and could not be disabled. This could cause unexpected transaction rollbacks in release mode.

If singleInstance is true when using multiple isolates, make sure no background isolate closes the database, since that might close the database for all isolates.

Set rollbackActiveTransactionOnOpen to false if you do not want an active transaction to be rolled back when the database is opened, typically if you explicitly create multiple isolate

Implementation

factory OpenDatabaseOptions({
  int? version,
  OnDatabaseConfigureFn? onConfigure,
  OnDatabaseCreateFn? onCreate,
  OnDatabaseVersionChangeFn? onUpgrade,
  OnDatabaseVersionChangeFn? onDowngrade,
  OnDatabaseOpenFn? onOpen,
  bool? readOnly = false,
  bool? singleInstance = true,
  bool? rollbackActiveTransactionOnOpen,
}) {
  return impl.SqfliteOpenDatabaseOptions(
    version: version,
    onConfigure: onConfigure,
    onCreate: onCreate,
    onUpgrade: onUpgrade,
    onDowngrade: onDowngrade,
    onOpen: onOpen,
    readOnly: readOnly,
    singleInstance: singleInstance,
    rollbackActiveTransactionOnOpen: rollbackActiveTransactionOnOpen,
  );
}