Native finalizer for db and stmt

Author: simolus3

sqlite3/CHANGELOG.md

@@ -6,6 +6,8 @@
   - You should drop your dependencies on `sqlite3_flutter_libs` and
     `sqlcipher_flutter_libs` when upgrading.
 - __Breaking change__: Parameters to `SqliteException`s are now named.
+- Use native finalizers to clear statements, parameters and sessions. This makes
+  closing databases after e.g. a reload much more efficient.
 
 ## 2.9.4
 

sqlite3/README.md

@@ -19,8 +19,6 @@ For native platforms, the basic sketch for using this library is to:
    open a temporary in-memory database.
 3. Use `Database.execute` or `Database.prepare` to execute statements directly
    or by preparing them first.
-4. Don't forget to close prepared statements or the database with `dispose()`
-   once you no longer need them.
 
 For a more complete example on how to use this library, see the [example](https://pub.dev/packages/sqlite3/example).
 

sqlite3/lib/src/ffi/bindings.dart

@@ -34,6 +34,8 @@ final supportsPrepareV3 = sqlite3_libversion_number() >= _firstVersionForV3;
 final supportsErrorOffset =
     sqlite3_libversion_number() >= _firstVersionForErrorOffset;
 
+final databaseFinalizer = NativeFinalizer(addresses.sqlite3_close_v2.cast());
+final statementFinalizer = NativeFinalizer(addresses.sqlite3_finalize.cast());
 final sessionDeleteFinalizer = NativeFinalizer(
   addresses.sqlite3session_delete.cast(),
 );
@@ -208,7 +210,7 @@ final class FfiBindings implements RawSqliteBindings {
   }
 
   @override
-  SqliteResult<RawSqliteDatabase> sqlite3_open_v2(
+  SqliteResult<RawSqliteDatabase?> sqlite3_open_v2(
     String name,
     int flags,
     String? zVfs,
@@ -225,7 +227,10 @@ final class FfiBindings implements RawSqliteBindings {
       flags,
       vfsPtr,
     );
-    final result = SqliteResult(resultCode, FfiDatabase(outDb.value));
+    final result = (
+      resultCode: resultCode,
+      result: outDb.isNullPointer ? null : FfiDatabase(outDb.value),
+    );
 
     namePtr.free();
     outDb.free();
@@ -740,7 +745,10 @@ final class FfiChangesetIterator implements RawChangesetIterator, Finalizable {
     final value = outValue.value;
     outValue.free();
 
-    return SqliteResult(result, value.isNullPointer ? null : FfiValue(value));
+    return (
+      resultCode: result,
+      result: value.isNullPointer ? null : FfiValue(value),
+    );
   }
 
   @override
@@ -759,7 +767,10 @@ final class FfiChangesetIterator implements RawChangesetIterator, Finalizable {
     final value = outValue.value;
     outValue.free();
 
-    return SqliteResult(result, value.isNullPointer ? null : FfiValue(value));
+    return (
+      resultCode: result,
+      result: value.isNullPointer ? null : FfiValue(value),
+    );
   }
 
   @override
@@ -800,17 +811,21 @@ final class FfiChangesetIterator implements RawChangesetIterator, Finalizable {
   }
 }
 
-final class FfiDatabase implements RawSqliteDatabase {
+final class FfiDatabase implements RawSqliteDatabase, Finalizable {
   final Pointer<sqlite3> db;
+  final Object detachToken = Object();
 
   NativeCallable<_UpdateHook>? _installedUpdateHook;
   NativeCallable<_CommitHook>? _installedCommitHook;
   NativeCallable<_RollbackHook>? _installedRollbackHook;
 
-  FfiDatabase(this.db);
+  FfiDatabase(this.db) {
+    databaseFinalizer.attach(this, db.cast(), detach: detachToken);
+  }
 
   @override
   int sqlite3_close_v2() {
+    databaseFinalizer.detach(detachToken);
     return libsqlite3.sqlite3_close_v2(db);
   }
 
@@ -1085,16 +1100,19 @@ final class FfiStatementCompiler implements RawStatementCompiler {
     final stmt = stmtOut.value;
     final libraryStatement = stmt.isNullPointer ? null : FfiStatement(stmt);
 
-    return SqliteResult(result, libraryStatement);
+    return (resultCode: result, result: libraryStatement);
   }
 }
 
-final class FfiStatement implements RawSqliteStatement {
+final class FfiStatement implements RawSqliteStatement, Finalizable {
   final Pointer<sqlite3_stmt> stmt;
+  final Object detachToken = Object();
 
   final List<Pointer> _allocatedArguments = [];
 
-  FfiStatement(this.stmt);
+  FfiStatement(this.stmt) {
+    statementFinalizer.attach(this, stmt.cast(), detach: detachToken);
+  }
 
   @visibleForTesting
   List<Pointer> get allocatedArguments => _allocatedArguments;
@@ -1238,6 +1256,7 @@ final class FfiStatement implements RawSqliteStatement {
 
   @override
   void sqlite3_finalize() {
+    statementFinalizer.detach(detachToken);
     libsqlite3.sqlite3_finalize(stmt);
   }
 

sqlite3/lib/src/ffi/libsqlite3.g.dart

@@ -866,6 +866,10 @@ class _SymbolAddresses {
   const _SymbolAddresses();
   ffi.Pointer<ffi.NativeFunction<ffi.Void Function(ffi.Pointer<ffi.Void>)>>
   get sqlite3_free => ffi.Native.addressOf(self.sqlite3_free);
+  ffi.Pointer<ffi.NativeFunction<ffi.Int Function(ffi.Pointer<sqlite3>)>>
+  get sqlite3_close_v2 => ffi.Native.addressOf(self.sqlite3_close_v2);
+  ffi.Pointer<ffi.NativeFunction<ffi.Int Function(ffi.Pointer<sqlite3_stmt>)>>
+  get sqlite3_finalize => ffi.Native.addressOf(self.sqlite3_finalize);
   ffi.Pointer<
     ffi.NativeFunction<ffi.Void Function(ffi.Pointer<sqlite3_session>)>
   >

sqlite3/lib/src/implementation/bindings.dart

@@ -116,7 +116,7 @@ abstract interface class RawSqliteBindings {
 
   String? sqlite3_temp_directory;
 
-  SqliteResult<RawSqliteDatabase> sqlite3_open_v2(
+  SqliteResult<RawSqliteDatabase?> sqlite3_open_v2(
     String name,
     int flags,
     String? zVfs,
@@ -166,15 +166,9 @@ abstract interface class RawSqliteSession {
 }
 
 /// Combines a sqlite result code and the result object.
-final class SqliteResult<T> {
-  final int resultCode;
-
-  /// The result of the operation, which is assumed to be valid if [resultCode]
-  /// is zero.
-  final T result;
-
-  SqliteResult(this.resultCode, this.result);
-}
+///
+/// The result is only assumed to be valid if the result code is zero.
+typedef SqliteResult<T> = ({T result, int resultCode});
 
 typedef RawXFunc = void Function(RawSqliteContext, List<RawSqliteValue>);
 typedef RawXStep = void Function(RawSqliteContext, List<RawSqliteValue>);

sqlite3/lib/src/implementation/sqlite3.dart

@@ -70,19 +70,28 @@ base class Sqlite3Implementation implements CommonSqlite3 {
 
     final result = bindings.sqlite3_open_v2(filename, flags, vfs);
     if (result.resultCode != SqlError.SQLITE_OK) {
-      final exception = createExceptionRaw(
-        bindings,
-        result.result,
-        result.resultCode,
-        operation: 'opening the database',
-      );
-      // Close the database after creating the exception, which needs to read
-      // the extended error from the database.
-      result.result.sqlite3_close_v2();
-      throw exception;
+      if (result.result case final db?) {
+        // Even with an opening error, we usually still get a database (the only
+        // exception is if SQLite can't allocate the db structure).
+        final exception = createExceptionRaw(
+          bindings,
+          db,
+          result.resultCode,
+          operation: 'opening the database',
+        );
+        // Close the database after creating the exception, which needs to read
+        // the extended error from the database.
+        db.sqlite3_close_v2();
+        throw exception;
+      } else {
+        throw SqliteException(
+          extendedResultCode: result.resultCode,
+          message: 'Could not open database',
+        );
+      }
     }
 
-    return wrapDatabase(result.result..sqlite3_extended_result_codes(1));
+    return wrapDatabase(result.result!..sqlite3_extended_result_codes(1));
   }
 
   @override

sqlite3/lib/src/wasm/bindings.dart

@@ -56,7 +56,7 @@ final class WasmSqliteBindings implements RawSqliteBindings {
   }
 
   @override
-  SqliteResult<RawSqliteDatabase> sqlite3_open_v2(
+  SqliteResult<RawSqliteDatabase?> sqlite3_open_v2(
     String name,
     int flags,
     String? zVfs,
@@ -74,7 +74,10 @@ final class WasmSqliteBindings implements RawSqliteBindings {
       ..free(vfsPtr);
     if (zVfs != null) bindings.free(vfsPtr);
 
-    return SqliteResult(result, WasmDatabase(bindings, dbPtr));
+    return (
+      resultCode: result,
+      result: dbPtr != 0 ? WasmDatabase(bindings, dbPtr) : null,
+    );
   }
 
   @override
@@ -443,7 +446,7 @@ final class WasmStatementCompiler implements RawStatementCompiler {
     final stmt = database.bindings.memory.int32ValueOfPointer(stmtOut);
     final libraryStatement = stmt == 0 ? null : WasmStatement(database, stmt);
 
-    return SqliteResult(result, libraryStatement);
+    return (resultCode: result, result: libraryStatement);
   }
 }
 
@@ -921,9 +924,9 @@ final class WasmChangesetIterator implements RawChangesetIterator {
     final value = _bindings.memory.int32ValueOfPointer(outValue);
     _bindings.free(outValue);
 
-    return SqliteResult(
-      resultCode,
-      value != 0 ? WasmValue(_bindings, value) : null,
+    return (
+      resultCode: resultCode,
+      result: value != 0 ? WasmValue(_bindings, value) : null,
     );
   }
 

sqlite3/tool/generate_bindings.dart

@@ -46,6 +46,8 @@ DeclarationFilters _includeSqlite3Only = DeclarationFilters(
   shouldInclude: (d) => d.isSqlite3Symbol,
   shouldIncludeSymbolAddress: (decl) {
     return switch (decl.originalName) {
+      'sqlite3_close_v2' => true,
+      'sqlite3_finalize' => true,
       'sqlite3changeset_finalize' => true,
       'sqlite3session_delete' => true,
       'sqlite3_free' => true,