Struct DB

pub struct DB { /* private fields */ }

This is the main struct which represents the database.

This struct holds the connection to the sled database and provides safe, high-level access to the various data trees. It manages a background thread for handling TTL (Time-To-Live) expirations automatically.

When this struct is dropped, it will signal the background thread to shut down and wait for it to finish gracefully.

This struct also holds 2 Arcsled::Tree directly instead of a single sled::Db, since almost all of the functions uses the tree directly which requires the sled::Db to constantly open each trees. Passing trees from the struct deletes the constant need to open the trees

Implementations

impl DB

pub fn new(path: &Path) -> Result<DB, Error>

Creates a new DB instance or opens an existing one at the specified path.

This function initializes the underlying sled database, opens the required data trees (data_tree, meta_tree, ttl_tree), and spawns a background thread to handle TTL expirations.

Errors

Returns a sled::Error if the database cannot be opened at the given path.

Examples found in repository

examples/metadata.rs (line 5)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let db = DB::new(Path::new("./my_database"))?;

    db.set("user:2", "Bob", None)?;

    // Increment the frequency counter
    db.increment_frequency("user:2")?;

    // Get the metadata for the key
    if let Some(meta) = db.get_metadata("user:2")? {
        println!("'user:2' has been accessed {} time(s)", meta.freq);
        // "'user:2' has been accessed 1 time(s)"
    }

    Ok(())
}

examples/basic_operations.rs (line 7)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Open the database. It will be created if it doesn't exist.
    let db = DB::new(Path::new("./my_database"))?;

    // 2. Set a value with a 10-second TTL.
    db.set("user:1", "Alice", Some(Duration::from_secs(10)))?;

    // 3. Get the value back.
    if let Some(value) = db.get("user:1")? {
        println!("Found value: {}", value); // "Found value: Alice"
    }

    // 4. Remove the data.
    db.remove("user:1")?;

    Ok(())
}

examples/concurrency.rs (line 6)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let db = Arc::new(DB::new("./my_database".as_ref())?);
    db.set("concurrent_key", "initial_value", None)?;

    let mut handles = vec![];
    for _ in 0..10 {
        let db_clone = Arc::clone(&db);
        let handle = thread::spawn(move || {
            for _ in 0..100 {
                db_clone.increment_frequency("concurrent_key").unwrap();
            }
        });
        handles.push(handle);
    }

    for handle in handles {
        handle.join().unwrap();
    }

    let final_meta = db.get_metadata("concurrent_key")?.unwrap();
    println!("Final frequency: {}", final_meta.freq); // "Final frequency: 1000"

    Ok(())
}

examples/ttl.rs (line 7)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let db = DB::new(Path::new("./my_database"))?;

    // Set a key with a 2-second TTL
    db.set("session:123", "user_token", Some(Duration::from_secs(2)))?;
    println!("'session:123' is set.");

    // The key exists initially
    assert!(db.get("session:123")?.is_some());

    // Wait for the TTL to expire
    sleep(Duration::from_secs(3));

    // The key should now be gone
    assert!(db.get("session:123")?.is_none());
    println!("'session:123' has expired.");

    // You can also update a key to make it permanent
    db.set(
        "user:permanent",
        "This will last forever",
        Some(Duration::from_secs(1)),
    )?;
    db.set("user:permanent", "This will last forever", None)?; // Remove the TTL

    sleep(Duration::from_secs(2));
    assert!(db.get("user:permanent")?.is_some());
    println!("'user:permanent' is still here.");

    Ok(())
}

pub fn set( &self, key: &str, val: &str, ttl: Option<Duration>, ) -> Result<(), Box<dyn Error>>

Sets a key-value pair with an optional Time-To-Live (TTL).

If the key already exists, its value and TTL will be updated. If ttl is None, the key will be persistent.

Errors

This function can return an error if there’s an issue with the underlying

Examples found in repository

