RaftKV is a distributed key-value store that uses the Raft consensus algorithm for replication and fault tolerance. It provides a simple HTTP API for key-value operations and supports automatic leader election and cluster membership management.

• Distributed key-value store with Raft consensus
• HTTP API for key-value operations
• Automatic leader election
• Cluster membership management
• Fault tolerance and data replication
• Multiple storage backends:
  • BoltDB (default)
  • SQLite
• Snapshot support for log compaction

• Go 1.24 or later
• Make (for using the Makefile)
• SQLite development libraries (if using SQLite storage)

sudo apt-get install sqlite3 libsqlite3-dev

brew install sqlite3

SQLite is included with the Go SQLite driver.

1. Clone the repository:

git clone https://github.com/yourusername/raftkv.git
cd raftkv

2. Install dependencies:

go mod download

Build the project using make:

make build

This will create the raftkv binary in the bin directory.

The project includes a Makefile with targets to run a 3-node cluster locally. Each node runs on different ports:

• Node 1: HTTP API on 8080, Raft on 8001
• Node 2: HTTP API on 8081, Raft on 8002
• Node 3: HTTP API on 8082, Raft on 8003

You can choose between two storage backends using the STORAGE environment variable:

1. BoltDB (default):

make run-cluster
# or
STORAGE=bolt make run-cluster

2. SQLite:

STORAGE=sqlite make run-cluster

The same storage option can be used with individual node commands:

# Run a single node with SQLite
STORAGE=sqlite make run-node1

# Run a single node with BoltDB (default)
make run-node1

Note: The Raft logs and snapshots will always use BoltDB for storage, regardless of the KV store backend chosen.

You can start each node separately in different terminal windows:

1. Start the first node (leader):

make run-node1

2. Start the second node:

make run-node2

3. Start the third node:

make run-node3

Alternatively, you can start all nodes with a single command:

make run-cluster

This will start all three nodes in the background. You can check their status using:

make status

To stop all nodes:

make stop-cluster

To clean up all node data:

make clean-data

1. Set a value:

curl -X PUT -d "value1" http://localhost:8080/v1/keys/key1

2. Get a value:

curl http://localhost:8080/v1/keys/key1

3. Delete a key:

curl -X DELETE http://localhost:8080/v1/keys/key1

Check the status of any node:

curl http://localhost:8080/v1/status

The response will include:

• leader: The address of the current leader
• state: The current state of the node (Leader/Follower)

Each node is configured using a YAML file in the configs directory. The configuration includes:

• Node ID
• Bind address for Raft communication
• Advertise address for Raft communication
• Data directory for persistent storage
• HTTP API address

Example configuration (node1.yaml):

node_id: "node1"
bind_addr: "127.0.0.1:8001"
advertise_addr: "127.0.0.1:8001"
data_dir: "data/node1"
http_addr: "127.0.0.1:8080"

.
├── bin/                    # Compiled binaries
├── cmd/                    # Command-line applications
│   └── raftkv/            # Main application
├── configs/               # Configuration files
├── data/                  # Data directory (created at runtime)
├── pkg/                   # Core packages
│   ├── api/              # HTTP API implementation
│   ├── raft/             # Raft consensus implementation
│   └── storage/          # Storage implementation
│       ├── bolt_store.go # BoltDB storage implementation
│       └── sqlite_store.go # SQLite storage implementation
├── Makefile              # Build and run targets
└── README.md            # This file

make build

make test

make clean

This project is licensed under the MIT License - see the LICENSE file for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request