diff --git a/client-sdks/reference/javascript-web.mdx b/client-sdks/reference/javascript-web.mdx index 2e8174c8..dcf39db8 100644 --- a/client-sdks/reference/javascript-web.mdx +++ b/client-sdks/reference/javascript-web.mdx @@ -488,6 +488,40 @@ export const db = new PowerSyncDatabase({ }); ``` +**Multi-Threaded In-Memory VFS** + +Since version 2.2.0 of the `@powersync/web` package, a per-tab in-memory file system can be configured to run with multiple worker threads. +This VFS uses a design similar to `OPFSWriteAheadVFS`, allowing concurrent reads and a writer to operate on the database in parallel. +Instead of writing files to OPFS, it uses `SharedArrayBuffer` to coordinate an in-memory database across workers. + +This setup is experimental and might change in the future. + +This configuration does not share data across tabs. Each tab gets a unique database and sync client, and databases opened with this +approach cannot be named. Thus, this VFS is primarily relevant when all of the following apply: + +1. You need highly concurrent, high-performance queries in your app. +2. At the same time, the overall database size (or at least the actively synced part of the database) is relatively small, as it gets + synced every time a tab is opened. +3. You don't need persistence. +4. You can enable [cross-origin isolation](https://web.dev/articles/cross-origin-isolation-guide) by using the appropriate headers. + Without cross-origin isolation and shared array buffers, constructing the pool will throw. +5. You don't need multiple tabs to share offline state. + +We don't expect this setup to be relevant for most users. Hence, the VFS is not bundled with the web SDK to avoid any impact on bundle size. +To use it, import `@powersync/web/in-memory-wal-experiment`: + +```js +import { InMemoryWriteAheadLogPool } from '@powersync/web/in-memory-wal-experiment'; +import { PowerSyncDatabase } from '@powersync/web'; + +export const db = new PowerSyncDatabase({ + schema: AppSchema, + opened: new InMemoryWriteAheadLogPool({ + numWorkers: 3 // Uses one writer, two additional workers for reads. + }), +}); +``` + #### VFS Compatibility Matrix | VFS Type | Multi-Tab (Standard) | Multi-Tab (Safari/iOS) | Concurrent Reads | Best For |