Struct Client

pub struct Client { /* private fields */ }

Thread-safe, optionally persistent client for interacting with a keystore database

Implementations

impl Client

pub fn new<P: AsRef<Path> + Clone + Debug>( path: P, sync_interval: Option<Duration>, ) -> Result<Box<dyn DatabaseClient>, DatabaseError>

Creates a database at the supplied path

use std::path::Path;
let c = Client::new(Path::new("temp.db"), None);

This database will not sync on its own and will need to be saved with

c.save();

To create a persistent database that will create a thread attached to the lifetime of the client provide a duration

use std::path::Path;
use std::time::Duration;
let c = Client::new(Path::new("temp3.db"), Some(Duration::from_millis(30)));

This thread will prune (remove stale entries) and save the database every duration

pub fn open<P: AsRef<Path> + Clone + Debug>( path: P, ) -> Result<Box<dyn DatabaseClient>, DatabaseError>

Opens an existing database at the supplied path

use std::path::Path;
let c = Client::open(Path::new("existing.db"));

This database will resume the sync settings that were provided when the database was created.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl DatabaseClient for Client

fn save(&mut self) -> Result<(), DatabaseError>

Removes stale entries as defined by the expiration value per table and saves the database to disk; using lz4 compression

use std::path::Path;
let c = Client::new(Path::new("saved.db"), None);

This database will not sync on its own and will need to be saved with

c.save();

fn create_table(&mut self, table: Table) -> Result<(), DatabaseError>

Creates a table within the database of the associated client

use persistent_keystore_rs::{Client, Table, FieldType};
use persistent_keystore_rs::prelude::*;
use std::time::Duration;
let mut c = Client::new(Path::new("createtable.db"), None).unwrap();
let table = Table::new()
    .name(String::from("MyTable"))
    .primary_field(FieldType::String).unwrap()
    .add_field(String::from("TimeStamp"), FieldType::Date).unwrap()
    .add_expiration(Duration::from_secs(2592000))
    .build().unwrap();
c.create_table(table).unwrap();

fn list_tables(&mut self) -> Result<Vec<String>, DatabaseError>

Lists tables within the database of the associated client

let mut c = Client::new(Path::new("listtable.db"), None).unwrap();
let tables = c.list_tables().unwrap();
assert_eq!(tables.len(), 1);
assert_eq!(tables[0], String::from("MyTable"));

fn drop_table(&mut self, table: &String) -> Result<(), DatabaseError>

Drops the specified table from within the database of the associated client

let mut c = Client::new(Path::new("droptable.db"), None).unwrap();
let tables = c.list_tables().unwrap();
assert_eq!(tables.len(), 1);
assert_eq!(tables[0], String::from("MyTable"));
c.drop_table(&String::from("MyTable")).unwrap();
let current_tables = c.list_tables().unwrap();
assert_eq!(current_tables.len(), 0);

fn insert(&mut self, table: String, entry: Entry) -> Result<(), DatabaseError>

Inserts the provided entry into the specified table within the database of the associated client. If an entry with the same primary key exists, an DatabaseError::EntryExists is returned

use persistent_keystore_rs::{Entry, Field};
use std::time::SystemTime;
let mut c = Client::new(Path::new("insertentry.db"), None).unwrap();
let entry = Entry::new()
    .set_primary_field(Field::String("MyFirstEntry".to_string())).unwrap()
    .add_field("TimeStamp".to_string(), Field::Date(SystemTime::now())).unwrap()
    .build().unwrap();
c.insert("MyTable".to_string(), entry).unwrap();

fn insert_or_update( &mut self, table: String, entry: Entry, ) -> Result<(), DatabaseError>

Inserts the provided entry into the specified table within the database of the associated client. If an entry with the same primary key exists, the entry is updated.

use persistent_keystore_rs::{Entry, Field};
use std::time::SystemTime;
let mut c = Client::new(Path::new("insertorupdateentry.db"), None).unwrap();
let entry = Entry::new()
    .set_primary_field(Field::String("MyFirstEntry".to_string())).unwrap()
    .add_field("TimeStamp".to_string(), Field::Date(SystemTime::now())).unwrap()
    .build().unwrap();
c.insert("MyTable".to_string(), entry.clone()).unwrap();
c.insert_or_update("MyTable".to_string(), entry).unwrap();

fn update(&mut self, table: String, entry: Entry) -> Result<(), DatabaseError>

