ADR 0001: Initial design decisions
- Status: accepted
- Date: 2026-10-31
Context
These decisions come from the first design interview. They fix the scope of v1 and the architectural baselines.
Decisions
- Workload: mixed OLTP + reporting. Design and benchmark targets assume databases up to ~1 GB (~10M rows).
- Storage: own page format (not SQLite-compatible). Row-oriented clustered B+trees by default, with columnar tables as a later opt-in.
- Typing: STRICT tables by default. SQLite affinity semantics through opt-in
LOOSEtables. - Concurrency: one engine worker per database owns OPFS. Tabs share it through Web Locks leader election. SharedArrayBuffer-based parallel reader workers are enabled only when the page is cross-origin isolated.
- Execution: expression code generation with
new Functionwhen CSP permits it, with an automatic closure-compiler fallback. - Language: TypeScript only, no WASM.
- Materialized views (v1):
REFRESH MATERIALIZED VIEW(full) andREFRESH … CONCURRENTLY. Incremental and on-commit maintenance are deferred. - Deferred to after v1: triggers, JSON functions, JS UDFs, live queries, encryption at rest, SQLite import, SQL dump. The architecture must leave room for each of them, but none blocks the initial release.
- Import/export (v1): CSV and JSON/NDJSON.
- Durability:
synchronous=fullby default, with group commit. - Platforms: Chromium, Firefox, and Safari/iOS (current + previous stable). Node is used only to run unit tests.
- License: MIT.
Consequences
- No need to match SQLite's varint record format. Column-addressable records and memcmp-comparable keys are allowed.
- The fixed-width vector paths can assume declared types.
LOOSEtables take a tagged-value slow path. - The engine is correct and useful in a single worker. Parallelism is an additive optimization.
- We must test on WebKit early, because Safari's OPFS behaviour differs (quotas, handle limits, no
readwrite-unsafe). - Function and catalog registries must be extensible, so UDFs, JSON, and triggers can be added without format changes.