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

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
KvSeparationOptions
Options for key-value separation
ReadTransactionsingle_writer_tx or ssi_tx
A cross-keyspace snapshot
Slice
An immutable byte slice that can be cloned without additional heap allocation
Snapshot
A cross-keyspace snapshot
TxDatabasesingle_writer_tx or ssi_tx
Transactional database
TxDatabaseBuildersingle_writer_tx or ssi_tx
Transactional database builder
TxKeyspacesingle_writer_tx or ssi_tx
Handle to a keyspace of a transactional database
WriteBatch
An atomic write batch
WriteTransactionsingle_writer_tx or ssi_tx
A single-writer (serialized) cross-keyspace transaction

Enums§

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

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)