From 668c9956d4f23818932cff8b87e477df1692eae9 Mon Sep 17 00:00:00 2001 From: Simon Binder Date: Thu, 9 Jul 2026 17:13:57 +0200 Subject: [PATCH 1/5] Document in-memory VFS --- client-sdks/reference/javascript-web.mdx | 45 ++++++++++++++++++++++-- 1 file changed, 42 insertions(+), 3 deletions(-) diff --git a/client-sdks/reference/javascript-web.mdx b/client-sdks/reference/javascript-web.mdx index b0471d8f..b438b2ab 100644 --- a/client-sdks/reference/javascript-web.mdx +++ b/client-sdks/reference/javascript-web.mdx @@ -457,14 +457,53 @@ export const db = new PowerSyncDatabase({ }); ``` +#### 3. In-Memory VFS + +Starting since version 1.39.0 of the `@powersync/web` package, an in-memory database can be used with `WASQLiteVFS.InMemoryVFS`. +No data is persisted in this file system, meaning that local writes will be lost if they're not uploaded before the tab is closed +and all data will be resynced whenever a tab is opened. +This makes it unsuitable for apps that need to work offline, but it can be useful for development. The VFS is also very fast, +making it useful for online-only apps with small data sizes and very frequent queries. + + +Like all other data, local mutations are not persisted when using an in-memory VFS. + +When using in-memory databases in production scenarios, consider watching `SELECT * FROM ps_crud LIMIT 1` to detect whether outstanding +local mutations exist and indicate that state to the user. A `beforeunload` event listener could also be useful in this state to +call `preventDefault()` on tab close events, causing browsers to ask for confirmation before closing the tab. + + +With Chrome and Firefox on Desktop, this VFS will run in a shared worker by default, meaning that all tabs have access to the same data +and will share a sync worker. +This behavior can be enabled or disabled on all browsers by passing the [`enableMultiTabs` flag](#available-flags). + +If support for multi-tabs is not desired, consider giving each tab a uniquely-named PowerSync instance. The in-memory database +would not be shared across tabs in either case, but only one PowerSync database with the same name can sync at a time. +Unique names ensure databases across tabs are fully independent: + +```JavaScript +export const db = new PowerSyncDatabase({ + schema: AppSchema, + database: new WASQLiteOpenFactory({ + dbFilename: `memory-${crypto.randomUUID()}.db`, + vfs: WASQLiteVFS.InMemoryVFS, + }), + flags: { + enableMultiTabs: false + } +}); +``` + #### VFS Compatibility Matrix | VFS Type | Multi-Tab (Standard) | Multi-Tab (Safari/iOS) | Concurrent Reads | Best For | | ------------------- | -------------------- | ---------------------- | ---------------- | ---------------------------------------------- | -| IDBBatchAtomicVFS | ✅ | ❌ | ❌ | Broadest compatibility, minimal setup | -| OPFSCoopSyncVFS | ✅ | ✅ | ❌ | Multi-tab + Safari/iOS support | -| AccessHandlePoolVFS | ❌ | ❌ | ❌ | Single-tab, single worker, access-handle OPFS | +| IDBBatchAtomicVFS | ✅ | ❌ | ❌ | Broadest compatibility, minimal setup | +| OPFSCoopSyncVFS | ✅ | ✅ | ❌ | Multi-tab + Safari/iOS support | +| AccessHandlePoolVFS | ❌ | ❌ | ❌ | Single-tab, single worker, access-handle OPFS | | OPFSWriteAheadVFS | ✅ | ❌ | ✅ | Chromium only; parallel reads via WAL + readers | +| InMemoryVFS | ✅ | ❌ | ❌ | Development, small data sizes | + **Note**: There are known issues with OPFS (all variants) when using Safari's incognito mode. From 30bb6789163ed2e143d3be84c8cd0e75b2371d2c Mon Sep 17 00:00:00 2001 From: Simon Binder Date: Thu, 9 Jul 2026 17:26:04 +0200 Subject: [PATCH 2/5] Claude fixes --- client-sdks/reference/javascript-web.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/client-sdks/reference/javascript-web.mdx b/client-sdks/reference/javascript-web.mdx index b438b2ab..8a62677b 100644 --- a/client-sdks/reference/javascript-web.mdx +++ b/client-sdks/reference/javascript-web.mdx @@ -459,7 +459,7 @@ export const db = new PowerSyncDatabase({ #### 3. In-Memory VFS -Starting since version 1.39.0 of the `@powersync/web` package, an in-memory database can be used with `WASQLiteVFS.InMemoryVFS`. +Since version 1.39.0 of the `@powersync/web` package, an in-memory database can be used with `WASQLiteVFS.InMemoryVFS`. No data is persisted in this file system, meaning that local writes will be lost if they're not uploaded before the tab is closed and all data will be resynced whenever a tab is opened. This makes it unsuitable for apps that need to work offline, but it can be useful for development. The VFS is also very fast, @@ -481,12 +481,12 @@ If support for multi-tabs is not desired, consider giving each tab a uniquely-na would not be shared across tabs in either case, but only one PowerSync database with the same name can sync at a time. Unique names ensure databases across tabs are fully independent: -```JavaScript +```js export const db = new PowerSyncDatabase({ schema: AppSchema, database: new WASQLiteOpenFactory({ dbFilename: `memory-${crypto.randomUUID()}.db`, - vfs: WASQLiteVFS.InMemoryVFS, + vfs: WASQLiteVFS.InMemoryVFS }), flags: { enableMultiTabs: false From 0e7fbbab122d7a7e1c4902804cbe4d022686c634 Mon Sep 17 00:00:00 2001 From: Simon Binder Date: Thu, 9 Jul 2026 17:36:55 +0200 Subject: [PATCH 3/5] More claude suggestions --- 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 8a62677b..ff40e1b3 100644 --- a/client-sdks/reference/javascript-web.mdx +++ b/client-sdks/reference/javascript-web.mdx @@ -462,19 +462,18 @@ export const db = new PowerSyncDatabase({ Since version 1.39.0 of the `@powersync/web` package, an in-memory database can be used with `WASQLiteVFS.InMemoryVFS`. No data is persisted in this file system, meaning that local writes will be lost if they're not uploaded before the tab is closed and all data will be resynced whenever a tab is opened. -This makes it unsuitable for apps that need to work offline, but it can be useful for development. The VFS is also very fast, -making it useful for online-only apps with small data sizes and very frequent queries. +This makes it unsuitable for apps that need to work offline, but it can be useful for development. The VFS is also faster than +all other single-threaded setups (both IndexedDB and OPFS except the write-ahead VFS), making it useful for online-only apps +with small data sizes and very frequent queries. -Like all other data, local mutations are not persisted when using an in-memory VFS. - When using in-memory databases in production scenarios, consider watching `SELECT * FROM ps_crud LIMIT 1` to detect whether outstanding -local mutations exist and indicate that state to the user. A `beforeunload` event listener could also be useful in this state to +local mutations exist and indicate that state to the user. A `beforeunload` event listener can also be useful in this state to call `preventDefault()` on tab close events, causing browsers to ask for confirmation before closing the tab. -With Chrome and Firefox on Desktop, this VFS will run in a shared worker by default, meaning that all tabs have access to the same data -and will share a sync worker. +With Chrome and Firefox on Desktop, this VFS will use a shared worker to enable multi-tab support by default, meaning that all +tabs have access to the same data and will share a sync worker. This behavior can be enabled or disabled on all browsers by passing the [`enableMultiTabs` flag](#available-flags). If support for multi-tabs is not desired, consider giving each tab a uniquely-named PowerSync instance. The in-memory database From 5d99880956e2fe6428506c88a4e59a8cd8983dae Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Fri, 10 Jul 2026 10:51:11 +0200 Subject: [PATCH 4/5] Intro polish --- client-sdks/reference/javascript-web.mdx | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/client-sdks/reference/javascript-web.mdx b/client-sdks/reference/javascript-web.mdx index ff40e1b3..01b89eb8 100644 --- a/client-sdks/reference/javascript-web.mdx +++ b/client-sdks/reference/javascript-web.mdx @@ -459,12 +459,14 @@ export const db = new PowerSyncDatabase({ #### 3. In-Memory VFS -Since version 1.39.0 of the `@powersync/web` package, an in-memory database can be used with `WASQLiteVFS.InMemoryVFS`. -No data is persisted in this file system, meaning that local writes will be lost if they're not uploaded before the tab is closed -and all data will be resynced whenever a tab is opened. -This makes it unsuitable for apps that need to work offline, but it can be useful for development. The VFS is also faster than -all other single-threaded setups (both IndexedDB and OPFS except the write-ahead VFS), making it useful for online-only apps -with small data sizes and very frequent queries. +Since version 1.39.0 of the `@powersync/web` package, you can use an in-memory database with `WASQLiteVFS.InMemoryVFS`. +It runs queries faster than any other single-threaded VFS (both IndexedDB and OPFS, except the write-ahead VFS). + +No data is persisted: local writes are lost if they aren't uploaded before the tab is closed, and all data is resynced whenever +a tab is opened. This makes it unsuitable for apps that need to work offline, but a good fit for: + +- Development, where starting from a fresh database on every load makes it easy to reproduce issues from a clean state. +- Online-only apps with very frequent queries and a dataset small enough to re-sync every time the app is opened. When using in-memory databases in production scenarios, consider watching `SELECT * FROM ps_crud LIMIT 1` to detect whether outstanding From 8cd2aba5c7eaeae15b740949f7e633cea0095f36 Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Fri, 10 Jul 2026 10:53:37 +0200 Subject: [PATCH 5/5] Polish --- client-sdks/reference/javascript-web.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/client-sdks/reference/javascript-web.mdx b/client-sdks/reference/javascript-web.mdx index 01b89eb8..0b1f6f1f 100644 --- a/client-sdks/reference/javascript-web.mdx +++ b/client-sdks/reference/javascript-web.mdx @@ -466,7 +466,7 @@ No data is persisted: local writes are lost if they aren't uploaded before the t a tab is opened. This makes it unsuitable for apps that need to work offline, but a good fit for: - Development, where starting from a fresh database on every load makes it easy to reproduce issues from a clean state. -- Online-only apps with very frequent queries and a dataset small enough to re-sync every time the app is opened. +- Online-only apps with very frequent queries and small datasets. When using in-memory databases in production scenarios, consider watching `SELECT * FROM ps_crud LIMIT 1` to detect whether outstanding