Crate fjall

source ·
Expand description

Fjall is an LSM-based embeddable key-value storage engine written in Rust. It features:

  • Thread-safe BTreeMap-like API
  • 100% safe & stable Rust
  • Range & prefix searching with forward and reverse iteration
  • Cross-partition snapshots (MVCC)
  • Automatic background maintenance

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 database
  • a 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};

let keyspace = Config::new(folder).open()?;

// 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 item in items.prefix("prefix") {
  // ...
}

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

// Iterators implement DoubleEndedIterator, so you can search backwards, too!
for item 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
// Also, by default every second the keyspace will be persisted asynchronously
keyspace.persist(PersistMode::SyncAll)?;

// Destroy the partition, removing all data in it.
// This may be useful when using temporary tables or indexes,
// as it is essentially an O(1) operation.
keyspace.delete_partition(items)?;

Modules§

Structs§

  • Batch
    An atomic write batch
  • BlockCache
    Block cache, in which blocks are cached in-memory after being retrieved from disk
  • Config
    Global keyspace configuration
  • Keyspace
    A keyspace is a single logical database which can house multiple partitions
  • PartitionCreateOptions
    Options to configure a partition
  • PartitionHandle
    Access to a keyspace partition
  • Snapshot
    A snapshot captures a read-only point-in-time view of the tree at the time the snapshot was created

Enums§

  • 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

Type Aliases§