Updates an existing entry in the specified table within the database of the associated client. If an entry does not exist, DatabaseError::EntryDoesNotExists is returned

use persistent_keystore_rs::{Entry, Field};
use std::time::SystemTime;
let mut c = Client::new(Path::new("updateentry.db"), None).unwrap();
let entry = Entry::new()
    .set_primary_field(Field::String("MyFirstEntry".to_string())).unwrap()
    .add_field("TimeStamp".to_string(), Field::Date(SystemTime::now())).unwrap()
    .build().unwrap();
c.update("MyTable".to_string(), entry).unwrap();

fn get( &mut self, table: String, primary_field: Field, ) -> Result<Entry, DatabaseError>

Get an existing entry from the specified table within the database of the associated client. If an entry does not exist, DatabaseError::EntryDoesNotExists is returned

use persistent_keystore_rs::Field;
let mut c = Client::new(Path::new("getentry.db"), None).unwrap();
let e = c.get("MyTable".to_string(), Field::String("MyFirstEntry".to_string())).unwrap();

fn delete( &mut self, table: String, primary_field: Field, ) -> Result<(), DatabaseError>

Delete an existing entry from the specified table within the database of the associated client. If an entry does not exist, DatabaseError::EntryDoesNotExists is returned

use persistent_keystore_rs::Field;
let mut c = Client::new(Path::new("delete.db"), None).unwrap();
c.delete("MyTable".to_string(), Field::String("MyFirstEntry".to_string())).unwrap();

fn delete_many( &mut self, table: String, criteria: HashMap<String, Field>, ) -> Result<u64, DatabaseError>

Delete all entries matching the supplied criteria.

use persistent_keystore_rs::Field;
use std::collections::HashMap;
let mut c = Client::new(Path::new("deletemany.db"), None).unwrap();
let mut criteria: HashMap<String, Field> = HashMap::new();
criteria.insert("OptionalField".to_string(), Field::String("MyTestingField".to_string()));
c.delete_many("MyTable".to_string(), criteria).unwrap();

fn scan(&mut self, table: String) -> Result<Vec<Entry>, DatabaseError>

Returns all entries from the specified table within the database of the associated client. If no entries exist, will return an empty vec

let mut c = Client::new(Path::new("scan.db"), None).unwrap();
let results = c.scan("MyTable".to_string()).unwrap();

fn query( &mut self, table: String, criteria: HashMap<String, Field>, ) -> Result<Vec<Entry>, DatabaseError>

Query for entries within a specified table meeting the supplied criteria.

use persistent_keystore_rs::Field;
use std::collections::HashMap;
let mut c = Client::new(Path::new("query.db"), None).unwrap();
let mut criteria: HashMap<String, Field> = HashMap::new();
criteria.insert("OptionalField".to_string(), Field::String("MyTestingField".to_string()));
let results = c.query("MyTable".to_string(), criteria).unwrap();

fn prune(&mut self) -> Result<(), DatabaseError>

Removes entries that have expired by the specified TTL field in the table. This is done automatically before saves if a sync_interval is provided.

use persistent_keystore_rs::{Client, Table, FieldType, Entry};
use persistent_keystore_rs::Field;
use std::collections::HashMap;
let mut c = Client::new(Path::new("prune.db"), None).unwrap();
let table = Table::new()
    .name(String::from("MyTable"))
    .add_expiration(Duration::from_secs(1))
    .primary_field(FieldType::String).unwrap()
    .add_field("FirstKey".to_string(), FieldType::I64).unwrap()
    .add_optional_field("OptionalKey".to_string(), FieldType::String).unwrap()
    .build().unwrap();

c.create_table(table).unwrap();

let entry_first = Entry::new()
    .set_primary_field(Field::String("This should Succeed".to_string())).unwrap()
    .add_field("FirstKey".to_string(), Field::I64(123123)).unwrap()
    .add_field("OptionalKey".to_string(), Field::String("My first entry".to_string())).unwrap()
    .build().unwrap();

let result = c.insert("MyTable".to_string(), entry_first);

if let Err(e) = result {
    panic!("No error expected, received {}", e)
} 

let output = c.scan("MyTable".to_string()).unwrap();

if output.len() != 1 {
    panic!("Expected scan results to be 1")
};

sleep(Duration::from_secs(2));
c.prune().unwrap();

let output = c.scan("MyTable".to_string()).unwrap();
if output.len() != 0 {
    panic!("Expected scan results to be 0")
};