9cef9b8d57
Merge _configs/ into config/ for single configuration directory. Update all path references. Changes: - Move _configs/* to config/ - Update .gitignore for new patterns - No code references to _configs/ found Impact: -1 root directory (layout_conventions.md compliance)
270 lines
6.7 KiB
Markdown
270 lines
6.7 KiB
Markdown
# 📦 Why RocksDB v0.23.0 Is In Your Build
|
|
|
|
## The Dependency Chain
|
|
|
|
```
|
|
Your Project (syntaxis)
|
|
↓
|
|
├─ syntaxis-core
|
|
│ ↓
|
|
│ └─ surrealdb = "2.3"
|
|
│ ↓
|
|
│ └─ surrealdb-core = "2.3.10"
|
|
│ ↓
|
|
│ └─ rocksdb v0.23.0 ← RIGHT HERE
|
|
│
|
|
├─ syntaxis-cli (uses syntaxis-core)
|
|
├─ syntaxis-api (uses syntaxis-core)
|
|
├─ syntaxis-tui (uses syntaxis-core)
|
|
└─ syntaxis-vapora (uses syntaxis-core)
|
|
```
|
|
|
|
## Direct Answer
|
|
|
|
**RocksDB is used by SurrealDB internally**, not directly by your code.
|
|
|
|
### Dependency Chain Explained
|
|
|
|
```
|
|
rocksdb v0.23.0
|
|
└─ surrealdb-core v2.3.10
|
|
└─ surrealdb v2.3.10
|
|
└─ syntaxis-core v0.1.0
|
|
└─ Your crates (cli, api, tui, etc.)
|
|
```
|
|
|
|
### What This Means
|
|
|
|
**RocksDB v0.23.0** is included because:
|
|
|
|
1. **SurrealDB depends on it**
|
|
- We added: `surrealdb = "2.3"` to syntaxis-core
|
|
- SurrealDB internally uses RocksDB for file-based storage
|
|
- RocksDB is a high-performance embedded key-value store
|
|
|
|
2. **For file-based deployment mode**
|
|
- When you use: `url = "file:///path/to/db"`
|
|
- SurrealDB uses RocksDB as the underlying storage engine
|
|
- This gives you persistent file-based database without a server
|
|
|
|
3. **It's optional - embedded mode only**
|
|
- For in-memory mode: `url = "mem://"` → RocksDB not needed
|
|
- For server mode: `ws://localhost:8000` → RocksDB on server side
|
|
- Rust code doesn't directly use RocksDB
|
|
|
|
---
|
|
|
|
## Cargo.toml Dependency Chain
|
|
|
|
### Your Addition
|
|
```toml
|
|
# syntaxis-core/Cargo.toml
|
|
|
|
[dependencies]
|
|
surrealdb = { version = "2.3", features = ["kv-mem", "kv-rocksdb"] }
|
|
↑ ↑
|
|
What we added This feature enables RocksDB support
|
|
```
|
|
|
|
### What SurrealDB Does
|
|
```toml
|
|
# surrealdb/Cargo.toml (internal - we don't control this)
|
|
|
|
[dependencies]
|
|
rocksdb = "0.23" ← Included for file-based storage
|
|
serde = "1.0"
|
|
tokio = "1.0"
|
|
# ... many other dependencies
|
|
```
|
|
|
|
### The Result
|
|
When you build, Cargo resolves:
|
|
```
|
|
surrealdb v2.3 → rocksdb v0.23.0
|
|
(automatically pulled in)
|
|
```
|
|
|
|
---
|
|
|
|
## Why Is This GOOD?
|
|
|
|
### ✅ It Means You Have Multiple Deployment Options
|
|
|
|
| Mode | Requires RocksDB? | How It Works |
|
|
|------|-------------------|-------------|
|
|
| In-Memory | ❌ NO | Data in RAM only |
|
|
| File-Based | ✅ YES | Uses RocksDB for persistence |
|
|
| Server Mode | ✅ YES (on server) | RocksDB on remote server |
|
|
| Docker | ✅ YES (in container) | Container has RocksDB |
|
|
| Kubernetes | ✅ YES (in pod) | Pod has RocksDB |
|
|
|
|
### ✅ You Don't Need To Manage RocksDB
|
|
|
|
- **Automatic**: SurrealDB handles RocksDB internals
|
|
- **Transparent**: You just specify `url = "file://..."`
|
|
- **Safe**: RocksDB is battle-tested, production-grade
|
|
- **Fast**: Highly optimized key-value store
|
|
|
|
### ✅ You Can Ignore It
|
|
|
|
If you use server mode (`ws://localhost:8000`):
|
|
- RocksDB is only on the server
|
|
- Your Rust binary doesn't link against it
|
|
- Smaller compiled binary size
|
|
- Can run on systems without RocksDB libraries
|
|
|
|
---
|
|
|
|
## How RocksDB Is Used
|
|
|
|
### Internally (You Don't See This)
|
|
|
|
```rust
|
|
// In surrealdb-core (internal SurrealDB code)
|
|
|
|
// When file-based:
|
|
let db = Database::new("file:///tmp/mydb")?;
|
|
↓
|
|
// SurrealDB uses RocksDB for storage
|
|
let rocksdb = rocksdb::DB::open(opts, "/tmp/mydb")?;
|
|
rocksdb.put(b"key", b"value")?;
|
|
```
|
|
|
|
### From Your Code (Simple)
|
|
|
|
```rust
|
|
// Your code (syntaxis-core)
|
|
let db = SurrealDatabase::new_file("/tmp/db").await?;
|
|
↓
|
|
// SurrealDB handles RocksDB internally
|
|
↓
|
|
// You just use the Database trait
|
|
let projects = db.list_projects().await?;
|
|
```
|
|
|
|
**You never directly interact with RocksDB!**
|
|
|
|
---
|
|
|
|
## What About Compilation?
|
|
|
|
### When You Compile
|
|
|
|
```bash
|
|
cargo build --workspace
|
|
↓
|
|
Rust resolves dependencies:
|
|
surrealdb v2.3
|
|
└─ rocksdb v0.23.0 ← Automatically downloaded
|
|
└─ librocksdb-sys v0.17.3+10.4.2 ← C/C++ bindings
|
|
↓
|
|
Downloads and compiles:
|
|
- RocksDB source (C++)
|
|
- Rust bindings to RocksDB
|
|
- Your code using SurrealDB
|
|
```
|
|
|
|
### Build Time Impact
|
|
|
|
- **First build**: Longer (compiles RocksDB C++ code)
|
|
- **Incremental builds**: Fast (cached)
|
|
- **Binary size**: Included when linked (file-based mode)
|
|
|
|
### To Check What's In Your Binary
|
|
|
|
```bash
|
|
# See all dependencies
|
|
cargo tree | grep rocksdb
|
|
|
|
# Check binary size
|
|
ls -lh target/debug/syntaxis-cli
|
|
ls -lh target/release/syntaxis-cli
|
|
|
|
# The release binary will be larger due to RocksDB code
|
|
```
|
|
|
|
---
|
|
|
|
## Do You Need to Do Anything?
|
|
|
|
### ❌ NO - It's Automatic
|
|
|
|
1. **No configuration needed**
|
|
- SurrealDB and RocksDB work together automatically
|
|
|
|
2. **No version conflicts**
|
|
- Cargo manages all versions
|
|
|
|
3. **No code changes needed**
|
|
- Your code stays the same
|
|
|
|
4. **Works transparently**
|
|
- Just use the Database trait
|
|
|
|
### ✅ You Can Control It Via Features
|
|
|
|
```toml
|
|
# If you wanted to disable file-based mode:
|
|
surrealdb = { version = "2.3", features = ["kv-mem"] }
|
|
↓
|
|
Only in-memory mode (no RocksDB)
|
|
|
|
# Current (with file-based support):
|
|
surrealdb = { version = "2.3", features = ["kv-mem", "kv-rocksdb"] }
|
|
↑
|
|
Both in-memory AND file-based modes
|
|
```
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
| Question | Answer |
|
|
|----------|--------|
|
|
| **Why RocksDB?** | SurrealDB uses it for file-based storage |
|
|
| **Required?** | Only for file-based/server deployments |
|
|
| **Your fault?** | No - automatic dependency |
|
|
| **Need to manage it?** | No - SurrealDB handles it |
|
|
| **Can you disable it?** | Yes - remove `kv-rocksdb` feature |
|
|
| **Affects binary?** | Yes - adds ~10-20MB to release binary |
|
|
| **Can you use server mode instead?** | Yes - RocksDB stays on server |
|
|
|
|
---
|
|
|
|
## Best Practice
|
|
|
|
### For Minimal Binary Size (Server Mode Only)
|
|
|
|
```toml
|
|
# syntaxis-core/Cargo.toml
|
|
surrealdb = { version = "2.3", features = ["kv-mem"] }
|
|
# Uses only in-memory mode
|
|
# No RocksDB linked into binary
|
|
# Connect to remote server: ws://localhost:8000
|
|
```
|
|
|
|
### For All Deployment Modes (Current)
|
|
|
|
```toml
|
|
# syntaxis-core/Cargo.toml
|
|
surrealdb = { version = "2.3", features = ["kv-mem", "kv-rocksdb"] }
|
|
# Supports in-memory, file-based, server modes
|
|
# RocksDB linked into binary when using file-based
|
|
# Most flexible
|
|
```
|
|
|
|
---
|
|
|
|
## Conclusion
|
|
|
|
**RocksDB v0.23.0 appears in your build because:**
|
|
|
|
1. ✅ You added SurrealDB 2.3 (correct!)
|
|
2. ✅ SurrealDB uses RocksDB for persistence (expected)
|
|
3. ✅ This is automatic and transparent
|
|
4. ✅ You don't need to do anything
|
|
|
|
**It's a normal, expected, beneficial dependency.** 🎯
|
|
|
|
You can deploy with confidence! The RocksDB inclusion means you have **multiple deployment options** including persistent file-based storage when needed.
|