fix(local): survive Windows libSQL handle linger during v1->v2 migration (#1209)

The v1->v2 data migration ran fsync/rename/remove on libSQL SQLite files whose native OS handle lingers past close() on Windows, crashing the daemon at boot with a fatal "Unknown error". POSIX never hits this, so it only reproduced on Windows (the v1.5.23 desktop/CLI startup regression). - fsyncFileIfExists opens read-write, since Windows FlushFileBuffers needs a writable handle (a read-only fd throws EPERM), and treats fsync as best-effort durability hardening. - remove of the source/staging file sets now retries EBUSY/EPERM the same way rename already did. - rename/remove retries force a GC pass first so libSQL's native finalizer releases the handle before the next attempt. Verified on a Windows VM: a seeded v1 database now migrates to v2 and the daemon announces ready.

Rhys Sullivan committed 4 months ago

Commit ffa4f701 parent b1d73bf2 files · +62 −14Browse files

Unified · Split

2 files

.changeset/windows-migration-handle-release.md +5 −0
apps/local/src/db/v1-v2-migration.ts +57 −14

.changeset/windows-migration-handle-release.md+5−0

@@ -0,0 +1,5 @@
	1	---
	2	"executor": patch
	3	---
	4
	5	Fix the desktop and CLI daemon crashing on first launch on Windows when a v1 local database is present. The v1 to v2 data migration performed file operations (fsync, rename, remove) on libSQL SQLite files whose native OS handles linger after close() on Windows, surfacing as a fatal "Unknown error" (EPERM on fsync of a read-only handle, EBUSY on rename/remove of just-closed files). POSIX is unaffected, so this only reproduced on Windows. The migration now opens files read-write for fsync (treating it as best-effort), retries removes the same way renames were already retried, and forces a GC pass on each retry so libSQL's native finalizer releases the handle before the next attempt. Fixes the v1.5.23 Windows startup regression.

apps/local/src/db/v1-v2-migration.ts+57−14

   }
 };
+// libSQL releases its OS file handle in a native finalizer, which on Windows
+// only runs on garbage collection and so lags client.close(). Forcing a GC
+// runs the finalizer, releasing the handle so a follow-up rename/rm succeeds.
+// No-op outside the Bun runtime (e.g. vitest on Node), where this is unneeded.
+const nudgeNativeHandleRelease = (): void => {
+  const bun = (globalThis as { Bun?: { gc?: (sync: boolean) => void } }).Bun;
+  bun?.gc?.(true);
+};
 // Windows reports EBUSY/EPERM on rename for a short window after a SQLite
 // handle closes (handle release lags the close call, and antivirus scanners
 // briefly lock the file). POSIX renames never hit this — retry with a short
-// backoff instead of failing the whole migration.
+// backoff, forcing handle release first, instead of failing the whole migration.
 const renameWithRetry = async (source: string, target: string): Promise<void> => {
   // ~8s total. 1.9s was not enough on Windows: libSQL's native handle and
   // antivirus scans hold the freshly-written db past close() (observed as an
     } catch (cause) {
       const code = (cause as NodeJS.ErrnoException).code;
       if ((code !== "EBUSY" && code !== "EPERM") || attempt >= delaysMs.length) throw cause;
+      nudgeNativeHandleRelease();
+      await new Promise((resolveDelay) => setTimeout(resolveDelay, delaysMs[attempt]));
+    }
+  }
+};
+// Same lingering-handle window as renameWithRetry: on Windows a libSQL file's
+// native handle (and antivirus locks) can briefly outlive close(), so removing
+// a just-closed source/staging db throws EBUSY/EPERM. POSIX never hits this.
+const rmWithRetry = async (path: string): Promise<void> => {
+  const delaysMs = [50, 100, 250, 500, 1000, 2000, 4000];
+  for (let attempt = 0; ; attempt++) {
+    try {
+      fs.rmSync(path, { force: true });
+      return;
+    } catch (cause) {
+      const code = (cause as NodeJS.ErrnoException).code;
+      if ((code !== "EBUSY" && code !== "EPERM") || attempt >= delaysMs.length) throw cause;
+      nudgeNativeHandleRelease();
       await new Promise((resolveDelay) => setTimeout(resolveDelay, delaysMs[attempt]));
     }
   }
 };
