spacejam/sled: an embedded Rust key-value store between the 0.34 line and a 1.0 rewrite

What sled is for, and who is the target reader

sled is an embedded database written in Rust. It is embedded in the sense that it links into your process rather than running as a separate server you connect to over a socket. The README describes the API as similar to a threadsafe BTreeMap<[u8], [u8]>, and the example code backs that up: you open a path, insert a key, get it back, iterate a range, remove a key, run a compare-and-swap, and flush.

The audience is a Rust application that needs durable local storage but does not want to operate a database server. A desktop application keeping a local index, a service that wants an on-disk cache it controls, or a tool that needs ordered iteration over byte keys are all shapes that fit. The crate keywords in Cargo.toml list redis, mongo, sqlite, lmdb and rocksdb, which tells you the author positions it against both embedded engines and small servers. The categories are database-implementations, concurrency, data-structures, algorithms and caching, so the project is as much a data structure as a product.

If your data is relational, with joins and ad-hoc queries, sled is the wrong layer. It stores byte keys and byte values in ordered trees. Everything above that, including serialization, is your job. The README points at examples/structured.rs for working with structured data without paying deserialization costs, which is a hint about how the project expects you to build on it.

How the storage engine and API actually work

The README describes the implementation as a cpu-scalable lock-free design over flash-optimized log-structured storage, with performance characterized as LSM-tree-like for writes and traditional B+ tree-like for reads. Those two statements together are the design claim: write path batched and append-oriented, read path index-driven. The repository topics include b-plus-tree, b-tree, log-structured, lock-free and concurrent, which match that description.

The API surface is a set of trees. You open a database and then open named keyspaces with open_tree, so one process can hold several independent key spaces. Operations on a single key are atomic, and compare_and_swap is the primitive for conditional writes. For multi-key atomicity there are serializable ACID transactions that can read and write across multiple keys and multiple keyspaces. There are also write batches via apply_batch, merge operators, forward and reverse range iterators, and watch_prefix for subscribing to changes on a key prefix.

Two mechanisms are worth knowing because they change how you store data. First, the README states sled applies prefix encoding to long keys with shared prefixes grouped in a range, plus suffix truncation, and that if keys are the same length and sequential the system can avoid storing 99% or more of the key data in most cases, behaving like a learned index. Second, the ID generator is described as crash-safe and monotonic, capable of generating 75 to 125 million unique IDs per second. Both numbers come from the README, not from independent measurement.

The IVec type is the one thing that surprises newcomers. The README calls it an inlinable Arced slice used for efficiency. Values you read come back as IVec, and the example compares a get result against sled::IVec::from("value").

Installing sled and running a first tree

The README does not carry an installation section, but the repository is a Cargo package, so the dependency is declared in Cargo.toml. The published crate name is sled. The Cargo.toml on the main branch declares version 1.0.0-alpha.124, while the most recent release listed is v0.34.7 from 2021-09-12, so what you get depends on whether you pin a release or track the branch.

Add the dependency:

[dependencies]
sled = "0.34"

Then the README's own example is the shortest real use. It opens a database at a path, inserts a key, reads it back, iterates a range, removes, and flushes:

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

let old_value = tree.insert("key", "value")?;

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

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

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

tree.flush()?;

What you should see is the assertion passing after the insert, an empty loop body because the range is only there to show the shape, and flush returning once data is stable on disk. The README notes that flush blocks until all operations are stable on disk, and that flush_async returns a Future for the same purpose. It also states that sled automatically fsyncs every 500 milliseconds by default, configurable through the flush_every_ms setting, so calling flush yourself is about tightening that window, not about making persistence happen at all.

If you want compression, the README says zstd support is behind the compression build feature and is disabled by default. You would enable it as a feature on the dependency rather than expecting it to be on.

One instance per database, and other constraints you cannot design around

The sharpest limitation is stated plainly: sled does not support multiple open instances for the time being, and the README asks you to keep sled open for the duration of your process's lifespan. That removes a whole class of deployment patterns. You cannot run two worker processes against the same directory and let the filesystem sort it out. A global lazy_static instance is suggested as safe and convenient, with the usual caveats about global variables. If your architecture assumes several processes sharing one local store, sled is the wrong tool and you want a server-backed database instead.

