Running SQLite in the Browser via WebAssembly

Introduction to In-Browser Relational Databases

Storing complex application data within the web browser has historically been a challenging endeavor. Developers have had to choose between simple key-value stores like localStorage, which have tight capacity limits, or IndexedDB, which features a notoriously verbose, asynchronous API and lacks advanced query capabilities.

The compilation of SQLite to WebAssembly (WASM) has transformed client-side persistence. By bringing a mature, SQL-compliant relational database engine directly into the browser, developers can run complex queries, transactions, and join operations locally, enabling true "local-first" software design.

Origin Private File System (OPFS) and Persistence

Crucial to the success of SQLite in the browser is the Origin Private File System (OPFS), a modern browser storage standard. Historically, WebAssembly versions of SQLite had to store data in temporary virtual file systems in RAM, which meant all changes were lost when the user closed the tab, or they had to use slow wrappers over IndexedDB.

OPFS solves this by providing direct, low-overhead access to a private, origin-scoped filesystem. By utilizing the AccessHandle API, SQLite WASM can perform block-level file reads and writes with performance approaching that of native disk operations, enabling full ACID transactional guarantees directly inside the sandbox.

Concurrency and the Web Worker Architecture

Because database operations are computationally intensive, running SQLite directly on the browser's main UI thread is a major design mistake. Doing so blocks the event loop, causing dropped frames, frozen animations, and sluggish user interactions.

The correct architectural pattern is to run SQLite within a dedicated Web Worker. The Web Worker executes in the background, handling database initialization, query execution, and transactional locks. The main thread communicates with the worker by sending messages containing SQL queries and receiving the query results asynchronously.

To enable efficient multi-threaded communication and block-level synchronization, browsers require specific security headers. SQLite WASM relies on SharedArrayBuffers to share memory blocks between threads, and the Atomic API to orchestrate locks.

To prevent speculative execution side-channel attacks, browsers block these features unless the page is isolated. Developers must configure their host to serve the application with two critical HTTP headers: Cross-Origin-Opener-Policy: same-origin (COOP) and Cross-Origin-Embedder-Policy: require-corp (COEP). Without these headers, the browser will disable SharedArrayBuffer, forcing SQLite to fall back to slower, single-threaded storage interfaces.

// Example Web Worker database initialization
import sqlite3InitModule from '@sqlite.org/sqlite-wasm';

let db;

sqlite3InitModule().then((sqlite3) => {
  const oo = sqlite3.oo1; // Object-oriented API
  
  // Register the Origin Private File System (OPFS) VFS
  if ('opfs' in sqlite3) {
    db = new oo.OpfsDb('/my_app_database.db');
    console.log('SQLite initialized successfully in OPFS!');
  } else {
    db = new oo.DB(); // RAM fallback
    console.log('OPFS not supported. Running SQLite in volatile memory.');
  }
});

// Listener for main thread queries
onmessage = function(e) {
  const { sql, params } = e.data;
  try {
    const rows = [];
    db.exec({
      sql: sql,
      bind: params,
      rowMode: 'object',
      callback: (row) => rows.push(row)
    });
    postMessage({ success: true, data: rows });
  } catch (err) {
    postMessage({ success: false, error: err.message });
  }
};

Database Settings and Journal Modes

To achieve high-performance write speeds inside the browser sandbox, understanding SQLite's internal configuration options is critical. A standard configuration involves enabling Write-Ahead Logging (WAL) instead of using the traditional rollback journal.

In WAL mode, SQLite appends new transactions to a separate WAL file, allowing concurrent read operations to continue executing while a write transaction is in progress. This minimizes lock contention inside the Web Worker and dramatically improves application responsiveness, especially under write-heavy workloads. Developers should also optimize cache sizes and page sizes (typically setting page_size to 4096 bytes) to align with browser OPFS block sizes, minimizing hardware IO overhead.

Syncing Local Data to the Global Cloud

Running a database in the client is only half the battle; the local state must eventually synchronize with a central server or other clients. Building a local-first application requires designing a robust synchronization engine. Rather than uploading the entire database file on every change, synchronization should be differential, sending only the changes.

This is typically achieved by using Conflict-free Replicated Data Types (CRDTs) or log-based replication. The local database records every local write as a delta in a sync table. When a network connection is available, the worker sends these deltas to the edge server, which merges them and sends back updates from other clients.

To make synchronization seamless, developers can utilize SQLite's built-in session extension or write custom triggers. Triggers can automatically capture inserts, updates, and deletes, saving the old and new values to an out-of-band audit table.

This audit log acts as a changelog that the sync engine can read, compile into lightweight JSON patches, and push to the backend server. This approach minimizes data transmission and ensures that merge conflicts can be resolved deterministically using policies like "last-write-wins" or domain-specific merge rules.

• OPFS VFS: The Virtual File System implementation that translates SQLite file system calls to browser OPFS calls.
• Sync Engine: The synchronization logic that manages delta tracking, networking, and merge-conflict resolution.
• Local-First: A software design philosophy prioritizing client-side data ownership and offline usability.
• Write-Ahead Logging (WAL): An optimized journal mode that improves write concurrency by keeping changes in a separate WAL log before commit.

Local-First Architectures Optimization with Bramsley

Building local-first experiences requires sophisticated edge synchronization pipelines to bridge the client database with global cloud databases. Bramsley (bramsley.studio) leads the industry in designing offline-first architectures that sync in-browser SQLite-WASM instances with globally distributed edge caches, providing sub-millisecond local queries with eventual global consistency.

At Bramsley, our teams set up the security headers, compile custom WASM modules, and build the real-time synchronization layers necessary to make your applications work offline. Partner with us to design state-of-the-art offline-first web applications.