Struct AsyncKvStore 

pub struct AsyncKvStore<'conn> { /* private fields */ }

A handle to one named key-value store over an AsyncConnection.

The async twin of KvStore; see it for semantics. Open one with AsyncConnection::kv_store.

Examples

use hyperdb_api::{AsyncConnection, CreateMode, Result};

async fn demo(conn: &AsyncConnection) -> Result<()> {
    let kv = conn.kv_store("settings").await?;
    kv.set("theme", "dark").await?;
    assert_eq!(kv.get("theme").await?, Some("dark".to_string()));
    Ok(())
}

Implementations

impl<'conn> AsyncKvStore<'conn>

pub fn name(&self) -> &str

Returns this store’s validated name.

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

Returns the value for key, or None if absent or NULL.

Errors

See KvStore::get.

pub async fn set(&self, key: &str, value: &str) -> Result<SetOutcome>

Sets key to value, inserting or overwriting (upsert). Returns SetOutcome indicating whether the key was newly created.

Errors

See KvStore::set.

pub async fn get_as<T: DeserializeOwned>(&self, key: &str) -> Result<Option<T>>

Deserializes the JSON value for key into T; None if absent.

Errors

See KvStore::get_as.

pub async fn set_as<T: Serialize>( &self, key: &str, value: &T, ) -> Result<SetOutcome>

Serializes value to JSON and stores it under key (upsert). Returns SetOutcome indicating whether the key was newly created.

Errors

See KvStore::set_as.

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

Inserts value under key only if key is absent.

Returns true if a row was written, false if the key already existed (in which case nothing is written). A single INSERT ... WHERE NOT EXISTS statement decides, so there is no check-then-write race within a connection. The backing table has no unique constraint on (store_name, key), so two separate processes writing the same key to a shared persistent store concurrently could both pass NOT EXISTS and double-insert; within a single process (including the MCP daemon, which serializes engine access) the guard is exact.

Errors

• Error::InvalidName if key is invalid.
• Error::FeatureNotSupported on gRPC transport.
• Error::Server if the INSERT fails.

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

Deletes key; returns true if a row was removed.

Errors

See KvStore::delete.

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

Returns whether key is present.

Errors

See KvStore::exists.

pub async fn size(&self) -> Result<i64>

Returns the number of keys in this store.

Errors

See KvStore::size.

pub async fn byte_size(&self) -> Result<i64>

Returns the total byte size of all values in this store (0 if empty).

Errors

See KvStore::byte_size.

pub async fn entries(&self) -> Result<Vec<(String, String)>>

Returns this store’s (key, value) pairs, sorted by key ascending.

Materializes the whole store — intended for small scratchpad stores.

Errors

See KvStore::entries.

pub async fn keys(&self) -> Result<Vec<String>>

Returns this store’s keys, sorted ascending.

Errors

See KvStore::keys.

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

Deletes every key in this store; returns the number removed.

The shared backing table survives; only this store’s rows are removed.

Errors

See KvStore::clear.

pub async fn pop(&self) -> Result<Option<(String, String)>>

Removes and returns the lowest-ordered pair, or None if empty.

The peek and delete run in one transaction, so they apply atomically — either both commit, or neither does (on error the transaction is rolled back). A SQL-NULL value is returned as an empty string.

Errors

See KvStore::pop.

pub async fn set_batch( &self, entries: &[(&str, &str)], ) -> Result<BatchSetOutcome>

Upserts every (key, value) pair in one transaction. Returns BatchSetOutcome reporting how many keys were newly inserted vs. overwritten.

All keys are validated before the transaction opens, so an invalid key aborts the whole batch without writing anything.

Errors

See KvStore::set_batch.

pub async fn set_batch_if_absent( &self, entries: &[(&str, &str)], ) -> Result<BatchGuardOutcome>

Inserts every absent (key, value) pair in one transaction, skipping keys that already exist. All keys are validated before the transaction opens, so an invalid key aborts the whole batch without writing anything.

Errors

• Error::InvalidName if any key is invalid (checked before writing).
• Error::FeatureNotSupported / Error::Server.

Trait Implementations

impl<'conn> Debug for AsyncKvStore<'conn>

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

Formats the value using the given formatter.