4.7 KiB
HeroDB
<<<<<<< HEAD Redis-compatible database server with encryption and AGE cryptographic operations.
Features
- Redis protocol compatibility
- String, hash, and list data types
- Key expiration and persistence
- Database encryption with ChaCha20-Poly1305
- AGE encryption/decryption operations
- Digital signatures with Ed25519
- Persistent storage using redb
Installation
=======
HeroDB is a Redis-compatible database built with Rust, offering a flexible and secure storage solution. It supports two primary storage backends: redb (default) and sled, both with full encryption capabilities. HeroDB aims to provide a robust and performant key-value store with advanced features like data-at-rest encryption, hash operations, list operations, and cursor-based scanning.
Purpose
The main purpose of HeroDB is to offer a lightweight, embeddable, and Redis-compatible database that prioritizes data security through transparent encryption. It's designed for applications that require fast, reliable data storage with the option for strong cryptographic protection, without the overhead of a full-fledged Redis server.
Features
- Redis Compatibility: Supports a subset of Redis commands over RESP (Redis Serialization Protocol) via TCP.
- Dual Backend Support:
redb(default): Optimized for concurrent access and high-throughput scenarios.sled: A lock-free, log-structured database, excellent for specific workloads.
- Data-at-Rest Encryption: Transparent encryption for both backends using the
ageencryption library. - Key-Value Operations: Full support for basic string, hash, and list operations.
- Expiration: Time-to-live (TTL) functionality for keys.
- Scanning: Cursor-based iteration for keys and hash fields (
SCAN,HSCAN). - AGE Cryptography Commands: HeroDB-specific extensions for cryptographic operations.
Quick Start
Building HeroDB
To build HeroDB, navigate to the project root and run:
append
cargo build --release
<<<<<<< HEAD
Usage
./target/release/herodb --dir /path/to/db --port 6379
Options
--dir: Database directory (required)--port: Server port (default: 6379)--debug: Enable debug logging--encrypt: Enable database encryption--encryption-key: Master encryption key for encrypted databases
Examples
# Basic server
herodb --dir ./data
# Encrypted database
herodb --dir ./data --encrypt --encryption-key "your-key"
# Custom port with debug
herodb --dir ./data --port 7000 --debug
Redis Commands
Supports standard Redis commands including:
- Strings: GET, SET, MGET, MSET, INCR, DEL
- Hashes: HGET, HSET, HGETALL, HDEL, HEXISTS
- Lists: LPUSH, RPUSH, LPOP, RPOP, LLEN, LRANGE
- Keys: KEYS, SCAN, EXISTS, EXPIRE, TTL
- Transactions: MULTI, EXEC, DISCARD
- Server: PING, ECHO, INFO, CONFIG
AGE Commands
Extended commands for cryptographic operations:
- Key Generation:
AGE GENENC,AGE GENSIGN,AGE KEYGEN - Encryption:
AGE ENCRYPT,AGE DECRYPT,AGE ENCRYPTNAME - Signing:
AGE SIGN,AGE VERIFY,AGE SIGNNAME - Management:
AGE LIST
Client Usage
Connect using any Redis client:
redis-cli -p 6379 SET key value
redis-cli -p 6379 GET key
redis-cli -p 6379 AGE GENENC
Architecture
- Storage: redb embedded database
- Protocol: Redis RESP protocol over TCP
- Encryption: ChaCha20-Poly1305 for data, AGE for operations
- Concurrency: Tokio async runtime =======
Running HeroDB
You can start HeroDB with different backends and encryption options:
Default redb Backend
./target/release/herodb --dir /tmp/herodb_redb --port 6379
sled Backend
./target/release/herodb --dir /tmp/herodb_sled --port 6379 --sled
redb with Encryption
./target/release/herodb --dir /tmp/herodb_encrypted --port 6379 --encrypt --key mysecretkey
sled with Encryption
./target/release/herodb --dir /tmp/herodb_sled_encrypted --port 6379 --sled --encrypt --key mysecretkey
Usage with Redis Clients
HeroDB can be interacted with using any standard Redis client, such as redis-cli, redis-py (Python), or ioredis (Node.js).
Example with redis-cli
redis-cli -p 6379 SET mykey "Hello from HeroDB!"
redis-cli -p 6379 GET mykey
# → "Hello from HeroDB!"
redis-cli -p 6379 HSET user:1 name "Alice" age "30"
redis-cli -p 6379 HGET user:1 name
# → "Alice"
redis-cli -p 6379 SCAN 0 MATCH user:* COUNT 10
# → 1) "0"
# 2) 1) "user:1"
Documentation
For more detailed information on commands, features, and advanced usage, please refer to the documentation:
append