Struct KvStore 

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

A handle to one named key-value store, backed by KV_TABLE.

Borrows its Connection for the handle’s lifetime ('conn), matching the crate’s Catalog/Inserter borrow convention. Open one with Connection::kv_store.

Examples

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

fn main() -> Result<()> {
    let conn = Connection::connect("localhost:7483", "app.hyper", CreateMode::CreateIfNotExists)?;
    let kv = conn.kv_store("settings")?;
    kv.set("theme", "dark")?;
    assert_eq!(kv.get("theme")?, Some("dark".to_string()));
    Ok(())
}

Implementations

impl<'conn> KvStore<'conn>

pub fn name(&self) -> &str

Returns this store’s validated name.

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

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

Errors

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

pub 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

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

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

Deserializes the JSON-encoded value for key into T.

Returns None if the key is absent.

Errors

• Error::InvalidName if key is invalid.
• Error::Serialization if the stored value is not valid JSON for T.
• Error::FeatureNotSupported / Error::Server as for get.

pub 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

• Error::InvalidName if key is invalid.
• Error::Serialization if value cannot be serialized to JSON.
• Error::FeatureNotSupported / Error::Server as for set.

pub 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 fn delete(&self, key: &str) -> Result<bool>

Deletes key; returns true if a row was removed.

Errors

• Error::InvalidName if key is invalid.
• Error::FeatureNotSupported / Error::Server.

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

Returns whether key is present in this store.

Errors

• Error::InvalidName if key is invalid.
• Error::FeatureNotSupported / Error::Server.

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

Returns the number of keys in this store.

Errors

• Error::FeatureNotSupported / Error::Server.

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

Returns this store’s keys, sorted ascending.

Errors

• Error::FeatureNotSupported / Error::Server.

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

Returns the total byte length of all values in this store (SUM(OCTET_LENGTH(value))). Returns 0 for an empty store; NULL values contribute 0 via COALESCE.

Errors

• Error::FeatureNotSupported / Error::Server.

pub 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

• Error::FeatureNotSupported / Error::Server.

pub 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

• Error::FeatureNotSupported / Error::Server.

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

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

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

Errors

• Error::FeatureNotSupported / Error::Server.

pub 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

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

pub 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 KvStore<'conn>

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

Formats the value using the given formatter.