raftdb is a simple distributed key value store based on the Raft consensus protocol. It can be run on Linux, OSX, and Windows.

Building raftdb requires Go 1.9 or later. gvm is a great tool for installing and managing your versions of Go.

Starting and running a raftdb cluster is easy. Download raftdb like so:

mkdir -p $GOPATH/src/github/hanj4096
cd $GOPATH/src/github/hanj4096
git clone github.com/hanj4096/raftdb

Build raftdb like so:

cd $GOPATH/src/github.com/hanj4096/raftdb
go install ./...

Add your servers’ hostnames and IP addresses to each cluster server’s /etc/hosts file (the hostnames below are representative).

<Meta_1_IP> raft-cluster-host-01
<Meta_2_IP> raft-cluster-host-02
<Meta_3_IP> raft-cluster-host-03

Verification steps:

Before proceeding with the installation, verify on each server that the other servers are resolvable. Here is an example set of shell commands using ping:

ping -qc 1 raft-cluster-host-01

ping -qc 1 raft-cluster-host-02

ping -qc 1 raft-cluster-host-03

We highly recommend that each server be able to resolve the IP from the hostname alone as shown here. Resolve any connectivity issues before proceeding with the installation. A healthy cluster requires that every meta node can communicate with every other meta node.

Run your first raftdb node like so:

$GOPATH/bin/raftd -id node01  -haddr raft-cluster-host-01:8091 -raddr raft-cluster-host-01:8089 ~/.raftdb

Let's bring up 2 more nodes, so we have a 3-node cluster. That way we can tolerate the failure of 1 node:

$GOPATH/bin/raftd -id node02 -haddr raft-cluster-host-02:8091 -raddr raft-cluster-host-02:8089 -join raft-cluster-host-01:8091 ~/.raftdb

$GOPATH/bin/raftd -id node03 -haddr raft-cluster-host-03:8091 -raddr raft-cluster-host-03:8089 -join raft-cluster-host-01:8091 ~/.raftdb

You can now set a key and read its value back:

curl -X POST raft-cluster-host-01:8091/key -d '{"foo": "bar"}' -L
curl -X GET raft-cluster-host-01:8091/key/foo -L

You can now delete a key and its value:

curl -X DELETE raft-cluster-host-01:8091/key/foo -L

You can now read the key's value by different read consistency level:

curl -X GET raft-cluster-host-01:8091/key/foo?level=stale
curl -X GET raft-cluster-host-01:8091/key/foo?level=default  -L
curl -X GET raft-cluster-host-01:8091/key/foo?level=consistent  -L