A database, built from the disk up.
VaultDB is a key-value store, a SQL engine and a vector search index, written from scratch in Go. Every page here talks to it live.
This is VaultDB's B-tree logic, running in your browser.
Playground
The real engine runs right here in your browser, so the database is yours alone. Type a command, or pick an example.
Starting VaultDB in your browser...
How it works
What happens between pressing Enter and seeing OK.
Parser
Cuts your line into words, keeping
"quoted text"together. SQL goes through a lexer and a recursive descent parser instead.Engine
Checks the command and decides what to do. Runs SQL statements one at a time so two clients can never write the same row.
B-tree
Keeps every key sorted in memory. 100,000 keys fit in four levels, so a lookup takes about 0.2 microseconds.
Append-only log
Every change is written to disk first, with two CRC-32C checksums, and forced onto the disk with fsync before you see
OK.
Finding meaning with HNSW
Vector search finds the stored items closest in meaning to a question. Checking every item is exact but slow, so VaultDB builds an HNSW graph: a few long-distance links on the top layer, more detailed links below.
A search starts at the top, hops towards the target until it can't get closer, then drops a layer. On 100,000 vectors that is 81 times faster than checking everything, and it still finds 99.5% of the true nearest neighbours.
A simplified drawing of the real algorithm, with points on flat layers. Real embeddings have hundreds of dimensions.
Surviving a power cut
Data is never edited in place. Each change becomes a record at the end of the log, and on start-up VaultDB replays the log from the beginning.
If the power goes off mid-write, the half-written record fails its checksum and is cut off. Damage anywhere else stops start-up with the exact byte offset instead of loading wrong data. Old records are tidied away by compaction: write a fresh log, fsync it, then rename it over the old one in one atomic step.
One record. The header checksum is verified before any length is trusted.
Benchmarks
Measured with the benchmark tool in the repository: 128-dimension vectors, the 10 nearest neighbours, on a two-core machine.
The uniform random line is the worst case on purpose. In 128 dimensions random points are almost all the same distance apart, so no shortcut can find "the nearest" reliably. Real text embeddings cluster by topic, which is why the clustered line matters in practice.
Ask the docs
Ask how VaultDB works. It searches its own code and README with HNSW and shows the passages it found.