Cleanup.

Author: rkistner

.gitignore

@@ -7,3 +7,7 @@
 pubspec.lock
 
 .idea
+*.db
+*.db-*
+test-db
+sqlite-autoconf-*

README.md

@@ -7,7 +7,7 @@ great as an in-app database. However, SQLite is designed for many different use
 some configuration for optimal performance as an in-app database.
 
 The [sqlite3](https://pub.dev/packages/sqlite3) Dart bindings are great for direct synchronous access
-to a SQLite database, but leaves the configuration the developer.
+to a SQLite database, but leaves the configuration up to the developer.
 
 This library wraps the bindings and configures the database with a good set of defaults, with
 all database calls being asynchronous to avoid blocking the UI, while still providing direct SQL
@@ -16,6 +16,59 @@ query access.
 ## Features
 
  * All operations are asynchronous by default - does not block the main isolate.
+ * Watch a query to automatically re-run on changes to the underlying data.
  * Concurrent transactions supported by default - one write transaction and many multiple read transactions.
- * Uses WAL mode with minimal locking.
+ * Uses WAL mode for fast writes and running read transactions concurrently with a write transaction.
  * Direct synchronous access in an isolate is supported for performance-sensitive use cases. 
+ * Automatically convert query args to JSON where applicable, making JSON1 operations simple.
+ * Direct SQL queries - no wrapper classes or code generation required.
+
+## Installation
+
+```sh
+dart pub add sqlite_async
+```
+
+For flutter applications, additionally add `sqlite3_flutter_libs` to include the native SQLite
+library.
+
+For other platforms, see the [sqlite3 package docs](https://pub.dev/packages/sqlite3#supported-platforms).
+
+Web is currently not supported.
+
+## Getting Started
+
+```dart
+import 'package:sqlite_async/sqlite_async.dart';
+
+final migrations = SqliteMigrations()
+  ..add(SqliteMigration(1, (tx) async {
+    await tx.execute(
+        'CREATE TABLE test_data(id INTEGER PRIMARY KEY AUTOINCREMENT, data TEXT)');
+  }));
+
+void main() async {
+  final db = SqliteDatabase(path: 'test.db');
+  await migrations.migrate(db);
+
+  // Use execute() or executeBatch() for INSERT/UPDATE/DELETE statements
+  await db.executeBatch('INSERT INTO test_data(data) values(?)', [
+    ['Test1'],
+    ['Test2']
+  ]);
+
+  // Use getAll(), get() or getOptional() for SELECT statements
+  var results = await db.getAll('SELECT * FROM test_data');
+  print('Results: $results');
+
+  // Combine multiple statements into a single write transaction for:
+  // 1. Atomic persistence (all updates are either applied or rolled back).
+  // 2. Improved throughput.
+  await db.writeTransaction((tx) async {
+    await db.execute('INSERT INTO test_data(data) values(?)', ['Test3']);
+    await db.execute('INSERT INTO test_data(data) values(?)', ['Test4']);
+  });
+
+  await db.close();
+}
+```

example/json_example.dart

@@ -2,6 +2,7 @@ import 'package:sqlite_async/sqlite_async.dart';
 
 // This example shows using a custom class and SQLite's JSON1 functionality,
 // to efficiently map between custom data objects and SQLite.
+// This is especially useful for bulk INSERT, UPDATE or DELETE statements,
 
 class User {
   int? id;
@@ -51,13 +52,13 @@ SELECT name, email FROM (${User.selectJsonData('?')})
 RETURNING id''', [users]);
   var ids = idRows.map((row) => row['id']).toList();
 
-  // Alternative using json1 functions directly
+  // Alternative, using json1 functions directly
   await db.execute('''
 INSERT INTO users(name, email)
 SELECT e.value ->> 'name', e.value ->> 'email' FROM json_each(?) e
 RETURNING id''', [users]);
 
-  // Select by id
+  // Select using "WHERE id IN ..."
   var queriedUsers = (await db.getAll(
           "SELECT id, name, email FROM users WHERE id IN (SELECT json_each.value FROM json_each(?)) ORDER BY name",
           [ids]))
@@ -66,12 +67,17 @@ RETURNING id''', [users]);
 
   print(queriedUsers);
 
-  // Bulk update
+  // Bulk update using UPDATE FROM
   await db.execute('''
 UPDATE users
   SET name = args.name, email = args.email
 FROM (${User.selectJsonData('?')}) as args
   WHERE users.id = args.id''', [queriedUsers]);
 
+  // Bulk delete using "WHERE id IN ..."
+  await db.execute('''
+DELETE FROM users WHERE id IN (SELECT json_each.value FROM json_each(?))''',
+      [queriedUsers.map((u) => u.id).toList()]);
+
   await db.close();
 }

lib/src/mutex.dart

@@ -97,12 +97,17 @@ class SimpleMutex implements Mutex {
     await lock(() async {});
   }
 
+  /// Get a serialized instance that can be passed over to a different isolate.
   SerializedMutex get shared {
     _shared ??= SharedMutexServer._withMutex(this);
     return _shared!.serialized;
   }
 }
 
