# DLedger: a Raft commitlog library that ships its own demo jar

> DLedger is a Java library for building a high-available, strongly consistent commitlog on top of Raft. It gives you leader election, parallel replication, a state machine and multi-raft, but the sample jar only demonstrates standalone single-node use, and snapshots, dynamic membership and SSL are still listed as work in progress.

**openmessaging/dledger** — A raft-based java library for building high-available, high-durable, strong-consistent commitlog.

- Repository: https://github.com/openmessaging/dledger
- Stars: 830 · Forks: 321
- Language: Java
- License: Apache-2.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/openmessaging-dledger

## A commitlog library that stops short of being a database

DLedger is a Java library whose declared purpose is to provide a high-available, high-durable, strongly consistent commitlog that can act as the persistent layer for a distributed storage system, with messaging, streaming, key-value and database systems given as examples. That positioning matters, because it fixes the scope of the project. You are not getting a storage engine, a query language, a transaction manager or a client protocol. You are getting the replicated log, and the log is the part that is genuinely hard to get right.

The intended users are backend engineers building a distributed system who want consensus inside their own JVM instead of bolting a separate distributed system next to their service. A message broker, a log aggregator, a replicated key-value store or a stream processor are all plausible fits, since all of them need an ordered, durable, agreed-on sequence of writes before they can do anything else.

The project's own introduction makes a strong claim, stating that it has been proven to be a true production ready product and that it adds many features not described in the original Raft paper. That claim sits in the introduction rather than in a benchmark or a case study, and the project publishes no performance numbers, no latency figures and no deployment list. Treat the claim as a positioning statement from the maintainers rather than as measured evidence.

## Leader election, preferred leader and a pre-vote phase

The mechanism starts with leader election, which is the entry point for every write the library accepts. DLedger adds a preferred leader election path on top of the basic mechanism, and it also implements a pre-vote protocol, the phase described in the Ongaro dissertation where a candidate asks the cluster whether it could win an election before it starts one. Pre-vote exists to stop a partitioned node from disrupting a healthy cluster when it returns, since a node that has been cut off cannot know it was removed.

Two network partition behaviours are called out as supported: high tolerance of symmetric network partition and high tolerance of asymmetric network partition. The distinction matters in practice. A symmetric partition means the two sides can neither hear each other nor be heard. An asymmetric partition means traffic flows in one direction only, which is the harder case for a naive implementation because one side keeps receiving stale requests from the other.

The feature list also names high performance, high reliable storage support as a goal rather than a measured claim, and points to a separate Jepsen verification project with fault injection hosted under the openmessaging organisation. That external project is a better signal of how seriously the consensus layer was checked than the marketing wording is, but it is a companion repository, not part of the library you would depend on.

## Parallel and asynchronous replication across a state machine

Once a leader exists, writes are replicated. DLedger describes parallel log replication between leader and followers, meaning several follower batches can be in flight at the same time rather than the leader waiting for one round trip before sending the next, and asynchronous replication, which lets the leader accept client requests without a synchronous quorum confirmation on every append. Asynchronous replication raises the throughput ceiling and lowers latency, and it also means the library must be explicit about what a successful append guarantees, something the documentation here leaves largely open.

The library also provides a state machine. In this design the replicated log is not just a byte stream, it is the input to a deterministic state machine that each node applies, so followers and leader converge on the same application state. That is the hook a distributed key-value store or a broker would use, and it is the reason the project describes itself as a persistent layer rather than as a replication transport.

Multi-Raft is listed as a feature, meaning several independent log groups, each with its own leader, can live in the same process. That design lets one JVM carry many small, logically separate replicated logs, which is attractive for services that need many small coordination groups instead of a single global one. The cost is that the library now competes for the same threads, disk and network of the host application, and the documentation does not describe how the groups are isolated from one another when they share those resources.

## Building the project and appending your first record

The quick start lists two prerequisites: a 64bit JDK 1.8+ and Maven 3.2.x. With those in place the whole library is built with a single command, and the tests are skipped for speed.

```bash
mvn clean install -DskipTests
```

The repository contains a top-level pom.xml and an example module, and the build output that the README refers to is a runnable jar in the example module. Running the jar with no arguments prints the command line help, which is the fastest way to see the available modes.

```bash
java -jar example/target/dledger-example.jar
```

The appender mode starts a standalone append-only log server, described as a high-available, high-durable, strongly consistent, append-only log store. In standalone mode there is no peer to replicate to, so what you are exercising is the write and read path rather than the consensus path.

```bash
java -jar example/target/dledger-example.jar appender
```

With a server running in another terminal you can append a value, and the documentation states that this leaves a log containing that value in the appender.

```bash
java -jar example/target/dledger-example.jar append -d "Hello World"
```

Reading it back takes an index, and the documented example uses index zero, which is where the first record lives.

```bash
java -jar example/target/dledger-example.jar get -i 0
```

The project ships a dependency on a Maven Central artifact under the io.openmessaging.storage group, so the library is published as an ordinary Java dependency rather than something you have to build from source to use it.

## The register model shows the state machine, not a cluster

The same example jar contains a second mode, a simple multi-register model. It exists to show the state machine and key-value style access path rather than raw log appends, and it exposes a write command with a key and a value and a read command with a key.

```bash
java -jar example/target/dledger-example.jar register
```

