UnisonDB: A Log-Native Edge Database That Replicates Through Object Storage

The Edge Replication Problem UnisonDB Targets

An edge deployment that writes locally and must also stay consistent across many sites ends up rebuilding the same pipeline: a database for local durability, a change-data-capture layer, a message bus, and a consumer per replica. UnisonDB's claim is that the write-ahead log already contains the change stream, so a separate bus is redundant. The README describes it as a log-native, real-time database that replicates like a message bus, and lists Kafka, Pub/Sub and CDC pipelines among the components it intends to replace. The audience is narrow and identifiable: teams running many small nodes where data and computation sit together, not teams running a single large cluster in one region. If your architecture has one primary region and a handful of readers, the fan-out story does not apply to you, and the value proposition mostly collapses into an ordinary embedded key-value store with network access.

How Writes Travel: Raft, WAL, and Two Replication Paths

The architecture has two distinct roles. Write servers accept mutations and, when Raft is enabled, commit them through a quorum before acknowledging. The commit lands in a B+Tree storage engine backed by a write-ahead log, so durability comes from the log rather than from the tree structure itself. Read-only edge replicas and relayers then consume that log through one of two transports. The first is a live gRPC stream, which behaves like a conventional replication feed and needs a reachable writer. The second is blob-backed replication, where the writer publishes the WAL as immutable segment files plus bounded catalog metadata into object storage, and any number of readers poll and catch up directly. That second path is the interesting one architecturally. It converts replication from a connection problem into a storage problem: readers do not need the writer to be online, and the writer does not need to track who is connected. The README states that relayer and replica nodes use in-sync replica replication, while write servers use Raft consensus, so there are two different consistency mechanisms in play depending on which node you are looking at. Multi-hop relaying is supported, which is how the README arrives at its fan-out arithmetic: a primary reaching 100 hubs, each hub reaching 100 further nodes, for a claimed 10,100 in total. Those latency and throughput figures come from the project's own benchmark section, run on an Apple M2 Pro with 16 GB of memory, and should be treated as vendor measurements rather than independent results.

Storage Models and the ZeroMQ Notification Sidecar

UnisonDB describes itself as multi-model, and the three models are key-value, wide-column and large objects. The HTTP API reflects this in its path shape: a PUT to /api/v1/default/kv/mykey with a JSON body containing a base64-encoded value, where default is the namespace. Namespace isolation is the multi-tenancy mechanism, and it is the only one described in the material, so expect isolation at the namespace boundary rather than per-key access control. The storage backend is pluggable, with two B+Tree implementations listed: BoltDB, described as a single-file ACID-compliant B+Tree, and LMDB, described as memory-mapped with copy-on-write semantics. That choice is not cosmetic. A memory-mapped tree behaves differently under memory pressure and file-size limits than a single-file one, and the README does not explain how to pick between them or what happens when a mapped file outgrows the address space on a small edge device. Change notifications are delivered through ZeroMQ in a sidecar process, with the README claiming sub-millisecond latency. The sidecar arrangement means a notification path that is separate from the replication path, which is a reasonable separation but also one more process to supervise on each node.

Getting a Server Running and Writing a Key

The quick start is four steps and assumes Go is installed. Clone the repository, build the binary with go build -o unisondb ./cmd/unisondb, then start it with ./unisondb server --config config.toml. The config file is TOML and is passed by path, but the README does not inline its contents; the configuration guide is a separate documentation page, so the first real task after cloning is reading that page rather than copying a working config from the repository root. Once the server is up, the HTTP API listens on port 4000 by default in the example, and a write looks like a PUT to http://localhost:4000/api/v1/default/kv/mykey with Content-Type: application/json and a body of {"value":"bXl2YWx1ZQ=="}. That value is base64, which is worth noting because it means binary payloads pass through the JSON API without escaping problems, at the cost of a 33 percent size increase on the wire. For the blob replication path, the README points at cmd/examples/blobstore-minio, described as a local MinIO example using the same S3-compatible provider path, which is the closest thing to a runnable end-to-end demonstration of the feature that makes this project distinct.

The Alpha Label and What the README Does Not Settle

The repository carries a status badge reading alpha, and no releases were retrieved for this assessment. That combination matters more than any feature list. There is no versioned artifact to pin, so an upgrade means tracking the main branch or building from a commit you select yourself. The README also leaves several operational questions open. It does not describe how WAL segments are garbage collected from object storage once every reader has consumed them, which is the failure mode that turns blob-backed replication into an unbounded storage bill. It does not state what happens to a reader that falls behind while the catalog metadata is pruned. It does not cover conflict handling when a relay writes back upstream, or whether that direction is supported at all. The fan-out numbers are presented without the topology, instance types or network conditions behind them beyond the single-machine benchmark environment. None of this makes the design wrong, but it means the alpha label is doing real work: the gaps are in the areas you would need answered before putting this in front of customers. The Apache-2.0 licence removes legal friction for embedding it, and that is the least complicated part of the decision.

Where a Conventional Embedded Store Fits Better

The obvious alternative for the same deployment shape is an embedded key-value store such as bbolt or BadgerDB, both of which appear in the project's own benchmark comparison. The difference is not speed, it is where replication lives. bbolt and BadgerDB give you a local store and stop there; moving data between nodes is your problem, which in practice means writing a change feed or accepting that each node is independent. UnisonDB folds the feed into the storage engine and offers two transports for it, which is the whole reason to accept a server process, a sidecar and a Raft path instead of a library call. The trade is real in the other direction: an embedded library cannot go down separately from your application, needs no port, and has no quorum to lose. If your edge nodes are genuinely independent and you reconcile data centrally in batch, BadgerDB plus your own sync job is less machinery for the same outcome. The benchmark in the README compares UnisonDB against BadgerDB, BoltDB and LMDB through a Redis-compatible interface using redis-benchmark, with 50 iterations of mixed SET and GET, 200k operations per run, 10 parallel clients, 10 pipelined requests, 4 threads and 1KB payloads, on an M2 Pro with the LMDB backend. It measures single-node throughput and p50 latency, which tells you nothing about the replication behaviour the project is actually selling.

Maintenance Surface and Licence Position

The maintenance cost sits in three places. First, the config.toml file, which is the single source of truth for backend selection, replication mode and namespace behaviour, and which is documented outside the repository. Second, the object-storage lifecycle for WAL segments, which is your responsibility to monitor because the README does not describe an automatic retention policy. Third, the ZeroMQ sidecar, which is a separate process per node. Upgrades are the sharpest edge: with no releases retrieved and an alpha status badge, there is no changelog to read before moving a node forward, so a staged rollout with a replica you can discard is the only defensible approach. On licensing, Apache-2.0 permits commercial use, modification and redistribution, and includes an express patent grant, which is normally what an edge vendor wants. It also means you carry no obligation to publish modifications. This is a description of the licence text, not legal advice; if you are embedding the database in a shipped appliance, have counsel confirm the notice and attribution requirements against your distribution model.

Editorial conclusion

Adopt UnisonDB only if you are comfortable running alpha software in front of edge traffic and you already operate S3, MinIO, GCS or Azure Blob, since blob-backed replication is the part that distinguishes it from a plain embedded key-value store. Skip it if you need a stable release line, a managed control plane, or a query language more expressive than key-value, wide-column and large-object access. Before committing, verify the config.toml keys for the LMDB backend and the blob catalog against the configuration guide, and run the MinIO example under cmd/examples/blobstore-minio to confirm the object-store path works in your environment.

Official sources

1. ankur-anand/unisondb on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README