+/// Serialized version of a Mutex, can be passed over to different isolates.
+/// Use [open] to get a Mutex instance.
+///
+/// Uses [SendPort] to communicate with the source mutex.
 class SerializedMutex {
   final SerializedPortClient client;
 
@@ -113,6 +118,9 @@ class SerializedMutex {
   }
 }
 
+/// Mutex instantiated from a source mutex, potentially in a different isolate.
+///
+/// Uses a [SendPort] to communicate with the source mutex.
 class SharedMutex implements Mutex {
   final ChildPortClient client;
 
@@ -176,11 +184,6 @@ class SharedMutexServer {
 
   late final PortServer server;
 
-  factory SharedMutexServer._() {
-    final Mutex mutex = Mutex();
-    return SharedMutexServer._withMutex(mutex);
-  }
-
   SharedMutexServer._withMutex(this.mutex) {
     server = PortServer((Object? arg) async {
       return await _handle(arg);

lib/src/sqlite_connection_impl.dart

@@ -238,6 +238,7 @@ void _sqliteConnectionIsolate(_SqliteConnectionParams params) async {
         throw sqlite.SqliteException(
             0, 'Transaction must be closed within the read or write lock');
       }
+      return null;
     } else if (data is _SqliteIsolateStatement) {
       if (data.sql == 'BEGIN' || data.sql == 'BEGIN IMMEDIATE') {
         if (txId != null) {
@@ -282,6 +283,9 @@ void _sqliteConnectionIsolate(_SqliteConnectionParams params) async {
       }
     } else if (data is _SqliteIsolateConnectionClose) {
       db.dispose();
+      return null;
+    } else {
+      throw ArgumentError('Unknown data type $data');
     }
   });
 

lib/src/sqlite_database.dart

@@ -121,8 +121,10 @@ class SqliteDatabase with SqliteQueries implements SqliteConnection {
         } else {
           updates!.tables.addAll(message.tables);
         }
+        return null;
       } else if (message is InitDb) {
         await _initialized;
+        return null;
       } else if (message is SubscribeToUpdates) {
         if (subscriptions.containsKey(message.port)) {
           return;
@@ -131,9 +133,13 @@ class SqliteDatabase with SqliteQueries implements SqliteConnection {
           message.port.send(event);
         });
         subscriptions[message.port] = subscription;
+        return null;
       } else if (message is UnsubscribeToUpdates) {
         final subscription = subscriptions.remove(message.port);
         subscription?.cancel();
+        return null;
+      } else {
+        throw ArgumentError('Unknown message type: $message');
       }
     });
   }

test/isolate_test.dart

@@ -1,9 +1,7 @@
 import 'dart:isolate';
-import 'dart:math';
 
-import 'package:sqlite_async/sqlite_async.dart';
 import 'package:test/test.dart';
-import 'package:sqlite3/sqlite3.dart' as sqlite;
+
 import 'util.dart';
 
 void main() {

test/migration_test.dart

@@ -1,8 +1,6 @@
-import 'dart:math';
-
 import 'package:sqlite_async/sqlite_async.dart';
 import 'package:test/test.dart';
-import 'package:sqlite3/sqlite3.dart' as sqlite;
+
 import 'util.dart';
 
 void main() {

test/watch_test.dart

@@ -2,11 +2,9 @@ import 'dart:async';
 import 'dart:isolate';
 import 'dart:math';
 
-import 'package:async/async.dart';
 import 'package:sqlite3/sqlite3.dart';
 import 'package:sqlite_async/sqlite_async.dart';
 import 'package:sqlite_async/src/database_utils.dart';
-import 'package:sqlite_async/src/isolate_connection_factory.dart';
 import 'package:test/test.dart';
 
 import 'util.dart';