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") {
  // ...
}

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

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

// 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
util
Utility functions

Structs§

Config
Global database configuration
Conflict
Transaction conflict
Database
A database is a single logical database which can house multiple keyspaces
DatabaseBuilder
Database builder
Guard
Guard to access key-value pairs
Iter
A wrapper around iterators that keep a snapshot alive
Keyspace
Handle to a keyspace
KeyspaceCreateOptions
Options to configure a keyspace
KvSeparationOptions
Options for key-value separation
OptimisticTxDatabase
Transactional database
OptimisticTxKeyspace
Handle to a keyspace of a transactional database
OptimisticWriteTx
A cross-keyspace transaction using optimistic concurrency control
OwnedWriteBatch
An atomic write batch
SingleWriterTxDatabase
Single-writer transactional database
SingleWriterTxKeyspace
Handle to a keyspace of a transactional database
SingleWriterWriteTx
A single-writer (serialized) cross-keyspace transaction
Slice
An immutable byte slice that can be cloned without additional heap allocation
Snapshot
A cross-keyspace snapshot

Enums§

CompressionType
Compression algorithm to use
Error
Errors that may occur in the storage engine
FormatVersion
Disk format version
JournalRecoveryError
Errors that can occur during journal recovery
PersistMode
The persist mode allows setting the durability guarantee of previous writes

Traits§

Readable
Readable snapshot

Type Aliases§

KvPair
KV-tuple (key + value)
Result
Result helper type
SeqNo
Sequence number - a monotonically increasing counter
UserKey
User defined key (byte array)
UserValue
User defined data (byte array)