A distributed, multi-tenant key-value & object store written in Rust

minikv provides strong consistency (Raft + 2PC), durability (WAL), and production-grade observability, security, and multi-tenancy — all in a modern Rust codebase.

Built in public as a learning-by-doing project — now evolved into a complete, reference implementation of distributed systems in Rust.

minikv v0.9.0 introduces cloud-native and performance features:

• Kubernetes Operator: CRD-based cluster management with autoscaling
• Time-series engine: Compression, downsampling, aggregations
• Geo-partitioning: Data locality and compliance (GDPR)
• Data tiering: Hot/warm/cold/archive automatic data movement
• io_uring: Zero-copy I/O for Linux (optional)

Previous highlights (v0.8.0): cross-DC replication, CDC, admin UI, backup/restore, plugins.

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

minikv is a distributed key-value store written in Rust, designed for simplicity, speed, and reliability.

Who is this for ?
minikv is for engineers learning distributed systems, teams experimenting with Rust-based infrastructure, and anyone curious about consensus, durability, and system trade-offs.

• Clustered : Raft consensus and 2PC for transactional writes
• Virtual Sharding : 256 vshards for elastic scaling & balancing
• WAL : Write-ahead log for durability
• gRPC for node communication, HTTP REST & S3 API for clients
• Bloom filters, snapshots, watch/subscribe for performance & reactivity

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

# Start a node
cargo run -- --config config.example.toml

# API examples
curl localhost:8080/health/ready   # readiness
curl localhost:8080/metrics        # Prometheus metrics
curl localhost:8080/admin/status   # admin dashboard

# Create API key (admin)
curl -X POST http://localhost:8080/admin/keys -d '{"role":"ReadWrite","tenant_id":"acme"}'

# S3 (demo)
curl -X PUT localhost:8080/s3/mybucket/mykey -d 'hello minikv!'
curl localhost:8080/s3/mybucket/mykey

For cluster setup and advanced options, see the documentation.

┌─────────────────────────────────────────────────────┐
│                       Clients                       │
│          REST │ S3 │ gRPC │ WS            │
└──────────────────────────┬──────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────┐
│                  Coordinators                        │
│    ┌───────┐  ┌───────┐  ┌───────┐                 │
│    │ Raft  │──│ Raft  │──│ Raft  │  (3-5 nodes)   │
│    │Leader │  │Follower│  │Follower│                 │
│    └───────┘  └───────┘  └───────┘                 │
└──────────────────────────┬──────────────────────────┘
                           │ Metadata + Routing
┌──────────────────────────▼──────────────────────────┐
│                  Volume Servers                      │
│    ┌───────┐  ┌───────┐  ┌───────┐                 │
│    │Volume1│  │Volume2│  │Volume3│  (N nodes)      │
│    │Shards │  │Shards │  │Shards │                 │
│    │0-85   │  │86-170 │  │171-255│                 │
│    └───┬───┘  └───┬───┘  └───┬───┘                 │
│        ▼          ▼          ▼                     │
│    ┌───────┐  ┌───────┐  ┌───────┐                 │
│    │RocksDB│  │ Sled  │  │Memory │                 │
│    └───────┘  └───────┘  └───────┘                 │
└─────────────────────────────────────────────────────┘

• Write throughput : over 50,000 operations/sec (single node, in-memory)
• Sub-millisecond read latency
• Cluster tested (3–5 nodes, commodity VMs)
• Built-in Prometheus metrics

• Raft consensus (leader election, log replication)
• Two-phase commit (2PC) for multi-key transactions
• 256 virtual shards with consistent hashing
• Automatic rebalancing and failover
• Cross-datacenter async replication
• Conflict resolution (LWW, vector clocks)

• Pluggable backends: RocksDB, Sled, in-memory
• Write-ahead log (WAL)
• Bloom filters for fast lookups
• LZ4/Zstd compression
• Data tiering (hot/warm/cold/archive)
• Compaction and garbage collection

• Dedicated time-series engine
• Multiple resolutions (raw, 1min, 5min, 1h, 1day)
• Automatic downsampling
• Delta and Gorilla compression
• Aggregations: sum, avg, min, max, count, stddev

• Region-aware data placement
• Routing: nearest, primary, round-robin, geo-fenced
• GDPR/data residency compliance
• Automatic failover between regions

• HTTP REST: CRUD, batch, range, prefix queries
• S3-compatible: Buckets, objects, multipart upload
• gRPC: Internal node communication
• WebSocket/SSE: Real-time watch/subscribe

• API keys with Argon2 hashing
• JWT authentication
• Role-based access control (RBAC)
• Multi-tenant isolation
• AES-256-GCM encryption at rest
• TLS for HTTP and gRPC
• Audit logging

• Tenant isolation
• Per-tenant quotas (storage, requests)
• Rate limiting (token bucket)

• Prometheus metrics
• OpenTelemetry tracing
• Structured logging
• Admin Web UI dashboard
• Health probes (/health/ready, /health/live)

• Backup & restore (full, incremental)
• Change Data Capture (CDC)
• Plugin system (storage, auth, hooks)
• Kubernetes Operator (v0.9.0)
• io_uring zero-copy I/O (Linux, v0.9.0)

apiVersion: minikv.io/v1alpha1
kind: MiniKVCluster
metadata:
  name: my-cluster
spec:
  coordinators:
    replicas: 3
  volumes:
    replicas: 3
    replicationFactor: 3
  security:
    tls:
      enabled: true
  autoscaling:
    enabled: true
    maxReplicas: 10

Deploy with:

kubectl apply -f k8s/crds/minikvcluster.yaml
kubectl apply -f k8s/examples/basic-cluster.yaml

• Kubernetes Operator (CRD, autoscaling)
• Time-series engine
• Geo-partitioning
• Data tiering
• io_uring (Linux)

• MiniQL query optimizer
• Full-text search (tantivy)
• Helm chart
• Connection pooling

• Vector embeddings storage
• Distributed transactions (Percolator)
• Read replicas
• Multi-region active-active

• Serverless mode (scale to zero)
• WebAssembly UDFs
• Change streams (Kafka Connect)
• Point-in-time recovery

• GPU-accelerated queries
• Raft learner nodes
• Auto-sharding (split/merge)
• Global secondary indexes
• CockroachDB-style SQL layer

cargo build          # Build
cargo test           # Tests
cargo clippy         # Lint
cargo fmt            # Format

src/
├── bin/              # Binaries (coord, volume, cli)
├── common/           # Shared modules
│   ├── raft.rs       # Consensus
│   ├── storage.rs    # Storage backends
│   ├── auth.rs       # Authentication
│   ├── encryption.rs # Encryption at rest
│   ├── replication.rs# Cross-DC replication
│   ├── cdc.rs        # Change Data Capture
│   ├── backup.rs     # Backup/restore
│   ├── plugin.rs     # Plugin system
│   ├── timeseries.rs # Time-series
│   ├── geo.rs        # Geo-partitioning
│   ├── tiering.rs    # Data tiering
│   ├── io_uring.rs   # io_uring backend
│   └── io_uring.rs   # io_uring backend
├── coordinator/      # Coordinator logic
├── volume/           # Volume server
└── ops/              # Operational tools
k8s/                  # Kubernetes manifests
bench/                # k6 benchmarks

See CONTRIBUTING.md.

GitHub: whispem/minikv

MIT License - See LICENSE