Skip to content

Latest commit

 

History

History
148 lines (133 loc) · 6.76 KB

README.md

File metadata and controls

148 lines (133 loc) · 6.76 KB
Raw

Build Release Go Report Card codecov Maintainability GoDoc License codebeat badge Scrutinizer Code Quality

Gerdu

About

Gerdu is a distributed key-value in-memory database server written in Go programming language. Currently, it supports two eviction policy LFU and LRU. It also supports for weak reference type of cache where the cache consumes as much memory as the garbage collector allows it to use.

You can enable gRPC, redis HTTP and memcached and enjoy taking advantage of all protocols simultaneously.

Features

  • Wire protocol support for Redis and memcached
  • Different eviction policy LRU, LFU, weak
  • gRPC and HTTP protocol support
  • Distributed and fault-tolerant via Raft
  • Telemetry features through Prometheus

Build

go build -v

Usage

Usage of gerdu:
  -capacity string
    	The size of cache, once cache reached this capacity old values will evicted.
    	Specify a numerical value followed by one of the following units (not case sensitive)
    	K or KB: Kilobytes
    	M or MB: Megabytes
    	G or GB: Gigabytes
    	T or TB: Terabytes (default "64MB")
  -cert string
    	SSL certificate public key
  -grpcport int
    	the grpc server port number (default 8081)
  -host string
    	The host that server listens (default "127.0.0.1")
  -httpport int
    	the http server port number (default 8080)
  -id string
    	Node ID (default "master")
  -join string
    	Set join address, if any
  -key string
    	SSL certificate private key
  -log string
    	log level can be any of values of 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace' (default "info")
  -mcdport int
    	the memcached server port number (default 11211)
  -protocols string
    	protocol 'grpc', 'redis' or 'mcd' (memcached), multiple comma-separated values, http is not optional
  -raft string
    	Set Raft bind address (default "127.0.0.1:12000")
  -storage string
    	Path to store log files and snapshot, will store in memory if not set
  -type string
    	type of cache, lru or lfu, weak (default "lru")

Example

Example of usage: To insert or update or delete a key

$ ./gerdu --protocols=http,grpc,mcd --log trace
INFO[0000] Gerdu started listening HTTP on 127.0.0.1:8080 
INFO[0000] Gerdu started memcached server on 127.0.0.1:11211 
INFO[0000] Gerdu started listening gRPC on 127.0.0.1:8081 

$ curl --request PUT --data '1' http://localhost:8080/cache/1
$ curl --request GET --data '1' http://localhost:8080/cache/1
1
$ curl --request PUT --data '2' http://localhost:8080/cache/2
$ curl --request PUT --data '3' http://localhost:8080/cache/3
$ curl --request PUT --data 'some new value' http://localhost:8080/cache/3
$ curl --request DELETE http://localhost:8080/cache/3 # Delete key 3
$ curl --request GET localhost:8080/cache/3 # Not found 404

To retrieve the key

$ curl --request GET localhost:8080/cache/3

Distributed Mode

Gerdu can be ran in either single mode or distributed mode. You need to specify --raft, --id, --join parameters to join an existing node.
A Gerdu cluster of 3 nodes can tolerate a single node failure, while a cluster of 5 can tolerate 2 node failures. The recommended configuration is to either run 3 or 5 raft servers. This maximizes availability without greatly sacrificing performance.

$ ./gerdu -httpport 8083 --join :8080 --id node1 --raft :12003
$ ./gerdu -httpport 8084 --join :8080 --id node2 --raft :12004

Telemetry

Prometheus metrics

$ curl --request GET localhost:8080/metrics
...
# HELP gerdu_adds_total The total number of new added nodes
# TYPE gerdu_adds_total counter
gerdu_adds_total 52152
# HELP gerdu_deletes_total The total number of deletes nodes
# TYPE gerdu_deletes_total counter
gerdu_deletes_total 23
# HELP gerdu_hits_total The total number of cache hits
# TYPE gerdu_hits_total counter
gerdu_hits_total 1563
# HELP gerdu_misses_total The total number of missed cache hits
# TYPE gerdu_misses_total counter
gerdu_misses_total 16
...

Sample applications

Sample applications are available in: