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

package/src/vfs.ts

@@ -36,6 +36,7 @@ import {
 	getMetaKey,
 	type SqliteFileTag,
 } from "./kv";
+import { EMPTY_DB_PAGE } from "./generated/empty-db-page";
 import {
 	FILE_META_VERSIONED,
 	CURRENT_VERSION,
@@ -43,7 +44,41 @@ import {
 import type { FileMeta } from "../schemas/file-meta/mod";
 import type { KvVfsOptions } from "./types";
 
-type SqliteEsmFactory = (config?: { wasmBinary?: ArrayBuffer | Uint8Array }) => Promise<unknown>;
+/**
+ * Common interface for database handles returned by ISqliteVfs.open().
+ * Both the concrete Database class and the pool's TrackedDatabase wrapper
+ * implement this, so consumers can use either interchangeably.
+ */
+export interface IDatabase {
+	exec(
+		sql: string,
+		callback?: (row: unknown[], columns: string[]) => void,
+	): Promise<void>;
+	run(sql: string, params?: SqliteBindings): Promise<void>;
+	query(
+		sql: string,
+		params?: SqliteBindings,
+	): Promise<{ rows: unknown[][]; columns: string[] }>;
+	close(): Promise<void>;
+	readonly fileName: string;
+}
+
+/**
+ * Common interface for SQLite VFS backends. Both standalone SqliteVfs and
+ * PooledSqliteHandle implement this so callers can use either interchangeably.
+ */
+export interface ISqliteVfs {
+	open(fileName: string, options: KvVfsOptions): Promise<IDatabase>;
+	destroy(): Promise<void>;
+}
+
+type SqliteEsmFactory = (config?: {
+	wasmBinary?: ArrayBuffer | Uint8Array;
+	instantiateWasm?: (
+		imports: WebAssembly.Imports,
+		receiveInstance: (instance: WebAssembly.Instance) => void,
+	) => WebAssembly.Exports;
+}) => Promise<unknown>;
 type SQLite3Api = ReturnType<typeof Factory>;
 type SqliteBindings = Parameters<SQLite3Api["bind_collection"]>[1];
 type SqliteVfsRegistration = Parameters<SQLite3Api["vfs_register"]>[0];
@@ -65,6 +100,55 @@ const MAX_FILE_SIZE_BYTES = (MAX_CHUNK_INDEX + 1) * CHUNK_SIZE;
 const MAX_FILE_SIZE_HI32 = Math.floor(MAX_FILE_SIZE_BYTES / UINT32_SIZE);
 const MAX_FILE_SIZE_LO32 = MAX_FILE_SIZE_BYTES % UINT32_SIZE;
 
+// Maximum number of keys the KV backend accepts in a single deleteBatch or putBatch call.
+const KV_MAX_BATCH_KEYS = 128;
+
+// -- BATCH_ATOMIC and KV round trip documentation --
+//
+// KV round trips per actor database lifecycle:
+//
+//   Open (new database):
+//     1 putBatch  -- xOpen pre-writes EMPTY_DB_PAGE + metadata (2 keys)
+//     PRAGMAs are in-memory, 0 KV ops
+//
+//   Open (existing database / wake from sleep):
+//     1 get       -- xOpen reads metadata to determine file size
+//     PRAGMAs are in-memory, 0 KV ops
+//
+//   First SQL operation (e.g., migration CREATE TABLE):
+//     1 getBatch  -- pager reads page 1 (database header)
+//     N getBatch  -- pager reads additional pages as needed by the schema
+//     1 putBatch  -- BATCH_ATOMIC commit (all dirty pages + metadata)
+//
+//   Subsequent writes (warm pager cache):
+//     0 reads     -- pages served from pager cache
+//     1 putBatch  -- BATCH_ATOMIC commit
+//
+//   Subsequent reads (warm pager cache):
+//     0 reads     -- pages served from pager cache
+//     0 writes    -- SELECT-only, no dirty pages
+//
+//   Large writes (> 127 dirty pages):
+//     BATCH_ATOMIC COMMIT returns SQLITE_IOERR, SQLite falls back to
+//     journal mode with multiple putBatch calls (each <= 128 keys).
+//
+// BATCH_ATOMIC requires SQLite's pager to use an in-memory journal.
+// The pager only does this when dbSize > 0. For new databases, xOpen
+// pre-writes a valid empty page (EMPTY_DB_PAGE) so dbSize is 1 from
+// the start. Without this, the first transaction opens a real journal
+// file, and locking_mode=EXCLUSIVE prevents it from ever being closed,
+// permanently disabling BATCH_ATOMIC.
+//
+// See scripts/generate-empty-db-page.ts for how EMPTY_DB_PAGE is built.
+
+// BATCH_ATOMIC capability flag returned by xDeviceCharacteristics.
+const SQLITE_IOCAP_BATCH_ATOMIC = 0x4000;
+
+// xFileControl opcodes for atomic write bracketing.
+const SQLITE_FCNTL_BEGIN_ATOMIC_WRITE = 31;
+const SQLITE_FCNTL_COMMIT_ATOMIC_WRITE = 32;
+const SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE = 33;
+
 // libvfs captures this async/sync mask at registration time. Any VFS callback
 // that returns a Promise must be listed here so SQLite uses async relays.
 const SQLITE_ASYNC_METHODS = new Set([
@@ -77,6 +161,7 @@ const SQLITE_ASYNC_METHODS = new Set([
 	"xFileSize",
 	"xDelete",
 	"xAccess",
+	"xFileControl",
 ]);
 
 interface LoadedSqliteRuntime {
@@ -102,30 +187,55 @@ function isSQLiteModule(value: unknown): value is SQLiteModule {
 	);
 }
 
-
 /**
  * Lazily load and instantiate the async SQLite module for this VFS instance.
  * We do this on first open so actors that do not use SQLite do not pay module
  * parse and wasm initialization cost at startup, and we pass wasmBinary
  * explicitly so this works consistently in both ESM and CJS bundles.
  */
-async function loadSqliteRuntime(): Promise<LoadedSqliteRuntime> {
+async function loadSqliteRuntime(
+	wasmModule?: WebAssembly.Module,
+): Promise<LoadedSqliteRuntime> {
 	// Keep the module specifier assembled at runtime so TypeScript declaration
 	// generation does not try to typecheck this deep dist import path.
 	// Uses Array.join() instead of string concatenation to prevent esbuild/tsup
 	// from constant-folding the expression at build time, which would allow
 	// Turbopack to trace into the WASM package.
-	const specifier = ["@rivetkit/sqlite", "dist", "wa-sqlite-async.mjs"].join("/");
+	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 require = createRequire(import.meta.url);
-	const sqliteDistPath = "@rivetkit/sqlite/dist/";
-	const wasmPath = require.resolve(sqliteDistPath + "wa-sqlite-async.wasm");
-	const wasmBinary = readFileSync(wasmPath);
-	const module = await sqliteEsmFactory({ wasmBinary });
+
+	let module: unknown;
+	if (wasmModule) {
+		// Use the pre-compiled WebAssembly.Module directly, skipping
+		// WebAssembly.compile. The Emscripten instantiateWasm callback lets us
+		// provide a module that has already been compiled and cached by the pool.
+		module = await sqliteEsmFactory({
+			instantiateWasm(
+				imports: WebAssembly.Imports,
+				receiveInstance: (instance: WebAssembly.Instance) => void,
+			) {
+				WebAssembly.instantiate(wasmModule, imports).then((instance) => {
+					receiveInstance(instance);
+				});
+				return {} as WebAssembly.Exports;
+			},
+		});
+	} else {
+		const require = createRequire(import.meta.url);
+		const sqliteDistPath = "@rivetkit/sqlite/dist/";
+		const wasmPath = require.resolve(
+			sqliteDistPath + "wa-sqlite-async.wasm",
+		);
+		const wasmBinary = readFileSync(wasmPath);
+		module = await sqliteEsmFactory({ wasmBinary });
+	}
+
 	if (!isSQLiteModule(module)) {
 		throw new Error("Invalid SQLite runtime module");
 	}
@@ -153,6 +263,12 @@ interface OpenFile {
 	flags: number;
 	/** KV options for this file */
 	options: KvVfsOptions;
+	/** True while inside a BATCH_ATOMIC write bracket */
+	batchMode: boolean;
+	/** Buffered dirty pages during batch mode. Key is the chunk index. */
+	dirtyBuffer: Map<number, Uint8Array> | null;
+	/** File size saved at BEGIN_ATOMIC_WRITE for rollback */
+	savedFileSize: number;
 }
 
 interface ResolvedFile {
@@ -180,7 +296,9 @@ function decodeFileMeta(data: Uint8Array): number {
 }
 
 function isValidFileSize(size: number): boolean {
-	return Number.isSafeInteger(size) && size >= 0 && size <= MAX_FILE_SIZE_BYTES;
+	return (
+		Number.isSafeInteger(size) && size >= 0 && size <= MAX_FILE_SIZE_BYTES
+	);
 }
 
 /**
@@ -219,18 +337,19 @@ class AsyncMutex {
 /**
  * Database wrapper that provides a simplified SQLite API
  */
-export class Database {
+export class Database implements IDatabase {
 	readonly #sqlite3: SQLite3Api;
 	readonly #handle: number;
 	readonly #fileName: string;
-	readonly #onClose: () => void;
+	readonly #onClose: () => Promise<void>;
 	readonly #sqliteMutex: AsyncMutex;
+	#closed = false;
 
 	constructor(
 		sqlite3: SQLite3Api,
 		handle: number,
 		fileName: string,
-		onClose: () => void,
+		onClose: () => Promise<void>,
 		sqliteMutex: AsyncMutex,
 	) {
 		this.#sqlite3 = sqlite3;
@@ -245,7 +364,10 @@ export class Database {
 	 * @param sql - SQL statement to execute
 	 * @param callback - Called for each result row with (row, columns)
 	 */
-	async exec(sql: string, callback?: (row: unknown[], columns: string[]) => void): Promise<void> {
+	async exec(
+		sql: string,
+		callback?: (row: unknown[], columns: string[]) => void,
+	): Promise<void> {
 		await this.#sqliteMutex.run(async () => {
 			await this.#sqlite3.exec(this.#handle, sql, callback);
 		});
@@ -258,7 +380,10 @@ export class Database {
 	 */
 	async run(sql: string, params?: SqliteBindings): Promise<void> {
 		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);
 				}
@@ -275,11 +400,17 @@ export class Database {
 	 * @param params - Parameter values to bind
 	 * @returns Object with rows (array of arrays) and columns (column names)
 	 */
-	async query(sql: string, params?: SqliteBindings): Promise<{ rows: unknown[][]; columns: string[] }> {
+	async query(
+		sql: string,
+		params?: SqliteBindings,
+	): Promise<{ rows: unknown[][]; columns: string[] }> {
 		return this.#sqliteMutex.run(async () => {
 			const rows: unknown[][] = [];
 			let columns: string[] = [];
-			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);
 				}
@@ -300,10 +431,22 @@ export class Database {
 	 * Close the database
 	 */
 	async close(): Promise<void> {
+		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(): string {
+		return this.#fileName;
 	}
 
 	/**
@@ -327,7 +470,7 @@ export class Database {
  * Each instance is independent and has its own @rivetkit/sqlite WASM module.
  * This allows multiple instances to operate concurrently without interference.
  */
-export class SqliteVfs {
+export class SqliteVfs implements ISqliteVfs {
 	#sqlite3: SQLite3Api | null = null;
 	#sqliteSystem: SqliteSystem | null = null;
 	#initPromise: Promise<void> | null = null;
@@ -335,10 +478,13 @@ export class SqliteVfs {
 	#sqliteMutex = new AsyncMutex();
 	#instanceId: string;
 	#destroyed = false;
+	#openDatabases: Set<Database> = new Set();
+	#wasmModule?: WebAssembly.Module;
 
-	constructor() {
+	constructor(wasmModule?: WebAssembly.Module) {
 		// Generate unique instance ID for VFS name
-		this.#instanceId = crypto.randomUUID().replace(/-/g, '').slice(0, 8);
+		this.#instanceId = crypto.randomUUID().replace(/-/g, "").slice(0, 8);
+		this.#wasmModule = wasmModule;
 	}
 
 	/**
@@ -357,7 +503,9 @@ export class SqliteVfs {
 		// Synchronously create the promise if not started
 		if (!this.#initPromise) {
 			this.#initPromise = (async () => {
-				const { sqlite3, module } = await loadSqliteRuntime();
+				const { sqlite3, module } = await loadSqliteRuntime(
+					this.#wasmModule,
+				);
 				if (this.#destroyed) {
 					return;
 				}
@@ -387,10 +535,7 @@ export class SqliteVfs {
 	 * @param options - KV storage operations for this database
 	 * @returns A Database instance
 	 */
-	async open(
-		fileName: string,
-		options: KvVfsOptions,
-	): Promise<Database> {
+	async open(fileName: string, options: KvVfsOptions): Promise<IDatabase> {
 		if (this.#destroyed) {
 			throw new Error("SqliteVfs is closed");
 		}
@@ -398,6 +543,17 @@ export class SqliteVfs {
 		// Serialize all open operations within this instance
 		await this.#openMutex.acquire();
 		try {
+			// Reject double-open of the same fileName. Two handles to the same
+			// file would have separate pager caches and no real locking
+			// (xLock/xUnlock are no-ops), causing silent data corruption.
+			for (const db of this.#openDatabases) {
+				if (db.fileName === fileName) {
+					throw new Error(
+						`SqliteVfs: fileName "${fileName}" is already open on this instance`,
+					);
+				}
+			}
+
 			// Initialize @rivetkit/sqlite and SqliteSystem on first call
 			await this.#ensureInitialized();
 
@@ -418,27 +574,102 @@ export class SqliteVfs {
 					sqliteSystem.name,
 				),
 			);
-			// TODO: Benchmark PRAGMA tuning for KV-backed SQLite after open.
-			// Start with journal_mode=PERSIST and journal_size_limit to reduce
-			// journal churn on high-latency KV without introducing WAL.
+			// Single-writer optimizations for KV-backed SQLite. Each actor owns
+			// its database exclusively. BATCH_ATOMIC batches dirty pages into a
+			// single putBatch call instead of 5-7 individual KV round trips per
+			// write transaction.
+			//
+			// BATCH_ATOMIC requires an in-memory journal, which SQLite only uses
+			// when dbSize > 0. The xOpen handler pre-writes a valid empty page 1
+			// for new databases so this condition is satisfied from the start.
+			// See xOpen and scripts/generate-empty-db-page.ts for details.
+			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");
+			});
 
-			// Create cleanup callback
-			const onClose = () => {
-				sqliteSystem.unregisterFile(fileName);
+			// Wrap unregistration under #openMutex so it serializes with
+			// registerFile and prevents interleaving when short names recycle.
+			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: string,
+	): Promise<{ allSucceeded: boolean }> {
+		const snapshot = [...this.#openDatabases];
+		let allSucceeded = true;
+		for (const db of snapshot) {
+			if (db.fileName === fileName) {
+				try {
+					await db.close();
+				} catch {
+					allSucceeded = false;
+					// When close fails, onClose never fires, leaving orphaned
+					// entries in #openDatabases and #registeredFiles. Clean up
+					// manually so stale registrations don't accumulate.
+					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(): Promise<void> {
+		const snapshot = [...this.#openDatabases];
+		for (const db of snapshot) {
+			try {
+				await db.close();
+			} catch {
+				// Best-effort teardown. Swallow errors.
+			}
+		}
+	}
+
 	/**
 	 * Tears down this VFS instance and releases internal references.
 	 */
@@ -481,8 +712,7 @@ class SqliteSystem implements SqliteVfsRegistration {
 	readonly name: string;
 	readonly mxPathName = SQLITE_MAX_PATHNAME_BYTES;
 	readonly mxPathname = SQLITE_MAX_PATHNAME_BYTES;
-	#mainFileName: string | null = null;
-	#mainFileOptions: KvVfsOptions | null = null;
+	readonly #registeredFiles: Map<string, KvVfsOptions> = new Map();
 	readonly #openFiles: Map<number, OpenFile> = new Map();
 	readonly #sqlite3: SQLite3Api;
 	readonly #module: SQLiteModule;
@@ -499,8 +729,7 @@ class SqliteSystem implements SqliteVfsRegistration {
 
 	async close(): Promise<void> {
 		this.#openFiles.clear();
-		this.#mainFileName = null;
-		this.#mainFileOptions = null;
+		this.#registeredFiles.clear();
 	}
 
 	isReady(): boolean {
@@ -519,53 +748,50 @@ class SqliteSystem implements SqliteVfsRegistration {
 	}
 
 	/**
-	 * Registers a file with its KV options (before opening)
+	 * Registers a file with its KV options (before opening).
 	 */
 	registerFile(fileName: string, options: KvVfsOptions): void {
-		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: string): void {
-		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: string): ResolvedFile | null {
-		if (!this.#mainFileName || !this.#mainFileOptions) {
-			return null;
+		// Direct match: O(1) lookup for main database file.
+		const directOptions = this.#registeredFiles.get(path);
+		if (directOptions) {
+			return { options: directOptions, fileTag: FILE_TAG_MAIN };
 		}
 
-		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 };
-		}
-		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 };
+		// Sidecar match: strip each known suffix and check the base name.
+		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;
@@ -577,12 +803,13 @@ class SqliteSystem implements SqliteVfsRegistration {
 			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}.`,
 		);
 	}
 
@@ -608,7 +835,12 @@ class SqliteSystem implements SqliteVfsRegistration {
 		const metaKey = getMetaKey(fileTag);
 
 		// Get existing file size if the file exists
-		const sizeData = await options.get(metaKey);
+		let sizeData: Uint8Array | null;
+		try {
+			sizeData = await options.get(metaKey);
+		} catch {
+			return VFS.SQLITE_CANTOPEN;
+		}
 
 		let size: number;
 
@@ -619,9 +851,37 @@ class SqliteSystem implements SqliteVfsRegistration {
 				return VFS.SQLITE_IOERR;
 			}
 		} else if (flags & VFS.SQLITE_OPEN_CREATE) {
-			// File doesn't exist, create it
-			size = 0;
-			await options.put(metaKey, encodeFileMeta(size));
+			if (fileTag === FILE_TAG_MAIN) {
+				// Pre-write a valid empty database page so SQLite sees
+				// dbSize > 0 on first read. This enables BATCH_ATOMIC
+				// from the very first write transaction. Without this,
+				// SQLite's pager opens a real journal file for the first
+				// write (because jrnlBufferSize returns a positive value
+				// when dbSize == 0), and with locking_mode=EXCLUSIVE that
+				// real journal is never closed, permanently disabling
+				// batch atomic writes.
+				//
+				// The page is generated by scripts/generate-empty-header.ts
+				// using the same wa-sqlite WASM binary we ship.
+				const chunkKey = getChunkKey(fileTag, 0);
+				size = EMPTY_DB_PAGE.length;
+				try {
+					await options.putBatch([
+						[chunkKey, EMPTY_DB_PAGE],
+						[metaKey, encodeFileMeta(size)],
+					]);
+				} catch {
+					return VFS.SQLITE_CANTOPEN;
+				}
+			} else {
+				// Sidecar files (journal, WAL, SHM) start empty.
+				size = 0;
+				try {
+					await options.put(metaKey, encodeFileMeta(size));
+				} catch {
+					return VFS.SQLITE_CANTOPEN;
+				}
+			}
 		} else {
 			// File doesn't exist and we're not creating it
 			return VFS.SQLITE_CANTOPEN;
@@ -636,6 +896,9 @@ class SqliteSystem implements SqliteVfsRegistration {
 			metaDirty: false,
 			flags,
 			options,
+			batchMode: false,
+			dirtyBuffer: null,
+			savedFileSize: 0,
 		});
 
 		// Set output flags to the actual flags used.
@@ -650,17 +913,22 @@ class SqliteSystem implements SqliteVfsRegistration {
 			return VFS.SQLITE_OK;
 		}
 
-		// Delete-on-close files should skip metadata flush because the file will
-		// be removed immediately.
-		if (file.flags & VFS.SQLITE_OPEN_DELETEONCLOSE) {
-			await this.#delete(file.path);
+		try {
+			// Delete-on-close files should skip metadata flush because the file
+			// will be removed immediately.
+			if (file.flags & VFS.SQLITE_OPEN_DELETEONCLOSE) {
+				await this.#delete(file.path);
+			} else if (file.metaDirty) {
+				await file.options.put(
+					file.metaKey,
+					encodeFileMeta(file.size),
+				);
+				file.metaDirty = false;
+			}
+		} catch {
+			// Always clean up the file handle even if the KV operation fails.
 			this.#openFiles.delete(fileId);
-			return VFS.SQLITE_OK;
-		}
-
-		if (file.metaDirty) {
-			await file.options.put(file.metaKey, encodeFileMeta(file.size));
-			file.metaDirty = false;
+			return VFS.SQLITE_IOERR;
 		}
 
 		this.#openFiles.delete(fileId);
@@ -683,7 +951,7 @@ class SqliteSystem implements SqliteVfsRegistration {
 			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);
@@ -700,19 +968,44 @@ class SqliteSystem implements SqliteVfsRegistration {
 
 		// Calculate which chunks we need to 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,
+		);
 
-		// Fetch all needed chunks
+		// Fetch needed chunks, checking dirty buffer first in batch mode.
 		const chunkKeys: Uint8Array[] = [];
+		const chunkIndexToBuffered: Map<number, Uint8Array> = new Map();
 		for (let i = startChunk; i <= endChunk; i++) {
+			// In batch mode, serve from dirty buffer if available.
+			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: (Uint8Array | null)[];
+		try {
+			kvChunks =
+				chunkKeys.length > 0
+					? await options.getBatch(chunkKeys)
+					: [];
+		} catch {
+			return VFS.SQLITE_IOERR_READ;
+		}
+
+		// Re-read HEAPU8 after await to defend against buffer detachment
+		// from memory.grow() that may have occurred during getBatch.
+		data = this.#module.HEAPU8.subarray(pData, pData + iAmt);
 
 		// Copy data from chunks to output buffer
+		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;
 
 			// Calculate the range within this chunk
@@ -729,7 +1022,10 @@ class SqliteSystem implements SqliteVfsRegistration {
 				const destStart = chunkOffset + readStart - iOffset;
 
 				if (sourceEnd > sourceStart) {
-					data.set(chunkData.subarray(sourceStart, sourceEnd), destStart);
+					data.set(
+						chunkData.subarray(sourceStart, sourceEnd),
+						destStart,
+					);
 				}
 
 				// Zero-fill if chunk is smaller than expected
@@ -772,7 +1068,7 @@ class SqliteSystem implements SqliteVfsRegistration {
 			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;
@@ -788,6 +1084,34 @@ class SqliteSystem implements SqliteVfsRegistration {
 		const startChunk = Math.floor(iOffset / CHUNK_SIZE);
 		const endChunk = Math.floor((iOffset + writeLength - 1) / CHUNK_SIZE);
 
+		// Batch mode: buffer pages in dirtyBuffer instead of writing to KV.
+		// COMMIT_ATOMIC_WRITE flushes the buffer in a single putBatch.
+		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,
+				);
+				// .slice() creates an independent copy that won't be
+				// invalidated by memory.grow() after an await.
+				file.dirtyBuffer.set(
+					i,
+					data.subarray(sourceStart, sourceEnd).slice(),
+				);
+			}
+
+			// Update file size if write extends the file
+			const newSize = Math.max(file.size, writeEndOffset);
+			if (newSize !== file.size) {
+				file.size = newSize;
+				file.metaDirty = true;
+			}
+
+			return VFS.SQLITE_OK;
+		}
+
 		interface WritePlan {
 			chunkKey: Uint8Array;
 			chunkOffset: number;
@@ -810,7 +1134,8 @@ class SqliteSystem implements SqliteVfsRegistration {
 				0,
 				Math.min(CHUNK_SIZE, file.size - chunkOffset),
 			);
-			const needsExisting = writeStart > 0 || existingBytesInChunk > writeEnd;
+			const needsExisting =
+				writeStart > 0 || existingBytesInChunk > writeEnd;
 			const chunkKey = this.#chunkKey(file, i);
 			let existingChunkIndex = -1;
 			if (needsExisting) {
@@ -826,9 +1151,19 @@ class SqliteSystem implements SqliteVfsRegistration {
 			});
 		}
 
-		const existingChunks = chunkKeysToFetch.length > 0
-			? await options.getBatch(chunkKeysToFetch)
-			: [];
+		let existingChunks: (Uint8Array | null)[];
+		try {
+			existingChunks =
+				chunkKeysToFetch.length > 0
+					? await options.getBatch(chunkKeysToFetch)
+					: [];
+		} catch {
+			return VFS.SQLITE_IOERR_WRITE;
+		}
+
+		// Re-read HEAPU8 after await to defend against buffer detachment
+		// from memory.grow() that may have occurred during getBatch.
+		data = this.#module.HEAPU8.subarray(pData, pData + iAmt);
 
 		// Prepare new chunk data
 		const entriesToWrite: [Uint8Array, Uint8Array][] = [];
@@ -841,7 +1176,9 @@ class SqliteSystem implements SqliteVfsRegistration {
 			// Create new chunk data
 			let newChunk: Uint8Array;
 			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);
@@ -850,13 +1187,17 @@ class SqliteSystem implements SqliteVfsRegistration {
 			// Copy data from input buffer to chunk
 			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]);
 		}
 
 		// Update file size if we wrote past the end
 		const previousSize = file.size;
+		const previousMetaDirty = file.metaDirty;
 		const newSize = Math.max(file.size, writeEndOffset);
 		if (newSize !== previousSize) {
 			file.size = newSize;
@@ -867,7 +1208,13 @@ class SqliteSystem implements SqliteVfsRegistration {
 		}
 
 		// Write all chunks and metadata
-		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;
 		}
@@ -894,9 +1241,17 @@ class SqliteSystem implements SqliteVfsRegistration {
 		// If truncating to larger size, just update metadata
 		if (size >= file.size) {
 			if (size > file.size) {
+				const previousSize = file.size;
+				const previousMetaDirty = file.metaDirty;
 				file.size = size;
 				file.metaDirty = true;
-				await options.put(file.metaKey, encodeFileMeta(file.size));
+				try {
+					await options.put(file.metaKey, encodeFileMeta(file.size));
+				} catch {
+					file.size = previousSize;
+					file.metaDirty = previousMetaDirty;
+					return VFS.SQLITE_IOERR_TRUNCATE;
+				}
 				file.metaDirty = false;
 			}
 			return VFS.SQLITE_OK;
@@ -908,33 +1263,52 @@ class SqliteSystem implements SqliteVfsRegistration {
 		const lastChunkToKeep = Math.floor((size - 1) / CHUNK_SIZE);
 		const lastExistingChunk = Math.floor((file.size - 1) / CHUNK_SIZE);
 
-		// Delete chunks beyond the new size
-		const keysToDelete: Uint8Array[] = [];
-		for (let i = lastChunkToKeep + 1; i <= lastExistingChunk; i++) {
-			keysToDelete.push(this.#chunkKey(file, i));
+		// Update metadata first so a crash leaves orphaned chunks (wasted
+		// space) rather than metadata pointing at missing chunks (corruption).
+		const previousSize = file.size;
+		const previousMetaDirty = file.metaDirty;
+		file.size = size;
+		file.metaDirty = true;
+		try {
+			await options.put(file.metaKey, encodeFileMeta(file.size));
+		} catch {
+			file.size = previousSize;
+			file.metaDirty = previousMetaDirty;
+			return VFS.SQLITE_IOERR_TRUNCATE;
 		}
+		file.metaDirty = false;
 
-		if (keysToDelete.length > 0) {
-			await options.deleteBatch(keysToDelete);
-		}
+		// Remaining operations clean up old chunk data. Metadata already
+		// reflects the new size, so failures here leave orphaned/oversized
+		// chunks that are invisible to SQLite (xRead clips to file.size).
+		try {
+			// Truncate the last kept chunk if needed
+			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);
+				}
+			}
 
-		// Truncate the last kept chunk if needed
-		if (size > 0 && size % CHUNK_SIZE !== 0) {
-			const lastChunkKey = this.#chunkKey(file, lastChunkToKeep);
-			const lastChunkData = await options.get(lastChunkKey);
+			// Delete chunks beyond the new size
+			const keysToDelete: Uint8Array[] = [];
+			for (let i = lastChunkToKeep + 1; i <= lastExistingChunk; i++) {
+				keysToDelete.push(this.#chunkKey(file, i));
+			}
 
-			if (lastChunkData && lastChunkData.length > size % CHUNK_SIZE) {
-				const truncatedChunk = lastChunkData.subarray(0, size % CHUNK_SIZE);
-				await options.put(lastChunkKey, truncatedChunk);
+			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;
 		}
 
-		// Update file size
-		file.size = size;
-		file.metaDirty = true;
-		await options.put(file.metaKey, encodeFileMeta(file.size));
-		file.metaDirty = false;
-
 		return VFS.SQLITE_OK;
 	}
 
@@ -944,7 +1318,11 @@ class SqliteSystem implements SqliteVfsRegistration {
 			return VFS.SQLITE_OK;
 		}
 
-		await file.options.put(file.metaKey, encodeFileMeta(file.size));
+		try {
+			await file.options.put(file.metaKey, encodeFileMeta(file.size));
+		} catch {
+			return VFS.SQLITE_IOERR_FSYNC;
+		}
 		file.metaDirty = false;
 		return VFS.SQLITE_OK;
 	}
@@ -960,8 +1338,16 @@ class SqliteSystem implements SqliteVfsRegistration {
 		return VFS.SQLITE_OK;
 	}
 
-	async xDelete(_pVfs: number, zName: number, _syncDir: number): Promise<number> {
-		await this.#delete(this.#module.UTF8ToString(zName));
+	async xDelete(
+		_pVfs: number,
+		zName: number,
+		_syncDir: number,
+	): Promise<number> {
+		try {
+			await this.#delete(this.#module.UTF8ToString(zName));
+		} catch {
+			return VFS.SQLITE_IOERR_DELETE;
+		}
 		return VFS.SQLITE_OK;
 	}
 
@@ -989,7 +1375,9 @@ class SqliteSystem implements SqliteVfsRegistration {
 			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(
@@ -1010,7 +1398,12 @@ class SqliteSystem implements SqliteVfsRegistration {
 		}
 
 		const compactMetaKey = getMetaKey(resolved.fileTag);
-		const metaData = await resolved.options.get(compactMetaKey);
+		let metaData: Uint8Array | null;
+		try {
+			metaData = await resolved.options.get(compactMetaKey);
+		} catch {
+			return VFS.SQLITE_IOERR_ACCESS;
+		}
 
 		// Set result: 1 if file exists, 0 otherwise
 		this.#writeInt32(pResOut, metaData ? 1 : 0);
@@ -1032,15 +1425,95 @@ class SqliteSystem implements SqliteVfsRegistration {
 		return VFS.SQLITE_OK;
 	}
 
-	xFileControl(_fileId: number, _flags: number, _pArg: number): number {
-		return VFS.SQLITE_NOTFOUND;
+	async xFileControl(
+		fileId: number,
+		flags: number,
+		_pArg: number,
+	): Promise<number> {
+		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 = 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;
+
+				// Dynamic limit: if metadata is dirty, we need one slot for it.
+				// If metadata is not dirty (file.size unchanged), all slots are available for pages.
+				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;
+				}
+
+				// Build entries array from dirty buffer + metadata.
+				const entries: [Uint8Array, Uint8Array][] = [];
+				if (dirtyBuffer) {
+					for (const [chunkIndex, data] of dirtyBuffer) {
+						entries.push([this.#chunkKey(file, chunkIndex), data]);
+					}
+					dirtyBuffer.clear();
+				}
+				if (file.metaDirty) {
+					entries.push([file.metaKey, encodeFileMeta(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: number): number {
-		return 0;
+		return SQLITE_IOCAP_BATCH_ATOMIC;
 	}
 
-	xFullPathname(_pVfs: number, zName: number, nOut: number, zOut: number): number {
+	xFullPathname(
+		_pVfs: number,
+		zName: number,
+		nOut: number,
+		zOut: number,
+	): number {
 		const path = this.#module.UTF8ToString(zName);
 		const bytes = TEXT_ENCODER.encode(path);
 		const out = this.#module.HEAPU8.subarray(zOut, zOut + nOut);
@@ -1127,5 +1600,5 @@ function delegalize(lo32: number, hi32: number): number {
 	if (hi === MAX_FILE_SIZE_HI32 && lo > MAX_FILE_SIZE_LO32) {
 		return -1;
 	}
-	return (hi * UINT32_SIZE) + lo;
+	return hi * UINT32_SIZE + lo;
 }