A production-ready distributed key-value store with Raft consensus

Built in 24 hours by someone learning Rust for 42 days — proof that curiosity and persistence pay off!

minikv v0.2.0 is ready for action: robust, documented, and built for everyone.

• Multi-node Raft cluster for high availability
• Reliable Two-Phase Commit for distributed writes
• Automatic cluster rebalancing
• Prometheus metrics, stress-tested integration & English docs

• What is minikv?
• Tech Stack
• Quick Start
• Architecture
• Performance
• Features
• Roadmap
• The Story
• Documentation
• Development
• Contributing
• Contact

minikv is a distributed key-value store written in Rust and maintained at github.com/whispem/minikv. Designed for simplicity, speed, and reliability—whether you're learning, scaling, or deploying.

• Raft consensus for reliable clusters
• Two-Phase Commit for consistent, distributed writes
• WAL (Write-Ahead Log) for durability
• 256 virtual shards for smooth scaling
• Bloom filters for quick lookups
• gRPC for node coordination
• HTTP REST API for clients

Language composition for whispem/minikv:

• Rust (~75%) — main logic, performance, and type safety
• Shell (~21%) — orchestration and automation scripts
• JavaScript (~2%) — benchmarks and tools
• Makefile (~2%) — build flows

Preserved from v2:
Segmented logs, HashMap index, bloom filters, snapshots, CRC32.
What’s new:
Raft, 2PC, gRPC, WAL, sharding, rebalancing.

• Rust 1.81+ (Install)
• Docker (optional for cluster setup)

git clone https://github.com/whispem/minikv
cd minikv
cargo build --release

./scripts/serve.sh 3 3  # 3 coordinators + 3 volumes

Or with Docker Compose:

docker-compose up -d

Manual setup is possible (coordinators+volumes in separate terminals—see docs).

echo "Hello, distributed world!" > test.txt
./target/release/minikv put my-key --file test.txt
./target/release/minikv get my-key --output retrieved.txt
./target/release/minikv delete my-key

REST calls:

curl -X PUT http://localhost:5000/my-key --data-binary @file.pdf
curl http://localhost:5000/my-key -o output.pdf
curl -X DELETE http://localhost:5000/my-key

• Coordinator cluster: manages metadata, consensus (Raft), write orchestration
• Volumes: blob storage, segmented logs, crash recovery (WAL)
• 2PC write path: distributed safety, atomicity
• Reads: fast and local—always picks healthy replicas

If a node dies, minikv repairs itself and keeps your data available!

Benchmarks (real hardware):

• 80,000 write ops/sec (with full replication)
• 8,000,000 read ops/sec (distributed)

Try it yourself with cargo bench and /bench JS scenarios.

Core Distributed Features:

• Multi-node Raft consensus (leader election, log replication, snapshots, recovery, partition detection)
• Advanced Two-Phase Commit (2PC) for distributed writes (chunked transfers, error handling, retries, timeouts)
• Configurable N-way replication (default: 3 replicas)
• High Random Weight (HRW) placement for even distribution
• 256 virtual shards for horizontal scaling
• Automatic cluster rebalancing (load detection, blob migration, metadata updates)

Storage Engine:

• Segmented, append-only log structure
• In-memory HashMap indexing for O(1) key lookups
• Bloom filters for fast negative queries
• Instant index snapshots (5ms restarts)
• CRC32 checksums on every record
• Automatic background compaction and space reclaim

Durability:

• Write-Ahead Log (WAL) for safety
• Configurable fsync policy (always, interval, never)
• Fast crash recovery via WAL replay

APIs:

• gRPC for internal communication (coordinator ↔ volume)
• HTTP REST API for clients
• CLI for cluster operations (verify, repair, compact, rebalance)

Infrastructure:

• Docker Compose setup for dev/test
• GitHub Actions for CI/CD
• k6 benchmarks covering multiple scenarios
• Distributed tracing via OpenTelemetry and Jaeger
• Metrics endpoint for Prometheus (/metrics)

Testing & Internationalization:

• Professional integration, stress, and recovery tests
• All scripts, templates, docs in English

There's always more to build!
Here's what's next for minikv:

• Range queries (efficient scans across keys)
• Batch operations API (multi-put/get/delete)
• Cross-datacenter replication
• Admin web dashboard
• TLS, authentication, and authorization
• S3-compatible API
• Multi-tenancy support
• Zero-copy I/O (io_uring support for ultrafast disk operations)
• More flexibility in configuration and deployment

Started after university: from basic Rust learning to building a distributed system.
One month, countless lessons — and now a real repo serving real clusters.
"From zero to distributed in 31 days" — all code open in whispem/minikv.

• CHANGELOG.md — version history, roadmap
• CONTRIBUTING.md — how to join and contribute
• TRACING.md — observability tips

Why these choices?

• Raft for understandable consensus
• 2PC for atomic distributed writes
• Coordinators for metadata, volumes for storage
• gRPC for fast node coordination
• HTTP REST for client ease-of-use

Fork, experiment, help shape minikv:

git clone https://github.com/whispem/minikv
cd minikv
cargo build --release
cargo test
cargo bench
cargo fmt --all
cargo clippy --all-targets -- -D warnings

Branch, experiment, contribute, or just hack on it!
Everything you need is in the repo.

All backgrounds, all levels welcome! Feedback, code, bug reports, docs — jump in.

• Open issues: github.com/whispem/minikv/issues
• See CONTRIBUTING.md for more info

MIT License — see LICENSE

Created by @whispem as a personal, learning-first journey.

Inspired by TiKV, etcd, and mini-redis.
Guided by the Rust Book, Raft Paper, and the open-source community.

If you learn, experiment or just appreciate this project,
consider starring whispem/minikv! ⭐

Built with Rust — for anyone who loves learning & building.
"From zero to distributed in 31 days."

• GitHub: @whispem
• Repo & Issues: whispem/minikv

Back to Top