Building a Key-Value Store: Your First Database Component

What We’re Building Today

Today we’re building the foundation of FerrisDB - a simple key-value store! Think of it like a super-fast notebook where you can store and retrieve information using a unique key.

graph LR
    A[Your App] -->|"set('user:123', 'Alice')"| B[Key-Value Store]
    B -->|"get('user:123')"| A
    B -->|"Returns 'Alice'"| A

The Real-World Problem

Every web app needs fast data access. When someone visits your e-commerce site:

• You need their shopping cart (key: cart:user123)
• You need their session (key: session:abc123)
• You need product details (key: product:789)

Redis solves this problem. Today, we’ll build our own version!

What You’ll Learn

🦀 New Rust Concepts

• Variables: How Rust handles data
• Mutability: When data can change
• Structs: Creating custom types
• HashMap: Rust’s key-value collection
• Option: Handling missing values

📚 Database Knowledge

• Key-Value Model: Simplest database design
• In-Memory Storage: Trading durability for speed
• Hash Tables: O(1) performance magic

Prerequisites

Before You Start

Required:

• Rust installed (rustup.rs)
• Basic programming knowledge (any language)
• A text editor

Time Needed: ~30 minutes

No Prior Rust Knowledge Required! 🎉

Setup

Let’s create our workspace:

# Create a new Rust project
cargo new --lib tutorial-01-kv-store
cd tutorial-01-kv-store

# Open in your editor
code . # or your preferred editor

Let’s Build!

Step 1: Creating Our Storage Structure

Let’s start with the simplest possible key-value store:

Write This Code

// In src/lib.rs
// A struct is like a class in other languages
pub struct KeyValueStore {
    // For now, we'll add fields in the next step
}

Understanding the Code

pub struct KeyValueStore {
//│  │     └─ The name of our type
//│  └─ Keyword to define a new type
//└─ "public" - other code can use this
}

If You Know JavaScript

// In JavaScript, you might write:
class KeyValueStore {
  // fields go here
}

// Or with modern JS:
const KeyValueStore = class {
  // implementation
};

Key differences:

• Rust uses struct instead of class
• pub makes it public (like export)
• No inheritance in Rust (we’ll use traits later)

If You Know Python

# In Python, you might write:
class KeyValueStore:
    def __init__(self):
        # Initialize here
        pass

Key differences:

• Rust separates data (struct) from methods (impl)
• No self in the struct definition
• Types are defined at compile time

🦀 New Rust Concept: Structs

A struct is Rust’s way of creating custom types. Think of it like:

• A class without inheritance (Java/C#)
• An object literal with a fixed shape (JavaScript)
• A dataclass (Python)

Why structs? They group related data together with guaranteed memory layout.

📖 Learn more: The Rust Book - Structs

Step 2: Adding Storage with HashMap

Now let’s add actual storage to our struct:

Evolve Our Code

use std::collections::HashMap;

pub struct KeyValueStore {
    // HashMap is like Map in JS or dict in Python
    data: HashMap<String, String>,
}

What Changed

 use std::collections::HashMap;

pub struct KeyValueStore {
     data: HashMap<String, String>,
}

We added:

• use statement to import HashMap
• A field called data that stores String keys and String values

📚 Database Concept: Hash Tables

Hash tables provide O(1) average-case lookups - that means finding a value is equally fast whether you have 10 items or 10 million!

Real databases like Redis use hash tables for:

• Session storage
• Caching
• Counters
• Any key-value data

Trade-off: No ordering, uses more memory than arrays.

Step 3: Creating New Instances

Let’s add a way to create new key-value stores:

Add This Code

impl KeyValueStore {
    // This is like a constructor
    pub fn new() -> Self {
        KeyValueStore {
            data: HashMap::new(),
        }
    }
}

Understanding impl Blocks

impl KeyValueStore {
//│  └─ The type we're adding methods to
//└─ "implementation" - where methods live

    pub fn new() -> Self {
    //     │   │    └─ Returns our type
    //     │   └─ No parameters
    //     └─ Function name (convention: "new")

        KeyValueStore {
            data: HashMap::new(),
        }
    }
}

Test What We Built

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn new_creates_empty_store() {
        let store = KeyValueStore::new();
        assert!(store.is_empty());
        assert_eq!(store.len(), 0);
    }
}