+const removeSqliteFileSetWithRetry = async (path: string): Promise<void> => {
+  for (const suffix of fileSetSuffixes) await rmWithRetry(`${path}${suffix}`);
+};
 const fsyncFileIfExists = (path: string): void => {
   if (!fs.existsSync(path)) return;
-  const fd = fs.openSync(path, "r");
+  // Windows FlushFileBuffers requires a writable handle, so fsync on a
+  // read-only ("r") fd throws EPERM and would crash the v1->v2 migration at
+  // boot. Open read-write for the flush, and treat fsync as best-effort
+  // durability hardening (the rename/copy already wrote the bytes) so a
+  // platform or filesystem that refuses the flush does not fail the migration.
+  let fd: number;
+  try {
+    fd = fs.openSync(path, "r+");
+  } catch {
+    return;
+  }
   try {
     fs.fsyncSync(fd);
+  } catch {
+    // best-effort: some platforms/filesystems refuse fsync on certain handles
   } finally {
     fs.closeSync(fd);
   }
       await renameWithRetry(`${source}${suffix}`, `${target}${suffix}`);
       fsyncDirectory(dirname(target));
     } else {
-      fs.rmSync(`${target}${suffix}`, { force: true });
+      await rmWithRetry(`${target}${suffix}`);
     }
   }
 };
     if (!fs.existsSync(from)) continue;
     const to = `${target}${suffix}`;
     if (fs.existsSync(to)) {
-      fs.rmSync(from, { force: true });
+      await rmWithRetry(from);
     } else {
       await renameWithRetry(from, to);
       fsyncDirectory(dirname(to));
     await pauseMigrationForTest("staging-consumed");
   }
   await writeMigrationJournal(journalPath, { ...journal, phase: "committed" });
-  removeSqliteFileSet(journal.normalizedSource);
+  await removeSqliteFileSetWithRetry(journal.normalizedSource);
-  removeSqliteFileSet(journal.staging);
+  await removeSqliteFileSetWithRetry(journal.staging);
   await cleanupSecretBackups(journal);
   removeMigrationJournal(journalPath);
 };
   const { journal } = journalRead;
   if (journal.phase === "building") {
-    removeSqliteFileSet(journal.normalizedSource);
+    await removeSqliteFileSetWithRetry(journal.normalizedSource);
-    removeSqliteFileSet(journal.staging);
+    await removeSqliteFileSetWithRetry(journal.staging);
     await restoreAuthFromJournal(journal);
     await cleanupSecretBackups(journal);
     removeMigrationJournal(journalPath);
     return "recovered";
   }
-  removeSqliteFileSet(journal.normalizedSource);
+  await removeSqliteFileSetWithRetry(journal.normalizedSource);
-  removeSqliteFileSet(journal.staging);
+  await removeSqliteFileSetWithRetry(journal.staging);
   await cleanupSecretBackups(journal);
   removeMigrationJournal(journalPath);
   return "recovered";
     // WAL/SHM sidecars before journaling the staged DB as complete; otherwise a
     // crash mid-sidecar move would make staging appear present after the base DB
     // had already been installed.
-    for (const suffix of ["-wal", "-shm"] as const)
+    for (const suffix of ["-wal", "-shm"] as const) await rmWithRetry(`${stagingPath}${suffix}`);
-      fs.rmSync(`${stagingPath}${suffix}`, { force: true });
     fsyncDirectory(dirname(stagingPath));
     await writeMigrationJournal(journalPath, { ...journal, phase: "built" });
     await pauseMigrationForTest("built");
         await restoreAuthFromJournal(journal);
         await cleanupSecretBackups(journal);
       }
-      if (normalizedSourcePath) removeSqliteFileSet(normalizedSourcePath);
+      if (normalizedSourcePath) await removeSqliteFileSetWithRetry(normalizedSourcePath);
-      if (stagingPath) removeSqliteFileSet(stagingPath);
+      if (stagingPath) await removeSqliteFileSetWithRetry(stagingPath);
       removeMigrationJournal(journalPath);
     }
     throw cause;