Rename dispose to close

Author: simolus3

.github/workflows/release.yml

@@ -33,9 +33,9 @@ jobs:
         # because caches from non-default branches aren't visible to runs on tags.
         # On windows, the sqlite3 build is not reproducible. So to avoid a hash mismatch, we temporarily use artifacts
         # built for a test run for releases as well.
-        artifact-ids: "4427181234"
+        artifact-ids: "4438896082"
         repository: simolus3/sqlite3.dart
-        run-id: "18966728824"
+        run-id: "19001906517"
         github-token: ${{ github.token }}
         path: sqlite-compiled
     - name: Set tag name

examples/flutter_integration_tests/integration_test/integration_test.dart

@@ -110,5 +110,5 @@ void main() {
 }
 
 extension on Database {
-  void closeWhenDone() => addTearDown(dispose);
+  void closeWhenDone() => addTearDown(close);
 }

examples/flutter_integration_tests/lib/main.dart

@@ -35,7 +35,7 @@ class _SqliteDiagnosticTextState extends State<_SqliteDiagnosticText> {
     setState(() {
       _text = 'Version: ${sqlite3.version}\nOptions: $options';
     });
-    db.dispose();
+    db.close();
   }
 
   @override

sqlite3/CHANGELOG.md

@@ -1,4 +1,4 @@
-## 3.0.0-beta.1
+## 3.0.0-beta.2
 
 - __Breaking change__: Use [build hooks](https://dart.dev/tools/hooks) to load
   SQLite instead of `DynamicLibrary`.
@@ -9,7 +9,10 @@
     package is now part of `package:sqlite3`.
 - __Breaking change__: Parameters to `SqliteException`s are now named.
 - On native platforms, use native finalizers to reliably clear statements and databases.
+- On the web, use regular finalizers more consistently.
 - Refactor binding text and blob values to reduce the chance of memory leaks.
+- Deprecated `dispose()` on `CommonDatabase` and `CommonPreparedStatement`. Use `close()`
+  instead.
 
 ## 2.9.4
 

sqlite3/README.md

@@ -19,8 +19,9 @@ 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.
+4. Consider closing statements or databases explicitly with `close()` once you're
+   done with them. `package:sqlite3` uses native finalizers to do that automatically
+   too, though.
 
 For a more complete example on how to use this library, see the [example](https://pub.dev/packages/sqlite3/example).
 

sqlite3/example/custom_extension/test/extension_test.dart

@@ -9,7 +9,7 @@ void main() {
 
   test('can use vec0', () {
     final db = sqlite3.openInMemory();
-    addTearDown(db.dispose);
+    addTearDown(db.close);
 
     db.execute(
       'create virtual table vec_examples using vec0(sample_embedding float[8])',

sqlite3/example/main.dart

@@ -26,7 +26,7 @@ void main() {
     ..execute(['Nirvana']);
 
   // Dispose a statement when you don't need it anymore to clean up resources.
-  stmt.dispose();
+  stmt.close();
 
   // You can run select statements with PreparedStatement.select, or directly
   // on the database:
@@ -49,6 +49,7 @@ void main() {
   );
   print(db.select('SELECT dart_version()'));
 
-  // Don't forget to dispose the database to avoid memory leaks
-  db.dispose();
+  // Don't forget to dispose the database to avoid memory leaks (optional on
+  // native platforms).
+  db.close();
 }

sqlite3/example/web/main.dart

@@ -26,7 +26,7 @@ Future<void> main() async {
       ..execute('pragma user_version = 1')
       ..execute('CREATE TABLE foo (bar INTEGER NOT NULL);')
       ..execute('INSERT INTO foo (bar) VALUES (?)', [3])
-      ..dispose();
+      ..close();
 
     final db = sqlite3.open('/database');
     print(db.select('SELECT * FROM foo'));
@@ -50,7 +50,7 @@ Future<void> main() async {
       ..execute('pragma user_version = 1')
       ..execute('CREATE TABLE foo (bar INTEGER NOT NULL);')
       ..execute('INSERT INTO foo (bar) VALUES (?)', [3])
-      ..dispose();
+      ..close();
 
     final db = sqlite3.open('/database');
     try {

sqlite3/example/web/worker.dart

@@ -39,7 +39,7 @@ void main() {
         ..execute('pragma user_version = 1')
         ..execute('CREATE TABLE foo (bar INTEGER NOT NULL);')
         ..execute('INSERT INTO foo (bar) VALUES (?)', [3])
-        ..dispose();
+        ..close();
 
       final db = sqlite3.open('/database');
       print(db.select('SELECT * FROM foo'));

sqlite3/lib/src/database.dart

@@ -140,7 +140,7 @@ abstract class CommonDatabase {
   /// The [persistent] flag can be used as a hint to the query planner that the
   /// statement will be retained for a long time and probably reused many times.
   /// Without this flag, sqlite assumes that the prepared statement will be used
-  /// just once or at most a few times before [CommonPreparedStatement.dispose]
+  /// just once or at most a few times before [CommonPreparedStatement.close]
   /// is called.
   /// If [vtab] is disabled (it defaults to `true`) and the statement references
   /// a virtual table, [prepare] throws an exception.
@@ -271,7 +271,15 @@ abstract class CommonDatabase {
   bool get autocommit;
 
   /// Closes this database and releases associated resources.
+  @Deprecated('Call close() instead')
   void dispose();
+
+  /// Closes this database and releases associated resources.
+  ///
+  /// On native platforms, a native finalizer will also close the connection
+  /// automatically. On the web, finalizers are less reliable. For this reason,
+  /// closing databases explicitly is still recommended.
+  void close();
 }
 
 /// The kind of an [SqliteUpdate] received through a [CommonDatabase.updates]