WebDB/ Early Prototype

The Browser-Native
Relational Database

An ultra-lean <50 KB WebAssembly engine with true SQL power, type-safe queries, and instant persistence over OPFS & IndexedDB. Zero server roundtrips, no complex headers.

View Specs→GitHub

< 50 KB

Ultra lightweight

90%+ smaller than SQLite Wasm

OPFS + IDB

Universal Storage

Fast OPFS in Workers, seamless Safari fallback

60 FPS

Non-Blocking UI

Zero UI stutter with async event-loop execution

Zero Config

Cross-Browser Ready

No COOP/COEP headers required anywhere

Built for the Modern Browser Experience

WebDB bridges the gap between fragile key-value stores and heavyweight desktop Wasm ports. Here is where it excels in production web applications:

Offline-First Web Apps & PWAs

Eliminate spinners and network stalls. Render instantly from local storage, mutate data offline with full ACID safety, and seamlessly synchronize changes when reconnected.

Local-First Productivity & SaaS

Build Notion, Linear, or Figma-grade creative suites where user documents reside directly in the client. Multi-tab concurrency is safely coordinated via Web Locks without server trips.

Client-Side AI & Vector Search

Store high-dimensional vector embeddings generated by WebLLM or Transformers.js. Perform instant similarity searches with 128-bit Wasm SIMD directly in the browser for local RAG.

Query Remote Data without Full Downloads

Host multi-gigabyte catalogs or archives on S3 or Cloudflare R2. Query precise records on demand via HTTP Range requests without downloading the entire database.

Privacy-Centric Personal Vaults

Healthcare portals, password managers, financial ledgers, and journaling apps where customer data must never touch your backend unencrypted. The database lives and dies on the client device.

In-Browser Analytics & Dashboards

Offload complex multi-table aggregations, filtering, and joins from your API servers directly into the user's browser. Transform raw CSVs or JSON payloads into relational tables on the fly.

A powerful <50 KB database without sacrificing features

By compiling type-safe TypeScript queries directly into engine bytecode, WebDB removes the bloated C SQL parser—delivering a full relational engine in under 50 KB.

┌┐└┘Query Builder

┌┐└┘SQL string

┌┐└┘AST tree

┌┐└┘Byte Codes

Redundant string formatting & AST parsing inside Wasm (slow + 2.5 MB bundle bloat)

Skipping the SQL Middleman

Ported desktop databases serialize queries into SQL text strings only to re-parse them inside Wasm using a heavy C engine. WebDB compiles TypeScript queries directly into bytecode, cutting out the runtime parser and shaving megabytes of binary bloat.

Zero Server Headers Required

Desktop engines rely on pthread shims requiring strict COOP/COEP isolation headers that break OAuth popups and Stripe payment frames. WebDB is event-loop native, coordinating multi-tab concurrency through navigator.locks on any static host or CDN.

How WebDB Differs from Ported Desktop Engines

Web developers shouldn't have to compromise between the awkward cursors of IndexedDB and multi-megabyte C/C++ desktop engines ported with Emscripten. WebDB rethinks the relational database engine specifically for web platform runtime constraints.

Capability	Legacy Engines (SQLite / PGlite)	WebDBWeb-Native
Bundle Size	1 MB – 5 MB+ Heavy initial download dragging full desktop shims	< 50 KB Instant startup, optimized strictly for web bundles
I/O Model	Asyncify Simulation Simulates synchronous disk I/O, risking UI frame drops	Native Non-Blocking Pure async execution pipeline designed for IndexedDB & OPFS
Server Headers	COOP / COEP Required Breaks external OAuth popups, Stripe, and embeds	Zero Headers Runs on any static host, CDN, or PWA without config
Platform Mindset	OS-First Mindset Assumes POSIX disk, threads, and bundles redundant C code	Browser-First Mindset Built ground-up around web primitives: `Intl`, `crypto`, & async I/O
Custom Storage (VFS)	Complex C / Wasm Shims Requires low-level C structs and Emscripten bridging	Pure TypeScript Implement a clean async interface directly in plain TS
Memory Model	Fixed Linear Heap Monolithic upfront allocation with GC copy overhead	Adaptive Page Pool Dynamic LRU cache that respects low-memory mobile tabs

Universal Storage Built for the Web Platform

Desktop C databases assume synchronous, blocking disk calls. WebDB is inherently asynchronous—it requests storage pages without locking up JavaScript, resuming execution the moment data arrives.

OPFS Storage Adapter

Direct access to the browser's Origin Private File System using FileSystemSyncAccessHandle inside dedicated Web Workers. Delivers blazing-fast read/write throughput for high-frequency persistence.

