Fault tolerant, sharded key value storage written in GoLang

Overview

Ravel is a sharded, fault-tolerant key-value store built using BadgerDB and hashicorp/raft. You can shard your data across multiple clusters with multiple replicas, the data is persisted on disk using BadgerDB for high throughput in reads and writes. Replication and fault-tolerance is done using Raft.

Ravel exposes a simple HTTP API for the user to read and write data and Ravel handles the sharding and the replication of data across clusters.

Table of Contents

Installation

Ravel has two functional components. A cluster admin server and a replica node, both of them have their separate binary files. To setup Ravel correctly, you'll need to start one cluster admin server and many replica nodes as per requirement.

Using curl

This will download the ravel_node and ravel_cluster_admin binary files and move it to /usr/local/bin, make sure you have it in your $PATH

curl https://raw.githubusercontent.com/adityameharia/ravel/main/install.sh | bash

From Source

  • cmd/ravel_node directory has the implementation of ravel_node which is the replica node
  • cmd/ravel_cluster_admin directory has the implementation of ravel_cluster_admin which is the cluster admin server
  1. Clone this repository
git clone https://github.com/adityameharia/ravel
cd ravel
git checkout master
  1. Build ravel_node and ravel_cluster_admin
cd cmd/ravel_node
go build 
sudo mv ./ravel_node /usr/local/bin
cd ../ravel_cluster_admin
go build
sudo mv ./ravel_cluster_admin /usr/local/bin

This will build the ravel_node and ravel_cluster_admin binaries in cmd/ravel_node and cmd/ravel_cluster_admin respectively and move them to /usr/local/bin

Usage

Usage info for ravel_cluster_admin

$ ravel_cluster_admin --help
NAME:
   Ravel Cluster Admin - Start a Ravel Cluster Admin server

USAGE:
   ravel_cluster_admin [global options] command [command options] [arguments...]

COMMANDS:
   help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --http value        Address (with port) on which the HTTP server should listen
   --grpc value        Address (with port) on which the gRPC server should listen
   --backupPath value  Path where the Cluster Admin should persist its state on disk
   --help, -h          show help

Usage info for ravel_node

$ ravel_node --help
NAME:
   Ravel Replica - Manage a Ravel replica server

USAGE:
   ravel_node [global options] command [command options] [arguments...]

COMMANDS:
   start    Starts a replica server
   kill     Removes and deletes all the data in the cluster
   help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --help, -h  show help (default: false)

Usage info for the start command in ravel_node. Use this command to start a replica server.

$ ravel_node start --help
NAME:
   ravel_node start - Starts a replica server

USAGE:
   ravel_node start [command options] [arguments...]

OPTIONS:
   --storagedir value, -s value    Storage Dir (default: "~/ravel_replica")
   --grpcaddr value, -g value      GRPC Addr of this replica (default: "localhost:50000")
   --raftaddr value, -r value      Raft Internal address for this replica (default: "localhost:60000")
   --adminrpcaddr value, -a value  GRPC address of the cluster admin (default: "localhost:42000")
   --yaml value, -y value          yaml file containing the config
   --leader, -l                    Register this node as a new leader or not (default: false)
   --help, -h                      show help (default: false)

Setup a Cluster

Executing the following instructions will setup a sample Ravel instance. The most simple configuration of a Ravel instance would consist of 2 clusters with 3 replicas each.

The key value pairs will be sharded across the two clusters and replicated thrice on each cluster. The admin will automatically decide which replica goes to which cluster. Adding and removing clusters from the system automatically relocates all the keys in that cluster to some other one. Deleting the last standing cluster deletes all the keys in the instance.

  1. Setup the cluster admin server
sudo ravel_cluster_admin --http="localhost:5000" --grpc="localhost:42000" --backupPath="~/ravel_admin"
  1. Setting up the cluster leaders
sudo ravel_node start -s="/tmp/ravel_leader1" -l=true -r="localhost:60000" -g="localhost:50000" -a="localhost:42000"
sudo ravel_node start -s="/tmp/ravel_leader2" -l=true -r="localhost:60001" -g="localhost:50001" -a="localhost:42000"
  1. Setting up the replicas