examples/metadata.rs (line 7)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let db = DB::new(Path::new("./my_database"))?;

    db.set("user:2", "Bob", None)?;

    // Increment the frequency counter
    db.increment_frequency("user:2")?;

    // Get the metadata for the key
    if let Some(meta) = db.get_metadata("user:2")? {
        println!("'user:2' has been accessed {} time(s)", meta.freq);
        // "'user:2' has been accessed 1 time(s)"
    }

    Ok(())
}

examples/basic_operations.rs (line 10)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Open the database. It will be created if it doesn't exist.
    let db = DB::new(Path::new("./my_database"))?;

    // 2. Set a value with a 10-second TTL.
    db.set("user:1", "Alice", Some(Duration::from_secs(10)))?;

    // 3. Get the value back.
    if let Some(value) = db.get("user:1")? {
        println!("Found value: {}", value); // "Found value: Alice"
    }

    // 4. Remove the data.
    db.remove("user:1")?;

    Ok(())
}

examples/concurrency.rs (line 7)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let db = Arc::new(DB::new("./my_database".as_ref())?);
    db.set("concurrent_key", "initial_value", None)?;

    let mut handles = vec![];
    for _ in 0..10 {
        let db_clone = Arc::clone(&db);
        let handle = thread::spawn(move || {
            for _ in 0..100 {
                db_clone.increment_frequency("concurrent_key").unwrap();
            }
        });
        handles.push(handle);
    }

    for handle in handles {
        handle.join().unwrap();
    }

    let final_meta = db.get_metadata("concurrent_key")?.unwrap();
    println!("Final frequency: {}", final_meta.freq); // "Final frequency: 1000"

    Ok(())
}

examples/ttl.rs (line 10)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let db = DB::new(Path::new("./my_database"))?;

    // Set a key with a 2-second TTL
    db.set("session:123", "user_token", Some(Duration::from_secs(2)))?;
    println!("'session:123' is set.");

    // The key exists initially
    assert!(db.get("session:123")?.is_some());

    // Wait for the TTL to expire
    sleep(Duration::from_secs(3));

    // The key should now be gone
    assert!(db.get("session:123")?.is_none());
    println!("'session:123' has expired.");

    // You can also update a key to make it permanent
    db.set(
        "user:permanent",
        "This will last forever",
        Some(Duration::from_secs(1)),
    )?;
    db.set("user:permanent", "This will last forever", None)?; // Remove the TTL

    sleep(Duration::from_secs(2));
    assert!(db.get("user:permanent")?.is_some());
    println!("'user:permanent' is still here.");

    Ok(())
}

pub fn get(&self, key: &str) -> Result<Option<String>, Box<dyn Error>>

Retrieves the value for a given key.

Errors

Returns an error if the value cannot be retrieved from the database or if the value is not valid UTF-8.

Examples found in repository

examples/basic_operations.rs (line 13)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Open the database. It will be created if it doesn't exist.
    let db = DB::new(Path::new("./my_database"))?;

    // 2. Set a value with a 10-second TTL.
    db.set("user:1", "Alice", Some(Duration::from_secs(10)))?;

    // 3. Get the value back.
    if let Some(value) = db.get("user:1")? {
        println!("Found value: {}", value); // "Found value: Alice"
    }

    // 4. Remove the data.
    db.remove("user:1")?;

    Ok(())
}

examples/ttl.rs (line 14)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let db = DB::new(Path::new("./my_database"))?;

    // Set a key with a 2-second TTL
    db.set("session:123", "user_token", Some(Duration::from_secs(2)))?;
    println!("'session:123' is set.");

    // The key exists initially
    assert!(db.get("session:123")?.is_some());

    // Wait for the TTL to expire
    sleep(Duration::from_secs(3));

    // The key should now be gone
    assert!(db.get("session:123")?.is_none());
    println!("'session:123' has expired.");

    // You can also update a key to make it permanent
    db.set(
        "user:permanent",
        "This will last forever",
        Some(Duration::from_secs(1)),
    )?;
    db.set("user:permanent", "This will last forever", None)?; // Remove the TTL

    sleep(Duration::from_secs(2));
    assert!(db.get("user:permanent")?.is_some());
    println!("'user:permanent' is still here.");

    Ok(())
}

