Merge main

Author: simolus3

.github/workflows/main.yml

@@ -156,6 +156,33 @@ jobs:
         if-no-files-found: error
         retention-days: 1
 
+  integration_test_web:
+    needs: [analyze, fetch_sqlite]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dart-lang/setup-dart@v1
+        with:
+          sdk: beta
+      - name: Download compiled sqlite3
+        uses: actions/download-artifact@v5
+        with:
+          artifact-ids: ${{ needs.fetch_sqlite.outputs.artifact_id }}
+          path: sqlite-compiled
+      - uses: actions/cache@v4
+        with:
+          path: "${{ env.PUB_CACHE }}"
+          key: dart-dependencies-${{ matrix.dart }}-${{ runner.os }}
+          restore-keys: |
+            dart-dependencies-${{ matrix.dart }}-
+            dart-dependencies-
+
+      - name: Web tests
+        run: |
+          cp ../sqlite-compiled/*.wasm web/
+          dart pub get
+          dart test -P gh_actions -r expanded
+        working-directory: sqlite3_web
 
 # The integration tests for android are currently broken (the emulator doesn't want to
 # start up...)

sqlite3/CHANGELOG.md

@@ -7,6 +7,15 @@
     `sqlcipher_flutter_libs` when upgrading.
 - __Breaking change__: Parameters to `SqliteException`s are now named.
 
+## 2.9.4
+
+- `SimpleOpfsFileSystem`: Allow opening with `readwrite-unsafe`, which can be used to implement
+  multi-tab OPFS databases on Chrome with an outer locking scheme.
+
+## 2.9.3
+
+- Allow iterating over statements after `SQLITE_BUSY` errors.
+
 ## 2.9.2
 
 - Fix a bug introduced in version `2.9.1` where the SQLite framework provided by

sqlite3/lib/src/implementation/statement.dart

@@ -397,7 +397,11 @@ class _ActiveCursorIterator extends IteratingCursor {
     }
 
     // We're at the end of the result set or encountered an exception here.
-    statement._currentCursor = null;
+    if (result != SqlError.SQLITE_BUSY) {
+      // Statements failing with SQLITE_BUSY can be retried in some instances,
+      // so we don't want to detach the cursor.
+      statement._currentCursor = null;
+    }
 
     if (result != SqlError.SQLITE_OK && result != SqlError.SQLITE_DONE) {
       throwException(

sqlite3/lib/src/wasm/js_interop/new_file_system_access.dart

@@ -85,3 +85,23 @@ extension FileSystemDirectoryHandleApi on FileSystemDirectoryHandle {
     }
   }
 }
+
+// https://github.com/whatwg/fs/blob/main/proposals/MultipleReadersWriters.md
+extension ProposedLockingSchemeApi on FileSystemFileHandle {
+  external JSPromise<FileSystemSyncAccessHandle> createSyncAccessHandle(
+    FileSystemCreateSyncAccessHandleOptions options,
+  );
+}
+
+// https://github.com/whatwg/fs/blob/main/proposals/MultipleReadersWriters.md#modes-of-creating-a-filesystemsyncaccesshandle
+@anonymous
+extension type FileSystemCreateSyncAccessHandleOptions._(JSObject _)
+    implements JSObject {
+  external factory FileSystemCreateSyncAccessHandleOptions({JSString? mode});
+
+  static FileSystemCreateSyncAccessHandleOptions unsafeReadWrite() {
+    return FileSystemCreateSyncAccessHandleOptions(
+      mode: 'readwrite-unsafe'.toJS,
+    );
+  }
+}

sqlite3/lib/src/wasm/vfs/simple_opfs.dart

@@ -96,17 +96,27 @@ final class SimpleOpfsFileSystem extends BaseVirtualFileSystem {
   /// Throws a [VfsException] if OPFS is not available - please note that
   /// this file system implementation requires a recent browser and only works
   /// in dedicated web workers.
+  ///
+  /// When [readWriteUnsafe] is passed, the synchronous file handles are opened
+  /// using the [proposed lock mode](https://github.com/whatwg/fs/blob/main/proposals/MultipleReadersWriters.md).
+  /// This mode is currently not supported across browsers, but can be used on
+  /// Chrome for faster database access across tabs.
   static Future<SimpleOpfsFileSystem> loadFromStorage(
     String path, {
     String vfsName = 'simple-opfs',
+    bool readWriteUnsafe = false,
   }) async {
     final storage = storageManager;
     if (storage == null) {
       throw VfsException(SqlError.SQLITE_ERROR);
     }
 
     final (_, directory) = await _resolveDir(path);
-    return inDirectory(directory, vfsName: vfsName);
+    return inDirectory(
+      directory,
+      vfsName: vfsName,
+      readWriteUnsafe: readWriteUnsafe,
+    );
   }
 
   /// Deletes the file system directory handle that would store sqlite3
@@ -136,14 +146,27 @@ final class SimpleOpfsFileSystem extends BaseVirtualFileSystem {
   /// Loads an [SimpleOpfsFileSystem] in the desired [root] directory, which must be
   /// a Dart wrapper around a [FileSystemDirectoryHandle].
   ///
+  /// When [readWriteUnsafe] is passed, the synchronous file handles are opened
+  /// using the [proposed lock mode](https://github.com/whatwg/fs/blob/main/proposals/MultipleReadersWriters.md).
+  /// This mode is currently not supported across browsers, but can be used on
+  /// Chrome for faster database access across tabs.
+  ///
   /// [FileSystemDirectoryHandle]: https://developer.mozilla.org/en-US/docs/Web/API/FileSystemDirectoryHandle
   static Future<SimpleOpfsFileSystem> inDirectory(
     FileSystemDirectoryHandle root, {
     String vfsName = 'simple-opfs',
+    bool readWriteUnsafe = false,
   }) async {
     Future<FileSystemSyncAccessHandle> open(String name) async {
       final handle = await root.openFile(name, create: true);
-      return await handle.createSyncAccessHandle().toDart;
+
+      final syncHandlePromise = readWriteUnsafe
+          ? ProposedLockingSchemeApi(handle).createSyncAccessHandle(
+              FileSystemCreateSyncAccessHandleOptions.unsafeReadWrite(),
+            )
+          : handle.createSyncAccessHandle();
+
+      return await syncHandlePromise.toDart;
     }
 
     final meta = await open('meta');

sqlite3/test/common/prepared_statement.dart

@@ -587,6 +587,38 @@ void testPreparedStatements(
         throwsSqlError(19, 2067),
       );
     });
+
+    test('recovers from SQLITE_BUSY', () {
+      final vfs = _ErrorInjectingVfs(
+        InMemoryFileSystem(),
+        name: 'test-recover-sqlite-busy',
+      );
+      sqlite3.registerVirtualFileSystem(vfs);
+      addTearDown(() => sqlite3.unregisterVirtualFileSystem(vfs));
+
+      var db = sqlite3.open('/db', vfs: vfs.name);
+      addTearDown(() => db.dispose());
+
+      db
+        ..execute('CREATE TABLE foo (bar TEXT) STRICT')
+        ..execute('INSERT INTO foo (bar) VALUES (?)', ['testing'])
+        ..dispose();
+
+      db = db = sqlite3.open('/db', vfs: vfs.name);
+      final stmt = db.prepare('SELECT * FROM foo');
+      final cursor = stmt.selectCursor();
+      vfs.maybeError = () => throw VfsException(SqlError.SQLITE_BUSY);
+
+      expect(
+        () => cursor.moveNext(),
+        throwsSqlError(SqlError.SQLITE_BUSY, SqlError.SQLITE_BUSY),
+      );
+      vfs.maybeError = null;
+      expect(cursor.moveNext(), isTrue);
+      expect(cursor.current, {'bar': 'testing'});
+
+      stmt.dispose();
+    });
   });
 }
 
@@ -604,3 +636,111 @@ class _CustomValue implements CustomStatementParameter {
     stmt.statement.sqlite3_bind_int64(index, 42);
   }
 }
+
+final class _ErrorInjectingVfs extends BaseVirtualFileSystem {
+  final VirtualFileSystem _base;
+  void Function()? maybeError;
+
+  _ErrorInjectingVfs(this._base, {required super.name});
+
+  void _op() {
+    maybeError?.call();
+  }
+
+  @override
+  int xAccess(String path, int flags) {
+    _op();
+    return _base.xAccess(path, flags);
+  }
+
+  @override
+  void xDelete(String path, int syncDir) {
+    _op();
+    return _base.xDelete(path, syncDir);
+  }
+
+  @override
+  String xFullPathName(String path) {
+    _op();
+    return _base.xFullPathName(path);
+  }
+
+  @override
+  XOpenResult xOpen(Sqlite3Filename path, int flags) {
+    _op();
+    final inner = _base.xOpen(path, flags);
+    return (
+      outFlags: inner.outFlags,
+      file: _ErrorInjectingFile(this, inner.file),
+    );
+  }
+
+  @override
+  void xSleep(Duration duration) {
+    return _base.xSleep(duration);
+  }
+}
+
+final class _ErrorInjectingFile implements VirtualFileSystemFile {
+  final _ErrorInjectingVfs _vfs;
+  final VirtualFileSystemFile _base;
+
+  _ErrorInjectingFile(this._vfs, this._base);
+
+  @override
+  void xRead(Uint8List target, int fileOffset) {
+    _vfs._op();
+    return _base.xRead(target, fileOffset);
+  }
+
+  @override
+  int xCheckReservedLock() {
+    _vfs._op();
+    return _base.xCheckReservedLock();
+  }
+
+  @override
+  int get xDeviceCharacteristics => _base.xDeviceCharacteristics;
+
+  @override
+  void xClose() {
+    _vfs._op();
+    _base.xClose();
+  }
+
+  @override
+  int xFileSize() {
+    _vfs._op();
+    return _base.xFileSize();
+  }
+
+  @override
+  void xLock(int mode) {
+    _vfs._op();
+    _base.xLock(mode);
+  }
+
+  @override
+  void xSync(int flags) {
+    _vfs._op();
+    _base.xSync(flags);
+  }
+
+  @override
+  void xTruncate(int size) {
+    _vfs._op();
+    _base.xTruncate(size);
+  }
+
+  @override
+  void xUnlock(int mode) {
+    _vfs._op();
+    _base.xUnlock(mode);
+  }
+
+  @override
+  void xWrite(Uint8List buffer, int fileOffset) {
+    _vfs._op();
+    _base.xWrite(buffer, fileOffset);
+  }
+}

sqlite3_web/CHANGELOG.md

@@ -1,6 +1,13 @@
-## 0.4.0-dev
+## 0.5.0-dev
 
-- Use version 3.x of `package:sqlite3`.
+- Use version 3 of `package:sqlite3`.
+
+## 0.4.0
+
+- Remove `userVersion` and `setUserVersion`. Users should run the pragma statements manually.
+- Add `requestLock`, which can be used to make multiple database calls in a locked context.
+- Allow aborting requests.
+- Add support for a new Web FS (OPFS) access mode based on `readwrite-unsafe`.
 
 ## 0.3.2
 

sqlite3_web/README.md

@@ -28,7 +28,7 @@ And that is what this package can do for you:
 ## Getting started
 
 Note: While this package can be used by end applications, it is meant as a
-building block for database packages like `sqlite3_async` or `drift`. Using
+building block for database packages like `sqlite_async` or `drift`. Using
 these packages helps avoid some setup work.
 
 Workers are responsible for opening databases and exposing them through message
@@ -75,6 +75,36 @@ Future<void> connectToDatabase() async {
 }
 ```
 
+## Lock and transaction management
+
+This package provides the `select` and `execute` method returning:
+
+1. The `autocommit` state of the database after running the statement.
+2. The last insert rowid value.
+3. For `select`, results.
+
+Because each database typically only uses a single connection (likely hosted in a shared worker),
+implementing transactions requires multiple statements to run without interference from others.
+
+The `requestLock` API is a helpful building block for this. In its callback, no other tab will
+have access to the database:
+
+```dart
+await db.requestLock((lock) async {
+  await db.execute('BEGIN', token: lock);
+  await db.execute(
+    '... other statements',
+    token: lock,
+    checkInTransaction: true,
+  );
+  await db.execute('COMMIT', token: lock, checkInTransaction: true);
+});
+```
+
+Inside a lock context, the `LockToken` must be passed to `select` and `execute`.
+Additionally, the `checkInTransaction` flag can be used to verify that the database
+is not in autocommit mode before running a statement.
+
 ## Custom requests
 
 In some cases, it may be useful to re-use the worker communication scheme
@@ -86,3 +116,10 @@ open transactions can be implemented in the worker by overriding
 `handleCustomRequest` in `WorkerDatabase`. You can encode requests and
 responses as arbitrary values exchanged as `JSAny?`.
 On the client side, requests can be issued with `Database.customRequest`.
+
+## Testing this package
+
+This package uses both regular `dart test` tests and integration tests.
+All tests need a compatible `sqlite3.wasm` file in `web/`.
+
+Integration tests also require `geckodriver` and `chromedriver` to be installed.

sqlite3_web/dart_test.yaml

@@ -1,7 +1,15 @@
 platforms: [vm, chrome, firefox]
 compilers: [dart2wasm, dart2js]
 
+tags:
+  webdriver:
+    # Sometimes spawning the driver times out, it's just easier to retry.
+    retry: 2
+
 override_platforms:
   firefox:
     settings:
       arguments: "-headless"
+
+presets:
+  gh_actions: