Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/Reeywhaar/nut

Port of Bolt DB in Rust
https://github.com/Reeywhaar/nut

database embed key-value-store rust

Last synced: 3 months ago
JSON representation

Port of Bolt DB in Rust

Lists

README 

        
# Nut



#### Port of [Bolt DB](https://github.com/boltdb/bolt) in Rust



- **Compatible with Bolt's database format** and provides similar api.



  _Since Nut supports same format as Bolt there are known issues:_



  - Bolt uses Memmap to operate, there is no LRU or other cache, so if database doesn't fit in memory, then it's end of game, Nut will inevitably crash.

  - Data structures are written directly onto disk. No serialization takes place, so Nut doesn't understand db file from computer with different Endianness, for example.



- **Transaction based**. In case of error transaction will be rolled back.

- **Multiple readers, single writer.**

  Nut works just like Bolt: you can have one writer and multiple readers at a time, just be sure they run on different threads. Making writer and reader transaction in same thread will cause deadlock. Writer can write freely if memory map is have enough free pages, in other case it will be waiting for reading transactions to close.



# Usage



Package available at crates.io: https://crates.io/crates/nut



Documentation available at https://docs.rs/nut/0.1.2/nut/



Usual way is to `cargo build --release` in console. Docs available via `cargo doc --no-deps --open`. Api is very similar to Bolt if you are familiar with it.



# Examples



### Create db and put something



```rust

use nut::DBBuilder;



let mut db = DBBuilder::new("test.db").build().unwrap();

let mut tx = db.begin_rw_tx().unwrap();

{

	let mut flowers = tx.create_bucket(b"flowers").unwrap();

	// returns mutable reference to bucket,

		// which prevents of reborrowing tx



	flowers.put(

		b"iris",

		b"song by American alternative rock band Goo Goo Dolls".to_vec()

	).unwrap();

	flowers.put(

		b"binary data",

		vec![127, 127, 127, 127]

	).unwrap();



	{

		// you can create subbuckets as well

		let mut annuals = flowers

			.create_bucket_if_not_exists(b"annuals").unwrap();



		// api is basically same as for transaction

		annuals.put(

			b"corn",

			b"American nu metal band from Bakersfield".to_vec()

		).unwrap();

		// releasing subbucket

	}



	// releasing bucket to be able use tx again

}

// due to RAII tx will be automatically closed if no error occured,

// or rolled back if there was some.

// Additionally you can commit or rollback manually

tx.rollback().unwrap();

```



**Note:** All buckets obtained from transaction should be dropped before calling either `rollback` or `commit`.



### Getting data back



```rust

use nut::DBBuilder;



let mut db = DBBuilder::new("test.db").build().unwrap();



// creating read only transaction

// read only ransaction will be automatically rolled back

let mut tx = db.begin_tx().unwrap();



// getting bucket

let flowers = tx.bucket(b"flowers").unwrap();

let data = flowers.get(b"iris").unwrap();

assert_eq!(

	data,

	&b"song by American alternative rock band Goo Goo Dolls"[..]

);

```



### Getting available buckets



```rust

use nut::DBBuilder;



let mut db = DBBuilder::new("test.db").build().unwrap();

let mut tx = db.begin_tx().unwrap();



{

	// .buckets() available to conveniently retrieve all buckets keys

	let bucket_names = tx.buckets(); // returns Vec>



	// bucket key is any binary data, not only string

	assert_eq!(bucket_names, vec!["flowers".as_bytes().to_vec()]);

}



{

	// additionally there is .cursor() method

	// that returns Cursor struct,

	// which is able to iterate through bucket contents

	let cursor = tx.cursor();



	assert_eq!(

		&cursor.first().unwrap().value.unwrap(),

		&"flowers".as_bytes()

	);

}

```



# Nut Bin



Crate also provides `nut` binary which is helpful to inspect database file in various ways. It can be found after `cargo build --release` in `./target/release/nut`.



Excerpt from man:



```bash

USAGE:

    nut [SUBCOMMAND]



FLAGS:

    -h, --help       Prints help information

    -V, --version    Prints version information



SUBCOMMANDS:

    check    Runs an exhaustive check to verify that all pages are accessible or are marked as freed.

    dump     Dumps hex of the page

    help     Prints this message or the help of the given subcommand(s)

    info     Prints database info

    pages    Prints a table of pages with their type (Meta, Leaf, Branch, Freelist)

    tree     Prints buckets tree

```



# Disclaimer



I'm not planning to actively mantain this project since it just a hobby project to check out Rust, and there are better alternatives in terms of performance.



---



MIT License