A simple, fast and easy to use self-contained single file storage for Rust
Clone or download
Latest commit 4f9e9f5 Aug 13, 2018
Permalink
Failed to load latest commit information.
examples Rename reload/sync to load/save May 10, 2018
src Add write passthrough Aug 13, 2018
.gitignore Initial Commit Oct 15, 2016
.travis.yml Add mmap based backend Jun 19, 2018
Cargo.toml Bump rc version Aug 13, 2018
LICENSE Initial Commit Oct 15, 2016
README.md Applying comments #1 Jun 19, 2018

README.md

Rustbreak

Build Status Crates Link

Documentation

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!

Features

  • Simple To Use, Fast, Secure
  • Threadsafe
  • Serde compatible storage (ron, bincode, or yaml included)

Quickstart

Add this to your Cargo.toml:

[dependencies.rustbreak]
version = "2"
features = ["ron_enc"] # You can also use "yaml_enc" or "bin_enc"
                       # Check the documentation to add your own!
extern crate failure;
extern crate rustbreak;
use std::collections::HashMap;
use rustbreak::{MemoryDatabase, deser::Ron};

fn main() -> Result<(), failure::Error> {
    let db = MemoryDatabase::<HashMap<u32, String>, 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.
# use std::collections::HashMap;
use rustbreak::{MemoryDatabase, deser::Ron};

let db = MemoryDatabase::<HashMap<String, String>, 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:

[dependencies.rustbreak]
version = "1"
features = ["yaml_enc"]

You can now use rustbreak::deser::Yaml as deserialization struct.

Ron

If you would like to use ron you need to specify ron_enc as a feature:

[dependencies.rustbreak]
version = "1"
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:

[dependencies.rustbreak]
version = "1"
features = ["bin_enc"]

You can now use rustbreak::deser::Bincode as deserialization struct.