@rivetkit/sqlite-vfs 2.1.5 → 2.1.6-rc.1

package/dist/tsup/index.js

@@ -40,6 +40,14 @@ function getChunkKey(fileTag, chunkIndex) {
   return key;
 }
 
+// src/generated/empty-db-page.ts
+var HEADER_PREFIX = new Uint8Array([83, 81, 76, 105, 116, 101, 32, 102, 111, 114, 109, 97, 116, 32, 51, 0, 16, 0, 1, 1, 0, 64, 32, 32, 0, 0, 0, 3, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 3, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 3, 0, 46, 138, 17, 13, 0, 0, 0, 0, 16, 0, 0]);
+var EMPTY_DB_PAGE = (() => {
+  const page = new Uint8Array(4096);
+  page.set(HEADER_PREFIX);
+  return page;
+})();
+
 // schemas/file-meta/versioned.ts
 import { createVersionedDataHandler } from "vbare";
 
@@ -103,6 +111,11 @@ var MAX_CHUNK_INDEX = 4294967295;
 var MAX_FILE_SIZE_BYTES = (MAX_CHUNK_INDEX + 1) * CHUNK_SIZE;
 var MAX_FILE_SIZE_HI32 = Math.floor(MAX_FILE_SIZE_BYTES / UINT32_SIZE);
 var MAX_FILE_SIZE_LO32 = MAX_FILE_SIZE_BYTES % UINT32_SIZE;
+var KV_MAX_BATCH_KEYS = 128;
+var SQLITE_IOCAP_BATCH_ATOMIC = 16384;
+var SQLITE_FCNTL_BEGIN_ATOMIC_WRITE = 31;
+var SQLITE_FCNTL_COMMIT_ATOMIC_WRITE = 32;
+var SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE = 33;
 var SQLITE_ASYNC_METHODS = /* @__PURE__ */ new Set([
   "xOpen",
   "xClose",
@@ -112,7 +125,8 @@ var SQLITE_ASYNC_METHODS = /* @__PURE__ */ new Set([
   "xSync",
   "xFileSize",
   "xDelete",
-  "xAccess"
+  "xAccess",
+  "xFileControl"
 ]);
 function isSqliteEsmFactory(value) {
   return typeof value === "function";
@@ -124,18 +138,34 @@ function isSQLiteModule(value) {
   const candidate = value;
   return typeof candidate.UTF8ToString === "function" && candidate.HEAPU8 instanceof Uint8Array;
 }
-async function loadSqliteRuntime() {
-  const specifier = ["@rivetkit/sqlite", "dist", "wa-sqlite-async.mjs"].join("/");
+async function loadSqliteRuntime(wasmModule) {
+  const specifier = ["@rivetkit/sqlite", "dist", "wa-sqlite-async.mjs"].join(
+    "/"
+  );
   const sqliteModule = await import(specifier);
   if (!isSqliteEsmFactory(sqliteModule.default)) {
     throw new Error("Invalid SQLite ESM factory export");
   }
   const sqliteEsmFactory = sqliteModule.default;
-  const require2 = createRequire(import.meta.url);
-  const sqliteDistPath = "@rivetkit/sqlite/dist/";
-  const wasmPath = require2.resolve(sqliteDistPath + "wa-sqlite-async.wasm");
-  const wasmBinary = readFileSync(wasmPath);
-  const module = await sqliteEsmFactory({ wasmBinary });
+  let module;
+  if (wasmModule) {
+    module = await sqliteEsmFactory({
+      instantiateWasm(imports, receiveInstance) {
+        WebAssembly.instantiate(wasmModule, imports).then((instance) => {
+          receiveInstance(instance);
+        });
+        return {};
+      }
+    });
+  } else {
+    const require2 = createRequire(import.meta.url);
+    const sqliteDistPath = "@rivetkit/sqlite/dist/";
+    const wasmPath = require2.resolve(
+      sqliteDistPath + "wa-sqlite-async.wasm"
+    );
+    const wasmBinary = readFileSync(wasmPath);
+    module = await sqliteEsmFactory({ wasmBinary });
+  }
   if (!isSQLiteModule(module)) {
     throw new Error("Invalid SQLite runtime module");
   }
@@ -189,6 +219,7 @@ var Database = class {
   #fileName;
   #onClose;
   #sqliteMutex;
+  #closed = false;
   constructor(sqlite3, handle, fileName, onClose, sqliteMutex) {
     this.#sqlite3 = sqlite3;
     this.#handle = handle;
@@ -213,7 +244,10 @@ var Database = class {
    */
   async run(sql, params) {
     await this.#sqliteMutex.run(async () => {
-      for await (const stmt of this.#sqlite3.statements(this.#handle, sql)) {
+      for await (const stmt of this.#sqlite3.statements(
+        this.#handle,
+        sql
+      )) {
         if (params) {
           this.#sqlite3.bind_collection(stmt, params);
         }
@@ -232,7 +266,10 @@ var Database = class {
     return this.#sqliteMutex.run(async () => {
       const rows = [];
       let columns = [];
-      for await (const stmt of this.#sqlite3.statements(this.#handle, sql)) {
+      for await (const stmt of this.#sqlite3.statements(
+        this.#handle,
+        sql
+      )) {
         if (params) {
           this.#sqlite3.bind_collection(stmt, params);
         }
@@ -250,10 +287,20 @@ var Database = class {
    * Close the database
    */
   async close() {
+    if (this.#closed) {
+      return;
+    }
+    this.#closed = true;
     await this.#sqliteMutex.run(async () => {
       await this.#sqlite3.close(this.#handle);
     });
-    this.#onClose();
+    await this.#onClose();
+  }
+  /**
+   * Get the database file name
+   */
+  get fileName() {
+    return this.#fileName;
   }
   /**
    * Get the raw @rivetkit/sqlite API (for advanced usage)
@@ -276,8 +323,11 @@ var SqliteVfs = class {
   #sqliteMutex = new AsyncMutex();
   #instanceId;
   #destroyed = false;
-  constructor() {
+  #openDatabases = /* @__PURE__ */ new Set();
+  #wasmModule;
+  constructor(wasmModule) {
     this.#instanceId = crypto.randomUUID().replace(/-/g, "").slice(0, 8);
+    this.#wasmModule = wasmModule;
   }
   /**
    * Initialize @rivetkit/sqlite and VFS (called once per instance)
@@ -291,7 +341,9 @@ var SqliteVfs = class {
     }
     if (!this.#initPromise) {
       this.#initPromise = (async () => {
-        const { sqlite3, module } = await loadSqliteRuntime();
+        const { sqlite3, module } = await loadSqliteRuntime(
+          this.#wasmModule
+        );
         if (this.#destroyed) {
           return;
         }
@@ -324,6 +376,13 @@ var SqliteVfs = class {
     }
     await this.#openMutex.acquire();
     try {
+      for (const db2 of this.#openDatabases) {
+        if (db2.fileName === fileName) {
+          throw new Error(
+            `SqliteVfs: fileName "${fileName}" is already open on this instance`
+          );
+        }
+      }
       await this.#ensureInitialized();
       if (!this.#sqlite3 || !this.#sqliteSystem) {
         throw new Error("Failed to initialize SQLite");
@@ -338,20 +397,79 @@ var SqliteVfs = class {
           sqliteSystem.name
         )
       );
-      const onClose = () => {
-        sqliteSystem.unregisterFile(fileName);
+      await this.#sqliteMutex.run(async () => {
+        await sqlite3.exec(db, "PRAGMA page_size = 4096");
+        await sqlite3.exec(db, "PRAGMA journal_mode = DELETE");
+        await sqlite3.exec(db, "PRAGMA synchronous = NORMAL");
+        await sqlite3.exec(db, "PRAGMA temp_store = MEMORY");
+        await sqlite3.exec(db, "PRAGMA auto_vacuum = NONE");
+        await sqlite3.exec(db, "PRAGMA locking_mode = EXCLUSIVE");
+      });
+      const onClose = async () => {
+        this.#openDatabases.delete(database);
+        await this.#openMutex.run(async () => {
+          sqliteSystem.unregisterFile(fileName);
+        });
       };
-      return new Database(
+      const database = new Database(
         sqlite3,
         db,
         fileName,
         onClose,
         this.#sqliteMutex
       );
+      this.#openDatabases.add(database);
+      return database;
     } finally {
       this.#openMutex.release();
     }
   }
+  /**
+   * Force-close all Database handles whose fileName exactly matches the
+   * given name. Snapshots the set to an array before iterating to avoid
+   * mutation during async iteration.
+   *
+   * Uses exact file name match because short names are numeric strings
+   * ('0', '1', ..., '10', '11', ...) and a prefix match like
+   * startsWith('1') would incorrectly match '10', '11', etc., causing
+   * cross-actor corruption. Sidecar files (-journal, -wal, -shm) are not
+   * tracked as separate Database handles, so prefix matching for sidecars
+   * is not needed.
+   */
+  async forceCloseByFileName(fileName) {
+    const snapshot = [...this.#openDatabases];
+    let allSucceeded = true;
+    for (const db of snapshot) {
+      if (db.fileName === fileName) {
+        try {
+          await db.close();
+        } catch {
+          allSucceeded = false;
+          this.#openDatabases.delete(db);
+          const sqliteSystem = this.#sqliteSystem;
+          if (sqliteSystem) {
+            await this.#openMutex.run(async () => {
+              sqliteSystem.unregisterFile(db.fileName);
+            });
+          }
+        }
+      }
+    }
+    return { allSucceeded };
+  }
+  /**
+   * Force-close all open Database handles. Best-effort: errors are
+   * swallowed so this is safe to call during instance teardown.
+   */
+  async forceCloseAll() {
+    const snapshot = [...this.#openDatabases];
+    for (const db of snapshot) {
+      try {
+        await db.close();
+      } catch {
+      }
+    }
+  }
   /**
    * Tears down this VFS instance and releases internal references.
    */
@@ -385,8 +503,7 @@ var SqliteSystem = class {
   name;
   mxPathName = SQLITE_MAX_PATHNAME_BYTES;
   mxPathname = SQLITE_MAX_PATHNAME_BYTES;
-  #mainFileName = null;
-  #mainFileOptions = null;
+  #registeredFiles = /* @__PURE__ */ new Map();
   #openFiles = /* @__PURE__ */ new Map();
   #sqlite3;
   #module;
@@ -401,8 +518,7 @@ var SqliteSystem = class {
   }
   async close() {
     this.#openFiles.clear();
-    this.#mainFileName = null;
-    this.#mainFileOptions = null;
+    this.#registeredFiles.clear();
   }
   isReady() {
     return true;
@@ -417,48 +533,45 @@ var SqliteSystem = class {
     this.#sqlite3.vfs_register(this, false);
   }
   /**
-   * Registers a file with its KV options (before opening)
+   * Registers a file with its KV options (before opening).
    */
   registerFile(fileName, options) {
-    if (!this.#mainFileName) {
-      this.#mainFileName = fileName;
-      this.#mainFileOptions = options;
-      return;
-    }
-    if (this.#mainFileName !== fileName) {
-      throw new Error(
-        `SqliteSystem is actor-scoped and expects one main file. Got ${fileName}, expected ${this.#mainFileName}.`
-      );
-    }
-    this.#mainFileOptions = options;
+    this.#registeredFiles.set(fileName, options);
   }
   /**
-   * Unregisters a file's KV options (after closing)
+   * Unregisters a file's KV options (after closing).
    */
   unregisterFile(fileName) {
-    if (this.#mainFileName === fileName) {
-      this.#mainFileName = null;
-      this.#mainFileOptions = null;
-    }
+    this.#registeredFiles.delete(fileName);
   }
   /**
-   * Resolve file path to the actor's main DB file or known SQLite sidecars.
+   * Resolve file path to a registered database file or one of its SQLite
+   * sidecars (-journal, -wal, -shm). File tags are reused across files
+   * because each file's KvVfsOptions routes to a separate KV namespace.
    */
   #resolveFile(path) {
-    if (!this.#mainFileName || !this.#mainFileOptions) {
-      return null;
-    }
-    if (path === this.#mainFileName) {
-      return { options: this.#mainFileOptions, fileTag: FILE_TAG_MAIN };
-    }
-    if (path === `${this.#mainFileName}-journal`) {
-      return { options: this.#mainFileOptions, fileTag: FILE_TAG_JOURNAL };
+    const directOptions = this.#registeredFiles.get(path);
+    if (directOptions) {
+      return { options: directOptions, fileTag: FILE_TAG_MAIN };
     }
-    if (path === `${this.#mainFileName}-wal`) {
-      return { options: this.#mainFileOptions, fileTag: FILE_TAG_WAL };
-    }
-    if (path === `${this.#mainFileName}-shm`) {
-      return { options: this.#mainFileOptions, fileTag: FILE_TAG_SHM };
+    if (path.endsWith("-journal")) {
+      const baseName = path.slice(0, -8);
+      const options = this.#registeredFiles.get(baseName);
+      if (options) {
+        return { options, fileTag: FILE_TAG_JOURNAL };
+      }
+    } else if (path.endsWith("-wal")) {
+      const baseName = path.slice(0, -4);
+      const options = this.#registeredFiles.get(baseName);
+      if (options) {
+        return { options, fileTag: FILE_TAG_WAL };
+      }
+    } else if (path.endsWith("-shm")) {
+      const baseName = path.slice(0, -4);
+      const options = this.#registeredFiles.get(baseName);
+      if (options) {
+        return { options, fileTag: FILE_TAG_SHM };
+      }
     }
     return null;
   }
@@ -467,11 +580,12 @@ var SqliteSystem = class {
     if (resolved) {
       return resolved;
     }
-    if (!this.#mainFileName) {
+    if (this.#registeredFiles.size === 0) {
       throw new Error(`No KV options registered for file: ${path}`);
     }
+    const registered = Array.from(this.#registeredFiles.keys()).join(", ");
     throw new Error(
-      `Unsupported SQLite file path ${path}. Expected one of ${this.#mainFileName}, ${this.#mainFileName}-journal, ${this.#mainFileName}-wal, ${this.#mainFileName}-shm.`
+      `Unsupported SQLite file path ${path}. Registered base names: ${registered}.`
     );
   }
   #chunkKey(file, chunkIndex) {
@@ -484,7 +598,12 @@ var SqliteSystem = class {
     }
     const { options, fileTag } = this.#resolveFileOrThrow(path);
     const metaKey = getMetaKey(fileTag);
-    const sizeData = await options.get(metaKey);
+    let sizeData;
+    try {
+      sizeData = await options.get(metaKey);
+    } catch {
+      return VFS.SQLITE_CANTOPEN;
+    }
     let size;
     if (sizeData) {
       size = decodeFileMeta2(sizeData);
@@ -492,8 +611,25 @@ var SqliteSystem = class {
         return VFS.SQLITE_IOERR;
       }
     } else if (flags & VFS.SQLITE_OPEN_CREATE) {
-      size = 0;
-      await options.put(metaKey, encodeFileMeta2(size));
+      if (fileTag === FILE_TAG_MAIN) {
+        const chunkKey = getChunkKey(fileTag, 0);
+        size = EMPTY_DB_PAGE.length;
+        try {
+          await options.putBatch([
+            [chunkKey, EMPTY_DB_PAGE],
+            [metaKey, encodeFileMeta2(size)]
+          ]);
+        } catch {
+          return VFS.SQLITE_CANTOPEN;
+        }
+      } else {
+        size = 0;
+        try {
+          await options.put(metaKey, encodeFileMeta2(size));
+        } catch {
+          return VFS.SQLITE_CANTOPEN;
+        }
+      }
     } else {
       return VFS.SQLITE_CANTOPEN;
     }
@@ -504,7 +640,10 @@ var SqliteSystem = class {
       size,
       metaDirty: false,
       flags,
-      options
+      options,
+      batchMode: false,
+      dirtyBuffer: null,
+      savedFileSize: 0
     });
     this.#writeInt32(pOutFlags, flags);
     return VFS.SQLITE_OK;
@@ -514,14 +653,19 @@ var SqliteSystem = class {
     if (!file) {
       return VFS.SQLITE_OK;
     }
-    if (file.flags & VFS.SQLITE_OPEN_DELETEONCLOSE) {
-      await this.#delete(file.path);
+    try {
+      if (file.flags & VFS.SQLITE_OPEN_DELETEONCLOSE) {
+        await this.#delete(file.path);
+      } else if (file.metaDirty) {
+        await file.options.put(
+          file.metaKey,
+          encodeFileMeta2(file.size)
+        );
+        file.metaDirty = false;
+      }
+    } catch {
       this.#openFiles.delete(fileId);
-      return VFS.SQLITE_OK;
-    }
-    if (file.metaDirty) {
-      await file.options.put(file.metaKey, encodeFileMeta2(file.size));
-      file.metaDirty = false;
+      return VFS.SQLITE_IOERR;
     }
     this.#openFiles.delete(fileId);
     return VFS.SQLITE_OK;
@@ -534,7 +678,7 @@ var SqliteSystem = class {
     if (!file) {
       return VFS.SQLITE_IOERR_READ;
     }
-    const data = this.#module.HEAPU8.subarray(pData, pData + iAmt);
+    let data = this.#module.HEAPU8.subarray(pData, pData + iAmt);
     const options = file.options;
     const requestedLength = iAmt;
     const iOffset = delegalize(iOffsetLo, iOffsetHi);
@@ -547,14 +691,31 @@ var SqliteSystem = class {
       return VFS.SQLITE_IOERR_SHORT_READ;
     }
     const startChunk = Math.floor(iOffset / CHUNK_SIZE);
-    const endChunk = Math.floor((iOffset + requestedLength - 1) / CHUNK_SIZE);
+    const endChunk = Math.floor(
+      (iOffset + requestedLength - 1) / CHUNK_SIZE
+    );
     const chunkKeys = [];
+    const chunkIndexToBuffered = /* @__PURE__ */ new Map();
     for (let i = startChunk; i <= endChunk; i++) {
+      if (file.batchMode && file.dirtyBuffer) {
+        const buffered = file.dirtyBuffer.get(i);
+        if (buffered) {
+          chunkIndexToBuffered.set(i, buffered);
+          continue;
+        }
+      }
       chunkKeys.push(this.#chunkKey(file, i));
     }
-    const chunks = await options.getBatch(chunkKeys);
+    let kvChunks;
+    try {
+      kvChunks = chunkKeys.length > 0 ? await options.getBatch(chunkKeys) : [];
+    } catch {
+      return VFS.SQLITE_IOERR_READ;
+    }
+    data = this.#module.HEAPU8.subarray(pData, pData + iAmt);
+    let kvIdx = 0;
     for (let i = startChunk; i <= endChunk; i++) {
-      const chunkData = chunks[i - startChunk];
+      const chunkData = chunkIndexToBuffered.get(i) ?? kvChunks[kvIdx++];
       const chunkOffset = i * CHUNK_SIZE;
       const readStart = Math.max(0, iOffset - chunkOffset);
       const readEnd = Math.min(
@@ -566,7 +727,10 @@ var SqliteSystem = class {
         const sourceEnd = Math.min(readEnd, chunkData.length);
         const destStart = chunkOffset + readStart - iOffset;
         if (sourceEnd > sourceStart) {
-          data.set(chunkData.subarray(sourceStart, sourceEnd), destStart);
+          data.set(
+            chunkData.subarray(sourceStart, sourceEnd),
+            destStart
+          );
         }
         if (sourceEnd < readEnd) {
           const zeroStart = destStart + (sourceEnd - sourceStart);
@@ -594,7 +758,7 @@ var SqliteSystem = class {
     if (!file) {
       return VFS.SQLITE_IOERR_WRITE;
     }
-    const data = this.#module.HEAPU8.subarray(pData, pData + iAmt);
+    let data = this.#module.HEAPU8.subarray(pData, pData + iAmt);
     const iOffset = delegalize(iOffsetLo, iOffsetHi);
     if (iOffset < 0) {
       return VFS.SQLITE_IOERR_WRITE;
@@ -607,6 +771,26 @@ var SqliteSystem = class {
     }
     const startChunk = Math.floor(iOffset / CHUNK_SIZE);
     const endChunk = Math.floor((iOffset + writeLength - 1) / CHUNK_SIZE);
+    if (file.batchMode && file.dirtyBuffer) {
+      for (let i = startChunk; i <= endChunk; i++) {
+        const chunkOffset = i * CHUNK_SIZE;
+        const sourceStart = Math.max(0, chunkOffset - iOffset);
+        const sourceEnd = Math.min(
+          writeLength,
+          chunkOffset + CHUNK_SIZE - iOffset
+        );
+        file.dirtyBuffer.set(
+          i,
+          data.subarray(sourceStart, sourceEnd).slice()
+        );
+      }
+      const newSize2 = Math.max(file.size, writeEndOffset);
+      if (newSize2 !== file.size) {
+        file.size = newSize2;
+        file.metaDirty = true;
+      }
+      return VFS.SQLITE_OK;
+    }
     const plans = [];
     const chunkKeysToFetch = [];
     for (let i = startChunk; i <= endChunk; i++) {
@@ -635,23 +819,35 @@ var SqliteSystem = class {
         existingChunkIndex
       });
     }
-    const existingChunks = chunkKeysToFetch.length > 0 ? await options.getBatch(chunkKeysToFetch) : [];
+    let existingChunks;
+    try {
+      existingChunks = chunkKeysToFetch.length > 0 ? await options.getBatch(chunkKeysToFetch) : [];
+    } catch {
+      return VFS.SQLITE_IOERR_WRITE;
+    }
+    data = this.#module.HEAPU8.subarray(pData, pData + iAmt);
     const entriesToWrite = [];
     for (const plan of plans) {
       const existingChunk = plan.existingChunkIndex >= 0 ? existingChunks[plan.existingChunkIndex] : null;
       let newChunk;
       if (existingChunk) {
-        newChunk = new Uint8Array(Math.max(existingChunk.length, plan.writeEnd));
+        newChunk = new Uint8Array(
+          Math.max(existingChunk.length, plan.writeEnd)
+        );
         newChunk.set(existingChunk);
       } else {
         newChunk = new Uint8Array(plan.writeEnd);
       }
       const sourceStart = plan.chunkOffset + plan.writeStart - iOffset;
       const sourceEnd = sourceStart + (plan.writeEnd - plan.writeStart);
-      newChunk.set(data.subarray(sourceStart, sourceEnd), plan.writeStart);
+      newChunk.set(
+        data.subarray(sourceStart, sourceEnd),
+        plan.writeStart
+      );
       entriesToWrite.push([plan.chunkKey, newChunk]);
     }
     const previousSize = file.size;
+    const previousMetaDirty = file.metaDirty;
     const newSize = Math.max(file.size, writeEndOffset);
     if (newSize !== previousSize) {
       file.size = newSize;
@@ -660,7 +856,13 @@ var SqliteSystem = class {
     if (file.metaDirty) {
       entriesToWrite.push([file.metaKey, encodeFileMeta2(file.size)]);
     }
-    await options.putBatch(entriesToWrite);
+    try {
+      await options.putBatch(entriesToWrite);
+    } catch {
+      file.size = previousSize;
+      file.metaDirty = previousMetaDirty;
+      return VFS.SQLITE_IOERR_WRITE;
+    }
     if (file.metaDirty) {
       file.metaDirty = false;
     }
@@ -678,34 +880,57 @@ var SqliteSystem = class {
     const options = file.options;
     if (size >= file.size) {
       if (size > file.size) {
+        const previousSize2 = file.size;
+        const previousMetaDirty2 = file.metaDirty;
         file.size = size;
         file.metaDirty = true;
-        await options.put(file.metaKey, encodeFileMeta2(file.size));
+        try {
+          await options.put(file.metaKey, encodeFileMeta2(file.size));
+        } catch {
+          file.size = previousSize2;
+          file.metaDirty = previousMetaDirty2;
+          return VFS.SQLITE_IOERR_TRUNCATE;
+        }
         file.metaDirty = false;
       }
       return VFS.SQLITE_OK;
     }
     const lastChunkToKeep = Math.floor((size - 1) / CHUNK_SIZE);
     const lastExistingChunk = Math.floor((file.size - 1) / CHUNK_SIZE);
-    const keysToDelete = [];
-    for (let i = lastChunkToKeep + 1; i <= lastExistingChunk; i++) {
-      keysToDelete.push(this.#chunkKey(file, i));
-    }
-    if (keysToDelete.length > 0) {
-      await options.deleteBatch(keysToDelete);
-    }
-    if (size > 0 && size % CHUNK_SIZE !== 0) {
-      const lastChunkKey = this.#chunkKey(file, lastChunkToKeep);
-      const lastChunkData = await options.get(lastChunkKey);
-      if (lastChunkData && lastChunkData.length > size % CHUNK_SIZE) {
-        const truncatedChunk = lastChunkData.subarray(0, size % CHUNK_SIZE);
-        await options.put(lastChunkKey, truncatedChunk);
-      }
-    }
+    const previousSize = file.size;
+    const previousMetaDirty = file.metaDirty;
     file.size = size;
     file.metaDirty = true;
-    await options.put(file.metaKey, encodeFileMeta2(file.size));
+    try {
+      await options.put(file.metaKey, encodeFileMeta2(file.size));
+    } catch {
+      file.size = previousSize;
+      file.metaDirty = previousMetaDirty;
+      return VFS.SQLITE_IOERR_TRUNCATE;
+    }
     file.metaDirty = false;
+    try {
+      if (size > 0 && size % CHUNK_SIZE !== 0) {
+        const lastChunkKey = this.#chunkKey(file, lastChunkToKeep);
+        const lastChunkData = await options.get(lastChunkKey);
+        if (lastChunkData && lastChunkData.length > size % CHUNK_SIZE) {
+          const truncatedChunk = lastChunkData.subarray(
+            0,
+            size % CHUNK_SIZE
+          );
+          await options.put(lastChunkKey, truncatedChunk);
+        }
+      }
+      const keysToDelete = [];
+      for (let i = lastChunkToKeep + 1; i <= lastExistingChunk; i++) {
+        keysToDelete.push(this.#chunkKey(file, i));
+      }
+      for (let b = 0; b < keysToDelete.length; b += KV_MAX_BATCH_KEYS) {
+        await options.deleteBatch(keysToDelete.slice(b, b + KV_MAX_BATCH_KEYS));
+      }
+    } catch {
+      return VFS.SQLITE_IOERR_TRUNCATE;
+    }
     return VFS.SQLITE_OK;
   }
   async xSync(fileId, _flags) {
@@ -713,7 +938,11 @@ var SqliteSystem = class {
     if (!file || !file.metaDirty) {
       return VFS.SQLITE_OK;
     }
-    await file.options.put(file.metaKey, encodeFileMeta2(file.size));
+    try {
+      await file.options.put(file.metaKey, encodeFileMeta2(file.size));
+    } catch {
+      return VFS.SQLITE_IOERR_FSYNC;
+    }
     file.metaDirty = false;
     return VFS.SQLITE_OK;
   }
@@ -726,7 +955,11 @@ var SqliteSystem = class {
     return VFS.SQLITE_OK;
   }
   async xDelete(_pVfs, zName, _syncDir) {
-    await this.#delete(this.#module.UTF8ToString(zName));
+    try {
+      await this.#delete(this.#module.UTF8ToString(zName));
+    } catch {
+      return VFS.SQLITE_IOERR_DELETE;
+    }
     return VFS.SQLITE_OK;
   }
   /**
@@ -745,7 +978,9 @@ var SqliteSystem = class {
     for (let i = 0; i < numChunks; i++) {
       keysToDelete.push(getChunkKey(fileTag, i));
     }
-    await options.deleteBatch(keysToDelete);
+    for (let b = 0; b < keysToDelete.length; b += KV_MAX_BATCH_KEYS) {
+      await options.deleteBatch(keysToDelete.slice(b, b + KV_MAX_BATCH_KEYS));
+    }
   }
   async xAccess(_pVfs, zName, _flags, pResOut) {
     const path = this.#module.UTF8ToString(zName);
@@ -755,7 +990,12 @@ var SqliteSystem = class {
       return VFS.SQLITE_OK;
     }
     const compactMetaKey = getMetaKey(resolved.fileTag);
-    const metaData = await resolved.options.get(compactMetaKey);
+    let metaData;
+    try {
+      metaData = await resolved.options.get(compactMetaKey);
+    } catch {
+      return VFS.SQLITE_IOERR_ACCESS;
+    }
     this.#writeInt32(pResOut, metaData ? 1 : 0);
     return VFS.SQLITE_OK;
   }
@@ -769,11 +1009,72 @@ var SqliteSystem = class {
   xUnlock(_fileId, _flags) {
     return VFS.SQLITE_OK;
   }
-  xFileControl(_fileId, _flags, _pArg) {
-    return VFS.SQLITE_NOTFOUND;
+  async xFileControl(fileId, flags, _pArg) {
+    switch (flags) {
+      case SQLITE_FCNTL_BEGIN_ATOMIC_WRITE: {
+        const file = this.#openFiles.get(fileId);
+        if (!file) return VFS.SQLITE_NOTFOUND;
+        file.savedFileSize = file.size;
+        file.batchMode = true;
+        file.metaDirty = false;
+        file.dirtyBuffer = /* @__PURE__ */ new Map();
+        return VFS.SQLITE_OK;
+      }
+      case SQLITE_FCNTL_COMMIT_ATOMIC_WRITE: {
+        const file = this.#openFiles.get(fileId);
+        if (!file) return VFS.SQLITE_NOTFOUND;
+        const { dirtyBuffer, options } = file;
+        const maxDirtyPages = file.metaDirty ? KV_MAX_BATCH_KEYS - 1 : KV_MAX_BATCH_KEYS;
+        if (dirtyBuffer && dirtyBuffer.size > maxDirtyPages) {
+          dirtyBuffer.clear();
+          file.dirtyBuffer = null;
+          file.size = file.savedFileSize;
+          file.metaDirty = false;
+          file.batchMode = false;
+          return VFS.SQLITE_IOERR;
+        }
+        const entries = [];
+        if (dirtyBuffer) {
+          for (const [chunkIndex, data] of dirtyBuffer) {
+            entries.push([this.#chunkKey(file, chunkIndex), data]);
+          }
+          dirtyBuffer.clear();
+        }
+        if (file.metaDirty) {
+          entries.push([file.metaKey, encodeFileMeta2(file.size)]);
+        }
+        try {
+          await options.putBatch(entries);
+        } catch {
+          file.dirtyBuffer = null;
+          file.size = file.savedFileSize;
+          file.metaDirty = false;
+          file.batchMode = false;
+          return VFS.SQLITE_IOERR;
+        }
+        file.dirtyBuffer = null;
+        file.metaDirty = false;
+        file.batchMode = false;
+        return VFS.SQLITE_OK;
+      }
+      case SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE: {
+        const file = this.#openFiles.get(fileId);
+        if (!file || !file.batchMode) return VFS.SQLITE_OK;
+        if (file.dirtyBuffer) {
+          file.dirtyBuffer.clear();
+          file.dirtyBuffer = null;
+        }
+        file.size = file.savedFileSize;
+        file.metaDirty = false;
+        file.batchMode = false;
+        return VFS.SQLITE_OK;
+      }
+      default:
+        return VFS.SQLITE_NOTFOUND;
+    }
   }
   xDeviceCharacteristics(_fileId) {
-    return 0;
+    return SQLITE_IOCAP_BATCH_ATOMIC;
   }
   xFullPathname(_pVfs, zName, nOut, zOut) {
     const path = this.#module.UTF8ToString(zName);
@@ -850,8 +1151,345 @@ function delegalize(lo32, hi32) {
   }
   return hi * UINT32_SIZE + lo;
 }
+
+// src/pool.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { createRequire as createRequire2 } from "module";
+var SqliteVfsPool = class {
+  #config;
+  #modulePromise = null;
+  #instances = /* @__PURE__ */ new Set();
+  #actorToInstance = /* @__PURE__ */ new Map();
+  #actorToHandle = /* @__PURE__ */ new Map();
+  #shuttingDown = false;
+  constructor(config2) {
+    if (!Number.isInteger(config2.actorsPerInstance) || config2.actorsPerInstance < 1) {
+      throw new Error(
+        `actorsPerInstance must be a positive integer, got ${config2.actorsPerInstance}`
+      );
+    }
+    this.#config = config2;
+  }
+  /**
+   * Compile the WASM module once and cache the promise. Subsequent calls
+   * return the same promise, avoiding redundant compilation.
+   */
+  #getModule() {
+    if (!this.#modulePromise) {
+      this.#modulePromise = (async () => {
+        const require2 = createRequire2(import.meta.url);
+        const wasmPath = require2.resolve(
+          "@rivetkit/sqlite/dist/wa-sqlite-async.wasm"
+        );
+        const wasmBinary = readFileSync2(wasmPath);
+        return WebAssembly.compile(wasmBinary);
+      })();
+      this.#modulePromise.catch(() => {
+        this.#modulePromise = null;
+      });
+    }
+    return this.#modulePromise;
+  }
+  /** Number of live WASM instances in the pool. */
+  get instanceCount() {
+    return this.#instances.size;
+  }
+  /** Number of actors currently assigned to pool instances. */
+  get actorCount() {
+    return this.#actorToInstance.size;
+  }
+  /**
+   * Acquire a pooled VFS handle for the given actor. Returns a
+   * PooledSqliteHandle with sticky assignment. If the actor is already
+   * assigned, the existing handle is returned.
+   *
+   * Bin-packing: picks the instance with the most actors that still has
+   * capacity. If all instances are full, creates a new one using the
+   * cached WASM module.
+   */
+  async acquire(actorId) {
+    if (this.#shuttingDown) {
+      throw new Error("SqliteVfsPool is shutting down");
+    }
+    const existingHandle = this.#actorToHandle.get(actorId);
+    if (existingHandle) {
+      return existingHandle;
+    }
+    let bestInstance = null;
+    let bestCount = -1;
+    for (const instance of this.#instances) {
+      if (instance.destroying) continue;
+      const count = instance.actors.size;
+      if (count < this.#config.actorsPerInstance && count > bestCount) {
+        bestInstance = instance;
+        bestCount = count;
+      }
+    }
+    if (!bestInstance) {
+      const wasmModule = await this.#getModule();
+      if (this.#shuttingDown) {
+        throw new Error("SqliteVfsPool is shutting down");
+      }
+      const existingHandleAfterAwait = this.#actorToHandle.get(actorId);
+      if (existingHandleAfterAwait) {
+        return existingHandleAfterAwait;
+      }
+      for (const instance of this.#instances) {
+        if (instance.destroying) continue;
+        const count = instance.actors.size;
+        if (count < this.#config.actorsPerInstance && count > bestCount) {
+          bestInstance = instance;
+          bestCount = count;
+        }
+      }
+      if (!bestInstance) {
+        const vfs = new SqliteVfs(wasmModule);
+        bestInstance = {
+          vfs,
+          actors: /* @__PURE__ */ new Set(),
+          shortNameCounter: 0,
+          actorShortNames: /* @__PURE__ */ new Map(),
+          availableShortNames: /* @__PURE__ */ new Set(),
+          poisonedShortNames: /* @__PURE__ */ new Set(),
+          opsInFlight: 0,
+          idleTimer: null,
+          destroying: false
+        };
+        this.#instances.add(bestInstance);
+      }
+    }
+    this.#cancelIdleTimer(bestInstance);
+    let shortName;
+    const recycled = bestInstance.availableShortNames.values().next();
+    if (!recycled.done) {
+      shortName = recycled.value;
+      bestInstance.availableShortNames.delete(shortName);
+    } else {
+      shortName = String(bestInstance.shortNameCounter++);
+    }
+    bestInstance.actors.add(actorId);
+    bestInstance.actorShortNames.set(actorId, shortName);
+    this.#actorToInstance.set(actorId, bestInstance);
+    const handle = new PooledSqliteHandle(
+      shortName,
+      actorId,
+      this
+    );
+    this.#actorToHandle.set(actorId, handle);
+    return handle;
+  }
+  /**
+   * Release an actor's assignment from the pool. Force-closes all database
+   * handles for the actor, recycles or poisons the short name, and
+   * decrements the instance refcount.
+   */
+  async release(actorId) {
+    const instance = this.#actorToInstance.get(actorId);
+    if (!instance) {
+      return;
+    }
+    const shortName = instance.actorShortNames.get(actorId);
+    if (shortName === void 0) {
+      return;
+    }
+    const { allSucceeded } = await instance.vfs.forceCloseByFileName(shortName);
+    if (allSucceeded) {
+      instance.availableShortNames.add(shortName);
+    } else {
+      instance.poisonedShortNames.add(shortName);
+    }
+    instance.actors.delete(actorId);
+    instance.actorShortNames.delete(actorId);
+    this.#actorToInstance.delete(actorId);
+    this.#actorToHandle.delete(actorId);
+    if (instance.actors.size === 0 && instance.opsInFlight === 0 && !this.#shuttingDown) {
+      this.#startIdleTimer(instance);
+    }
+  }
+  /**
+   * Track an in-flight operation on an instance. Increments opsInFlight
+   * before running fn, decrements after using try/finally to prevent
+   * drift from exceptions. If the decrement brings opsInFlight to 0
+   * with refcount also 0, starts the idle timer.
+   */
+  async #trackOp(instance, fn) {
+    instance.opsInFlight++;
+    try {
+      return await fn();
+    } finally {
+      instance.opsInFlight--;
+      if (instance.actors.size === 0 && instance.opsInFlight === 0 && !instance.destroying && !this.#shuttingDown) {
+        this.#startIdleTimer(instance);
+      }
+    }
+  }
+  /**
+   * Open a database on behalf of an actor, tracked as an in-flight
+   * operation. Used by PooledSqliteHandle to avoid exposing PoolInstance.
+   */
+  async openForActor(actorId, shortName, options) {
+    const instance = this.#actorToInstance.get(actorId);
+    if (!instance) {
+      throw new Error(`Actor ${actorId} is not assigned to any pool instance`);
+    }
+    return this.#trackOp(
+      instance,
+      () => instance.vfs.open(shortName, options)
+    );
+  }
+  /**
+   * Track an in-flight database operation for the given actor. Resolves the
+   * actor's pool instance and wraps the operation with opsInFlight tracking.
+   * If the actor has already been released, the operation runs without
+   * tracking since the instance may already be destroyed.
+   */
+  async trackOpForActor(actorId, fn) {
+    const instance = this.#actorToInstance.get(actorId);
+    if (!instance) {
+      return fn();
+    }
+    return this.#trackOp(instance, fn);
+  }
+  #startIdleTimer(instance) {
+    if (instance.idleTimer || instance.destroying) return;
+    const idleDestroyMs = this.#config.idleDestroyMs ?? 3e4;
+    instance.idleTimer = setTimeout(() => {
+      instance.idleTimer = null;
+      if (instance.actors.size === 0 && instance.opsInFlight === 0 && !instance.destroying) {
+        this.#destroyInstance(instance);
+      }
+    }, idleDestroyMs);
+  }
+  #cancelIdleTimer(instance) {
+    if (instance.idleTimer) {
+      clearTimeout(instance.idleTimer);
+      instance.idleTimer = null;
+    }
+  }
+  async #destroyInstance(instance) {
+    instance.destroying = true;
+    this.#cancelIdleTimer(instance);
+    this.#instances.delete(instance);
+    try {
+      await instance.vfs.forceCloseAll();
+      await instance.vfs.destroy();
+    } catch (error) {
+      console.warn("SqliteVfsPool: failed to destroy instance", error);
+    }
+  }
+  /**
+   * Graceful shutdown. Rejects new acquire() calls, cancels idle timers,
+   * force-closes all databases, destroys all VFS instances, and clears pool
+   * state.
+   */
+  async shutdown() {
+    this.#shuttingDown = true;
+    const instances = [...this.#instances];
+    for (const instance of instances) {
+      this.#cancelIdleTimer(instance);
+      this.#instances.delete(instance);
+      if (instance.opsInFlight > 0) {
+        console.warn(
+          `SqliteVfsPool: shutting down instance with ${instance.opsInFlight} in-flight operation(s). Concurrent close is safe due to Database.close() idempotency.`
+        );
+      }
+      try {
+        await instance.vfs.forceCloseAll();
+        await instance.vfs.destroy();
+      } catch (error) {
+        console.warn("SqliteVfsPool: failed to destroy instance during shutdown", error);
+      }
+    }
+    this.#actorToInstance.clear();
+    this.#actorToHandle.clear();
+  }
+};
+var TrackedDatabase = class {
+  #inner;
+  #pool;
+  #actorId;
+  constructor(inner, pool, actorId) {
+    this.#inner = inner;
+    this.#pool = pool;
+    this.#actorId = actorId;
+  }
+  async exec(...args) {
+    return this.#pool.trackOpForActor(
+      this.#actorId,
+      () => this.#inner.exec(...args)
+    );
+  }
+  async run(...args) {
+    return this.#pool.trackOpForActor(
+      this.#actorId,
+      () => this.#inner.run(...args)
+    );
+  }
+  async query(...args) {
+    return this.#pool.trackOpForActor(
+      this.#actorId,
+      () => this.#inner.query(...args)
+    );
+  }
+  async close() {
+    return this.#pool.trackOpForActor(
+      this.#actorId,
+      () => this.#inner.close()
+    );
+  }
+  get fileName() {
+    return this.#inner.fileName;
+  }
+};
+var PooledSqliteHandle = class {
+  #shortName;
+  #actorId;
+  #pool;
+  #released = false;
+  constructor(shortName, actorId, pool) {
+    this.#shortName = shortName;
+    this.#actorId = actorId;
+    this.#pool = pool;
+  }
+  /**
+   * Open a database on the shared instance. Uses the pool-assigned short
+   * name as the VFS file path, with the caller's KvVfsOptions for KV
+   * routing. The open call itself is tracked as an in-flight operation,
+   * and the returned Database is wrapped so that exec(), run(), query(),
+   * and close() are also tracked via opsInFlight.
+   */
+  async open(_fileName, options) {
+    if (this.#released) {
+      throw new Error("PooledSqliteHandle has been released");
+    }
+    const db = await this.#pool.openForActor(
+      this.#actorId,
+      this.#shortName,
+      options
+    );
+    return new TrackedDatabase(
+      db,
+      this.#pool,
+      this.#actorId
+    );
+  }
+  /**
+   * Release this actor's assignment back to the pool. Idempotent: calling
+   * destroy() more than once is a no-op, preventing double-release from
+   * decrementing the instance refcount below actual.
+   */
+  async destroy() {
+    if (this.#released) {
+      return;
+    }
+    this.#released = true;
+    await this.#pool.release(this.#actorId);
+  }
+};
 export {
   Database,
-  SqliteVfs
+  PooledSqliteHandle,
+  SqliteVfs,
+  SqliteVfsPool
 };
 //# sourceMappingURL=index.js.map