Run it:

cargo test new_creates_empty_store

What This Test Proves

This test verifies our constructor creates an empty store. The assert! macro checks boolean conditions, while assert_eq! compares values for equality. This proves our basic structure works!

Step 4: Storing Values

Now for the core functionality - storing key-value pairs:

Add set() Method

impl KeyValueStore {
    pub fn new() -> Self {
        KeyValueStore {
            data: HashMap::new(),
        }
    }

    // Add this method
    pub fn set(&mut self, key: String, value: String) {
        self.data.insert(key, value);
    }
}

Understanding Mutability

pub fn set(&mut self, key: String, value: String) {
//         │    │
//         │    └─ "mutable borrow of self"
//         └─ We need to modify the struct

    self.data.insert(key, value);
    //        │      └─ HashMap's insert method
    //        └─ Adds or updates the key
}

🦀 New Rust Concept: Mutability with &mut

In Rust, data is immutable by default. To modify something, you need to:

1. Declare it with mut (for variables)
2. Use &mut (for references)

Think of it like:

• &self = “I want to read this”
• &mut self = “I want to read AND write this”

This prevents accidental modifications and data races!

📖 Learn more: The Rust Book - References and Borrowing

Step 5: Retrieving Values

Let’s add the ability to get values back:

Add get() Method

impl KeyValueStore {
    // ... new() and set() methods ...

    pub fn get(&self, key: &str) -> Option<String> {
        self.data.get(key).cloned()
    }
}

Understanding Option

pub fn get(&self, key: &str) -> Option<String> {
//         │     │            └─ Might return a String
//         │     └─ Borrow the key (don't take ownership)
//         └─ Only need to read

    self.data.get(key).cloned()
    //        │       └─ Make a copy of the value
    //        └─ Returns Option<&String>
}

If You Know JavaScript

// JavaScript returns undefined for missing keys
const value = map.get("key"); // undefined or value

// Rust returns Option<T>
let value = store.get("key"); // Some(value) or None

Option is Rust’s null-safe way of handling missing values!

🦀 New Rust Concept: Option<T>

Option<T> is Rust’s way of handling nullable values safely:

• Some(value) - We have a value
• None - No value exists

No more null pointer exceptions! The compiler forces you to handle both cases.

📖 Learn more: The Rust Book - Option

Step 6: Adding Utility Methods

Let’s add some helpful methods to check the store’s state:

Add len() and is_empty()

impl KeyValueStore {
    // ... previous methods ...

    pub fn len(&self) -> usize {
        self.data.len()
    }

    pub fn is_empty(&self) -> bool {
        self.data.is_empty()
    }
}

Why These Methods?

These utility methods follow Rust conventions:

• len() - Returns the number of entries (like Vec, HashMap, etc.)
• is_empty() - More readable than len() == 0

Database insight: Real databases track metrics like entry count for performance monitoring!

Step 7: Complete Working Example

Let’s put it all together with a comprehensive test:

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn set_stores_value_and_get_retrieves_it() {
        let mut store = KeyValueStore::new();

        // Test basic set and get
        store.set("user:1".to_string(), "Alice".to_string());
        assert_eq!(store.get("user:1"), Some("Alice".to_string()));

        // Test missing key
        assert_eq!(store.get("user:2"), None);

        // Test overwrite
        store.set("user:1".to_string(), "Alice Smith".to_string());
        assert_eq!(store.get("user:1"), Some("Alice Smith".to_string()));
    }
}

Run all tests:

cargo test

What This Test Teaches

This comprehensive test demonstrates three key concepts:

1. Happy path: Basic set/get functionality works
2. Option<T> handling: Missing keys return None (not crashes!)
3. Update behavior: Setting the same key twice updates the value

This is exactly how real databases like Redis work!

Step 8: Trying It Out

Let’s see our key-value store in action outside of tests:

src/main.rs

use tutorial_01_kv_store::KeyValueStore;

fn main() {
    let mut store = KeyValueStore::new();

    // Store some user data
    store.set("user:1".to_string(), "Alice".to_string());
    store.set("user:2".to_string(), "Bob".to_string());

    // Retrieve and display
    println!("Looking up users...");

    match store.get("user:1") {
        Some(name) => println!("User 1: {}", name),
        None => println!("User 1 not found"),
    }

    // Try a missing key
    match store.get("user:999") {
        Some(name) => println!("User 999: {}", name),
        None => println!("User 999 not found"),
    }
}

