LotusDB: an embedded Go key-value store that claims LSM and B+ tree at once

Open, Put, Get, Delete is the entire first-run surface

LotusDB is imported as a Go package at github.com/lotusdblabs/lotusdb/v2. There is no server to start and no config file. You take lotusdb.DefaultOptions, set a directory, and call Open.

// specify the options
options := lotusdb.DefaultOptions
options.DirPath = "/tmp/lotusdb_basic"

// open a database
db, err := lotusdb.Open(options)
if err != nil {
	panic(err)
}

From there the example writes a key with db.Put([]byte("name"), []byte("lotusdb")), reads it back with db.Get([]byte("name")), and removes it with db.Delete. Keys and values are plain byte slices, so serialisation is your job. The example defers db.Close() in a function that discards the returned error, which is fine for a demo and worth changing in production code where a failed close can hide a lost write.

The README snippet is cut off mid-line at the Delete call, so for anything beyond these four operations you are sent to the examples directory.

The README promises LSM and B+ tree, then leaves the Design Overview empty

The project's own description calls it compatible with LSM tree and B+ tree, and the README lists three features: combining the advantages of LSM and B+ tree, fast read and write performance, and much lower read and space amplification than a typical LSM. It also says LotusDB is an optimization of badger and bbolt.

Those are claims, and the README gives no number behind any of them. The Design Overview heading sits directly under the feature list with no text beneath it. A reader who wants to know how data moves from memory to disk, or what triggers a merge, has to open the source.

The file names in the repository root at least show where to look: memtable.go, bptree.go, vlog.go, hashtable.go, heap.go, index.go, iterator.go, batch.go and diskio.go. A benchmark directory is also present. Treat the speed and amplification statements as hypotheses to test with that directory, not as measured results.

Dependencies show badger and rosedblabs pieces under the hood

The go.mod declares go 1.21 and a direct dependency list worth reading before you vendor the library:

require (
	github.com/bwmarrin/snowflake v0.3.0
	github.com/cespare/xxhash/v2 v2.2.0
	github.com/dgraph-io/badger/v4 v4.2.0
	github.com/gofrs/flock v0.8.1
	github.com/rosedblabs/diskhash v0.0.0-20230910084041-289755737e2a
	github.com/rosedblabs/wal v1.3.8
	github.com/stretchr/testify v1.9.0
	golang.org/x/sync v0.5.0
)

badger v4.2.0 is a direct requirement, which sits oddly beside a README that frames LotusDB as an optimization of badger. The README does not say which badger component is used. The rosedblabs diskhash and wal modules are pinned to a pseudo-version and v1.3.8, and a fork at github.com/lotusdblabs/bbolt appears as an indirect requirement.

If your build is audited, that is a lot of third-party code for a store that presents itself as self-contained. Go 1.21 is also the declared language floor, so older toolchains will not build it.

Three example programs are the only usage documentation beyond the snippet

The README points to an examples directory with three folders: basic, batch and iterator. Those match the batch.go and iterator.go files in the repository root.

What that means in practice: the README documents one write path and one read path. Anything about transactions, atomic multi-key writes, range scans or ordering guarantees has to be learned from the batch and iterator examples or from the code. The README does not document configuration beyond DirPath, so the other fields on DefaultOptions are discovered by reading options.go.

The repository also holds errors.go, so error values are defined in one place, but the README names none of them. If your code needs to branch on a specific failure, such as a missing key versus an I/O problem, check that file before you write the handler. Treat the first Get on an absent key as something to test, because the README example only shows a key that exists.

The package is at v2.1.0, and the last release date is May 2024

Tagged releases are v1.0.0 on 2022-03-20, v2.0.0 on 2023-09-04 and v2.1.0 on 2024-05-18. The module path ends in /v2, matching the major version, so a v1 import path will not resolve to the same API.

The repository was last pushed on 2026-08-27, which is later than the last release by well over two years. That means main may contain changes that are not in any tag. Pinning to v2.1.0 gets you a tested release; tracking main gets you whatever landed since. The go.mod in main already references a lotusdblabs/bbolt version stamped 20250108, a date after v2.1.0, which confirms the default branch has moved past the tag.

The project is not archived. There is a CHANGELOG.md in the root, which is where to confirm what changed between v2.1.0 and main before you choose a pin.

Nothing in the README covers durability, crash recovery or concurrent access

A key-value store is judged on what happens when the process dies. The README says nothing about write-ahead logging, fsync behaviour, recovery after a crash, or file locking, and it does not explain what happens if two processes open the same DirPath.

The dependency list suggests where to look. gofrs/flock is a file-lock library and rosedblabs/wal is a write-ahead log package. Those names are evidence that locking and logging exist somewhere in the code, but the README does not tell you how they are used or what guarantees follow. Reading db.go and vlog.go is the reliable route.

The consequence for adoption: do not put data you cannot lose into LotusDB on the strength of the README alone. Write a test that kills the process mid-batch and reopens the directory, and check what you get back.

Support is a Slack channel, GitHub Discussions and a WeChat group

The README's community section links a Slack workspace and the repository's Discussions page, and invites Chinese-speaking users to join a WeChat group by scanning a QR code. There is no mention of a formal issue triage policy or a support commitment.

The Slack invite URL belongs to a workspace named rosedblabs, not lotusdblabs. That fits the dependency list, where rosedblabs/wal and rosedblabs/diskhash appear, and suggests a shared team behind both projects. The README does not say so directly.

For a database you embed in your process, this is thin support. Bug reports will go through GitHub, and answers about internals will come from the people in those channels. The Apache-2.0 license lets you fork and patch if you need a fix that does not arrive.

Editorial conclusion

Use LotusDB if you want an embedded Go store you open from your own process, you can live with a README that states performance claims without numbers, and you are willing to read the source. Avoid it if you need published benchmarks, a server with a network protocol, or documentation beyond one example program. Before committing, run the benchmark directory against your own key sizes and read the examples for batch and iterator behaviour.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. lotusdblabs/lotusdb on GitHub
3. Project website
4. README
5. Releases