Crate fjall

Crate fjall 

Source
Expand description

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

  • A thread-safe BTreeMap-like API
  • 100% safe & stable Rust
  • LSM-tree-based storage similar to RocksDB
  • Range & prefix searching with forward and reverse iteration
  • Keyspaces (a.k.a. column families) with cross-keyspace atomic semantics
  • Built-in compression (default = LZ4)
  • Serializable transactions (optional)
  • Key-value separation for large blob use cases (optional)
  • Automatic background maintenance

It is not:

  • A standalone database server
  • A relational or wide-column database: it has no notion of columns or query language

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.

§Basic usage

use fjall::{PersistMode, Database, KeyspaceCreateOptions};

// A database may contain multiple keyspaces
// You should probably only use a single database for your application
let db = Database::builder(&folder).open()?;
// TxDatabase::builder for transactional semantics

// Each keyspace is its own physical LSM-tree
let items = db.keyspace("my_items", KeyspaceCreateOptions::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("user1") {
  // ...
}

// 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 database is dropped, it will try to persist with `PersistMode::SyncAll` as well
db.persist(PersistMode::SyncAll)?;

Modules§

compaction
Contains compaction strategies
config
Configuration policies

Structs§

Config
Global database configuration
Database
A database is a single logical database which can house multiple keyspaces
DatabaseBuilder
Database builder
Guard
Guard to access key-value pairs
Keyspace
Handle to a keyspace
KeyspaceCreateOptions
Options to configure a keyspace
ReadTransaction
A cross-keyspace, read-only transaction (snapshot)
Slice
An immutable byte slice that can be cloned without additional heap allocation
TxDatabase
Transactional database
TxDatabaseBuilder
Transactional database builder
TxKeyspace
Handle to a keyspace of a transactional database
WriteBatch
An atomic write batch
WriteTransaction
A single-writer (serialized) cross-keyspace 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

Constants§

KV_SEPARATION_DEFAULT_THRESHOLD
Default key-value separation blob size threshold

Type Aliases§

KvPair
KV-tuple, typically returned by an iterator
Result
Result helper type
SeqNo
Sequence number - a monotonically increasing counter
UserKey
User defined key
UserValue
User defined data (byte array)