Transactions carry a second constraint. The README says transactions are optimistic and warns against interacting with external state or performing IO inside a transaction closure unless it is idempotent. Optimistic concurrency means a conflicting transaction is retried, so a closure with a side effect can run more than once. That is a design rule, not a footnote.

Ordering is a third trap, and it is the kind that shows up late. The README explains that numeric keys must be stored big-endian if you want sled's iterators and ordered operations to agree with numeric order. Little-endian encoding appears to work until you pass 256 items, at which point lexicographic order of the serialized bytes diverges from numeric order. Rust integral types have to_be_bytes and from_be_bytes, and bincode can be configured for big-endian. Get this wrong and range scans silently return the wrong sequence.

Finally, the README itself carries a red notice that it is out of sync with the main branch, which contains a large in-progress rewrite. Documentation drift of that kind is a real cost: the docs.rs page for the published version and the code on main are not the same thing.

sled versus RocksDB and the newer Rust engines

The comparison people reach for is RocksDB. The difference in approach is mostly about language and integration. RocksDB is a C++ library with Rust bindings, which means a build toolchain that includes a C++ compiler and a foreign function boundary in your dependency graph. sled is pure Rust per its Cargo.toml description, so it builds with the Rust toolchain and shares the language's memory model. RocksDB has a much longer operational history and a wider set of tuning knobs; sled's README instead frames its performance claim as LSM-like writes with B+ tree-like reads, and explicitly tells you to measure your own workloads rather than relying on marketing for contrived ones. That advice cuts against the project's own numbers as much as anyone else's.

The other names in the related searches are redb and Fjall, both Rust embedded storage engines. Their internals are not described in the repository, so the honest difference to state is the one you can check yourself: sled exposes a BTreeMap-shaped tree API with IVec values, optimistic transactions and a background fsync interval, and the README's own warning about an in-progress 1.0 rewrite tells you the API is not frozen. If API stability is your deciding factor, that warning is the thing to weigh, not a feature list.

There is also a category difference worth naming. SurrealDB and similar projects appear in the related searches but are databases with their own query languages and server modes. sled is a library that stores bytes in order. Choosing between them is choosing between writing your own access layer and adopting someone else's.

Maintenance, versions and licence

The repository is not archived, and the last push was on 2026-04-04. The latest release listed is v0.34.7 from 2021-09-12, with v0.34.6 and v0.34.5 before it in 2020. There is a real gap between the release cadence and the commit activity, and the README explains part of it: the main branch holds a large in-progress rewrite. The Cargo.toml on main says version 1.0.0-alpha.124, which is an alpha, so the upgrade path from 0.34.x to 1.0 is not a finished story.

The practical upgrade cost follows from that. If you pin sled = "0.34", you are on a release line that has not moved since 2021. If you track main or a 1.0 alpha, you are on code the README itself says the documentation has not caught up with. Either way, budget for reading the source and the CHANGELOG.md at the repository root rather than trusting the published docs alone. The repository ships ARCHITECTURE.md, SAFETY.md and SECURITY.md, which is more internal documentation than many embedded stores provide, and the presence of fuzz/ and tests/ directories alongside tsan_suppressions.txt indicates the project invests in crash and concurrency testing. The topics list includes crash-testing, fuzzing and formal-methods.

On licensing, the package metadata is the thing to read, and it is not uniform. Cargo.toml declares license = "MIT OR Apache-2.0", and the repository root carries both LICENSE-MIT and LICENSE-APACHE. The repository metadata labels the project Apache-2.0. The dual declaration means you choose which terms apply to your use. That is a description of the files, not legal advice; if the distinction matters to your organisation, have someone read both licence files.

Editorial conclusion

Adopt sled when you want a pure-Rust embedded key-value store with a BTreeMap-shaped API, atomic single-key operations and ACID transactions, and you can tolerate a project whose README says it is out of sync with the main branch. Do not adopt it if you need multiple processes opening the same database, if you need a stable 1.0 API today, or if your queries are relational rather than key-ordered. Before committing, verify which version your Cargo.toml resolves to, whether you are pulling the 0.34.x release or the 1.0.0-alpha code on main, and whether the durability your workload needs is satisfied by the default flush_every_ms of 500 milliseconds or requires explicit flush calls.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. spacejam/sled on GitHub