qrrot - database with AI

Artur Piterov — Sat, 23 May 2026 18:05:35 +0000

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

Thank you!

DEV Community: Artur Piterov