v0.2.0

Author: rkistner

.gitignore

@@ -11,3 +11,4 @@ pubspec.lock
 *.db-*
 test-db
 sqlite-autoconf-*
+doc

CHANGELOG.md

@@ -1,7 +1,3 @@
-## 0.1.1
-
-- Expand examples.
-
-## 0.1.0
+## 0.2.0
 
 - Initial version.

lib/mutex.dart

@@ -0,0 +1,4 @@
+/// Mutex for locks in a single Isolate, or across isolates.
+library;
+
+export 'src/mutex.dart';

lib/sqlite3.dart

@@ -0,0 +1,5 @@
+/// Re-exports [sqlite3](https://pub.dev/packages/sqlite3) to expose sqlite3 without
+/// adding it as a direct dependency.
+library;
+
+export 'package:sqlite3/sqlite3.dart';

lib/sqlite_async.dart

@@ -1,13 +1,14 @@
-/// Support for doing something awesome.
+/// High-performance asynchronous interface for SQLite on Dart & Flutter.
 ///
-/// More dartdocs go here.
-library sqlite_dart;
+/// See [SqliteDatabase] as a starting point.
+library;
 
+export 'src/isolate_connection_factory.dart';
 export 'src/sqlite_connection.dart';
-export 'src/update_notification.dart';
 export 'src/sqlite_database.dart';
-export 'src/sqlite_options.dart';
-export 'src/sqlite_open_factory.dart';
 export 'src/sqlite_migrations.dart';
-export 'src/isolate_connection_factory.dart';
+export 'src/sqlite_open_factory.dart';
+export 'src/sqlite_options.dart';
+export 'src/sqlite_queries.dart';
+export 'src/update_notification.dart';
 export 'src/utils.dart';

lib/src/database_utils.dart

@@ -2,8 +2,6 @@ import 'dart:async';
 import 'dart:convert';
 import 'dart:isolate';
 
-import 'package:sqlite3/sqlite3.dart' as sqlite;
-
 import 'sqlite_connection.dart';
 
 Future<T> internalReadTransaction<T>(SqliteReadContext ctx,
@@ -42,39 +40,6 @@ Future<T> internalWriteTransaction<T>(SqliteWriteContext ctx,
   }
 }
 
-Future<T> asyncDirectTransaction<T>(sqlite.Database db,
-    FutureOr<T> Function(sqlite.Database db) callback) async {
-  for (var i = 50; i >= 0; i--) {
-    try {
-      db.execute('BEGIN IMMEDIATE');
-      late T result;
-      try {
-        result = await callback(db);
-        db.execute('COMMIT');
-      } catch (e) {
-        try {
-          db.execute('ROLLBACK');
-        } catch (e2) {
-          // Safe to ignore
-        }
-        rethrow;
-      }
-
-      return result;
-    } catch (e) {
-      if (e is sqlite.SqliteException) {
-        if (e.resultCode == 5 && i != 0) {
-          // SQLITE_BUSY
-          await Future.delayed(const Duration(milliseconds: 50));
-          continue;
-        }
-      }
-      rethrow;
-    }
-  }
-  throw AssertionError('Should not reach this');
-}
-
 /// Given a SELECT query, return the tables that the query depends on.
 Future<Set<String>> getSourceTablesText(
     SqliteReadContext ctx, String sql) async {

lib/src/isolate_connection_factory.dart

@@ -1,6 +1,8 @@
 import 'dart:async';
 import 'dart:isolate';
 
+import 'package:sqlite3/sqlite3.dart' as sqlite;
+
 import 'database_utils.dart';
 import 'mutex.dart';
 import 'port_channel.dart';
@@ -40,6 +42,19 @@ class IsolateConnectionFactory {
           updates.close();
         });
   }