pub fn increment_frequency(&self, key: &str) -> Result<(), Box<dyn Error>>

Atomically increments the frequency counter for a given key.

Errors

This function can return an error if the key does not exist or if there is an issue with the compare-and-swap operation.

Examples found in repository

examples/metadata.rs (line 10)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let db = DB::new(Path::new("./my_database"))?;

    db.set("user:2", "Bob", None)?;

    // Increment the frequency counter
    db.increment_frequency("user:2")?;

    // Get the metadata for the key
    if let Some(meta) = db.get_metadata("user:2")? {
        println!("'user:2' has been accessed {} time(s)", meta.freq);
        // "'user:2' has been accessed 1 time(s)"
    }

    Ok(())
}

examples/concurrency.rs (line 14)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let db = Arc::new(DB::new("./my_database".as_ref())?);
    db.set("concurrent_key", "initial_value", None)?;

    let mut handles = vec![];
    for _ in 0..10 {
        let db_clone = Arc::clone(&db);
        let handle = thread::spawn(move || {
            for _ in 0..100 {
                db_clone.increment_frequency("concurrent_key").unwrap();
            }
        });
        handles.push(handle);
    }

    for handle in handles {
        handle.join().unwrap();
    }

    let final_meta = db.get_metadata("concurrent_key")?.unwrap();
    println!("Final frequency: {}", final_meta.freq); // "Final frequency: 1000"

    Ok(())
}

pub fn remove(&self, key: &str) -> Result<(), Box<dyn Error>>

Removes a key-value pair and its associated metadata from the database.

Errors

Can return an error if the transaction to remove the data fails.

Examples found in repository

examples/basic_operations.rs (line 18)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Open the database. It will be created if it doesn't exist.
    let db = DB::new(Path::new("./my_database"))?;

    // 2. Set a value with a 10-second TTL.
    db.set("user:1", "Alice", Some(Duration::from_secs(10)))?;

    // 3. Get the value back.
    if let Some(value) = db.get("user:1")? {
        println!("Found value: {}", value); // "Found value: Alice"
    }

    // 4. Remove the data.
    db.remove("user:1")?;

    Ok(())
}

pub fn get_metadata( &self, key: &str, ) -> Result<Option<Metadata>, Box<dyn Error>>

Retrieves the metadata for a given key.

Errors

Returns an error if the metadata cannot be retrieved or deserialized.

Examples found in repository

examples/metadata.rs (line 13)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let db = DB::new(Path::new("./my_database"))?;

    db.set("user:2", "Bob", None)?;

    // Increment the frequency counter
    db.increment_frequency("user:2")?;

    // Get the metadata for the key
    if let Some(meta) = db.get_metadata("user:2")? {
        println!("'user:2' has been accessed {} time(s)", meta.freq);
        // "'user:2' has been accessed 1 time(s)"
    }

    Ok(())
}

examples/concurrency.rs (line 24)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let db = Arc::new(DB::new("./my_database".as_ref())?);
    db.set("concurrent_key", "initial_value", None)?;

    let mut handles = vec![];
    for _ in 0..10 {
        let db_clone = Arc::clone(&db);
        let handle = thread::spawn(move || {
            for _ in 0..100 {
                db_clone.increment_frequency("concurrent_key").unwrap();
            }
        });
        handles.push(handle);
    }

    for handle in handles {
        handle.join().unwrap();
    }

    let final_meta = db.get_metadata("concurrent_key")?.unwrap();
    println!("Final frequency: {}", final_meta.freq); // "Final frequency: 1000"

    Ok(())
}

Trait Implementations

impl Debug for DB

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for DB

fn drop(&mut self)

Gracefully shuts down the TTL background thread when the DB instance goes out of scope.