From fd061b57dd7b75159f84582309917be0f8e57404 Mon Sep 17 00:00:00 2001 From: Simon Binder Date: Thu, 13 Aug 2026 15:57:22 +0200 Subject: [PATCH 1/3] Document in-memory pool --- client-sdks/reference/javascript-web.mdx | 32 ++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/client-sdks/reference/javascript-web.mdx b/client-sdks/reference/javascript-web.mdx index 2e8174c8..41790e3e 100644 --- a/client-sdks/reference/javascript-web.mdx +++ b/client-sdks/reference/javascript-web.mdx @@ -488,6 +488,38 @@ export const db = new PowerSyncDatabase({ }); ``` +#### Multi-threaded in-memory VFS + +Since version 2.2.0 of `@powersync/web`, 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 however, it uses shared array buffers to coordinate an in-memory database across workers. + +This configuration does not share data across tabs (it gives each tab a unique database and sync client, 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. +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 | From 06445b1229dcfb73d605d66c8d770864aa136cce Mon Sep 17 00:00:00 2001 From: Simon Binder Date: Thu, 13 Aug 2026 16:07:07 +0200 Subject: [PATCH 2/3] style fixes --- client-sdks/reference/javascript-web.mdx | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/client-sdks/reference/javascript-web.mdx b/client-sdks/reference/javascript-web.mdx index 41790e3e..fff72a4b 100644 --- a/client-sdks/reference/javascript-web.mdx +++ b/client-sdks/reference/javascript-web.mdx @@ -488,15 +488,14 @@ export const db = new PowerSyncDatabase({ }); ``` -#### Multi-threaded in-memory VFS +#### Multi-Threaded In-Memory VFS -Since version 2.2.0 of `@powersync/web`, a per-tab in-memory file system can be configured to run with multiple worker threads. +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 however, it uses shared array buffers to coordinate an in-memory database across workers. +Instead of writing files to OPFS, however, it uses `SharedArrayBuffer` to coordinate an in-memory database across workers. -This configuration does not share data across tabs (it gives each tab a unique database and sync client, databases opened with this -approach cannot be named). -Thus, this VFS is primarily relevant when all of the following apply: +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 @@ -515,7 +514,7 @@ 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. + numWorkers: 3 // Uses one writer, two additional workers for reads. }), }); ``` From f100e7836344496821cb8d8195d0d5c76191609a Mon Sep 17 00:00:00 2001 From: Simon Binder Date: Thu, 13 Aug 2026 16:15:23 +0200 Subject: [PATCH 3/3] More style updates --- client-sdks/reference/javascript-web.mdx | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/client-sdks/reference/javascript-web.mdx b/client-sdks/reference/javascript-web.mdx index fff72a4b..dcf39db8 100644 --- a/client-sdks/reference/javascript-web.mdx +++ b/client-sdks/reference/javascript-web.mdx @@ -488,11 +488,13 @@ export const db = new PowerSyncDatabase({ }); ``` -#### Multi-Threaded In-Memory VFS +**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, however, it uses `SharedArrayBuffer` to coordinate an in-memory database across workers. +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: @@ -502,6 +504,7 @@ approach cannot be named. Thus, this VFS is primarily relevant when all of the f 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.