Crate fjall

Expand description

Fjall is a log-structured embeddable key-value storage engine written in Rust. It features:

Thread-safe BTreeMap-like API
100% safe & stable Rust
LSM-tree-based storage similar to RocksDB
Range & prefix searching with forward and reverse iteration
Cross-partition snapshots (MVCC)
Automatic background maintenance
Single-writer transactions (optional)
Key-value separation for large blob use cases (optional)

Each Keyspace is a single logical database and is split into partitions (a.k.a. column families) - you should probably only use a single keyspace for your application. Each partition is physically a single LSM-tree and its own logical collection; however, write operations across partitions are atomic as they are persisted in a single database-level journal, which will be recovered after a crash.

It is not:

a standalone server
a relational or wide-column database: it has no notion of columns

Keys are limited to 65536 bytes, values are limited to 2^32 bytes. As is normal with any kind of storage engine, larger keys and values have a bigger performance impact.

For the underlying LSM-tree implementation, see: https://crates.io/crates/lsm-tree.

use fjall::{Config, PersistMode, Keyspace, PartitionCreateOptions};

// A keyspace is a database, which may contain multiple collections ("partitions")
// You should probably only use a single keyspace for your application
//
let keyspace = Config::new(folder).open()?; // or open_transactional for transactional semantics

// Each partition is its own physical LSM-tree
let items = keyspace.open_partition("my_items", PartitionCreateOptions::default())?;

// Write some data
items.insert("a", "hello")?;

// And retrieve it
let bytes = items.get("a")?;

// Or remove it again
items.remove("a")?;

// Search by prefix
for kv in items.prefix("prefix") {
  // ...
}

// Search by range
for kv in items.range("a"..="z") {
  // ...
}

// Iterators implement DoubleEndedIterator, so you can search backwards, too!
for kv in items.prefix("prefix").rev() {
  // ...
}

// Sync the journal to disk to make sure data is definitely durable
// When the keyspace is dropped, it will try to persist with `PersistMode::SyncAll` as well
keyspace.persist(PersistMode::SyncAll)?;

Modules§

compaction: Contains compaction strategies

Structs§

Batch: An atomic write batch
BlobCacheDeprecated: Blob cache that caches frequently read blobs
BlockCacheDeprecated: Block cache that caches frequently read disk blocks
Config: Global keyspace configuration
Keyspace: A keyspace is a single logical database which can house multiple partitions
KvSeparationOptions: Configuration options for key-value-separated partitions.
PartitionCreateOptions: Options to configure a partition
PartitionHandle: Access to a keyspace partition
ReadTransaction: A cross-partition, read-only transaction (snapshot)
Slice: An immutable byte slice that can be cloned without additional heap allocation
Snapshot: A snapshot captures a read-only point-in-time view of the tree at the time the snapshot was created
TransactionalKeyspace: Transactional keyspace
TransactionalPartitionHandle: Access to a partition of a transactional keyspace
WriteTransaction: A single-writer (serialized) cross-partition transaction

Enums§

AnyTree: May be a standard Tree or a BlobTree
CompressionType: Compression algorithm to use.
Error: Errors that may occur in the storage engine
PersistMode: The persist mode allows setting the durability guarantee of previous writes
RecoveryError: Errors that can occur during journal recovery
TreeType: LSM-tree type
Version: Disk format version

Traits§

GarbageCollection: Functions for garbage collection strategies

Type Aliases§