[][src]Crate sled

sled is a high-performance embedded database with an API that is similar to a BTreeMap<[u8], [u8]>, but with several additional capabilities for assisting creators of stateful systems.

It is fully thread-safe, and all operations are atomic. Multiple Trees are supported with the Db::open_tree method.

ACID transactions involving reads and writes to multiple items are supported with the Tree::transaction method. Transactions may also operate over multiple Trees (see Tree::transaction docs for more info).

Users may also subscribe to updates on individual Trees by using the Tree::watch_prefix method, which returns a blocking Iterator over updates to keys that begin with the provided prefix. You may supply an empty prefix to subscribe to everything.

Merge operators (aka read-modify-write operators) are supported. A merge operator is a function that specifies how new data can be merged into an existing value without requiring both a read and a write. Using the Tree::merge method, you may "push" data to a Tree value and have the provided merge operator combine it with the existing value, if there was one. They are set on a per-Tree basis, and essentially allow any sort of data structure to be built using merges as an atomic high-level operation.

sled is built by experienced database engineers who think users should spend less time tuning and working against high-friction APIs. Expect significant ergonomic and performance improvements over time. Most surprises are bugs, so please let us know if something is high friction.

Examples

let t = sled::open("my_db").unwrap();

// insert and get
t.insert(b"yo!", b"v1");
assert_eq!(&t.get(b"yo!").unwrap().unwrap(), b"v1");

// Atomic compare-and-swap.
t.compare_and_swap(
    b"yo!",      // key
    Some(b"v1"), // old value, None for not present
    Some(b"v2"), // new value, None for delete
)
.unwrap();

// Iterates over key-value pairs, starting at the given key.
let scan_key: &[u8] = b"a non-present key before yo!";
let mut iter = t.range(scan_key..);
assert_eq!(&iter.next().unwrap().unwrap().0, b"yo!");
assert_eq!(iter.next(), None);

t.remove(b"yo!");
assert_eq!(t.get(b"yo!"), Ok(None));

Structs

Batch

A batch of updates that will be applied atomically to the Tree.

CompareAndSwapError

Compare and swap error.

Config

Top-level configuration for the system.

Db

The sled embedded database!

IVec

A buffer that may either be inline or remote and protected by an Arc

Iter

An iterator over keys and values in a Tree.

Subscriber

A subscriber listening on a specified prefix

TransactionalTree

A transaction that will be applied atomically to the Tree.

Tree

A flash-sympathetic persistent lock-free B+ tree

Enums

ConflictableTransactionError

An error type that is returned from the closure passed to the transaction method.

Error

An Error type encapsulating various issues that may come up in both the expected and unexpected operation of a PageCache.

Event

An event that happened to a key that a subscriber is interested in.

Link

Link denotes a tree node or its modification fragment such as key addition or removal.

TransactionError

An error type that is returned from the closure passed to the transaction method.

Traits

Transactional

A type that may be transacted on in sled transactions.

Functions

abort

A simple constructor for Err(TransactionError::Abort(_))

open

Opens a Db with a default configuration at the specified path. This will create a new storage directory at the specified path if it does not already exist. You can use the Db::was_recovered method to determine if your database was recovered from a previous instance. You can use Config::create_new if you want to increase the chances that the database will be freshly created.

Type Definitions

CompareAndSwapResult

Compare and swap result.

ConflictableTransactionResult

A transaction-related Result which is used for transparently handling concurrency-related conflicts when running transaction closures.

MergeOperator

Allows arbitrary logic to be injected into mere operations of the PageCache.

Result

The top-level result type for dealing with the PageCache.

TransactionResult

A transaction-related Result which is used for returning the final result of a transaction after potentially running the provided closure several times due to underlying conflicts.