scdb/
lib.rs

1/*!
2A very simple and fast key-value store but persisting data to disk, with a "localStorage-like" API.
3
4In front-end web development, [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage)
5provides a convenient way to quickly persist data to be used later by a given application even after a restart.
6Its API is extremely simple i.e.
7
8- `localStorage.getItem()`
9- `localStorage.setItem()`
10- `localStorage.removeItem()`
11- `localStorage.clear()`
12
13Such an embedded persistent data store with a simple API is hard to come by in backend (or even desktop) development, until now.
14
15scdb is meant to be like the 'localStorage' of backend and desktop (and possibly mobile) systems.
16Of course to make it a little more appealing, it has some extra features like:
17
18- Time-to-live (TTL) where a key-value pair expires after a given time.
19  Useful when used as a cache.
20- Searching for keys beginning with a given subsequence. [`is_search_enabled` param of `scdb::new()` must be true.]
21  Note: **Enabling searching makes `set`, `delete`, `clear` and `compact` slower than if it were disabled.**
22- Non-blocking reads from separate processes, and threads.
23  Useful in multithreaded applications
24- Fast Sequential writes to the store, queueing any writes from multiple processes and threads.
25  Useful in multithreaded applications
26
27# Usage
28
29First add `scdb` to your dependencies in your project's `Cargo.toml`.
30
31```toml
32[dependencies]
33scdb = "0.0.1" # or any available version you wish to use
34```
35
36Next:
37
38```rust
39# use std::io;
40
41# fn main() -> io::Result<()> {
42    // Create the store. You can configure its `max_keys`, `redundant_blocks` etc.
43    // The defaults are usable though.
44    // One very important config is `max_keys`.
45    // With it, you can limit the store size to a number of keys.
46    // By default, the limit is 1 million keys
47    let mut store = scdb::Store::new("db", // `store_path`
48                            Some(1000), // `max_keys`
49                            Some(1), // `redundant_blocks`
50                            Some(10), // `pool_capacity`
51                            Some(1800), // `compaction_interval`
52                            true)?; // `is_search_enabled` (if true, set, clear and delete
53                                    // are slower)
54    let key = b"foo";
55    let value = b"bar";
56
57    // Insert key-value pair into the store with no time-to-live
58    store.set(&key[..], &value[..], None)?;
59    # assert_eq!(store.get(&key[..])?, Some(value.to_vec()));
60
61    // Or insert it with an optional time-to-live (ttl)
62    // It will disappear from the store after `ttl` seconds
63    store.set(&key[..], &value[..], Some(1))?;
64    # assert_eq!(store.get(&key[..])?, Some(value.to_vec()));
65
66    // Getting the values by passing the key in bytes to store.get
67    let value_in_store = store.get(&key[..])?;
68    assert_eq!(value_in_store, Some(value.to_vec()));
69
70    // Updating the values is just like inserting them. Any key-value already in the store will
71    // be overwritten
72    store.set(&key[..], &value[..], None)?;
73
74    // Searching for all keys starting with a given substring is also possible.
75    // We can paginate the results.
76    // let's skip the first matched item, and return only upto to 2 items
77    let results = store.search(&b"f"[..], 1, 2)?;
78    # assert_eq!(results, vec![]);
79
80    // Or let's just return all matched items
81    let results = store.search(&b"f"[..], 0, 0)?;
82    # assert_eq!(results, vec![(key.to_vec(), value.to_vec())]);
83
84    // Delete the key-value pair by supplying the key as an argument to store.delete
85    store.delete(&key[..])?;
86    assert_eq!(store.get(&key[..])?, None);
87
88    // Deleting all key-value pairs to start afresh, use store.clear()
89    # store.set(&key[..], &value[..], None)?;
90    store.clear()?;
91    # assert_eq!(store.get(&key[..])?, None);
92
93    # Ok(())
94# }
95```
96 */
97
98#![deny(missing_docs)]
99#![warn(rust_2018_idioms)]
100
101pub use store::Store;
102
103mod internal;
104mod store;
scdb/lib.rs

scdb/
lib.rs
