Struct KvStore 

pub struct KvStore { /* private fields */ }

PostgreSQL-backed key-value store.

Provides a simple get/set/delete/set_if_absent/increment API over forge_kv and forge_kv_counters tables. All operations are atomic. TTLs are enforced both at read time (expired keys return None) and via periodic cleanup.

Keys are automatically namespaced with the configured prefix to prevent collisions between different subsystems sharing the same database.

Implementations

impl KvStore

pub fn new(pool: PgPool, namespace: &'static str) -> Self

pub async fn get(&self, key: &str) -> Result<Option<Vec<u8>>>

Get a value by key. Returns None if the key doesn’t exist or is expired.

pub async fn set( &self, key: &str, value: &[u8], ttl: Option<Duration>, ) -> Result<()>

Set a key to a value. Overwrites any existing value.

pub async fn set_if_absent( &self, key: &str, value: &[u8], ttl: Option<Duration>, ) -> Result<bool>

Set a key only if it doesn’t already exist (or is expired). Returns true if the key was set, false if it already existed.

Uses ON CONFLICT DO UPDATE ... WHERE to atomically treat expired rows as absent within a single statement (no CTE snapshot isolation issues).

pub async fn delete(&self, key: &str) -> Result<bool>

Delete a key. Returns true if the key existed.

pub async fn increment( &self, key: &str, delta: i64, ttl: Option<Duration>, ) -> Result<i64>

Atomically increment a counter by delta. Creates the counter at 0 if it doesn’t exist. Returns the new value. When ttl is None, an existing counter’s TTL is preserved (pass Some to override it). Expired counters are treated as non-existent (value resets to delta).

Uses ON CONFLICT DO UPDATE ... WHERE to handle expired rows atomically without CTE snapshot isolation issues.

pub async fn cleanup_expired(&self) -> Result<u64>

Remove expired keys from both tables. Returns total rows cleaned up.

Trait Implementations

impl KvHandle for KvStore

fn get<'a>( &'a self, key: &'a str, ) -> Pin<Box<dyn Future<Output = Result<Option<Vec<u8>>>> + Send + 'a>>

Get a value by key. Returns None if the key doesn’t exist or is expired.

fn set<'a>( &'a self, key: &'a str, value: &'a [u8], ttl: Option<Duration>, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'a>>

Set a key to a value, optionally with a TTL. Overwrites any existing value.

fn set_if_absent<'a>( &'a self, key: &'a str, value: &'a [u8], ttl: Option<Duration>, ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'a>>

Set a key only if it doesn’t already exist (or is expired). Returns true if the value was stored, false if a live entry already existed.

fn delete<'a>( &'a self, key: &'a str, ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'a>>

Delete a key. Returns true if the key existed.

fn increment<'a>( &'a self, key: &'a str, delta: i64, ttl: Option<Duration>, ) -> Pin<Box<dyn Future<Output = Result<i64>> + Send + 'a>>

Atomically increment a counter by delta.