Writing a value into key 13 uses two numeric flags, and the documentation states that the pair has been written to the register model.

```bash
java -jar example/target/dledger-example.jar write -k 13 -v 31
```

Reading the key back returns the value that was written, which demonstrates that the state machine applied the same log entry on the reading side.

```bash
java -jar example/target/dledger-example.jar read -k 13
```

What this tutorial does not do is start three or more nodes, join them, or form a group. Every command in the quick start is a standalone process. That is a real limit on what you can learn from the examples, because the properties the project advertises (leader election, partition tolerance, parallel replication) only exist once several peers are configured, and the repository does not document the cluster configuration format in the quick start. The example sources under example/src are where you would have to look for how nodes are wired together. Anyone evaluating the library for a real deployment should expect to write their own bootstrap, configuration and networking code.

## The alternative is to keep consensus out of the data path

The usual alternative to an embedded commitlog library is a split architecture: a separate coordination service provides leader election and small state, while the application keeps its own local log and treats the coordinator only as a hint about who is in charge. That approach keeps the durable write path local and cheap, and it isolates the failure domain of the coordinator from the data. DLedger takes the opposite position. It replicates the log itself between nodes, it ships a state machine, and it supports multiple independent raft groups inside one process, so consensus sits directly on the write path and the library owns the durability guarantees.

The trade-off is visible in the feature list. Because the log is the replicated object, the library needs things the split architecture does not: a pre-vote phase, careful handling of asymmetric partitions, and eventually snapshotting so that a restarting node does not have to replay the entire history. Snapshot is listed as working in progress, and the same list names dynamic membership and configuration change as features still to be added, along with SSL/TLS support.

Those three gaps decide the audience. If your system cannot yet tolerate an unbounded log replay on restart, cannot add or remove a node without a full cluster restart, and cannot run its peer traffic over plaintext, then the current DLedger release is not the right building block, whatever its consensus layer can do.

## Repository activity, release tags and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-09-04. The published release list tells a different story about distribution: the most recent release is dledger-all-0.4.0, tagged DLedger-0.4.0, dated 2023-08-31, before that dledger-all-0.3.2 from 2022-11-23 and dledger-all-0.3.1 from 2022-09-15. So the tree is receiving changes while the last tagged release is more than two years older. Anyone pinning a version in a build will be pinning code that predates the recent work, and the gap between a 2026 push and a 2023 tag is worth raising with the maintainers before you depend on a specific artifact.

The project is licensed under Apache License, Version 2.0, and the README links the licence text held in the repository. Apache-2.0 is a permissive licence with an express patent grant, and it requires that notices and the licence text travel with redistributed copies. This is a description of the licence terms and not legal advice, and any organisation should still have its own counsel review the obligations that apply to its use.

The repository layout also shows a proxy module, a jepsen directory, a script directory and a style directory alongside the core dledger and example modules, which tells you the project has tooling and fault testing in mind even where the quick start does not cover them.

## Conclusion

Adopt DLedger if you are writing a Java system that needs an embedded, replicated append-only log with a state machine and several independent log groups in one process, and you are willing to run it yourself. Do not adopt it if you need snapshots, secure transport or online membership changes, since the project still lists all three as pending work. Before committing, verify the JDK and Maven versions your build actually uses against the 64bit JDK 1.8+ and Maven 3.2.x prerequisites, and check whether the published artifact dledger-all-0.4.0 from 2023-08-31 matches the code you plan to depend on, given that the last push to the repository was on 2026-09-04.

## FAQ

### What does DLedger add on top of the original Raft paper?

The feature list names leader election, preferred leader election, a pre-vote protocol, parallel log replication, asynchronous replication, a state machine, multi-raft and tolerance of symmetric and asymmetric network partitions. Snapshot, dynamic membership and SSL/TLS support are listed as features still waiting to be added.

### What do I need to build DLedger and run the example?

The quick start states two prerequisites, a 64bit JDK 1.8+ and Maven 3.2.x, and one build command, mvn clean install -DskipTests. The build produces a runnable jar at example/target/dledger-example.jar, and running it without arguments prints the command line help.

### How do I append data and read it back with the DLedger example?

Start the appender with the appender mode, then run the append command with a -d value to write it into the log, for example a Hello World payload. Reading it back takes the get command with an -i index, and the documented example uses index 0 for the first record.

### Does the example show a multi-node cluster?

No. Every command in the quick start starts or talks to a standalone process, including the appender and the register model, and the documentation does not describe a multi-node bootstrap or configuration format. The feature list does claim multi-raft support, so cluster wiring would have to be worked out from the example sources.

### Is DLedger actively maintained and under what licence?

The repository is not archived and the last push was on 2026-09-04, but the most recent listed release is dledger-all-0.4.0 from 2023-08-31, so recent commits have not produced a new tag. The project is distributed under Apache License, Version 2.0.

## Sources

- [Issues](https://github.com/openmessaging/dledger/issues)
- [License: Apache-2.0](https://github.com/openmessaging/dledger/blob/master/LICENSE)
- [openmessaging/dledger on GitHub](https://github.com/openmessaging/dledger)
- [README](https://github.com/openmessaging/dledger/blob/master/README.md)
- [Releases](https://github.com/openmessaging/dledger/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/openmessaging-dledger