156 lines
5.0 KiB
Markdown
156 lines
5.0 KiB
Markdown
|
|
## Backend Support
|
|
|
|
HeroDB supports two storage backends, both with full encryption support:
|
|
|
|
- **redb** (default): Full-featured, optimized for production use
|
|
- **sled**: Alternative embedded database with encryption support
|
|
|
|
### Starting HeroDB with Different Backends
|
|
|
|
```bash
|
|
# Use default redb backend
|
|
./target/release/herodb --dir /tmp/herodb_redb --port 6379
|
|
|
|
# Use sled backend
|
|
./target/release/herodb --dir /tmp/herodb_sled --port 6379 --sled
|
|
|
|
# Use redb with encryption
|
|
./target/release/herodb --dir /tmp/herodb_encrypted --port 6379 --encrypt --key mysecretkey
|
|
|
|
# Use sled with encryption
|
|
./target/release/herodb --dir /tmp/herodb_sled_encrypted --port 6379 --sled --encrypt --key mysecretkey
|
|
```
|
|
|
|
### Command Support by Backend
|
|
|
|
Command Category | redb | sled | Notes |
|
|
|-----------------|------|------|-------|
|
|
**Strings** | | | |
|
|
SET | ✅ | ✅ | Full support |
|
|
GET | ✅ | ✅ | Full support |
|
|
DEL | ✅ | ✅ | Full support |
|
|
EXISTS | ✅ | ✅ | Full support |
|
|
INCR/DECR | ✅ | ✅ | Full support |
|
|
MGET/MSET | ✅ | ✅ | Full support |
|
|
**Hashes** | | | |
|
|
HSET | ✅ | ✅ | Full support |
|
|
HGET | ✅ | ✅ | Full support |
|
|
HGETALL | ✅ | ✅ | Full support |
|
|
HDEL | ✅ | ✅ | Full support |
|
|
HEXISTS | ✅ | ✅ | Full support |
|
|
HKEYS | ✅ | ✅ | Full support |
|
|
HVALS | ✅ | ✅ | Full support |
|
|
HLEN | ✅ | ✅ | Full support |
|
|
HMGET | ✅ | ✅ | Full support |
|
|
HSETNX | ✅ | ✅ | Full support |
|
|
HINCRBY/HINCRBYFLOAT | ✅ | ✅ | Full support |
|
|
HSCAN | ✅ | ✅ | Full support with pattern matching |
|
|
**Lists** | | | |
|
|
LPUSH/RPUSH | ✅ | ✅ | Full support |
|
|
LPOP/RPOP | ✅ | ✅ | Full support |
|
|
LLEN | ✅ | ✅ | Full support |
|
|
LRANGE | ✅ | ✅ | Full support |
|
|
LINDEX | ✅ | ✅ | Full support |
|
|
LTRIM | ✅ | ✅ | Full support |
|
|
LREM | ✅ | ✅ | Full support |
|
|
BLPOP/BRPOP | ✅ | ❌ | Blocking operations not in sled |
|
|
**Expiration** | | | |
|
|
EXPIRE | ✅ | ✅ | Full support in both |
|
|
TTL | ✅ | ✅ | Full support in both |
|
|
PERSIST | ✅ | ✅ | Full support in both |
|
|
SETEX/PSETEX | ✅ | ✅ | Full support in both |
|
|
EXPIREAT/PEXPIREAT | ✅ | ✅ | Full support in both |
|
|
**Scanning** | | | |
|
|
KEYS | ✅ | ✅ | Full support with patterns |
|
|
SCAN | ✅ | ✅ | Full cursor-based iteration |
|
|
HSCAN | ✅ | ✅ | Full cursor-based iteration |
|
|
**Transactions** | | | |
|
|
MULTI/EXEC/DISCARD | ✅ | ❌ | Only supported in redb |
|
|
**Encryption** | | | |
|
|
Data-at-rest encryption | ✅ | ✅ | Both support [age](age.tech) encryption |
|
|
AGE commands | ✅ | ✅ | Both support AGE crypto commands |
|
|
**Full-Text Search** | | | |
|
|
FT.CREATE | ✅ | ✅ | Create search index with schema |
|
|
FT.ADD | ✅ | ✅ | Add document to search index |
|
|
FT.SEARCH | ✅ | ✅ | Search documents with query |
|
|
FT.DEL | ✅ | ✅ | Delete document from index |
|
|
FT.INFO | ✅ | ✅ | Get index information |
|
|
FT.DROP | ✅ | ✅ | Drop search index |
|
|
FT.ALTER | ✅ | ✅ | Alter index schema |
|
|
FT.AGGREGATE | ✅ | ✅ | Aggregate search results |
|
|
|
|
### Performance Considerations
|
|
|
|
- **redb**: Optimized for concurrent access, better for high-throughput scenarios
|
|
- **sled**: Lock-free architecture, excellent for specific workloads
|
|
|
|
### Encryption Features
|
|
|
|
Both backends support:
|
|
- Transparent data-at-rest encryption using the `age` encryption library
|
|
- Per-database encryption (databases >= 10 are encrypted when `--encrypt` flag is used)
|
|
- Secure key derivation using the master key
|
|
|
|
### Backend Selection Examples
|
|
|
|
```bash
|
|
# Example: Testing both backends
|
|
redis-cli -p 6379 SET mykey "redb value"
|
|
redis-cli -p 6381 SET mykey "sled value"
|
|
|
|
# Example: Using encryption with both
|
|
./target/release/herodb --port 6379 --encrypt --key secret123
|
|
./target/release/herodb --port 6381 --sled --encrypt --key secret123
|
|
|
|
# Both support the same Redis commands
|
|
redis-cli -p 6379 HSET user:1 name "Alice" age "30"
|
|
redis-cli -p 6381 HSET user:1 name "Alice" age "30"
|
|
|
|
# Both support SCAN operations
|
|
redis-cli -p 6379 SCAN 0 MATCH user:* COUNT 10
|
|
redis-cli -p 6381 SCAN 0 MATCH user:* COUNT 10
|
|
```
|
|
|
|
### Migration Between Backends
|
|
|
|
To migrate data between backends, use Redis replication or dump/restore:
|
|
|
|
```bash
|
|
# Export from redb
|
|
redis-cli -p 6379 --rdb dump.rdb
|
|
|
|
# Import to sled
|
|
redis-cli -p 6381 --pipe < dump.rdb
|
|
```
|
|
|
|
## Authentication and Database Selection
|
|
|
|
Connections start with no database selected. Any storage-backed command (GET, SET, H*, L*, SCAN, etc.) will return an error until you issue a SELECT to choose a database.
|
|
|
|
HeroDB uses an `Admin DB 0` to govern database existence, access and per-db encryption. Access control is enforced via `Admin DB 0` metadata. See the full model in [docs/admin.md](./admin.md).
|
|
|
|
Examples:
|
|
```bash
|
|
# Public database (no key required)
|
|
redis-cli -p $PORT SELECT 1
|
|
# → OK
|
|
```
|
|
|
|
```bash
|
|
# Private database (requires access key)
|
|
redis-cli -p $PORT SELECT 2 KEY my-db2-access-key
|
|
# → OK
|
|
```
|
|
|
|
```bash
|
|
# Admin DB 0 (requires admin secret)
|
|
redis-cli -p $PORT SELECT 0 KEY my-admin-secret
|
|
# → OK
|
|
```
|
|
|
|
```bash
|
|
# Before selecting a DB, storage commands will fail
|
|
redis-cli -p $PORT GET key
|
|
# → -ERR No database selected. Use SELECT <id> [KEY <key>] first
|
|
``` |