opfs-sahpool: failed installOpfsSAHPoolVfs() can delete all existing databases in the pool
(1) By Daniel Steigerwald (steida) on 2026-09-26 11:26:21 [source]
When pool initialization fails, installOpfsSAHPoolVfs() runs:
.catch(async (e) => {
await thePool.removeVfs().catch(() => {});
throw e;
});
removeVfs() recursively removes .opaque, which holds every database in the
pool, and the VFS directory. So a failure in acquireAccessHandles(), for
example one pool file that cannot be opened, can delete all existing databases.
Checked with @sqlite.org/sqlite-wasm 3.53.4-build1; trunk has the same handler:
https://github.com/sqlite/sqlite/blob/ac70487e12adc0633dda9ef1598a6803d819f614/ext/wasm/api/sqlite3-vfs-opfs-sahpool.c-pp.js#L1454-L1456
In sqlite/sqlite-wasm#79 this cleanup was defended as leaving the VFS storage in a known state after an init failure (https://github.com/sqlite/sqlite-wasm/issues/79#issuecomment-2222537109). The reproduction below shows the cost: previously valid databases are deleted. An acquisition failure does not establish that they are corrupt, and such failures can be temporary. One possible cause, also noted in #79, is a reloaded page whose previous instance has not released its OPFS handles yet. Leaving the VFS unregistered with its handles closed would preserve the existing files for retry or recovery, without assuming that the databases are valid.
Remaining open handles may prevent complete removal, but they are not a reliable safeguard: they can be released before cleanup runs, and recursive removal can partially succeed (the File System Standard notes that it "can fail non-atomically": https://fs.spec.whatwg.org/#api-filesystemdirectoryhandle-removeentry). In the injected failure below, cleanup succeeds and deletes the pool.
Reproduction: three workers run sequentially on one origin, each initializing
sqlite3 with sqlite3InitModule() and each terminated before the next starts.
Worker 1 closes its database and pauses the VFS before termination. The failure
in Worker 2 is injected while no other worker is running, so this reproduction
does not involve concurrent access to the pool.
// Worker 1: create a database.
const pool = await sqlite3.installOpfsSAHPoolVfs({ name: "repro" });
const db = new pool.OpfsSAHPoolDb("/test.db");
db.exec("create table t(x); insert into t values ('important');");
db.close();
await pool.pauseVfs();
// Worker 2: one pool file fails to open once. The 200 ms delay lets the other
// acquisitions finish first, so their handles do not block the cleanup; the
// outcome depends on that timing.
const createSyncAccessHandle =
FileSystemFileHandle.prototype.createSyncAccessHandle;
let failed = false;
FileSystemFileHandle.prototype.createSyncAccessHandle = function (...args) {
if (!failed && !this.name.startsWith(".opfs-sahpool-sync-check")) {
failed = true;
return new Promise((_, reject) =>
setTimeout(() => reject(new DOMException("simulated", "UnknownError")), 200),
);
}
return createSyncAccessHandle.apply(this, args);
};
await sqlite3.installOpfsSAHPoolVfs({ name: "repro" }).catch(console.error);
// The OPFS root no longer contains ".repro".
// Worker 3: open the database again.
const pool3 = await sqlite3.installOpfsSAHPoolVfs({ name: "repro" });
const db3 = new pool3.OpfsSAHPoolDb("/test.db");
db3.selectValues("select name from sqlite_master"); // [] (["t"] without worker 2)
Same result in Chromium, Firefox and WebKit.
Suggestion: on initialization failure, let pending acquisitions settle, close
the acquired handles, unregister the VFS and rethrow, leaving the files in
place. Deleting storage would stay explicit, through removeVfs() or
clearOnInit.
A related detail from reading the code: acquireAccessHandles() opens all
files with Promise.all, so a sibling acquisition can complete after both
cleanup passes and leave a handle open. Settling all acquisitions before
releasing, as above, covers that too.
Daniel Steigerwald (Evolu)
(2) By Stephan Beal (stephan) on 2026-09-26 11:38:44 in reply to 1 [link] [source]
When pool initialization fails, installOpfsSAHPoolVfs() runs:...
As you later point out, that is intentional:
in sqlite/sqlite-wasm#79 this cleanup was defended as leaving the VFS storage in a known state after an init failure
And i still stand by that. As your analysis says:
An acquisition failure does not establish that they are corrupt, and such failures can be temporary.
i.e. we just don't know what their state is except that we cannot work with it.
Suggestion: on initialization failure, let pending acquisitions settle, close the acquired handles, unregister the VFS and rethrow, leaving the files in place. Deleting storage would stay explicit, through removeVfs() or clearOnInit.
i will consider that closely but am not currently convinced that it's the right thing to do. If the storage is broken and we do not clean it up then clients can hypothetically get into a state where they cannot use the VFS again until they call removeVfs() to clean up any lingering damage which is triggering the ostensible/assumed storage problem. Given that nobody has yet fussed about the current behavior causing them grief, but the potential for that happening if their VFS can't register because a prior failure did not wipe the slate clean, my current thinking is that the status quo is the safer way to go. i'm open to objecting views or the thoughtful discounting of mine, though.
(3) By Daniel Steigerwald (steida) on 2026-09-26 12:33:14 in reply to 2 [link] [source]
Thanks for considering it. I understand the concern about an application remaining unable to initialize until its storage is explicitly reset.
For a local-first application, however, the pool may contain the only copy of unsynced user data. Preserving files after failure leaves the application the option to retry, attempt recovery, or explicitly delete the pool if that is appropriate. Automatic deletion removes those options before the application receives the rejection. Preservation does not guarantee recovery, but deletion can make recovery impossible.
Lock contention is one concrete example where failure does not establish
corruption: the File System Standard
requires createSyncAccessHandle() to reject with NoModificationAllowedError
when it cannot obtain the exclusive lock. This is an expected failure mode of
the API.
I cannot quantify how often the destructive cleanup causes loss in production,
but I would not read the absence of reports as evidence that it is rare: the
deletion itself is not reported. The rejection carries the original
acquisition error, and removeVfs() logs nothing when it succeeds, so the
application sees an initialization error followed by an empty pool. From the
application's side, that looks much like storage the browser evicted or the
user cleared. More fundamentally, the library cannot know whether the existing
data is disposable or reconstructible.
Would you consider preserving files on initialization failure, or providing an explicit opt-in to that behavior if changing the default is undesirable? Applications that prefer automatic reset could retain that policy, while applications holding irreplaceable data could choose preservation.
To make this easier to evaluate, below is a patch against trunk (ac70487e12) that adds such an opt-in and fixes a related handle leak. It changes three things:
acquireAccessHandles()waits for every acquisition to settle before it releases the handles. Today, when one file fails early,Promise.all()rejects while the other acquisitions are still pending, and they complete after the cleanup has run. In our test, where the first file failed immediately, the failed context kept the other five pool files locked, so evenforceReinitIfPreviouslyFailedcould not retry in that context: it failed withNoModificationAllowedError(InvalidStateErrorin WebKit) on its own leftover handles. Note that those leaked handles also blocked the recursive deletion by accident; in that test the pool survived for that reason. With the leak fixed, the default cleanup can delete pools it previously failed to delete, which is one more reason to consider making preservation the default.A new option,
preserveOnInitFailure(defaultfalse, so the default deletion policy remains unchanged). When it is set, a failed initialization calls a newunregisterVfs()instead ofremoveVfs(). It unregisters and disposes the VFS and releases the handles without deleting the pool. It does not undo changes initialization already made, such as those ofclearOnInit. Unregistering is needed because the pool constructor already registers the VFS, so without it a retry would fail with "VFS name is already registered". This also covers a failure before the pool directory is opened, whereremoveVfs()returns early and leaves the VFS registered.The option is documented next to
forceReinitIfPreviouslyFailed. Making preservation the default would only mean changing the option's default.
--- a/ext/wasm/api/sqlite3-vfs-opfs-sahpool.c-pp.js
+++ b/ext/wasm/api/sqlite3-vfs-opfs-sahpool.c-pp.js
@@ -151,7 +151,8 @@
/* Logging verbosity 3+ == everything, 2 == warnings+errors, 1 ==
errors only. */
verbosity: 2,
- forceReinitIfPreviouslyFailed: false
+ forceReinitIfPreviouslyFailed: false,
+ preserveOnInitFailure: false
});
/** Logging routines, from most to least serious. */
@@ -613,8 +614,8 @@
throws, this.$error will contain the corresponding Error
object.
- If it throws, it releases any SAHs which it may have
- acquired before the exception was thrown, leaving the VFS in a
+ If it throws, it waits for every pending acquisition to settle,
+ then releases all SAHs it acquired, leaving the VFS in a
well-defined but unusable state.
If clearFiles is true, the client-stored state of each file is
@@ -628,27 +629,29 @@
files.push([name,h]);
}
}
- return Promise.all(files.map(async([name,h])=>{
- try{
- const ah = await h.createSyncAccessHandle()
- this.#mapSAHToName.set(ah, name);
- if(clearFiles){
- ah.truncate(HEADER_OFFSET_DATA);
- this.setAssociatedPath(ah, '', 0);
+ /* Settle every acquisition before releasing, so that an SAH
+ acquired after a sibling failed is released too. */
+ const results = await Promise.allSettled(files.map(async([name,h])=>{
+ const ah = await h.createSyncAccessHandle()
+ this.#mapSAHToName.set(ah, name);
+ if(clearFiles){
+ ah.truncate(HEADER_OFFSET_DATA);
+ this.setAssociatedPath(ah, '', 0);
+ }else{
+ const path = this.getAssociatedPath(ah);
+ if(path){
+ this.#mapFilenameToSAH.set(path, ah);
}else{
- const path = this.getAssociatedPath(ah);
- if(path){
- this.#mapFilenameToSAH.set(path, ah);
- }else{
- this.#availableSAH.add(ah);
- }
+ this.#availableSAH.add(ah);
}
- }catch(e){
- this.storeErr(e);
- this.releaseAccessHandles();
- throw e;
}
}));
+ const failure = results.find((r)=>'rejected'===r.status);
+ if(failure){
+ this.storeErr(failure.reason);
+ this.releaseAccessHandles();
+ throw failure.reason;
+ }
}
/**
@@ -922,6 +925,18 @@
/*otherwise ignored - there is no recovery strategy*/
}
return true;
+ }
+
+ /**
+ Unregisters and disposes this VFS and releases all of its SAHs
+ without deleting its files. Used when initialization fails and
+ the preserveOnInitFailure option is set.
+ */
+ unregisterVfs(){
+ if(!this.#cVfs.pointer) return;
+ capi.sqlite3_vfs_unregister(this.#cVfs.pointer);
+ this.#cVfs.dispose();
+ this.releaseAccessHandles();
}
@@ -1217,6 +1232,15 @@
initialize a second time instead of returning the cached
failure. See discussion at:
<https://github.com/sqlite/sqlite-wasm/issues/79>
+
+ - `preserveOnInitFailure`: (default=`false`) If truthy,
+ initialization failure unregisters and disposes the VFS and
+ releases acquired handles without recursively deleting its
+ storage. This does not undo changes already made during
+ initialization, including `clearOnInit`. Otherwise,
+ initialization failure invokes removeVfs(), which attempts to
+ delete the pool. Retrying a cached initialization failure
+ requires `forceReinitIfPreviouslyFailed`.
Peculiarities of this VFS vis a vis other SQLite VFSes:
@@ -1452,7 +1476,11 @@
thePool.log("VFS initialized.");
return poolUtil;
}).catch(async (e)=>{
- await thePool.removeVfs().catch(()=>{});
+ if( options.preserveOnInitFailure ){
+ thePool.unregisterVfs();
+ }else{
+ await thePool.removeVfs().catch(()=>{});
+ }
throw e;
});
}).catch((err)=>{
I applied the equivalent change to the 3.53.4-build1 npm build and ran it in
Chromium, Firefox and WebKit. With preserveOnInitFailure: true, the injected
failure from the reproduction leaves the stored rows intact, a retry in the
same worker with forceReinitIfPreviouslyFailed succeeds and reads them, and
after an immediate failure of the first file every pool file can be opened
again. The default cleanup still deletes the pool when the option is not set.
(4) By Stephan Beal (stephan) on 2026-09-26 12:45:09 in reply to 3 [link] [source]
+ preserveOnInitFailure: false
Yeah, that's a nice compromise. Consider this to be next in the JS TODO queue.
(5.2) By Stephan Beal (stephan) on 2026-09-29 09:03:26 edited from 5.1 in reply to 3 [link] [source]
+ unregisterVfs(){
Daniel, does your use case need this to be public? My instinct is to move this bit into the private pieces, but if you have a concrete need for this then it can remain public.
Edit: the current draft is at src:/timeline?r=opfs-sahpool-forum-5664cd4b, pending only the decision on whether unregisterVfs() needs to be made public. It is currently private. A snapshot version zip is at wasm:/uv/snapshot.html.
(6) By Daniel Steigerwald (steida) on 2026-09-29 12:52:24 in reply to 5.2 [link] [source]
Private is fine. Evolu releases the pool's handles with pauseVfs() when it closes a database and reuses the pool with unpauseVfs(), so it never unregisters a pool itself. With preserveOnInitFailure, it will retry a failed initialization with forceReinitIfPreviouslyFailed. The draft matches the patch I tested. Thanks!