← Work

plateauDB

A browser database on OPFS with an IndexedDB-compatible API, where query time plateaus as data grows

Role
Sole designer and builder
Status
0.1.0 released
Period
Nov 2026

Rust · WebAssembly · OPFS · Web Workers · TypeScript · Roaring bitmaps · Playwright · Next.js

Problem

IndexedDB is the only real database a web app gets, and it is slow where client apps hurt most. Every request is asynchronous, every transaction has overhead, and a query on several fields at once (this team, these states, newest first) has to be shaped into one compound index or merged by hand. As the local table grows, those queries grow with it.

The trigger was a report that Linear had built a Rust database on OPFS behind an IndexedDB-shaped API. My prior-art research could not find the post, so its claims stayed unverified. What the research did find: published OPFS-over-IndexedDB gains are 2-6x, SQLite and Postgres builds for the browser speak SQL rather than the IndexedDB API, and no Rust engine was both IndexedDB-compatible and OPFS-native. That gap was the project.

What it does

plateau is an IDBFactory. Code written for indexedDB takes it unchanged: databases, object stores, unique and multiEntry indexes, key ranges, cursors, auto-commit transactions and the usual events. Install it with npm install plateaudb.

Declare the fields you filter or sort on as typed columns and you get one addition, store.query, with eq, in and range filters, an orderBy, a limit and a count. A store without columns is a generic store and takes any value IndexedDB can clone, except Blob, File, ImageData and Error.

Several tabs share one database: one tab leads and holds the files, the others route their calls to it, and plateau.whenLeader() lets an app hold one server stream per origin.

Architecture

App code in any tab
IDBFactory, store.query
Leader election
Web Locks, BroadcastChannel
IndexedDB-compatible API
TypeScript, typed columns and generic values
Engine and query planner
Rust to WASM, dedicated worker
Page cache with memory budget
LRU, 64 MiB default
OPFS files
FileSystemSyncAccessHandle
One leader tab owns the worker and the files; other tabs forward their calls to it

Indexes. Every bitmap-indexed column keeps a roaring bitmap of internal row ids per value. The primary key is stored as sorted keys and row ids in chunks. An ordered index on a timestamp can be grouped by a bitmap column, so "team 7, newest first" or "team 7, changed since T, count" walks one group instead of the table. A multi-key query intersects bitmaps, then walks the ordered index until it has its limit.

Storage. The engine runs in a dedicated worker because only workers get synchronous OPFS access handles. The file opens lazily: it reads what the first query needs, not the whole file. Updates and deletes go into segments with per-segment delete bitmaps, and compaction merges them.

Loading. The worker and the WASM are separate files named with new URL(..., import.meta.url), so Vite and Next.js copy them with no config. It does not use SharedArrayBuffer, so it needs no COOP/COEP headers.

Key decisions

  1. A kill rule before the build. Before measuring anything I wrote down what would end the project: if SQLite-WASM on OPFS with matching indexes got within 2x of my engine, there was no reason for a new engine. Every milestone was scored against IndexedDB and SQLite with identical results checked across engines.

  2. Stay in the worker. Synchronous OPFS reads take about 1 µs from a worker handle and about 60 µs from the main thread in Chromium. I spiked a main-thread reader to win the first query on a fresh page; it measured 12.5 ms in Chromium against IndexedDB's 4.6, so I kept the worker and accepted the start-up cost as a known limit.

  3. Hybrid values. Declared fields become typed columns with real indexes; everything else is stored with the row. That keeps IndexedDB code working on day one and makes the speed opt-in, field by field.

  4. Crash safety tested by tearing writes. A crash loop cuts the file at 1,410 points across a save, a compaction and a save into freed space, and every reopen must land on exactly the old or the new state.

  5. A fresh public repository. The development history carried internal references, so the public source is one clean commit rather than the private repo flipped public.

Numbers

