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