sudo ravel_node start -s="/tmp/ravel_replica1" -r="localhost:60002" -g="localhost:50002" -a="localhost:42000"
sudo ravel_node start -s="/tmp/ravel_replica2" -r="localhost:60003" -g="localhost:50003" -a="localhost:42000"
sudo ravel_node start -s="/tmp/ravel_replica3" -r="localhost:60004" -g="localhost:50004" -a="localhost:42000"
sudo ravel_node start -s="/tmp/ravel_replica4" -r="localhost:60005" -g="localhost:50005" -a="localhost:42000"

NOTE

  • -l=true sets up a new cluster, defaults to false
  • Dont forget the storage directory as you will need it to delete the replica
  • All the commands and flag can be viewed using the -h or --help flag

Reading and Writing Data

Once the replicas and admin are set up, we can start sending HTTP requests to our cluster admin server to read, write and delete key value pairs.

The cluster admin server exposes 3 HTTP routes:

  • URL: /put

    • Method: POST
    • Description: Store a key value pair in the system
    • Request Body: {"key": "<your_key_here>", "val":<your_value_here>}
      • key = [string]
      • val = [string | float | JSON Object]
    • Success Response: 200 with body {"msg": "ok"}
  • URL: /get

    • Method:POST
    • Description: Get a key value pair from the system
    • Request Body: {"key": "<your_key_here>"
      • key = [string]
    • Success Response: 200 with body {"key": <key>, "val":<value>}
  • URL: /delete

    • Method:POST
    • Description: Delete a key value pair from the system
    • Request Body: {"key": "<your_key_here>"
      • key = [string]
    • Success Response: 200 with body {"msg": "ok"}

Sample Requests

  • Sample /put requests
{
  "key": "the_answer",
  "value": 42
}
{
  "key": "dogegod",
  "value": "Elon Musk"
}
{
  "key": "hello_friend",
  "value": {
    "elliot": "Rami Malek",
    "darlene": "Carly Chaikin"
  }
}
  • Sample /get request
{
  "key": "dogegod"
}
  • Sample /delete request
{
  "key": "dogegod"
}

Killing A Ravel Instance

Stopping a ravel instance neither deletes the data/configuration nor removes it from the system, it replicates a crash with the hope that the node will come back up. Once the node is up, it will sync up all the data from the leader node.

In order to delete all the data and configuration and remove the instance from the system you need to kill it.

ravel_node kill -s="the storage directory you specified while starting the node"

Stopping the ravel_cluster_admin breaks the entire system and renders it useless. It is recommended not to stop/kill the admin unless all the replicas have been properly killed.

The cluster admin server persists its state on disk for recovery. In order to truly reset it, you have to delete its storage directory.

Uninstalling Ravel

Ravel can be uninstalled by deleting the binaries from /usr/local/bin

sudo rm /usr/local/bin/ravel_node
sudo rm /usr/local/bin/ravel_cluster_admin

Documentation and Further Reading

Contributing

If you're interested in contributing to Ravel, check out CONTRIBUTING.md

Contact

Reach out to the authors with questions, concerns or ideas about improvement.

License

Copyright (c) Aditya Meharia and Junaid Rahim. All rights reserved. Released under the MIT License

Issues
  • HTTP API Improvement

    HTTP API Improvement

    Modify the HTTP API to align it more with HTTP semantics. Doing a POST request for /get is weird and stupid.

    • GET request for /get
    • PUT request for /put
    • DELETE request for /delete
    enhancement good first issue 
    opened by junaidrahim 0
  • Optimizing disk backup operations for cluster admin server

    Optimizing disk backup operations for cluster admin server

    • Currently, a backup operation follows every operation done on RavelConsistentHash. All the data in the maps are written from start again every time a backup is triggered.
    • Will have to refactor the consistent hash code to operate with data directly on disk
    enhancement 
    opened by junaidrahim 0
Releases(v0.1-alpha)
Owner
Aditya Meharia
A 2nd year btech student at KIIT. Interested in web,cloud nd cpp.
Aditya Meharia
Golang-key-value-store - Key Value Store API Service with Go DDD Architecture

This document specifies the tools used in the Key-Value store and reorganizes how to use them. In this created service, In-Memory Key-Value Service was created and how to use the API is specified in the HTML file in the folder named "doc"

Kemal Emre Ballı 3 Mar 16, 2022
A key-value db api with multiple storage engines and key generation

Jet is a deadly-simple key-value api. The main goals of this project are : Making a simple KV tool for our other projects. Learn tests writing and git

null 12 Apr 5, 2022
Keyval - A simple key-value storage library written in Go

keyval keyval is a simple key-value storage library written in Go and its back c

sina safari 3 Mar 1, 2022
The TinyKV course builds a key-value storage system with the Raft consensus algorithm.

The TinyKV Course The TinyKV course builds a key-value storage system with the Raft consensus algorithm. It is inspired by MIT 6.824 and TiKV Project.

null 7 Jan 4, 2022
A key-value storage transaction interpretator.

kv-txn-interpreter A key-value storage transaction interpreter, which provides an etcd-like transaction interface to help you build a transaction over

JmPotato 2 Feb 22, 2022
The TinyKV course builds a key-value storage system with the Raft consensus algorithm

The TinyKV Course The TinyKV course builds a key-value storage system with the Raft consensus algorithm. It is inspired by MIT 6.824 and TiKV Project.

ytt 0 Dec 21, 2021
rosedb is a fast, stable and embedded key-value (k-v) storage engine based on bitcask.

rosedb is a fast, stable and embedded key-value (k-v) storage engine based on bitcask. Its on-disk files are organized as WAL(Write Ahead Log) in LSM trees, optimizing for write throughput.

roseduan 2.9k Jun 26, 2022
Tinykv - The TinyKV course builds a key-value storage system with the Raft consensus algorithm

The TinyKV Course The TinyKV course builds a key-value storage system with the R

null 0 May 30, 2022
Simple Distributed key-value database (in-memory/disk) written with Golang.

Kallbaz DB Simple Distributed key-value store (in-memory/disk) written with Golang. Installation go get github.com/msam1r/kallbaz-db Usage API // Get

Mohamed Samir 5 Jan 18, 2022
Pogreb is an embedded key-value store for read-heavy workloads written in Go.

Embedded key-value store for read-heavy workloads written in Go

Artem Krylysov 900 Jun 26, 2022
ZedisDB - a key-value memory database written in Go

ZedisDB - a key-value memory database written in Go

Znkisoft 3 Feb 2, 2022
NutsDB a simple, fast, embeddable and persistent key/value store written in pure Go.

A simple, fast, embeddable, persistent key/value store written in pure Go. It supports fully serializable transactions and many data structures such as list, set, sorted set.

徐佳军 2.3k Jun 24, 2022
A rest-api that works with golang as an in-memory key value store

In Store A rest-api that works with golang as an in-memory key value store Usage Fist of all, clone the repo with the command below. You must have gol

Eyüp Arslan 0 Oct 24, 2021
Go-datastore - Key-value datastore interfaces for golang

go-datastore key-value datastore interfaces Lead Maintainer Steven Allen Table o

y 0 Jan 18, 2022
moss - a simple, fast, ordered, persistable, key-val storage library for golang

moss provides a simple, fast, persistable, ordered key-val collection implementation as a 100% golang library.

null 869 Jun 21, 2022
An embedded key/value database for Go.

Bolt Bolt is a pure Go key/value store inspired by Howard Chu's LMDB project. The goal of the project is to provide a simple, fast, and reliable datab

BoltDB 12.9k Jun 25, 2022
A disk-backed key-value store.

What is diskv? Diskv (disk-vee) is a simple, persistent key-value store written in the Go language. It starts with an incredibly simple API for storin

Peter Bourgon 1.2k Jun 26, 2022
Distributed reliable key-value store for the most critical data of a distributed system

etcd Note: The master branch may be in an unstable or even broken state during development. Please use releases instead of the master branch in order

etcd-io 40.3k Jun 24, 2022
Distributed cache and in-memory key/value data store. It can be used both as an embedded Go library and as a language-independent service.

Olric Distributed cache and in-memory key/value data store. It can be used both as an embedded Go library and as a language-independent service. With

Burak Sezer 2.2k Jul 1, 2022