syntaxis/docs/databases/surrealdb/rocksdb-explanation.md

📦 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

# 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

# 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)

// 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)

// 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

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

# 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

# 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)

# 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)

# 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.