dbxlite is a browser-native SQL analytics application that runs entirely in your browser. No servers, no uploads, no compromises on privacy. Here's how we built it.
Overview
At its core, dbxlite leverages DuckDB compiled to WebAssembly to provide a full-featured analytical database engine directly in your browser. This architecture enables powerful SQL queries on local files without any data leaving your machine.
| Connector | Status | Architecture | Notes |
|---|---|---|---|
| DuckDB | Implemented | Browser-only WASM | No server required |
| BigQuery | Implemented | Direct to GCP | CORS natively supported |
| Snowflake | Planned | Via CORS proxy | Future release |
Key Technical Highlights
- DuckDB runs entirely in-browser using WebAssembly (~105MB bundle)
- File handle persistence - local file references survive browser restarts
- BigQuery connects directly to Google APIs (no proxy needed)
- Type normalization unifies data types across connectors
- Memory-safe streaming with backpressure mechanisms
System Architecture
The application follows a layered architecture with clear separation between the UI, query routing, connector implementations, and data transformation layers.
Local Storage Architecture
dbxlite uses multiple storage mechanisms to handle different file types and maintain state across sessions.
| Storage Type | Persists | Location | Purpose |
|---|---|---|---|
| File handles | Yes | IndexedDB | References to local files via File System Access API |
| User settings | Yes | localStorage | Theme, formatting, editor preferences |
| DuckDB database | No | Browser RAM | Query execution engine - tables lost on refresh |
| Uploaded buffers | No | DuckDB virtual FS | Files copied to memory during session |
| Remote URLs | Yes* | localStorage | URL references only, files fetched on-demand |
WebAssembly & DuckDB
WebAssembly enables near-native performance in browsers by providing a binary instruction format that can be decoded and executed efficiently.
| Aspect | Traditional JS | WebAssembly |
|---|---|---|
| Format | Text (parsed) | Binary (decoded) |
| Speed | JIT compilation | Pre-compiled |
| Performance | Variable (GC pauses) | Predictable |
DuckDB WASM is the full DuckDB database engine compiled to WebAssembly - approximately 105MB with all features. It runs entirely in the browser with no server component.
WASM Bundle Selection
dbxlite uses the EH (Exception Handling) bundle for maximum compatibility:
| Bundle | Pros | Cons |
|---|---|---|
| EH (Selected) | Works everywhere, no special headers | Single-threaded |
| MVP | Smallest size | Limited features |
| COI | Multi-threaded, fastest | Requires COOP/COEP headers |
Worker Architecture
All DuckDB operations run in a dedicated Web Worker to keep the main thread responsive. The worker communicates with the main thread using a structured message protocol.
Message Types
Worker → Main Thread:
inited- Worker initialized and readyjson-schema- Result schema informationjson/arrow- Result data chunksquery-stats- Execution statisticsdone- Query execution completeerror- Error occurred
Main Thread → Worker:
init- Initialize with bundle pathsrun- Execute query with optionsregister_file- Register uploaded filecancel- Cancel running queryack- Acknowledge chunk (backpressure)
Memory Management
Careful memory management is essential when running a database engine in the browser.
| Setting | Value | Purpose |
|---|---|---|
memory_limit | -1 | Unlimited (browser limits) |
threads | 1 | Reduce fragmentation |
MAX_OUTSTANDING | 2 | Backpressure limit |
MAX_CHUNK_BYTES | 5MB | JSON chunk size |
GC_INTERVAL | 15s | Periodic cleanup |
BigQuery Integration
BigQuery integration connects directly to Google APIs without requiring a proxy server. Google's APIs support CORS natively, enabling secure browser-to-API communication.
React Application Structure
The frontend is built with React, using a provider-based architecture for state management and a collection of custom hooks for business logic.
Key Custom Hooks
| Hook | Purpose |
|---|---|
useTabManager | Tab CRUD operations and persistence |
useQueryExecution | Query execution, streaming, and cancellation |
useFileOperations | File open, save, and SQL insert operations |
useFileReload | Restore file handles from IndexedDB on app load |
useKeyboardShortcuts | Global keyboard bindings and shortcuts |
Getting Started
Ready to try dbxlite? Head over to sql.dbxlite.com and start querying your data. No signup required, no data uploaded - just powerful SQL in your browser.
The project is open source. Check out the code on GitHub.