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
  • 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 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 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
keyspace.persist(PersistMode::SyncAll)?;

Modules§

Structs§

  • Batch
    An atomic write batch
  • BlobCache
    Blob cache, in which blobs are cached in-memory after being retrieved from disk
  • 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
  • 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
    Transaction keyspace
  • TransactionalPartitionHandle
    Access to a partition of a transactional keyspace
  • WriteTransaction
    A single-writer (serialized) cross-partition transaction

Enums§

Traits§

Type Aliases§