Crate roach

Rust object archive: strongly-typed persistent key value storage

roach is a thin wrapper over redb which allows loading and storing strongly-typed data in a customizable fashion. It is ideal for applications which need to persistently store program state or other data in a variety of ways (such as in a serialized or compressed format). The following is a simple example of how to use roach:

use roach::*;
 
// Define an archive type.
struct MyArchive;
 
// Define a key-value pair which can be stored in the archive.
impl ArchiveType<str> for MyArchive {
    // The keys will be of type string, and will be stored simply by copying the bytes.
    type Key = str;
    // The values will be of type [u8], and will be compressed using zstd before storage.
    type Value = Zstd<[u8]>;
}
 
// Define another key type.
impl ArchiveType<u8> for MyArchive {
    type Key = Pod<u8>;
    type Value = [u8; 5];
}
 
// Create a new archive.
let archive = Archive::<MyArchive>::new(backend::InMemoryBackend::new()).unwrap();
// Begin a new atomic transaction.
let mut write_txn = archive.write().unwrap();
// Store something to the str table.
write_txn.set("henlo", &[5, 10, 15]).unwrap();
// Commit the transaction.
write_txn.commit().unwrap();
 
// Read the data back to verify that it was saved.
let read_txn = archive.read().unwrap();
assert_eq!(&read_txn.get("henlo").unwrap().unwrap(), &[5, 10, 15]);

Optional features

bytemuck - Enables the Pod data transform, which reads the bytes of a type directly to store them.

rmp_serde - Enables the Rmp data transform, which serializes Rust types to bytes and back.

zstd - Enables the Zstd data transform, which compresses data before it is stored.

Modules

• backend
  Provides backends to store archive data in various ways.

Structs

• AccessGuard
  Provides a view of raw archived data.
• Archive
  An archive of strongly-typed data.
• Const
  Marks an immutable type.
• FromArchive
  Marks a type that converts objects from their archived representation.
• Mut
  Marks a mutable type.
• Pod
  Archives a type by copying its raw bytes. Endianness is conserved when the value is stored.
• PodGuard
  Provides a view of Pod-archived data in an archive.
• Rmp
  Archives a type by serializing its contents with the MessagePack protocol.
• StringGuard
  Provides a view of archived string data.
• ToArchive
  Marks a type that converts objects to their archived representation.
• Transaction
  Facilitates an atomic interaction with an Archive.
• Zstd
  Archives a byte array by serializing it using the zstd algorithm.

Enums

• ArchiveError
  Describes an error that occurred while interacting with an archive.

Traits

• ArchiveType
  Defines a type of key-value pair which may be stored in an archive.
• DataConverter
  Implements the ability to convert from a canonical target type to an archived representation.
• DataTransform
  Implements the ability to convert archived data to in-memory data, or vice-versa.
• Direction
  Marks the direction in which an archive operation occurs.
• Mutability
  Marks whether a type is mutable or immutable.
• StorageBackend
  Implements persistent storage for a database.
• ToWriter
  Allows for writing contents to a Write.