+
+  /// Opens a synchronous sqlite.Database directly in the current isolate.
+  ///
+  /// This gives direct access to the database, but:
+  ///  1. No app-level locking is performed automatically. Transactions may fail
+  ///     with SQLITE_BUSY if another isolate is using the database at the same time.
+  ///  2. Other connections are not notified of any updates to tables made within
+  ///     this connection.
+  Future<sqlite.Database> openRawDatabase({bool readOnly = false}) async {
+    final db = await openFactory
+        .open(SqliteOpenOptions(primaryConnection: false, readOnly: readOnly));
+    return db;
+  }
 }
 
 class _IsolateUpdateListener {

lib/src/mutex.dart

@@ -13,6 +13,9 @@ abstract class Mutex {
   /// timeout is a timeout for acquiring the lock, not for the callback
   Future<T> lock<T>(Future<T> Function() callback, {Duration? timeout});
 
+  /// Release resources used by the Mutex.
+  ///
+  /// Subsequent calls to [lock] may fail, or may never call the callback.
   Future<void> close();
 }
 
@@ -32,7 +35,7 @@ class SimpleMutex implements Mutex {
 
   bool get locked => last != null;
 
-  SharedMutexServer? _shared;
+  _SharedMutexServer? _shared;
 
   @override
   Future<T> lock<T>(Future<T> Function() callback, {Duration? timeout}) async {
@@ -99,15 +102,15 @@ class SimpleMutex implements Mutex {
 
   /// Get a serialized instance that can be passed over to a different isolate.
   SerializedMutex get shared {
-    _shared ??= SharedMutexServer._withMutex(this);
+    _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.
+/// Use [open] to get a [SharedMutex] instance.
 ///
-/// Uses [SendPort] to communicate with the source mutex.
+/// Uses a [SendPort] to communicate with the source mutex.
 class SerializedMutex {
   final SerializedPortClient client;
 
@@ -176,15 +179,15 @@ class SharedMutex implements Mutex {
   }
 }
 
-/// Like Mutex, but can be coped across Isolates.
-class SharedMutexServer {
+/// Manages a [SerializedMutex], allowing a [Mutex] to be shared across isolates.
+class _SharedMutexServer {
   Completer? unlock;
   late final SerializedMutex serialized;
   final Mutex mutex;
 
   late final PortServer server;
 
-  SharedMutexServer._withMutex(this.mutex) {
+  _SharedMutexServer._withMutex(this.mutex) {
     server = PortServer((Object? arg) async {
       return await _handle(arg);
     });

lib/src/sqlite_database.dart

@@ -18,6 +18,9 @@ import 'update_notification.dart';
 /// Use one instance per database file. If multiple instances are used, update
 /// notifications may not trigger, and calls may fail with "SQLITE_BUSY" errors.
 class SqliteDatabase with SqliteQueries implements SqliteConnection {
+  /// The maximum number of concurrent read transactions if not explicitly specified.
+  static const int defaultMaxReaders = 5;
+
   /// Maximum number of concurrent read transactions.
   final int maxReaders;
 
@@ -56,11 +59,11 @@ class SqliteDatabase with SqliteQueries implements SqliteConnection {
   /// A maximum of [maxReaders] concurrent read transactions are allowed.
   factory SqliteDatabase(
       {required path,
-      maxReaders = 5,
-      options = const SqliteOptions.defaults()}) {
+      int maxReaders = defaultMaxReaders,
+      SqliteOptions options = const SqliteOptions.defaults()}) {
     final factory =
         DefaultSqliteOpenFactory(path: path, sqliteOptions: options);
-    return SqliteDatabase.withFactory(factory);
+    return SqliteDatabase.withFactory(factory, maxReaders: maxReaders);
   }
 
   /// Advanced: Open a database with a specified factory.
@@ -72,7 +75,8 @@ class SqliteDatabase with SqliteQueries implements SqliteConnection {
   ///  2. Running additional per-connection PRAGMA statements on each connection.
   ///  3. Creating custom SQLite functions.
   ///  4. Creating temporary views or triggers.
-  SqliteDatabase.withFactory(this.openFactory, {this.maxReaders = 5}) {
+  SqliteDatabase.withFactory(this.openFactory,
+      {this.maxReaders = defaultMaxReaders}) {
     updates = _updatesController.stream;
 
     _listenForEvents();
@@ -146,7 +150,7 @@ class SqliteDatabase with SqliteQueries implements SqliteConnection {
 
   /// A connection factory that can be passed to different isolates.
   ///
-  /// Use this to access the database in background isolates.s
+  /// Use this to access the database in background isolates.
   IsolateConnectionFactory isolateConnectionFactory() {
     return IsolateConnectionFactory(
         openFactory: openFactory,

lib/src/sqlite_queries.dart

@@ -2,7 +2,6 @@ import 'package:sqlite3/sqlite3.dart' as sqlite;
 
 import 'database_utils.dart';
 import 'sqlite_connection.dart';
-import 'throttle.dart';
 import 'update_notification.dart';
 
 /// Mixin to provide default query functionality.
@@ -52,8 +51,9 @@ mixin SqliteQueries implements SqliteWriteContext, SqliteConnection {
     assert(updates != null,
         'updates stream must be provided to allow query watching');
     final tables = triggerOnTables ?? await getSourceTables(this, sql);
-    final filteredStream = updates!.transform(filterTablesTransformer(tables));
-    final throttledStream = throttleUpdateNotifications(
+    final filteredStream =
+        updates!.transform(UpdateNotification.filterTablesTransformer(tables));
+    final throttledStream = UpdateNotification.throttleStream(
         filteredStream, throttle,
         addOne: UpdateNotification.empty());
 
@@ -89,9 +89,9 @@ mixin SqliteQueries implements SqliteWriteContext, SqliteConnection {
     assert(updates != null,
         'updates stream must be provided to allow query watching');
     final filteredStream = tables != null
-        ? updates!.transform(filterTablesTransformer(tables))
+        ? updates!.transform(UpdateNotification.filterTablesTransformer(tables))
         : updates!;
-    final throttledStream = throttleUpdateNotifications(
+    final throttledStream = UpdateNotification.throttleStream(
         filteredStream, throttle,
         addOne: triggerImmediately ? UpdateNotification.empty() : null);
     return throttledStream;