feat: Configurable Web VFS (added OPFS)

[stevensJourney]

Overview

This POC adds support for configuring different SQLite virtual filesystems on Web.

WA-SQLite's IDBBatchAtomicVFS is still used as the default VFS.

Synchronous Origin Private FileSystem (OPFS) VFS options are added. See WA-SQLite README for more details.

Notes

Configuration

OPFS can be configured with a WASQLiteOpenFactory. These options could be added to the default web constructor.

export const db = new PowerSyncDatabase({
  schema: AppSchema,
  database: new WASQLiteOpenFactory({
    dbFilename: 'examplsw1se112.db',
    vfs: WASQLiteVFS.OPFSCoopSyncVFS,
    flags: {
      enableMultiTabs: typeof SharedWorker !== 'undefined'
    } 
  }),
  flags: {
    enableMultiTabs: typeof SharedWorker !== 'undefined'
  }
});

Multiple Tab Support

The OPFS VFS currently only works in dedicated web workers. The current multiple tab support implementation has been updated in order to cater for this. For IndexDB we still use a single SharedWorker which manages a single SQLite connection between tabs. For OPFS each tab uses its own dedicated Worker which has its own SQLite connection. Table update notifications are shared between tabs via a BroadcastChannel. Exclusive locks between tab connections are maintained through Navigator locks as usual.

The initialisation for Web DBAdapters has been streamlined and extended in order to support OPFS. The abstractions and sharing of implementation is managed by new internal APIs and classes.

Safari Multiple Tab Support

The new code structure seemed to fix the long outstanding Safari multiple tab support issues when using pnpm serve but doing a build and using pnpm preview still shows the same problem.

However, using OPFSCoopSyncVFS now provides multiple tab support for both Safari and Safari iOS.
This is not yet enabled by default but can be enabled with an appropriate flag.

export const db = new PowerSyncDatabase({
  schema: AppSchema,
  database: new WASQLiteOpenFactory({
    dbFilename: 'multitab.db',
    vfs: WASQLiteVFS.OPFSCoopSyncVFS,
    flags: {
      enableMultiTabs: typeof SharedWorker !== 'undefined'
    } 
  }),
  flags: {
    enableMultiTabs: typeof SharedWorker !== 'undefined'
  }
});

OPFS VFS and Multiple tabs

The AccessHandlePoolVFS does not seem to work well when more than 1 dedicated worker accesses the filesystem. OPFSCoopSyncVFS works with multiple tabs.

Performance

OPFS (with AccessHandlePoolVFS) has been observed to be significantly faster than the IndexDB filesystem. The time to sync 23_000 rows was compared between IndexDB and OPFS

IndexDB

OPFS

Safari/Angular Demo

An issue was found with the Angular demo where it would not work with Safari, using OPFS resolves this - as such the demo has been updated.

Web Encryption

The #439 PR was merged into this branch and is meant to go into main with this changeset.

TODOS

• Better warnings for OPFS if configuration is invalid
• Better support for clearing OPFS storage

[changeset-bot]

🦋 Changeset detected

Latest commit: f8cad95

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@powersync/web	Minor
@powersync/diagnostics-app	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[rhashimoto]

Unsolicited drive-by comment:

The use of OPFS requires a secure context and additional HTTP headers when serving a web application. These are already documented for the Dart SDK.

OPFS itself doesn't require the COOP/COEP headers and associated restrictions. Some SQLite VFS implementations use SharedArrayBuffer to provide a synchronous interface for SQLite, and that is what requires COOP/COEP, not OPFS.

However, no example VFS in wa-sqlite uses SharedArrayBuffer. If you are using any VFS from the wa-sqlite project then COOP/COEP headers are unnecessary.

[stevensJourney]

Unsolicited drive-by comment:

The use of OPFS requires a secure context and additional HTTP headers when serving a web application. These are already documented for the Dart SDK.

OPFS itself doesn't require the COOP/COEP headers and associated restrictions. Some SQLite VFS implementations use SharedArrayBuffer to provide a synchronous interface for SQLite, and that is what requires COOP/COEP, not OPFS.

However, no example VFS in wa-sqlite uses SharedArrayBuffer. If you are using any VFS from the wa-sqlite project then COOP/COEP headers are unnecessary.

Thank you for the tip/catch, @rhashimoto! I copied this from our Dart docs without fully verifying it yet, so this is really helpful. I'll review the relevant sections and update them as needed. It's a personal honor to have you comment on this.

[DominicGBauer]

I don't have much context but reviewing the code everything seems in order

[rkistner]

Overall I like the new architecture, and I think OPFSCoopSyncVFS is a good VFS to recommend.

The implementation also looks good overall, but I picked up some issues during testing.

I used the react-supabase-todolist demo for testing, with the following setup:

const factory = new WASQLiteOpenFactory({
  dbFilename: 'test.db',
  vfs: WASQLiteVFS.OPFSCoopSyncVFS
});

export const db = new PowerSyncDatabase({
  schema: AppSchema,
  flags: {},
  database: factory
});

There appears to be an issue with infinite update notification loops as soon as two databases are open, in the same tab or different tabs.

Test case 1: Single tab, hot reload

A hot reload opens a new copy of the database with its own dedicated worker, without closing the previous one. Not sure if this is an issue by itself, but it leads to constant 200% cpu usage, increasing further if you trigger more hot reloads.

Test case 2: Multiple tabs

As soon as you have multiple tabs open, you get the same CPU usage issue as above, even without hot reloading.

Another issue with multiple tabs is that the uploading status changes to true every second, then immediately back to false, after triggering a single change.

Profiling

When profiling with 2 tabs open, it seems like this block is repeatedly hit in the workers:

powersync-js/packages/web/src/db/adapters/wa-sqlite/WASQLiteConnection.ts

Lines 224 to 229 in 428686a

	protected queueTableUpdate(tableNames: Set<string>) {
	tableNames.forEach((tableName) => this.updatedTables.add(tableName));
	if (this.updateTimer == null) {
	this.updateTimer = setTimeout(() => this.fireUpdates(), 0);
	}
	}

This is what leads me to believe the issue is related to update notification loops.

IDBBatchAtomicVFS

I did not see any of the above issues when using IDBBatchAtomicVFS, although I haven't tested it as thoroughly.

[Chriztiaan]

@rkistner there were two fixes (two separate commits), where the issues were:

1. Infinite looping of broadcasts - client A would broadcast to client B and then client B would rebroadcast to client A

• The broadcast flow is breaking after the first broadcast explicitly
• Resolves high CPU load when having multiple tabs open or when HMR spawns multiple workers

2. HMR creates a new dedicated worker without closing the previous one

• Fixed an issue where the dedicated worker wasn't being terminated when close() is called on the PS client.

The outstanding issue is that the PS client isn't closed on HMR. An option we can try is to add a Vite specific handler to our Vite demos:

if (import.meta.hot) {
 import.meta.hot.dispose(() => {
   // Cleanup before the worker module is replaced.
   db.close();
 });
}

We might consider adding that in a follow-up PR.