Struct microkv::kv::MicroKV

source ·

pub struct MicroKV { /* private fields */ }

Expand description

Defines the main interface structure to represent the most recent state of the data store.

Implementations§

source §

impl MicroKV

source

pub fn new_with_base_path<S: AsRef<str>>(dbname: S, base_path: PathBuf) -> Self

New MicroKV store with store to base path

source

pub fn new<S: AsRef<str>>(dbname: S) -> Self

Initializes a new empty and unencrypted MicroKV store with an identifying database name. This is the bare minimum that can operate as a key-value store, and can be configured using other builder methods.

source

pub fn open_with_base_path<S: AsRef<str>>(
dbname: S,
base_path: PathBuf
) -> Result<Self>

Open with base path

source

pub fn open<S: AsRef<str>>(dbname: S) -> Result<Self>

Opens a previously instantiated and encrypted MicroKV, given a db name. The public nonce generated from a previous session is also retrieved in order to do authenticated encryption later on.

source

pub fn get_db_path<S: AsRef<str>>(name: S) -> PathBuf

Helper that forms an absolute path from a given database name and the default workspace path.

source

pub fn get_db_path_with_base_path<S: AsRef<str>>(
name: S,
base_path: PathBuf
) -> PathBuf

with base path

source

pub fn with_pwd_clear<S: AsRef<str>>(self, unsafe_pwd: S) -> Self

Builds up the MicroKV with a cleartext password, which is hashed using the defaultly supported SHA-256 by sodiumoxide, in order to instantiate a 32-byte hash.

Use if the password to encrypt is not naturally pseudorandom and secured in-memory, and is instead read elsewhere, like a file or stdin (developer should guarantee security when implementing such methods, as MicroKV only guarantees hashing and secure storage).

source

pub fn with_pwd_hash(self, _pwd: [u8; 32]) -> Self

Builds up the MicroKV with a hashed buffer, which is then locked securely `for later use.

Use if the password to encrypt is generated as a pseudorandom value, or previously hashed by another preferred one-way function within or outside the application.

source

pub fn set_auto_commit(self, enable: bool) -> Self

Set is auto commit

source

pub fn namespace(&self, namespace: impl AsRef<str>) -> NamespaceMicrokv<'_>

source

pub fn namespace_default(&self) -> NamespaceMicrokv<'_>

source

pub fn get_unwrap<V>(&self, key: impl AsRef<str>) -> Result<V>where
V: DeserializeOwned + 'static,

unsafe get, may this api can change name to get_unwrap

source

pub fn get<V>(&self, key: impl AsRef<str>) -> Result<Option<V>>where
V: DeserializeOwned + 'static,

Decrypts and retrieves a value. Can return errors if lock is poisoned, ciphertext decryption doesn’t work, and if parsing bytes fail.

source

pub fn put<V>(&self, key: impl AsRef<str>, value: &V) -> Result<()>where
V: Serialize,

Encrypts and adds a new key-value pair to storage.

source

pub fn delete(&self, key: impl AsRef<str>) -> Result<()>

Delete removes an entry in the key value store.

source

pub fn lock_read<C, R>(&self, callback: C) -> Result<R>where
C: FnOnce(&IndexMap<String, SecVec<u8>>) -> R,

Arbitrary read-lock that encapsulates a read-only closure. Multiple concurrent readers can hold a lock and parse out data.

use microkv::MicroKV;
use microkv::namespace::ExtendedIndexMap;

let kv = MicroKV::new("example").with_pwd_clear("p@ssw0rd".to_string());
let value = String::from("my value");
kv.namespace("a").put("user", &value).expect("cannot insert user");
kv.namespace("b").put("user", &value).expect("cannot insert user");

kv.lock_read(|c| {
    let user_namespace_1: String = c.kv_get(&kv, "a", "user").expect("cannot read user").expect("key not found");
    let user_namespace_2: String = c.kv_get(&kv, "b", "user").expect("cannot read user").expect("key not found");
    assert_eq!(user_namespace_1, user_namespace_2);
}).expect("cannot get lock")

source

pub fn lock_write<C, R>(&self, callback: C) -> Result<R>where
C: FnOnce(&mut IndexMap<String, SecVec<u8>>) -> R,

Arbitrary write-lock that encapsulates a write-only closure Single writer can hold a lock and mutate data, blocking any other readers/writers before the lock is released.

use microkv::MicroKV;
use microkv::namespace::ExtendedIndexMap;

let kv = MicroKV::new("example").with_pwd_clear("p@ssw0rd".to_string());
let value: u32 = 123;
kv.put("number", &value).expect("cannot insert number");

kv.lock_write(|c| {
    let current_value: u32 = c.kv_get_unwrap(&kv, "", "number").expect("cannot read number");
    println!("Current value is: {current_value}");
    c.kv_put(&kv, "", "number", &(current_value + 1));
    let current_value: u32 = c.kv_get_unwrap(&kv, "", "number").expect("cannot read number");
    println!("Now the value is: {current_value}");
}).expect("cannot get lock")

source

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

Helper routine that acquires a reader lock and checks if a key exists.

source

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

Safely consumes an iterator over the keys in the IndexMap and returns a Vec<String> for further use.

Note that key iteration, not value iteration, is only supported in order to preserve security guarantees.

source

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

Safely consumes an iterator over a copy of in-place sorted keys in the IndexMap and returns a Vec<String> for further use.

Note that key iteration, not value iteration, is only supported in order to preserve security guarantees.

source

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

Empties out the entire underlying IndexMap in O(n) time, but does not delete the persistent storage file from disk. The IndexMap remains, and its capacity is kept the same.

source