closeExistingInstances static method

@experimental void closeExistingInstances()

Disposes resources allocated by all VmDatabase instances of this process.

This method will call sqlite3_close_v2 for every VmDatabase that this process has opened without closing later.

Warning: This functionality appears to cause crashes on iOS, and it does nothing on Android. It's mainly intended for Desktop operating systems, so try to avoid calling it where it's not necessary. For safety measures, avoid calling closeExistingInstances in release builds.

Ideally, all databases should be closed properly in Dart. In that case, it's not necessary to call closeExistingInstances. However, features like hot (stateless) restart can make it impossible to reliably close every database. In that case, we leak native sqlite3 database connections that aren't referenced by any Dart object. Drift can track those connections across Dart VM restarts by storing them in an in-memory sqlite database. Calling this method can cleanup resources and database locks after a restart.

Note that calling closeExistingInstances when you're still actively using a NativeDatabase can lead to crashes, since the database would then attempt to use an invalid connection. This, this method should only be called when you're certain that there aren't any active NativeDatabases, not even on another isolate.

A suitable place to call closeExistingInstances is at an early stage of your main method, before you're using drift.

void main() {
  // Guard against zombie database connections caused by hot restarts
  assert(() {
    VmDatabase.closeExistingInstances();
    return true;
  }());

  runApp(MyApp());
}

For more information, see issue 835.

Implementation

@experimental
static void closeExistingInstances() {
  tracker.closeExisting();
}