epoch_db/
lib.rs

1//! # EpochDB 🦀
2//!
3//! An intelligent, persistent, and concurrent key-value store for Rust,
4//! designed to manage data with a lifecycle.
5//!
6//! **EpochDB** is an opinionated database engine built on the robust foundation of `sled`.
7//! It's designed specifically for workloads where the relevance of data changes over time,
8//! such as caching, session management, and real-time analytics.
9//!
10//! It provides a high-level, ergonomic API by treating data's **access frequency**
11//! and **age** as first-class citizens.
12
13use db::errors::TransientError;
14use serde::{Deserialize, Serialize};
15use sled::Tree;
16use std::{
17    path::PathBuf,
18    sync::{Arc, atomic::AtomicBool},
19    thread::JoinHandle,
20};
21
22pub mod db;
23pub mod metadata;
24pub mod metrics;
25
26/// This is the main struct which represents the database.
27///
28/// This struct holds the connection to the `sled` database and provides
29/// safe, high-level access to the various data trees. It manages a background
30/// thread for handling TTL (Time-To-Live) expirations automatically.
31///
32/// When this struct is dropped, it will signal the background thread to shut down
33/// and wait for it to finish gracefully.
34///
35/// This struct also holds 2 Arc<sled::Tree> directly instead of a single sled::Db,
36/// since almost all of the functions uses the tree directly which requires the sled::Db to
37/// constantly open each trees.
38/// Passing trees from the struct deletes the constant need to open the trees
39#[derive(Debug)]
40pub struct DB {
41    /// Stores the key and value
42    data_tree: Arc<Tree>,
43    /// Stores the key and the metadata
44    meta_tree: Arc<Tree>,
45    /// Stores the ttl timestamp and the key
46    ttl_tree: Arc<Tree>,
47    /// Manage the background thread which checks for expired keys
48    ttl_thread: Option<JoinHandle<Result<(), TransientError>>>,
49    /// Manage the background thread to periodically check the DB Size
50    size_thread: Option<JoinHandle<Result<(), TransientError>>>,
51    /// Signals all threads to gracefully shutdown, when the DB is dropped
52    shutdown: Arc<AtomicBool>,
53    /// Path to the database
54    pub path: PathBuf,
55}
56
57/// Contains additional information about a key, such as its access frequency and lifecycle.
58///
59/// NOTE: This struct derives Serialize and Deserialize to be stored as raw bytes (&[u8]) in the underlying sled tree.
60#[derive(Debug, Serialize, Deserialize, PartialEq)]
61pub struct Metadata {
62    /// The number of time the key has been accessed
63    pub freq: u64,
64    /// Timestamp of key creation, in seconds since the UNIX epoch
65    pub created_at: u64,
66    /// The key's time-to-live in seconds. If None, the key is persistent and never expires.
67    pub ttl: Option<u64>,
68}
epoch_db/lib.rs

epoch_db/
lib.rs
