Persistent Databases in the Browser with DuckDB-Wasm and OPFS

DuckDB-Wasm can now open a persistent database file in the browser's Origin Private File System (OPFS). This allows data to survive page reloads and browser restarts. Previously, everything lived in the Wasm heap and vanished when the tab closed, requiring custom serialization and storage solutions. With the introduction of OPFS in modern browsers (since March 2023), DuckDB-Wasm can utilize it as a storage backend.

To open a database file in OPFS, use the opfs:// path in the database open call. The resulting .duckdb file contains a write-ahead log and checkpoints, ensuring data persistence. Note that the npm latest build (1.33.1-dev57.0) creates OPFS files but does not write to them. Install version 1.32.0 or later (1.33.1-dev64.0 or later) to achieve persistence.

After reloading the page, a CREATE TABLE IF NOT EXISTS statement finds the existing table, an INSERT adds a second row, and a COUNT prints 2. There is no need for synchronization or exporting data; the opfs:// prefix tells DuckDB-Wasm to resolve the path against the origin's private file system. The resulting .duckdb file can be opened with the CLI or Python client.

The OPFS file can also serve as a cache for remote datasets, with DuckDB-Wasm reading the remote file via HTTP range requests and caching derived results in OPFS. To write to opfs:// paths from SQL, add the opfs: { fileHandling: "auto" } option when opening the database. DuckDB-Wasm handles the data persistence using a write-ahead log and periodic checkpoints, similar to how it operates on local disk.

However, due to browser tabs often being terminated abruptly, it's recommended to call CHECKPOINT after writes that cannot be lost. Regular checkpointing after batches of user edits ensures data safety.