qrrot - database with AI

Here is a 2-3 sentence factual summary of the article:

The article introduces **qrrot**, a Go-based in-memory database with a TCP interface, binary storage, and a built-in AI assistant powered by Google's Gemini model. It features a strictly typed engine supporting string, int, and JSON values, a highly optimized byte-level parser that minimizes memory allocations, and achieves benchmark speeds of over 80,000 requests per second. The AI agent can execute complex, multi-step queries by iteratively reading the database state and generating conditional write commands, with safety checks that pause execution before performing destructive operations.

Writing your own in-memory database is a unique way to study Go under the hood and build a meaningful pet project. Creating a simple wrapper around a map is boring. That's why I asked myself: what if I wrote a truly fast engine with binary storage, and bolted an interactive AI assistant on top of it, allowing you to communicate in natural language and making it execute chains of queries autonomously? Thus qrrot was born — a Go-based in-memory store with a TCP interface, binary snapshots, and a built-in Gemini-based agent. In this article, I will provide the most detailed overview of my project: we'll break down the architecture, look at the benchmarks, explore how the AI works here, and at the end, I'll go over all the architectural pain points and flaws. 1. Under the hood: Data types and the engine At the core of qrrot lies a thread-safe Store struct, protected by a sync.RWMutex : type Store struct { mu sync.RWMutex data map string value.Value } Unlike primitive string-string stores, the engine is strictly typed and supports three classic data types: - string - classic strings; - int - 64-bit integers; - json - JSON objects. All values are stored in memory in a Value struct, which contains a byte slice and a type tag: type Type uint8 const TypeEmpty Type = iota TypeString TypeInt TypeJson type Value struct { valueType Type data byte } This makes it easy to serialize data and avoid reflection overhead when serving it to the client. The commands are as familiar as possible: put , get , del , exists , incr , decr , all . 2. The battle for nanoseconds: The parser and network layer When you're writing a database, the "hottest" spot is parsing incoming commands. A regular strings.Split won't work here: it allocates memory for every token, which will kill the garbage collector's performance at tens of thousands of requests per second. Zero-alloc almost parser I wrote a parser that iterates over a byte array, ignoring extra spaces and tabs. The real magic happens when handling strings with spaces for example, JSON objects . The parser understands double quotes " and escaped characters \" , carefully collecting tokens into a pre-allocated 8 byte buffer. The benchmark results Apple M4, Darwin ARM64 speak for themselves: - Raw in-memory operations: - BenchmarkStore Get - 6.29 ns/op , 0 B/op , 0 allocs/op - BenchmarkStore Put - 13.30 ns/op , 0 B/op , 0 allocs/op - - Command parsing: - BenchmarkParser ParseGet - 25.70 ns/op , 32 B/op , 1 allocs/op - BenchmarkParser ParsePut - 51.19 ns/op , 32 B/op , 2 allocs/op - Allocations in the parser are kept to an absolute minimum 1-2 per command — they are only spent on converting bytes to a string when creating the command object. TCP server Network communication is built on the standard net package. Each connection is handled in its own goroutine. The full cycle receiving a packet - parsing - locking the mutex - reading/writing - responding to the client works extremely fast: - BenchmarkTCPServer Get - 11 970 ns/op ~83 000 RPS - BenchmarkTCPServer Put - 12 157 ns/op ~82 000 RPS 3. The killer feature: Interactive AI assistant To activate it, simply start the database with the -ai flag and pass the API KEY . The ai command then becomes available in the REPL. Multi-step execution support Simply generating a single command doesn't work for complex tasks. For example, for the query "if the user ivan exists, increment his age" , the AI cannot immediately issue a write command, as it doesn't know the state of the database. To solve this, a loop up to 5 iterations is implemented under the hood, where the AI communicates with the DB engine using special tags: - QUERY READ: <command - The AI asks the database to perform a read e.g., get ivan . - QUERY WRITE: <command - Intermediate data write. - RESULT READ: / RESULT WRITE: - The final result. How it looks in practice: - You write: ai delete ivan's profile if his age is less than 30 - The LLM answers the engine: QUERY READ: all - The engine transparently for you executes all , searches for Ivan among the data, sees his age {"age": 25} json , and sends it back to the LLM. - The LLM understands that the user was found by the key let's say, ivan , and issues the final action: RESULT WRITE: del ivan . Human-in-the-loop Protection against the machine uprising The database never blindly executes destructive AI commands. If the LLM generates write commands put, del, incr, decr , qrrot pauses execution, draws a nice ASCII box with the execution plan, and waits for confirmation: ai wants to execute the following write command s : ┌─────────────────────────────────┐ 1. del ivan └─────────────────────────────────┘ execute final commands? y/n : This ensures that neural network hallucinations won't destroy your prod. 4. Data on disk: Binary snapshots In-memory is cool, but data needs to be saved. Instead of using heavyweight formats JSON/XML , qrrot saves dumps into its own custom binary format with the QRRT signature. The file structure is as dense as possible: - 4 bytes signature QRRT + 1 byte version. - Then records follow sequentially: 1 byte type 2 bytes key length key 4 bytes value length value . Atomicity of saving: When calling exit or intercepting system signals SIGINT / SIGTERM , the Graceful Shutdown mechanism is triggered: - The dump is written to a temporary file dump.qrr- .tmp . - f.Sync is called to force flushing OS buffers to the physical disk protection against power outages . - os.Rename is executed, which on POSIX systems is guaranteed to atomically replace the old file with the new one. I/O Benchmarks 10 million keys with long values and JSON : - Save to disk: 2.41 seconds . - Read, parse, and load 10M keys to RAM: 3.14 seconds . Additionally, an OOM protection mechanism is implemented for reading corrupted files: if the dump specifies a value length greater than 16 MB, the database will refuse to load that key, preventing a system crash. 5. On problems and architectural flaws Perfect code doesn't exist, especially if a project is written in two weeks by one person. qrrot was created as a pet project, and it is definitely not capable of competing with something like Redis in any way. It contains compromises that might shoot you in the foot as the load grows. Let's break them down: 1. Global lock The core of the database is a Store under a single sync.RWMutex . This is enough for 80k RPS on localhost, but on machines with dozens of cores, threads will start lining up in a queue. How to fix it: Rewrite it using sharding. Split the store into an array of 256 segments each with its own map and mutex . The segment is chosen by hashing the key. This will radically reduce lock contention. 2. OOM when taking snapshots In the current implementation, the Snapshot method first calls loadDataToRam , which performs maps.Copy res, s.data . This is a disaster for large databases. If you have 10 GB of data in memory, at the moment of creating a snapshot, the database will allocate another 10 GB of RAM just to create a safe copy of the map. How to fix it: Either lock the map while writing to disk kills DB availability , or implement MVCC Multi-Version Concurrency Control or a mechanism like RCU Read-Copy-Update . 3. Lack of a WAL Write-Ahead Log Snapshots are only saved on exit. If the server runs for a month, accumulates data, and the process is killed by SIGKILL or power is lost — all data since the start will disappear. How to fix it: Write an append-only log of every transaction to disk in real-time. On startup, the database should load the latest dump, and then "replay" operations from the WAL. 4. The AI assistant only works locally in the REPL The architecture of the AI agent with the interactive y/n prompt is tied to os.Stdin and os.Stdout . If you start the DB in TCP server mode and send the ai command over the network, the engine will honestly reply: ai is only available in interactive console i'll fix it . To work over the network, an interactive protocol on top of TCP would need to be implemented. 5. Memory overhead for simple numbers Values of type int int64 take up 8 bytes, but qrrot packs them into a Value struct with a type tag and a byte slice byte . This generates unnecessary allocations and memory overhead. For small data, this is inefficient compared to interface{} or unsafe tricks. Conclusion qrrot is a great testing ground for experiments. The project proves that in pure Go, using only the standard library excluding the AI client , you can quickly build a high-performance engine that withstands a massive RPS. The experience with an LLM as an autonomous agent turned out to be particularly interesting to me: the model handles multi-step tasks and JSON parsing inside the database perfectly, acting as a bridge between human language and strict DB logic. I'd be happy to hear your criticism, architectural advice, and see your pull requests: https://github.com/piterovxyz/qrrot https://github.com/piterovxyz/qrrot Thank you