Medians in ms, warm, at 1M rows: headless Chromium 158 and WebKit 27.2 on one Apple M5 Max, 20 runs each. The baselines are native IndexedDB with the best compound indexes a careful developer would declare, and SQLite-WASM on OPFS (opfs-sahpool) behind a thin layer that takes the same query object. plateauDB is measured through its IndexedDB API on a store with declared columns. Every engine returned identical results.

WorkloadChromium IDBChromium SQLiteChromium plateauDBWebKit IDBWebKit SQLiteWebKit plateauDB
Q1 team, state IN, newest 500.7730.2430.0780.840.320.14
Q2 assignee, label, priority16.31.1530.18517.841.20.28
Q3 team, updated since T, count48.150.2280.031.090.260.06
Q4 team, state IN, priority, newest 503.4330.2630.0856.070.330.14
1,000 point gets8.9185.7571.85517.776.42.41
Reopen0.7721.2070.1120.961.530.23
Fresh page, first query3.40728.166.2874.5245.1710.14

The plateau is the point. In Chromium, plateauDB's Q1 takes 0.09 ms at 10k rows and 0.078 at 1M; native IndexedDB's Q2 goes from 0.147 to 16.3 over the same range. Committing 1,000 replaced and 1,000 deleted rows at 1M takes about 9 ms in both browsers, against 85 and 266 ms for IndexedDB.

The last row is where it loses: a fresh page starts a worker and compiles WASM before the first answer.

What broke

  • It failed its own rule, twice. The first run was a kill by the rule as written: SQLite landed within 2x on the ordered and count queries. The growth bar was also wrong, since no engine can stay flat on a query whose answer grows with the table. I rewrote the rule with a fixed-size query and per-row growth, and said in the record that it was written after seeing the first numbers. The second run was still a kill (SQLite/plateau median 1.83x and 1.44x). One more pass, with a stated cause, cleared 2x in Chromium (2.31x) and Q3 at 1M fell from 0.43 to 0.015 ms.
  • Cold open was 278-381 ms against SQLite's 27-49 at 1M, because opening decoded the whole file and rebuilt the primary key. Lazy paged open brought it to 5.0 ms in Chromium.
  • Compaction ate memory. At 1M rows it left the WASM heap at about 375 MB and the file at twice its size. The memory budget brought peak WASM memory to 58.9 MiB, and generic-store files went from 2,872 MiB to 308.
  • A shortcut in the first API. Index key paths were in-memory maps rebuilt by a full scan on first use, which quietly undid lazy open. It was sent back and rebuilt as persisted indexes.
  • Firefox would not launch under Playwright on the test Mac, so it has never been measured.

Results

plateaudb 0.1.0 is on npm under MIT, with the source at github.com/jagadhis/plateaudb and the benchmarks on the project site. Installed from the registry into a fresh Vite production build, it opens, writes, reads, queries by index and walks cursors in Chromium 158 and WebKit 27.2.

It passes 84 of 85 WPT-style IndexedDB conformance tests in both browsers, against 85 of 85 for native IndexedDB; the one miss is a key stored as -0 coming back as 0. In a live-sync example, with 50 edits made during a forced disconnect, no change was missed across reconnect or leader crash, and a new leader was streaming again 10-16 ms after the old tab closed.

What I'd change

  • Fresh-page start-up. Through the API the first query on a new page costs 8-13 ms against native 4-5 ms. Reopens and warm queries win; the first impression does not.
  • Native fallback. 0.1.0 does not fall back to the browser's IndexedDB where OPFS sync access is missing, and in a WebKit ephemeral context open fails with UnknownError. The fallback is being built, not shipped.
  • Coverage. One machine, headless, two engines. Firefox, real Safari and phones are untested, and Dexie on top is a goal, not a result.
  • Generic stores gain less. Without declared columns, Q2 at 1M in Chromium is 8.203 ms against native 16.3: faster, but nowhere near the typed store.
  • The public mirror is synced by hand. Each release has to be copied from the private repo, which is a step I will forget eventually.
Next case studyTachyon →