IndexedDB Storage Adapter

Universal browser fallback running everywhere, including main thread contexts and mobile Safari on iOS. Stores binary database pages with full ACID transactional guarantees.

In-Memory Storage Adapter

Ultra-fast volatile page store backed by flat typed arrays. Delivers sub-millisecond query execution for unit test fixtures, transient UI states, and isolated sandbox analytics.

HTTP Range Streaming Adapter

Stream read-only databases hosted on static CDNs or S3 buckets. Fetches targeted pages on-demand using standard HTTP Range: bytes=X-Y headers with zero pre-downloading overhead.

EXTENSIBLE ARCHITECTURE

Build Your Own VFS Layer in Minutes

WebDB decouples the query engine completely from physical disk I/O. Implementing a custom storage layer is as simple as defining two asynchronous methods: readPage(pageId) and writePage(pageId, buffer). Easily connect WebDB to Cloudflare KV, Durable Objects, WebRTC peer swarms, or custom encrypted stores without touching engine internals.

custom-vfs.ts

class CloudflareKvVfs {
  
  async readPage(id) {
    return await kv.get("p" + id);
  }

  async writePage(id, bytes) {
    await kv.put("p" + id, bytes);
  }

}

REAL-WORLD USE CASE SPOTLIGHT

Query a 5GB Database on S3 Over 16KB of Network

Instead of downloading the entire database to the client, HttpVfsAdapter turns static object storage into a serverless query engine. When your query executes, WebDB inspects its B+Tree indexes and requests only the precise 4KB pages required via standard HTTP Range headers.

1. CLIENT QUERYdb.from("products")
.where("sku", "=", "A900")

4KB RANGE REQUEST

2. S3 / CDN BYTE-RANGE FETCHGET /catalog.webdb
Range: bytes=12288-16383

STREAMED 4KB PAGE

3. INSTANT IN-MEMORY CACHELeaf page parsed & row emitted in 0.1ms

http-streaming.tsHTTP VFS

import { WebDB, HttpVfsAdapter } from "@webdb/core";
 
const httpStorage = new HttpVfsAdapter(
  "https://example.com/ecommerce.db"
);
 
// 1. Mount remote db hosted on CDN / S3 / R2
const db = await WebDB.open({
  vfs: httpStorage,
});
 
// 2. Instant response: 
// only ~16Kb are transferred over the wire.
const products = await db
  .from("products")
  .where("category", "=", "Electronics")
  .where("in_stock", "=", true)
  .orderBy("rating", "desc")
  .limit(10)
  .toArray();
 
console.table(products);

Engineered for Resilient Web Applications

A relational database built for extreme memory efficiency and predictable browser execution.

Pluggable Storage Adapters

Co-equal support for bare-metal OPFS SyncAccessHandles in workers and universal IndexedDB in main thread/mobile Safari. Supports on-demand HTTP Range Request page streaming directly from S3/CDN.

Non-Blocking Query Engine

Designed specifically for the WebAssembly runtime to execute complex joins and aggregations smoothly without stack overflows or freezing the browser tab.

Crash-Proof Local Transactions

Write-Ahead Logging with atomic commits guarantees full ACID safety. Your data stays 100% resilient against accidental tab closes or sudden browser crashes.

Native UUIDv7 & ULID Support

Stored as compact 16-byte fixed binary slices (58% smaller than text UUIDs). Time-ordered UUIDv7 and ULID append sequentially with near-zero index fragmentation.

Seamless JavaScript Functions (UDFs)

Register arbitrary JS functions callable directly from queries. Run native browser regex and date comparisons at near-native speeds through shared memory.

Vector & Full-Text Hybrid Search

Designed to support 128-bit Wasm SIMD vector embeddings (VECTOR), Okapi BM25 full-text search with Intl.Segmenter, and transparent AES-256-GCM page encryption.

Simple, Type-Safe API

Explore how schema creation, queries, transactions, and execution plan inspection work in practice.

// 1. Define relational schema with typed columns & indexes
await db.createTable("users", [
  { name: "id", type: "UUID", flags: { primaryKey: true } },
  { name: "name", type: "TEXT", flags: { notNull: true } },
  { name: "age", type: "INT32" },
  { name: "score", type: "FLOAT64" },
]);
 
await db.createIndex("users", "score");
 
// 2. Query with type-safe fluent builder
const topScorers = await db
  .from("users")
  .where("age", ">=", 21)
  .whereNotNull("score")
  .orderBy("score", "desc")
  .limit(10)
  .toArray();
 
console.table(topScorers);