Saku: How I Went From Per-Line KV to 8M Writes/sec in One Week (While Learning C++)

Isnaini — Fri, 16 Oct 2026 15:28:02 +0000

Initial scope was simple: just make it fast. No fsync, no fancy durability. Just raw speed.

I was bored. Asked AI "what should I build in C++?" It said "KV store". Okay, let's do it.

This is the full story. Not a clean tutorial, just a war story of all the dumb decisions and tradeoffs I made in one week.

Day 1-2: Per-Line KV - 300k w/s, Slow as Hell

The dumbest version: key:value\n per line. Read with fgets, scan from top to bottom.

Slow. Want to read 1 key? You have to scan everything. O(n). 100MB file = pain.

Lesson: need binary format, not text.

The Binary Format

Ended up with my own format:

[Checksum 4B][Status 1B][Type 1B][Key Len 1B][Value Len Varint][Key][Value]

Some decisions that looked dumb but actually made sense:

1. Key Len limited to 256 (1 byte).
Why? Just an engine decision. I haven't found a use case where keys are 1KB long. If 1 byte is enough, why use 4 bytes? Save 3 bytes per record x 10 million = 30MB saved.

2. Value Len was 32 bytes at first.
I wanted to support 500MB values. Super wasteful. A small 10-byte value had to carry a 32-byte header.

Then I learned varint. Manipulate MSB as a continuation flag.

Small (<127): 0xxxxxxx -> 1 byte
Large: 1xxxxxxx 0xxxxxxx -> 2 bytes

From 32 bytes to 1 byte for small data. Heaven.

3. Checksum as a recovery mode.
I only knew the concept as "compare". At first it was reversed, then XOR, then CRC. Not just for validation, but to know which record is corrupted after a crash.

Day 3-4: Indexing - From Scanning to HashMap

Still slow. Every read still scans the file.

Solution: HashMap. But at first I stored key -> value in the HashMap. RAM exploded.

Changed to: key -> offset. HashMap only holds the position in the file, not the value itself. Bitcask-style. RAM-friendly, read is just seek(offset).

Day 4-5: I/O - Ring Buffer & Page Faults

Reading per payload was still slow. One read = one syscall.

Tried ring buffer: read per chunk, erase-read method. If payload is incomplete at the end of the chunk, re-read from the last payload offset.

Still slow. Learned about 4KB page faults. Every 4KB, the OS has to load a new page.

4KB chunk: thousands of syscalls
8MB chunk: hundreds of syscalls
16MB chunk: crazy fast

Why? Because 16MB = 4096 page faults at once, not one by one.

This is what took me from 300k to 8M w/s (raw, no safety).

Day 6-7: mmap - The Final Cheat Code

AI recommended: "try mmap".

Mind blown. The file doesn't need to be read anymore. The file is RAM.

char* data = (char*) mmap(nullptr, file_size, PROT_READ, MAP_PRIVATE, fd, 0);

No more string allocations. Everything is a full ref &[u8]. Zero-copy.

Raw speed: 8 million writes/sec.

But not safe. Added checksum + active flag for recovery:

Final: 1.3 million writes/sec, 31μs read on a 612MB file (10 million records).

Dropped from 8M? Yeah. But that's the safety tax. A race car without brakes is useless.

Tradeoffs I Intentionally Made

No fsync / flush. On purpose. My scope was just speed. If I used fsync, 1.3M would become 10k because you have to wait for the disk to actually spin. Fsync can be added later as Saku::flush() if needed.
No compaction. Append-only piles up garbage. Compaction needs file rewrite, would drop write speed to 200k. Let it pile up first, benchmark pure write path.
Key max 256 bytes. Size tradeoff. If you need more, just change that 1 byte to varint too.

Final Numbers

Write: 10,000,000 ops in 7.47s -> 1,337,999 writes/sec
Read: 612.6 MB file, key "example long key 9999999" -> 31μs
CPU: AMD Ryzen 7 5825U, 32GB RAM, Debian 13

Repo: https://github.com/isnakode/saku
make bench N=10000000 to try it.

What I Actually Learned

AI gives you the map, but you're the one walking in the jungle. Segfaults at 2 AM can't be AI'd.
Varint, checksum, mmap are not memorization, they are tradeoffs: size vs speed vs safety.
Limiting to 1 byte is an engineering decision, not laziness.
I went from read() read() read() -> ring buffer -> mmap, and watched syscalls drop from thousands to hundreds. You can't learn that from docs, you feel it.

DEV Community: Isnaini