Run it:

cargo run

You should see:

Looking up users...
User 1: Alice
User 999 not found

Step 9: Making It Clippy-Compliant

Rust has a helpful tool called clippy that suggests improvements. Let’s follow one of its recommendations:

Add Default Implementation

use std::collections::HashMap;

#[derive(Default)]  // Add this line
pub struct KeyValueStore {
    data: HashMap<String, String>,
}

This automatically implements the Default trait, which provides a standard way to create an empty store.

Why This Matters

// With Default, users can now do:
let store = KeyValueStore::default();

// In addition to:
let store = KeyValueStore::new();

It’s a Rust convention: if your type has an obvious “empty” or “default” state, implement Default!

Bonus: This satisfies Rust’s linter (clippy) and makes your code more idiomatic.

Running Clippy

You can check your code with clippy anytime: bash cargo clippy It’s like having a Rust expert review your code!

Comparing with Real FerrisDB

Our Tutorial Code

use std::collections::HashMap;

#[derive(Default)]
pub struct KeyValueStore {
    data: HashMap<String, String>,
}

impl KeyValueStore {
    pub fn new() -> Self {
        KeyValueStore {
            data: HashMap::new(),
        }
    }

    pub fn set(&mut self, key: String, value: String) {
        self.data.insert(key, value);
    }

    pub fn get(&self, key: &str) -> Option<String> {
        self.data.get(key).cloned()
    }

    pub fn len(&self) -> usize {
        self.data.len()
    }

    pub fn is_empty(&self) -> bool {
        self.data.is_empty()
    }
}

Real FerrisDB Approach

// Simplified from ferrisdb-storage/src/memtable/mod.rs
pub struct MemTable {
    skiplist: Arc<SkipList>,
    memory_usage: AtomicUsize,
    max_size: usize,
}

impl MemTable {
    pub fn set(&self, key: Vec<u8>, value: Vec<u8>) -> Result<()> {
        // Uses bytes for flexibility
        // Tracks memory usage
        // Returns Result for error handling
        // Uses skip list for ordering
    }
}

Key Differences

Real FerrisDB adds:

• Bytes instead of Strings: More flexible
• Skip List instead of HashMap: Maintains order
• Memory tracking: Knows when to flush
• Error handling: Production robustness
• Concurrency: Thread-safe operations

We’ll build toward these features in future tutorials!

🎉 Congratulations!

You’ve successfully built your first database component in Rust!

What You Built

• ✅ A working key-value store (like a mini Redis)
• ✅ Set and get operations
• ✅ Proper handling of missing keys
• ✅ Utility methods for counting and checking emptiness
• ✅ Your first Rust struct and methods

Rust Concepts You Mastered

• 🦀 Structs: Creating custom types
• 🦀 Mutability: Understanding &mut self vs &self
• 🦀 HashMap: Using Rust’s built-in collections
• 🦀 Option<T>: Safe handling of nullable values
• 🦀 Methods: Adding behavior with impl blocks

Database Knowledge You Gained

• 📚 Key-Value Model: The simplest database abstraction
• 📚 Hash Tables: O(1) performance for lookups
• 📚 In-Memory Storage: Speed vs durability trade-off

Next Steps

You Found Our Secret! 🤫

Tutorial 2 is still in stealth mode. We’re adding the final touches! Drop us a star if you want us to hurry up! ⭐

Practice Challenges

1. Add a delete() method 2. Add a len() method to count entries 3. Make keys case-insensitive

Quick Reference

Commands We Used

cargo new --lib tutorial-01-kv-store
cargo test
cargo test test_specific_name

Key Patterns

// Creating a struct
pub struct Name { field: Type }

// Adding methods
impl Name {
    pub fn method(&self) { }     // read-only
    pub fn method(&mut self) { } // read-write
}

// Using Option
match result {
    Some(value) => // use value,
    None => // handle missing,
}

---

📝 How was this tutorial?

We’re constantly improving! If anything was confusing, please let us know. Our goal is to make database internals accessible to every developer.

Great job! You’ve mastered the basics of Rust and built your first database component! 🚀