FlatSQL

Edgesource

FlatSQL

SQL queries over raw FlatBuffer storage.

PolyForm Noncommercial 1.0.0 licensed: free for noncommercial use; commercial use requires a license.

Built on FlatBuffers

Try the live demo View source

tj@edgesource.com

Built for Streaming

No parsing. No conversion. Binary data arrives ready to query.

Raw Streaming Ingest

Pipe size-prefixed FlatBuffers directly to the engine. File identifiers route to tables automatically.

File ID Routing

Each FlatBuffer's 4-byte identifier routes it to the correct table. No external metadata needed.

Inline Index Building

B-tree indexes built during streaming ingest. No separate indexing phase. Query immediately.

Zero-Copy Access

Direct pointer access to FlatBuffer data. No deserialization. Maximum performance.

Overview

A database built for the real-time, decentralized web.

Why FlatSQL?

Modern apps receive data from everywhere

Sensors
P2P Networks
Edge Devices
Cloud APIs
Streams

Traditional Database

1 Receive binary data
2 Parse to objects
3 Convert to SQL types
4 Insert rows
5 Query → serialize back
VS

FlatSQL

1 Receive binary data
2 Store as-is
3 Query directly

FlatSQL keeps data in its native FlatBuffer format, routes it by source, and queries it with SQL. Ideal for isomorphic applications where the same code runs in browsers, workers, and servers—all sharing the same binary protocol.

Distributed IoT
Collaborative Editing
Real-time Analytics
Edge Computing

Data Flow Architecture

FlatBuffers
Size-prefixed binary data streams in via stdin, socket, or API
→
File ID Router
4-byte identifier routes each buffer to the correct table
→
SQLite Index
SQLite B-tree indexes for fast lookups
→
SQLite VTable
SQL interface with zero-copy field extraction
→
Query Results
Direct pointer access to FlatBuffer fields

Design Decisions

  • Zero Deserialization — Data stays in FlatBuffer format, extracted on-demand
  • Source Routing — Same schema, multiple sources; query by _source field
  • Append-Only — Optimized for streaming; no write amplification
  • SQLite VTable — Full SQL without data copying

Benchmarks vs SQLite

Ingest 2.5x faster
Point Query 1.8x faster
Zero-Copy 8x faster
FlatSQL
SQLite

Trade-offs

  • Zero-Copy API — 1.7µs lookups (1.4x faster than SQLite)
  • VTable SQL — 12.9µs queries (5-7x slower due to API limits)
  • Append-Only — No updates; use delete + re-insert
  • In-Memory — Disk persistence via export/import

See full trade-offs analysis →

Interactive Demo

Stream FlatBuffers and query with SQL in real-time.

FlatSQL Engine

Loading WASM...

Streaming Ingest

Records 0
Bytes 0
Rate/sec -
Stream data to see activity

SQL Query

Encrypted Database, Keyed to Your Wallet

Sign in with your wallet to create a database only your wallet can unlock.

Each database gets its own random content key. The page wraps it to your wallet's encryption key and the engine encrypts the email and phone columns of every record under it; SQL reads them decrypted in this session only. The page saves the database in this browser as ciphertext; a later session reopens it only through your wallet.

JSON Schema IDL with x-flatbuffers Extensions

Generated by DA-Flatbuffers — used to initialize FlatSQL

Standalone Runtime API

One C++ WASI artifact runs in browsers through a small shim and in WasmEdge through a resident runner with native query caching.

import { createStandaloneArtifactBuilder } from "flatsql/artifacts/standalone";

const builder = await createStandaloneArtifactBuilder(schema, {
  runtime: "standalone"
});

await builder.registerFileId("TELE", "Telemetry");
await builder.ingestBuffers(telemetryBuffers);

await builder.registerQueryTemplate(
  "packetById",
  "SELECT packet_id, subsystem FROM Telemetry WHERE packet_id = ?",
  true
);

await builder.queryTemplate("packetById", [42]); // cache miss
await builder.queryTemplate("packetById", [42]); // cache hit
const stats = await builder.getQueryCacheStats();