https://github.com/namreg/godown
Distributed, fault-tolerant key-value storage written in go.
https://github.com/namreg/godown
distributed go key-value raft
Last synced: 3 months ago
JSON representation
Distributed, fault-tolerant key-value storage written in go.
- Host: GitHub
- URL: https://github.com/namreg/godown
- Owner: namreg
- License: mit
- Created: 2018-05-18T06:55:06.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2018-12-05T07:44:28.000Z (almost 7 years ago)
- Last Synced: 2024-07-21T00:33:05.983Z (about 1 year ago)
- Topics: distributed, go, key-value, raft
- Language: Go
- Homepage:
- Size: 3.32 MB
- Stars: 364
- Watchers: 23
- Forks: 26
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
## Godown
[](https://www.travis-ci.org/namreg/godown)
[](https://goreportcard.com/report/github.com/namreg/godown)
[](https://github.com/namreg/godown/blob/master/LICENSE)
[](https://codecov.io/gh/namreg/godown)
A simple, distributed, fault-tolerant key-value storage inspired by Redis. It uses [Raft](https://raft.github.io) protocotol as consensus algorithm.
It supports the following data structures: `String`, `Bitmap`, `Map`, `List`.
[](https://asciinema.org/a/lNp3lOJlnnp9WQW3kKnguL35e)
### How to install
#### Install via binaries
You can find binaries on the [Github releases page](https://github.com/namreg/godown/releases).
```bash
/application/godown/godown-server -dir=/application/godown/data01 -id=01 -listen=127.0.0.1:14001 -raft=127.0.0.1:24001
/application/godown/godown-server -dir=/application/godown/data02 -id=02 -listen=127.0.0.1:14002 -raft=127.0.0.1:24002 -join=127.0.0.1:14001
/application/godown/godown-server -dir=/application/godown/data03 -id=03 -listen=127.0.0.1:14003 -raft=127.0.0.1:24003 -join=127.0.0.1:14001
```
#### Install via docker
```bash
# creating a network
docker network create godown
# creating a volume
docker volume create godown
# bootstrap a cluster with a single node
docker run -it --rm -v godown:/var/lib/godown --name=godown_1 --net=godown -p 5000:5000 \
namreg/godown-server -id 1 -listen godown_1:5000 -raft godown_1:6000
# join the second node to the cluster
docker run -it --rm -v godown:/var/lib/godown --name=godown_2 --net=godown -p 5001:5001 \
namreg/godown-server -id 2 -listen godown_2:5001 -join godown_1:5000 -raft godown_2:6001
# join the third node to the cluster
docker run -it --rm -v godown:/var/lib/godown --name=godown_3 --net=godown -p 5002:5002 \
namreg/godown-server -id 3 -listen godown_3:5001 -join godown_1:5000 -raft godown_3:6002
```
Available options to run a server:
```bash
-dir string
Directory where data is stored.
-gc duration
Garbage collector interval.
-id string
Server unique id.
-join string
Server address to join.
-listen string
Server address to listen.
-raft string
Raft protocol listen address.
-resp string
Redis Serialization Protocol listen address.
-version
Show version.
```
### How to connect
You can connect to any godown node. All modifications will be replicated to all nodes.
#### Connect via any redis client
If you have specified `resp` address while starting a node, you can connect to the one by any redis client.
```go
package main
import (
"fmt"
"net"
"time"
"github.com/garyburd/redigo/redis"
)
const connectionTimeout = 100 * time.Millisecond
func main() {
conn, err := net.Dial("tcp", "6380")
if err != nil {
panic(err)
}
rconn := redis.NewConn(conn, connectionTimeout, connectionTimeout)
reply, err := rconn.Do("LRANGE", "list", 0, 100)
vals, err := redis.Strings(reply, err)
if err != nil {
panic(err)
}
fmt.Println(vals)
}
```
#### Connect via CLI
```bash
godown-cli
```
Available options:
```bash
-host string
Host to connect to a server (default "127.0.0.1")
-port string
Port to connect to a server (default "4000")
-version
Show godown version.
```
Supported commands:
| Command| Description |
|---|---|
| HELP command | Show the usage of the given command. |
| TYPE key | Returns the type stored at key. |
| KEYS pattern | Find all keys matching the given pattern. |
| PING [message] | Returns PONG if no argument is provided, otherwise return a copy of the argument as a bulk. |
| EXPIRE key seconds | Set a timeout on key. After the timeout has expired, the key will automatically be deleted. |
| TTL key | Returns the remaining time to live of a key. -1 returns if key does not have timeout. |
|---|---|---|
| SET key value | Set key to hold the string value. If key already holds a value, it is overwritten. |
| GET key | Get the value by key. If provided key does not exist NIL will be returned. |
| STRLEN key | Returns length of the given key. If key does not exists, 0 will be returned. |
| DEL key | Delete the given key. |
|---|---|---|
| SETBIT key offset value | Sets or clears the bit at offset in the string value stored at key. |
| GETBIT key offset | Returns the bit value at offset in the string value stored at key. |
|---|---|---|
| LPUSH key value [value ...] | Prepend one or multiple values to a list. |
| LPOP key | Removes and returns the first element of the list stored at key. |
| RPUSH key value [value ...] | Append one or multiple values to a list. |
| RPOP key | Removes and returns the last element of the list stored at key. |
| LLEN key | Returns the length of the list stored at key. If key does not exist, it is interpreted as an empty list and 0 is returned. |
| LINDEX key index | Returns the element at index index in the list stored at key.
The index is zero-based, so 0 means the first element, 1 the second element and so on. Negative indices can be used to designate elements starting at the tail of the list. |
| LRANGE key start stop | Returns the specified elements of the list stored at key.
The offsets start and stop are zero-based indexes, with 0 being the first element of the list (the head of the list), 1 being the next element and so on. |
| LREM key value | Removes all occurrences of elements equal to value from the list stored at key. |
|---|---|---|
| HSET key field value | Sets field in the hash stored at key to value. |
| HGET key field | Returns the value associated with field in the hash stored at key. |
| HKEYS key | Returns all field names in the hash stored at key. Order of fields is not guaranteed. |
| HVALS key | Returns all values in the hash stored at key. |
| HDEL key field [field ...] | Removes the specified fields from the hash stored at key. Returns the number of fields that were removed. |
#### Connect via go client
```go
package main
import (
"fmt"
"github.com/namreg/godown/client"
)
func main() {
c, err := client.New("127.0.0.1:4000")
if err != nil {
panic(err)
}
defer c.Close()
res := c.Get("key")
if res.Err() != nil {
panic(res.Err())
}
if res.IsNil() {
fmt.Print("key does not exist")
} else {
fmt.Println(res.Int64())
}
}
```
Client documentation available at [godoc](https://godoc.org/github.com/namreg/godown/client)
### TODO
- [ ] Write more docs
- [ ] Write more tests