v0.1.0 — Open Source · MIT

makrounaDB

Redis-inspired in-memory database,
written in modern C++.

RESP2 ProtocolTTL ExpirationAOF PersistenceNatural Language CLI
Get Started →View on GitHub
makrounaDB — zsh — 80×24
scroll

// overview

A database that speaks Redis,
built from first principles.

makrounaDB is a lightweight, Redis-compatible in-memory key-value store that runs as a CLI server. It implements the RESP2 wire protocol — meaning any Redis client connects without modification.

Written in modern C++, it supports TTL-based key expiration, append-only file persistence, and a unique natural language interface — so you can interact with your data the way you actually think.

“Sometimes you need a lightweight, embeddable key-value store — without the operational overhead of a full Redis deployment.”

RESP2
Wire Protocol
AOF
Persistence Mode
C++17
Language Standard
MIT
License

// features

Everything you need.

Nothing you don't.

RESP2 Protocol

Fully compatible with the Redis Serialization Protocol v2. Connect with any Redis client — redis-cli, Jedis, ioredis — without any code changes.

TTL Expiration

Set time-to-live on any key with EXPIRE. Lazy expiration on access, with periodic bounded cleanup run from the event loop.

AOF Persistence

Every write is appended to an AOF log in RESP-array format. On restart, the log is replayed through the same command dispatcher — zero data loss.

Natural Language CLI

Ask your database in plain English. "Set user to ghassen", "What is user?", "Expire user in 30 seconds" — the NL shell translates to RESP2.

Pasta Commands

Unique pasta-themed aliases: RIGATONI (DECR), LINGUINE (INCRBY), PENNE (SETNX), LASAGNA (RENAME), FARFALLE (GETDEL)… all real commands.

Event-Loop Server

Single-process TCP server using select() for readiness-based socket handling. Client input buffered and parsed incrementally per connection.

// command reference

Two flavors of commands.

Standard RESP2, and a pasta-themed twist.

Standard Commands

Redis-compatible RESP2 commands. Works with any existing client.

PING [message]Test connection, returns PONG
ECHO messageEcho back the given string
SET key valueSet a key to a string value
GET keyGet the value of a key
DEL key [key ...]Delete one or more keys
EXISTS key [key ...]Test for key existence
INCR keyIncrement integer value by 1
EXPIRE key secondsSet expiration in seconds
TTL keyGet remaining time-to-live

Pasta Commands

🍝

Because life is too short for boring command names. Fully functional aliases with a culinary twist — all of them are real, working commands.

RIGATONI key≡ DECR
Decrement integer by 1
LINGUINE key amount≡ INCRBY
Increment integer by N
VERMICELLI key amount≡ DECRBY
Decrement integer by N
SPAGHETTI key≡ STRLEN
Return byte length of value
PENNE key value≡ SETNX
Set only if key does not exist
ALDENTE key≡ PERSIST
Remove TTL so key never expires
FARFALLE key≡ GETDEL
Return value and delete atomically
LASAGNA key newkey≡ RENAME
Rename key to newkey

RESP2 format: *<argc>\r\n$<len>\r\n<arg>\r\n... · + Simple string · : Integer · $ Bulk string · - Error

// how it works

Up and running in minutes.

01

Build the Server

Compile makrounaDB from source using CMake and Ninja. A single self-contained binary is produced — no runtime dependencies.

bash
# Install prerequisites
sudo apt install -y g++ cmake ninja-build

# Configure and build
cmake -S . -B build -G Ninja
cmake --build build
# → ./build/makrounaDB
02

Start It Up

Launch the server on any port. Pass an AOF file path to enable persistence. The server is ready to accept RESP2 connections immediately.

bash
# Minimal start
./build/makrounaDB

# With explicit options
./build/makrounaDB --port 6379 --aof data/appendonly.aof

# Show all options
./build/makrounaDB --help
03

Connect & Query

Use any Redis client, send raw RESP2 frames via netcat, run the included Python example, or launch the natural language shell.

bash
# Natural language shell
./build/makrounaDB --nl-shell --host 127.0.0.1 --port 6379

# Type commands like:
#   set user to ghassen
#   what is user?
#   expire user in 30 seconds
#   does user exist?

# Or send raw RESP2 via nc
printf '*3\r\n$3\r\nSET\r\n$4\r\nname\r\n$10\r\nmakrounaDB\r\n' \
  | nc -N 127.0.0.1 6379
04

Benchmark & Ship

Run the built-in benchmark suite to measure throughput, or export .deb / .rpm packages for deployment.

bash
# Run test suite
ctest --test-dir build --output-on-failure

# Benchmark (generates benchmarks/report.md)
python3 benchmarks/simple_benchmark.py \
  --host 127.0.0.1 --port 6379 --requests 5000

# Build release packages
bash scripts/release/build_release.sh --format all

// architecture

Simple. Fast. Transparent.

A single-process server with a clear, linear request path. No hidden magic — just C++ doing what it does best.

Request Pipeline

Network Layer
TCP server · select() event loop
Protocol Parser
Incremental RESP2 frame parsing
Command Dispatcher
Routing + command semantics
Storage + TTL
unordered_map · expiration metadata · lazy cleanup
AOF Persistence
Append-only log · everysec flush · replay on startup
RESP Reply
Encoded response back to the client

Module Map

src/appCLI entrypoint and server lifecycle
src/networkTCP server and event loop
src/protocolRESP request parser and reply encoder
src/commandCommand routing and semantics
src/storageKeyspace and TTL behavior
src/persistenceAppend-only file persistence

Roadmap

  • ○Parser hardening for malformed frames and large payloads
  • ○Strict RESP2 error parity matrix against Redis
  • ○Worker-pool-backed background maintenance
  • ○Optional snapshot persistence mode

// installation

Start in seconds.

Build from source with CMake, run as a Docker container, or grab a native .deb / .rpm package.

1

Build from Source

bash
# 1. Prerequisites
sudo apt update
sudo apt install -y g++ cmake ninja-build python3 netcat-openbsd

# 2. Clone
git clone https://github.com/ghassenov/makrounaDB.git
cd makrounaDB

# 3. Build
cmake -S . -B build -G Ninja
cmake --build build

# 4. Run
./build/makrounaDB --port 6379 --aof data/appendonly.aof

🐳 Docker

Container image in the works. Run anywhere with zero build step.

📦 Release Packages

Export native packages using the included release scripts.

scripts/release/build_release.sh

🧪 Run Tests

ctest --test-dir build --output-on-failure
2

Docker

bash
# Pull the image
docker pull makrounadb/makrounadb:latest

# Run with default settings (port 6379)
docker run -p 6379:6379 makrounadb/makrounadb:latest

# Run with persistent AOF volume
docker run -p 6379:6379 \
  -v $(pwd)/data:/data \
  makrounadb/makrounadb:latest \
  --aof /data/appendonly.aof
3

Release Artifacts

bash
# Build .deb package
bash scripts/release/build_release.sh --format deb

# Build .rpm package
bash scripts/release/build_release.sh --format rpm

# Build all formats + publish GitHub Release
bash scripts/release/build_release.sh \
  --format all --github-release --tag v0.1.0

Ready to try makrounaDB?

Clone, build, and have a server running in under 60 seconds.

Clone on GitHub →View Commands