• Stars
    star
    389
  • Rank 110,500 (Top 3 %)
  • Language
    Rust
  • License
    Mozilla Public Li...
  • Created about 8 years ago
  • Updated almost 2 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A simple, fast and easy to use self-contained single file storage for Rust

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!

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:

[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 rustbreak;
use std::collections::HashMap;
use rustbreak::{MemoryDatabase, deser::Ron};

fn main() -> rustbreak::Result<()> {
    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 = "2"
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 = "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:

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

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

More Repositories

1

envious

Deserialize (potentially nested) environment variables into your custom structs
Rust
51
star
2

bevy_spicy_gamebase

Rust
21
star
3

bevy_spicy_aseprite

Rust
19
star
4

type_description

Provides machine-readable descriptions for rust types
Rust
19
star
5

furry.cafe

Rust
13
star
6

bevy_squares

Rust
13
star
7

spinner

A simple Rust library meant to make terminal applications more interactive
Rust
10
star
8

textwidth-rs

Rust
7
star
9

diesel_struct

An unofficial helper library for diesel
Rust
6
star
10

crane-workspaces

Nix
5
star
11

cloudmqtt

A simple and straightforward to use MQTT client/server
Rust
5
star
12

viereck

A simple to use, versatile graphical overlay on X11
Rust
5
star
13

aseprite-reader

Rust
4
star
14

nix_checks_junit

A utility to transform the result of a `nix flake check` into a junit compatible output
Rust
3
star
15

the_wyvern_rocks

The code powering
Ruby
3
star
16

rust-icalendar

A WIP implentation of the iCalendar format
Rust
2
star
17

hydrazine

An opinionated Admin interface for Rocket and Diesel
Rust
2
star
18

rpg

Rust
2
star
19

hemerashomepartybot

Rust
2
star
20

bbcode-rails

A BBCode implementation to be used alongside rails
Ruby
2
star
21

bevy_spicy_ldtk

Rust
2
star
22

infiniventure

A Block Adventure game; written in Rust
Rust
2
star
23

csidh

A pure Rust CSIDH implementation. This is for research purposes only!
HTML
1
star
24

telescope-git-author-picker

Lua
1
star
25

cge

An extensible card game engine
Nix
1
star
26

RubyStream

A simple streaming website with Sinatra, Coffee and Angular
Ruby
1
star
27

furry_camp_public

1
star
28

legends_of_manroki

1
star
29

hemera.systems

Personal Blog and Public Zettelkasten of Hemera
Markdown
1
star
30

game-jam-indie-tales-1

Rust
1
star
31

nsh

The Neikos Shell
Rust
1
star
32

bevy_rocket_tunnel

Rust
1
star
33

rusty-game-jam-1

Rust
1
star