pub struct Db { /* fields omitted */ }
The sled
embedded database!
Load existing or create a new Db
with a default configuration.
Load existing or create a new Db
.
Generate a monotonic ID. Not guaranteed to be
contiguous. Written to disk every idgen_persist_interval
operations, followed by a blocking flush. During recovery, we
take the last recovered generated ID and add 2x
the idgen_persist_interval
to it. While persisting, if the
previous persisted counter wasn't synced to disk yet, we will do
a blocking flush to fsync the latest counter, ensuring
that we will never give out the same counter twice.
Open or create a new disk-backed Tree with its own keyspace,
accessible from the Db
via the provided identifier.
Remove a disk-backed collection.
Returns true
if the database was
recovered from a previous process.
Note that database state is only
guaranteed to be present up to the
last call to flush
! Otherwise state
is synced to disk periodically if the
sync_every_ms
configuration option
is set to Some(number_of_ms_between_syncs)
or if the IO buffer gets filled to
capacity before being rotated.
Record a set of pages as being involved in
a transaction that is about to be written to
one of the structures in the Db. Do this
before performing transactions in case
the system crashes before all changes
can be written. During recovery,
you can call possibly_dirty_pages
to get the set of pages that may have
transactional state written to them.
Mark a transaction as being aborted. This
ensures that during recovery we know that
this transaction is not the last one that
should be recovered, because the process
finished the transaction, but we may need
to clean up its pending state still.
Mark a transaction as being completed. This
ensures that during recovery we know that
this transaction completed, and that we
can safely remove its entry in the
transaction table.
Remove entries associated with this transaction
in the transaction table, because we have
completed the transaction and finished
applying or removing pending state, and do
not need to know about it during crash recovery.
Call this during recovery to retrieve the set of
pages that were involved in a transaction
that was in a pending or aborted (but not
yet fully cleaned up) state during process
termination.
Subscribe to Event
s that happen to keys that have
the specified prefix. Events for particular keys are
guaranteed to be witnessed in the same order by all
threads, but threads may witness different interleavings
of Event
s across different keys. If subscribers don't
keep up with new writes, they will cause new writes
to block. There is a buffer of 1024 items per
Subscriber
. This can be used to build reactive
and replicated systems.
use sled::{Event, ConfigBuilder};
let config = ConfigBuilder::new().temporary(true).build();
let tree = sled::Db::start(config).unwrap();
let mut events = tree.watch_prefix(vec![]);
let tree_2 = tree.clone();
let thread = std::thread::spawn(move || {
tree.set(vec![0], vec![1]).unwrap();
});
for event in events.take(1) {
match event {
Event::Set(key, value) => assert_eq!(key, vec![0]),
Event::Merge(key, partial_value) => {}
Event::Del(key) => {}
}
}
thread.join().unwrap();
Clears the Tree
, removing all values.
Note that this is not atomic.
Flushes all dirty IO buffers and calls fsync.
If this succeeds, it is guaranteed that
all previous writes will be recovered if
the system crashes.
Returns true
if the Tree
contains a value for
the specified key.
Retrieve a value from the Tree
if it exists.
Retrieve the key and value before the provided key,
if one exists.
use sled::{ConfigBuilder, Error};
let config = ConfigBuilder::new().temporary(true).build();
let tree = sled::Db::start(config).unwrap();
for i in 0..10 {
tree.set(vec![i], vec![i]).expect("should write successfully");
}
assert!(tree.get_lt(vec![]).unwrap().is_none());
assert!(tree.get_lt(vec![0]).unwrap().is_none());
assert!(tree.get_lt(vec![1]).unwrap().unwrap().1 == vec![0]);
assert!(tree.get_lt(vec![9]).unwrap().unwrap().1 == vec![8]);
assert!(tree.get_lt(vec![10]).unwrap().unwrap().1 == vec![9]);
assert!(tree.get_lt(vec![255]).unwrap().unwrap().1 == vec![9]);
Retrieve the next key and value from the Tree
after the
provided key.
use sled::{ConfigBuilder, Error};
let config = ConfigBuilder::new().temporary(true).build();
let tree = sled::Db::start(config).unwrap();
for i in 0..10 {
tree.set(vec![i], vec![i]).expect("should write successfully");
}
assert!(tree.get_gt(vec![]).unwrap().unwrap().1 == vec![0]);
assert!(tree.get_gt(vec![0]).unwrap().unwrap().1 == vec![1]);
assert!(tree.get_gt(vec![1]).unwrap().unwrap().1 == vec![2]);
assert!(tree.get_gt(vec![8]).unwrap().unwrap().1 == vec![9]);
assert!(tree.get_gt(vec![9]).unwrap().is_none());
Compare and swap. Capable of unique creation, conditional modification,
or deletion. If old is None, this will only set the value if it doesn't
exist yet. If new is None, will delete the value if old is correct.
If both old and new are Some, will modify the value if old is correct.
If Tree is read-only, will do nothing.
use sled::{ConfigBuilder, Error};
let config = ConfigBuilder::new().temporary(true).build();
let t = sled::Db::start(config).unwrap();
assert_eq!(t.cas(&[1], None, Some(vec![1])), Ok(()));
assert_eq!(t.cas(&[1], Some(&*vec![1]), Some(vec![2])), Ok(()));
assert_eq!(t.cas(&[1], Some(&[2]), None), Ok(()));
assert_eq!(t.get(&[1]), Ok(None));
Set a key to a new value, returning the old value if it
was set.
Delete a value, returning the last result if it existed.
let config = sled::ConfigBuilder::new().temporary(true).build();
let t = sled::Db::start(config).unwrap();
t.set(&[1], vec![1]);
assert_eq!(t.del(&*vec![1]).unwrap().unwrap(), vec![1]);
assert_eq!(t.del(&*vec![1]), Ok(None));
Merge state directly into a given key's value using the
configured merge operator. This allows state to be written
into a value directly, without any read-modify-write steps.
Merge operators can be used to implement arbitrary data
structures.
Calling merge
will panic if no merge operator has been
configured.
fn concatenate_merge(
_key: &[u8],
old_value: Option<&[u8]>,
merged_bytes: &[u8]
) -> Option<Vec<u8>> {
let mut ret = old_value
.map(|ov| ov.to_vec())
.unwrap_or_else(|| vec![]);
ret.extend_from_slice(merged_bytes);
Some(ret)
}
let config = sled::ConfigBuilder::new()
.temporary(true)
.merge_operator(concatenate_merge)
.build();
let tree = sled::Db::start(config).unwrap();
let k = b"k1";
tree.set(k, vec![0]);
tree.merge(k, vec![1]);
tree.merge(k, vec![2]);
tree.set(k, vec![3]);
tree.del(k);
tree.merge(k, vec![4]);
Create a double-ended iterator over the tuples of keys and
values in this tree.
let config = sled::ConfigBuilder::new().temporary(true).build();
let t = sled::Db::start(config).unwrap();
t.set(&[1], vec![10]);
t.set(&[2], vec![20]);
t.set(&[3], vec![30]);
let mut iter = t.iter();
Create a double-ended iterator over tuples of keys and values,
starting at the provided key.
let config = sled::ConfigBuilder::new()
.temporary(true)
.build();
let t = sled::Db::start(config).unwrap();
t.set(b"0", vec![0]).unwrap();
t.set(b"1", vec![10]).unwrap();
t.set(b"2", vec![20]).unwrap();
t.set(b"3", vec![30]).unwrap();
t.set(b"4", vec![40]).unwrap();
t.set(b"5", vec![50]).unwrap();
let mut r = t.scan(b"2");
assert_eq!(r.next().unwrap().unwrap().0, b"2");
assert_eq!(r.next().unwrap().unwrap().0, b"3");
assert_eq!(r.next().unwrap().unwrap().0, b"4");
assert_eq!(r.next().unwrap().unwrap().0, b"5");
assert_eq!(r.next(), None);
let mut r = t.scan(b"2").rev();
assert_eq!(r.next().unwrap().unwrap().0, b"2");
assert_eq!(r.next().unwrap().unwrap().0, b"1");
assert_eq!(r.next().unwrap().unwrap().0, b"0");
assert_eq!(r.next(), None);
Create a double-ended iterator over tuples of keys and values,
where the keys fall within the specified range.
let config = sled::ConfigBuilder::new()
.temporary(true)
.build();
let t = sled::Db::start(config).unwrap();
t.set(b"0", vec![0]).unwrap();
t.set(b"1", vec![10]).unwrap();
t.set(b"2", vec![20]).unwrap();
t.set(b"3", vec![30]).unwrap();
t.set(b"4", vec![40]).unwrap();
t.set(b"5", vec![50]).unwrap();
let start: &[u8] = b"2";
let end: &[u8] = b"4";
let mut r = t.range(start..end);
assert_eq!(r.next().unwrap().unwrap().0, b"2");
assert_eq!(r.next().unwrap().unwrap().0, b"3");
assert_eq!(r.next(), None);
let start = b"2".to_vec();
let end = b"4".to_vec();
let mut r = t.range(start..end).rev();
assert_eq!(r.next().unwrap().unwrap().0, b"3");
assert_eq!(r.next().unwrap().unwrap().0, b"2");
assert_eq!(r.next(), None);
Create a double-ended iterator over keys, starting at the provided key.
let config = sled::ConfigBuilder::new().temporary(true).build();
let t = sled::Db::start(config).unwrap();
t.set(&[1], vec![10]);
t.set(&[2], vec![20]);
t.set(&[3], vec![30]);
let mut iter = t.scan(&*vec![2]);
Create a double-ended iterator over values, starting at the provided key.
let config = sled::ConfigBuilder::new().temporary(true).build();
let t = sled::Db::start(config).unwrap();
t.set(&[1], vec![10]);
t.set(&[2], vec![20]);
t.set(&[3], vec![30]);
let mut iter = t.scan(&*vec![2]);
Returns the number of elements in this tree.
Beware: performs a full O(n) scan under the hood.
Returns true
if the Tree
contains no elements.
Performs copy-assignment from source
. Read more
Executes the destructor for this type. Read more
type Target = Tree
The resulting type after dereferencing.
type Owned = T
Creates owned data from borrowed data, usually by cloning. Read more
🔬 This is a nightly-only experimental API. (toowned_clone_into
)
recently added
Uses borrowed data to replace owned data, usually by cloning. Read more
type Error = !
🔬 This is a nightly-only experimental API. (try_from
)
The type returned in the event of a conversion error.
🔬 This is a nightly-only experimental API. (try_from
)
Immutably borrows from an owned value. Read more
type Error = <U as TryFrom<T>>::Error
🔬 This is a nightly-only experimental API. (try_from
)
The type returned in the event of a conversion error.
🔬 This is a nightly-only experimental API. (try_from
)
Mutably borrows from an owned value. Read more
🔬 This is a nightly-only experimental API. (get_type_id
)
this method will likely be replaced by an associated static