███╗ ███╗███████╗██████╗ ██╗ ██╗███████╗ █████╗
████╗ ████║██╔════╝██╔══██╗██║ ██║██╔════╝██╔══██╗
██╔████╔██║█████╗ ██║ ██║██║ ██║███████╗███████║
██║╚██╔╝██║██╔══╝ ██║ ██║██║ ██║╚════██║██╔══██║
██║ ╚═╝ ██║███████╗██████╔╝╚██████╔╝███████║██║ ██║
╚═╝ ╚═╝╚══════╝╚═════╝ ╚═════╝ ⚠══════╝╚═╝ ╚═╝
A lightning-fast in-memory key-value store built with Rust ⚡
Medusa is a lightweight, high-performance in-memory key-value store inspired by Redis, built entirely in Rust. This project serves as a learning experiment to explore systems programming concepts and database internals.
- Low-level data storage and memory management
- TCP networking and concurrent client handling
- Command parsing and response serialization
- Systems programming with Rust's safety guarantees
- Database internals and performance optimization
- TTL (Time To Live) and expiration handling
- Pattern matching and advanced queries
- Benchmarking and performance testing
Just as the mythical Medusa possessed incredible power, this project channels that energy into a compact, efficient data store. While it won't turn you to stone, it might transform your understanding of how databases work under the hood!
| Learning | ⚡ Performance | Hands-on |
|---|---|---|
| Explore database internals | Fast in-memory operations | Build from scratch |
| Master Rust systems programming | Efficient TCP handling | Understand every line |
| Study Redis-like architectures | Minimal memory footprint | Learn by doing |
Important: This is not a production-ready Redis clone.
Missing Features:
- ❌ Clustering and replication
- ❌ Persistence and snapshots
- ❌ Advanced data types (sets, sorted sets, etc.)
- ❌ Pub/sub messaging
- ❌ Lua scripting
Focus: Understanding core concepts, not feature completeness.
- Set expiration times for keys
- Automatic cleanup of expired keys
- TTL querying and management
- Wildcard key searches (
KEYS user:*) - Advanced pattern matching capabilities
- Efficient key filtering
- Store field-value pairs within a key
- Operations: HSET, HGET, HGETALL, HDEL, HEXISTS, HLEN
- Perfect for storing object-like data structures
- Ordered collections of strings
- Operations: LPUSH, RPUSH, LPOP, RPOP, LLEN, LRANGE
- Support for negative indices in range operations
- Ideal for queues, stacks, and ordered data
- Environment variable support
- Configurable timeouts and limits
- Flexible server settings
- Built-in performance testing
- Multi-threaded benchmarks
- Stress testing capabilities
- Better connection management
- Timeout support
- Graceful error recovery
| Technology | Purpose |
|---|---|
 |
Systems Programming - Memory safety and performance |
 |
Network Layer - Client-server communication |
 |
Data Storage - In-memory key-value operations |
 |
Time Management - Automatic key expiration |
- Rust (latest stable)
- A terminal and some curiosity!
# Clone and navigate to the project
git clone https://github.com/Legacy-Engineers/medusa.git
cd medusa
# Build the project
cargo build --release
# Run the server
cargo run --bin medusa # to run the server
cargo run --bin medusa-client # to run the client# Run the interactive client
cargo run --bin medusa-client
# Or use the compiled binary
./target/release/medusa-client# Run performance benchmarks
cargo run --bin medusa-benchmark
# Custom benchmark parameters
cargo run --bin medusa-benchmark 127.0.0.1 2312 10000 8SET key value [TTL seconds] # Store key-value pair with optional TTL
GET key # Retrieve value by key
DELETE key # Remove key-value pair
EXISTS key # Check if key existsTTL key # Get time-to-live for key
EXPIRE key seconds # Set expiration time for keyHSET key field value # Set hash field to value
HGET key field # Get hash field value
HGETALL key # Get all hash fields and values
HDEL key field # Delete hash field
HEXISTS key field # Check if hash field exists
HLEN key # Get hash lengthLPUSH key value # Push value to left of list
RPUSH key value # Push value to right of list
LPOP key # Pop value from left of list
RPOP key # Pop value from right of list
LLEN key # Get list length
LRANGE key start stop # Get list range (supports negative indices)LIST # List all keys
KEYS pattern # Find keys matching pattern (use * for wildcard)
COUNT # Get number of entriesCLEAR/FLUSHALL # Remove all entries
INFO # Get server statistics
PING # Server health check
QUIT/EXIT # DisconnectSET user:1 "John Doe" 3600 # Set with 1 hour TTL
EXPIRE user:1 7200 # Set 2 hour expiration
KEYS user:* # Find all user keys
TTL user:1 # Check remaining time
HSET user:1 name "John" # Set hash field
HGET user:1 name # Get hash field
LPUSH tasks "task1" # Push to list
LRANGE tasks 0 -1 # Get all list itemsexport MEDUSA_HOST="127.0.0.1"
export MEDUSA_PORT="2312"
export MEDUSA_MAX_CONNECTIONS="100"
export MEDUSA_TIMEOUT="30"
export MEDUSA_ENABLE_TIMEOUTS="false"
export MEDUSA_LOG_LEVEL="info"
export MEDUSA_METRICS="false"
export MEDUSA_CLIENT_TIMEOUTS="false"The server supports various configuration options:
- Host/Port: Customize server binding
- Max Connections: Limit concurrent clients
- Timeouts: Configure connection timeouts (disabled by default)
- Logging: Adjust verbosity levels
Typical performance on modern hardware:
Benchmark Results: Single-threaded SET
Operations: 10000
Duration: 1.2s
Ops/sec: 8333.33
Avg Latency: 0.12ms
Benchmark Results: Multi-threaded (4 threads)
Total Operations: 40000
Total Ops/sec: 25000.00
- Lock-free operations where possible
- Efficient memory management
- Optimized TCP handling
- Automatic expired key cleanup
# Run all tests
cargo test
# Run specific test modules
cargo test store
cargo test server
# Run benchmarks
cargo run --bin medusa-benchmark| Resource | Description |
|---|---|
| Redis Source Code | The Original - Study the master |
| Build Your Own Redis | Step-by-step - C implementation guide |
| The Rust Book | Language Reference - Essential reading |
| Rust Async Book | Async Programming - For advanced features |
This is a learning project, but contributions that improve code quality, documentation, or educational value are welcome!
- Experiment freely - This is for learning!
- Document your discoveries - Share what you learn
- Report issues - Help improve the codebase
- Suggest improvements - Better ways to teach concepts
- Follow Rust conventions
- Add tests for new features
- Update documentation
- Use meaningful commit messages
This project is licensed under the MIT License - see the LICENSE file for details.
Built with ⚡ by curious minds for curious minds
"The best way to learn is to build"