Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/TheNeikos/rustbreak
A simple, fast and easy to use self-contained single file storage for Rust
https://github.com/TheNeikos/rustbreak
bincode database daybreak file hashmap ron rust rustbreak storage yaml
Last synced: 12 days ago
JSON representation
A simple, fast and easy to use self-contained single file storage for Rust
- Host: GitHub
- URL: https://github.com/TheNeikos/rustbreak
- Owner: TheNeikos
- License: mpl-2.0
- Archived: true
- Created: 2016-10-15T12:37:43.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2022-01-16T12:16:23.000Z (almost 3 years ago)
- Last Synced: 2024-04-14T07:34:03.174Z (7 months ago)
- Topics: bincode, database, daybreak, file, hashmap, ron, rust, rustbreak, storage, yaml
- Language: Rust
- Homepage: https://docs.rs/rustbreak/
- Size: 5.16 MB
- Stars: 393
- Watchers: 8
- Forks: 28
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Rustbreak
=========
[](https://travis-ci.org/TheNeikos/rustbreak)
[](https://crates.io/crates/rustbreak)
**[Documentation][doc]**
Rustbreak is an [Daybreak] inspired self-contained file
database. It is meant to be fast and simple to use. You add it to your
application and it should just work for you. The only thing you will have to
take care of is saving.
When to use it
--------------
This library started out because of a need to be able to quickly write an
application in rust that needed some persistence while still being able to write
arbitrary data to it.
In Ruby there is [Daybreak] however for Rust there was no similar crate, until
now!
When not to use it
------------------
Rustbreak makes several trade-offs to be easy to use and extend, so knowing of these drawbacks is important if
you wish to use the library:
- The Database needs to fit into memory (Rustbreak cannot do partial loads/saves, so if the Database exceeds your available memory you will run OOM)
- Not all backends support atomic saves, so if your program crashes while it is saving you might save incomplete data (Notably only `PathBackend` supports atomic saves)
Features
--------
- Simple To Use, Fast, Secure
- Threadsafe
- Serde compatible storage (ron, bincode, or yaml included)
Quickstart
----------
Add this to your `Cargo.toml`:
```toml
[dependencies.rustbreak]
version = "2"
features = ["ron_enc"] # You can also use "yaml_enc" or "bin_enc"
# Check the documentation to add your own!
```
```rust
extern crate rustbreak;
use std::collections::HashMap;
use rustbreak::{MemoryDatabase, deser::Ron};
fn main() -> rustbreak::Result<()> {
let db = MemoryDatabase::, Ron>::memory(HashMap::new())?;
println!("Writing to Database");
db.write(|db| {
db.insert(0, String::from("world"));
db.insert(1, String::from("bar"));
});
db.read(|db| {
// db.insert("foo".into(), String::from("bar"));
// The above line will not compile since we are only reading
println!("Hello: {:?}", db.get(&0));
})?;
Ok(())
}
```
Usage
-----
Usage is quite simple:
- Create/open a database using one of the Database constructors:
- Create a `FileDatabase` with `FileDatabase::from_path`.
- Create a `MemoryDatabase` with `MemoryDatabase::memory`.
- Create a `MmapDatabase` with `MmapDatabase::mmap` or `MmapDatabase::mmap_with_size` with `mmap` feature.
- Create a `Database` with `Database::from_parts`.
- `Write`/`Read` data from the Database
- Don't forget to run `save` periodically, or whenever it makes sense.
- You can save in parallel to using the Database. However you will lock
write acess while it is being written to storage.
```rust
# use std::collections::HashMap;
use rustbreak::{MemoryDatabase, deser::Ron};
let db = MemoryDatabase::, Ron>::memory(HashMap::new(), Ron);
println!("Writing to Database");
db.write(|db| {
db.insert("hello".into(), String::from("world"));
db.insert("foo".into(), String::from("bar"));
});
db.read(|db| {
// db.insert("foo".into(), String::from("bar"));
// The above line will not compile since we are only reading
println!("Hello: {:?}", db.get("hello"));
});
```
## Encodings
The following parts explain how to enable the respective features. You can also
enable several at the same time.
### Yaml
If you would like to use yaml you need to specify `yaml_enc` as a feature:
```toml
[dependencies.rustbreak]
version = "2"
features = ["yaml_enc"]
```
You can now use `rustbreak::deser::Yaml` as deserialization struct.
### Ron
If you would like to use [`ron`](https://github.com/ron-rs/ron) you need to
specify `ron_enc` as a feature:
```toml
[dependencies.rustbreak]
version = "2"
features = ["ron_enc"]
```
You can now use `rustbreak::deser::Ron` as deserialization struct.
### Bincode
If you would like to use bincode you need to specify `bin_enc` as a feature:
```toml
[dependencies.rustbreak]
version = "2"
features = ["bin_enc"]
```
You can now use `rustbreak::deser::Bincode` as deserialization struct.
[doc]:http://neikos.me/rustbreak/rustbreak/index.html
[Daybreak]:https://propublica.github.io/daybreak/