OpenRaft: an advanced Raft consensus engine for Rust storage systems

What OpenRaft solves, and who it is aimed at

Replicating a log across machines is the part of a distributed data system that is easiest to get subtly wrong: elections, membership changes and log truncation all interact. OpenRaft packages that layer as a library. The README states the project intends to improve Raft "as the next-generation consensus protocol for distributed data storage systems (SQL, NoSQL, KV, Streaming, Graph)", and it is the consensus engine of the meta-service cluster in Databend.

The audience is therefore narrow and technical. You are expected to bring your own storage engine, your own network transport and your own state machine, and to implement the traits OpenRaft defines for them. The examples directory makes the shape of that work concrete: raft-kv-memstore, raft-kv-rocksdb, log-rocks, log-wal, sm-mem and sm-rocks are separate crates, so you can see a memory store and a RocksDB-backed store side by side. If you want a database you can start with a config file, this is the wrong layer. If you are building the database, it is the layer you would otherwise write yourself.

The mechanism: a Raft core with pluggable stores and runtimes

OpenRaft is a library, not a process. The repository layout shows the split: the openraft crate holds the consensus logic, rt/, rt-tokio/, rt-compio/ and rt-monoio/ are runtime adapters, stores/ holds storage implementations, and macros/ holds the derive macros used to declare request and response types. The README describes it as "Advanced Raft in Rust on any async runtime", and the Makefile's feature-check target confirms which features exist as separate switches: tokio-rt, clap, bench, bt, serde, type-alias, compat, single-threaded, tracing-log, runtime-stats, metrics-logids, anyhow and serde_json.

Two protocol changes distinguish it from a textbook Raft. Extended joint membership, marked done on 2022-10-31, changes an arbitrary set of nodes in one operation, where standard Raft changes one node at a time and treats that as a special case. The redesigned Vote minimizes election conflict rate so that a split vote does not force a new term; the standard leader-ID mode is also supported. Pre-Vote landed on 2026-06-12 and is enabled through Config::enable_pre_vote: a node asks its peers whether they would grant it a vote before incrementing its term. That is a real safety-oriented default question, and it is off unless you turn it on.

Installing OpenRaft and running a first example

The README points to the OpenRaft guide as the place to start, and the examples are versioned by branch. Examples with OpenRaft 0.10 require 0.10.0-alpha.34 from crates.io; examples with OpenRaft 0.9 require 0.9. The workspace manifest sets edition 2024 and rust-version 1.88, so check your toolchain before anything else.

The crate is published on crates.io as openraft, and the README links its documentation on docs.rs. The examples are separate crates with their own manifests. From a checkout of the matching branch, build one of them, for example the memory-store key-value example:

cd examples/raft-kv-memstore
cargo run

What you should see is a small cluster brought up in-process with an in-memory log and state machine. The documentation does not promise that the example prints a fixed banner, so treat any output as the example's own. The important thing to read is the source: the example implements the storage traits and the network trait, and that is the work you will repeat in your own service. The Makefile also shows how the project itself is checked, including a defensive run with OPENRAFT_STORE_DEFENSIVE=on and a delayed-network run with OPENRAFT_NETWORK_SEND_DELAY=30, both of which are environment variables you can set against your own tests.

The pre-1.0 API is the main cost of adoption

OpenRaft states plainly that its API is not stable before 1.0.0 and that an upgrade may contain incompatible changes. That is not a footnote. The commit convention is the mitigation: a commit message starts with data-change for on-disk type changes that may require manual upgrade, change for incompatible changes, feat for compatible new features, and fix for bug fixes. Reading the change-log is therefore part of operating the library, not optional diligence.

The version split makes this concrete. Branch main targets release-0.10, and 0.10 is in alpha, with v0.10.0-alpha.33 released on 2026-08-05 and earlier alphas before it. Branch release-0.9 accepts no new features, only bug fixes, with v0.9.25 released on 2026-07-28. Branches 0.8, 0.7 and 0.6 are closed, and their upgrade guides remain published. A team that wants a quiet dependency should pin 0.9 and accept that it will not receive new protocol work. A team that wants Pre-Vote or the newest membership behaviour has to live on an alpha line. There is no third option.

One more boundary: the README's performance table is explicitly labelled "NOT a real world application benchmark". It reports 33,000 writes/sec for a single writer and up to 5,615,000 writes/sec for batch writes with 4096 clients, measured on a minimized store and network. Those numbers describe the framework's ceiling under a stripped-down harness, not what your service will do once a real state machine and disk are in the path.

OpenRaft compared with using raft-rs or writing the log yourself

The closest thing to a direct alternative in the Rust ecosystem is raft-rs, the TiKV-lineage Raft library. The difference in approach is where the boundary sits. raft-rs exposes the Raft state machine and expects the caller to drive it through ready-state polling and explicit message handling; the caller owns more of the loop. OpenRaft is built around an async, event-driven core with trait-based storage and network abstractions, and it adds protocol work that standard Raft does not have: extended joint membership for arbitrary node-set changes in one operation, and the redesigned Vote that avoids forcing a new term on a split vote.

If you already have a TiKV-shaped storage layer and want the smallest possible dependency, raft-rs is the more conservative choice. If you are writing a new Rust service on an async runtime and you want membership changes and election behaviour handled for you, OpenRaft's abstractions do more of that work. Neither is a database. The other honest alternative is not a library at all: run an existing consensus-backed system and talk to it over the network, which removes the API-churn problem entirely at the cost of a network hop and an operational dependency.

Testing, licence and the upgrade treadmill

The testing story is unusually explicit for a library at this stage. The README reports unit test coverage at 92%, a deterministic simulation fuzzer in tests-turmoil that runs in every CI build, and a Jepsen suite in jepsen/ that runs eight nemesis scenarios on every push to main: network partition, process pause, process kill, slow packets, flaky packets, clock skew, membership churn, and all of them combined. The Makefile adds a read-only verify target that runs fmt_check, feature-check, clippy and docs-check plus the test suites, and a separate feature-check that compiles each feature in isolation with --no-default-features so that removed features fail loudly. That is a stronger safety net than most pre-1.0 crates carry, and it is the main argument for trusting an alpha line.

Licensing is dual: the workspace manifest declares MIT OR Apache-2.0, and the repository carries LICENSE-APACHE and LICENSE-MIT. The README header and the crates.io metadata are the authority for the crate you actually depend on; confirm which of the two you are taking, since the choice affects patent and attribution terms. That is a decision for your own legal review, not something this article can settle.

The upgrade cost is the recurring one. Because data-change commits can alter on-disk types, an upgrade may require a manual migration, and the project publishes upgrade guides per version pair, including 0.8 to 0.9 and 0.9 to 0.10. Budget for reading the change-log at every bump, and for testing the migration against a copy of real data before it touches a cluster.

Editorial conclusion

Adopt OpenRaft if you are writing a Rust service that needs a replicated log and you can absorb pre-1.0 churn: pin the 0.9 line for production and read the change-log before every upgrade, because commits are tagged data-change, change, feat or fix. Do not adopt it if you need a stable API contract today, or if you expect a runnable database: OpenRaft is a consensus engine, and you supply the state machine, log store, network layer and snapshot handling. Before committing, check whether the feature you need has landed in 0.9 or only in 0.10, read the 0.9 to 0.10 upgrade guide, and confirm that the examples in the branch you target compile against the version you pin.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes