Sled

the champagne of beta embedded databases

Quick Start

An embedded database.

let tree = sled::open("/tmp/welcome-to-sled")?;

// insert and get, similar to std's BTreeMap
let old_value = tree.insert("key", "value")?;

assert_eq!(
  tree.get(&"key")?,
  Some(sled::IVec::from("value")),
);

// range queries
for kv_result in tree.range("key_1".."key_9") {}

// deletion
let old_value = tree.remove(&"key")?;

// atomic compare and swap
tree.compare_and_swap(
  "key",
  Some("current_value"),
  Some("new_value"),
)?;

// block until all operations are stable on disk
// (flush_async also available to get a Future)
tree.flush()?;

If you would like to work with structured data without paying expensive deserialization costs, check out the structured example!

Features

API similar to a threadsafe BTreeMap<[u8], [u8]>
serializable (ACID) transactions for atomically reading and writing to multiple keys in multiple keyspaces.
fully atomic single-key operations, including compare and swap
zero-copy reads
write batches
subscribe to changes on key prefixes
multiple keyspaces
merge operators
forward and reverse iterators over ranges of items
a crash-safe monotonic ID generator capable of generating 75-125 million unique ID's per second
zstd compression (use the compression build feature, disabled by default)
cpu-scalable lock-free implementation
flash-optimized log-structured storage
uses modern b-tree techniques such as prefix encoding and suffix truncation for reducing the storage costs of long keys with shared prefixes. If keys are the same length and sequential then the system can avoid storing 99%+ of the key data in most cases, essentially acting like a learned index

Expectations & Gotchas & Advice

Maybe one of the first things that seems weird is the IVec type. This is an inlinable Arced slice that makes some things more efficient.
Durability: sled automatically fsyncs every 500ms by default, which can be configured with the flush_every_ms configurable, or you may call flush / flush_async manually after operations.
Transactions are optimistic - do not interact with external state or perform IO from within a transaction closure unless it is idempotent.
Internal tree node optimizations: sled performs prefix encoding on long keys with similar prefixes that are grouped together in a range, as well as suffix truncation to further reduce the indexing costs of long keys. Nodes will skip potentially expensive length and offset pointers if keys or values are all the same length (tracked separately, don't worry about making keys the same length as values), so it may improve space usage slightly if you use fixed-length keys or values. This also makes it easier to use structured access as well.
sled does not support multiple open instances for the time being. Please keep sled open for the duration of your process's lifespan. It's totally safe and often quite convenient to use a global lazy_static sled instance, modulo the normal global variable trade-offs. Every operation is threadsafe, and most are implemented under the hood with lock-free algorithms that avoid blocking in hot paths.

Performance

LSM tree-like write performance with traditional B+ tree-like read performance
over a billion operations in under a minute at 95% read 5% writes on 16 cores on a small dataset
measure your own workloads rather than relying on some marketing for contrived workloads

A note on lexicographic ordering and endianness

If you want to store numerical keys in a way that will play nicely with sled's iterators and ordered operations, please remember to store your numerical items in big-endian form. Little endian (the default of many things) will often appear to be doing the right thing until you start working with more than 256 items (more than 1 byte), causing lexicographic ordering of the serialized bytes to diverge from the lexicographic ordering of their deserialized numerical form.

Rust integral types have built-in to_be_bytes and from_be_bytes methods.
bincode can be configured to store integral types in big-endian form.

Interaction with async

If your dataset resides entirely in cache (achievable at startup by setting the cache to a large enough value and performing a full iteration) then all reads and writes are non-blocking and async-friendly, without needing to use Futures or an async runtime.

To asynchronously suspend your async task on the durability of writes, we support the flush_async method, which returns a Future that your async tasks can await the completion of if they require high durability guarantees and you are willing to pay the latency costs of fsync. Note that sled automatically tries to sync all data to disk several times per second in the background without blocking user threads.

We support async subscription to events that happen on key prefixes, because the Subscriber struct implements Future<Output=Option<Event>>:

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

let mut sub = sled.watch_prefix("");

sled.insert(b"a", b"a").unwrap();

extreme::run(async move {
    while let Some(event) = (&mut sub).await {
        println!("got event {:?}", event);
    }
});

Minimum supported Rust version (MSRV)

We support Rust 1.40.0 and up.

Architecture

lock-free tree on a lock-free pagecache on a lock-free log. the pagecache scatters partial page fragments across the log, rather than rewriting entire pages at a time as B+ trees for spinning disks historically have. on page reads, we concurrently scatter-gather reads across the log to materialize the page from its fragments. check out the architectural outlook for a more detailed overview of where we're at and where we see things going!

Philosophy

don't make the user think. the interface should be obvious.
don't surprise users with performance traps.
don't wake up operators. bring reliability techniques from academia into real-world practice.
don't use so much electricity. our data structures should play to modern hardware's strengths.

Known issues & warnings

if reliability is your primary constraint, use SQLite. sled is beta.
if storage price performance is your primary constraint, use RocksDB. sled uses too much space sometimes.
if you have a multi-process workload that rarely writes, use LMDB. sled is architected for use with long-running, highly-concurrent workloads such as stateful services or higher-level databases.
quite young, should be considered unstable for the time being.
the on-disk format is going to change in ways that require manual migrations before the 1.0.0 release!

Priorities

rework the transaction API to eliminate surprises and limitations
reduce space and memory usage
the 1.0.0 release date is imminent! just putting the final touches on, while performing intensive testing
combine merge operators with subscribers in a way that plays nicely with transactions
typed trees for low-friction serialization
replication support for both strongly and eventually consistent systems
continue to improve testing and make certain bug classes impossible through construction
continue to optimize the hell out of everything
continue to improve documentation and examples
continue to reduce compilation latency

Fund feature development

Like what we're doing? Help us out via GitHub Sponsors!

Contribution welcome!

want to help advance the state of the art in open source embedded databases? check out CONTRIBUTING.md!

ciusji/sled