Crate sled[−][src]
Expand description
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 with isolated keyspaces
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 db: sled::Db = sled::open("my_db").unwrap();
// insert and get
db.insert(b"yo!", b"v1");
assert_eq!(&db.get(b"yo!").unwrap().unwrap(), b"v1");
// Atomic compare-and-swap.
db.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 = db.range(scan_key..);
assert_eq!(&iter.next().unwrap().unwrap().0, b"yo!");
assert_eq!(iter.next(), None);
db.remove(b"yo!");
assert_eq!(db.get(b"yo!"), Ok(None));
let other_tree: sled::Tree = db.open_tree(b"cool db facts").unwrap();
other_tree.insert(
b"k1",
&b"a Db acts like a Tree due to implementing Deref<Target = Tree>"[..]
).unwrap();Re-exports
pub use self::transaction::Transactional;Modules
Structs
A batch of updates that will be applied atomically to the Tree.
Compare and swap error.
Top-level configuration for the system.
The sled embedded database! Implements
Deref<Target = sled::Tree> to refer to
a default keyspace / namespace / bucket.
A buffer that may either be inline or remote and protected by an Arc
An iterator over keys and values in a Tree.
A subscriber listening on a specified prefix
A flash-sympathetic persistent lock-free B+ tree.
Enums
An Error type encapsulating various issues that may come up
in the operation of a Db.
An event that happened to a key that a subscriber is interested in.
The high-level database mode, according to the trade-offs of the RUM conjecture.
Traits
A function that may be configured on a particular shared Tree
that will be applied as a kind of read-modify-write operator
to any values that are written using the Tree::merge method.
Functions
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
The top-level result type for dealing with
fallible operations. The errors tend to
be fail-stop, and nested results are used
in cases where the outer fail-stop error can
have try ? used on it, exposing the inner
operation that is expected to fail under
normal operation. The philosophy behind this
is detailed on the sled blog.