kvs

README

kvs

kvs is an in-memory key-value storage written in Go. It has 2 different usage. It can be used as a package by importing it to your code or as a server by creating an HTTP server. kvs stores persistent data in local machine's /tmp/kvs directory. The file extension is .kvs. For example, if you create a database named as user, it would be stored in a file name as users.kvs. It loads the data from file into memory if the database is already exists. Also, kvs supports saving data from memory to disk in a given time interval periodically. You can specify the time interval while creating the database. Both keys and values are stored as string. That's why the methods accept only strings.

Installation

You can add package to your project with the following command.

go get github.com/gozeloglu/kvs

Package Usage

Firstly, you need to create a database by calling kvs.Open(). It creates a new database if not exists or loads the data from existing database if it exists. If you want to use kvs as a package, you don't need to specify addr as a first parameter. As a third parameter, you pass time interval to save data to database periodically.

// Creates a "users" database and saves the data from memory to file per 2 minutes.
db, err := kvs.Open("", "users", 2*time.Minute)  

Then, simply you can call Set() and Get() methods. Set() takes key and value as parameters and adds the key-value pair to memory. Get() takes key as a parameter and returns the value of the key. Both Set() and Get() methods takes string as parameters.

// "john" is stored as key with "23" as value in memory.
db.Set("john", "23")

// Returns "23" to age.
age := db.Get("john")

If you want to make sure that all data stores in memory would save to disk, you can call Close() method. It writes the data to disk and closes the database.

// Writes data in memory to disk
db.Close()

If you want to see full code, you can take a look /example/pkg/main.go.

Package Example

package main

import (
	"fmt"
	"github.com/gozeloglu/kvs"
	"log"
	"time"
)

func main() {
	db, err := kvs.Open("", "users", 2*time.Minute)
	if err != nil {
		log.Fatalf(err.Error())
	}

	db.Set("john", "23")
	db.Set("jack", "43")

	johnAge := db.Get("john")
	fmt.Println(johnAge)

	jackAge := db.Get("jack")
	fmt.Println(jackAge)

	db.Del("jack")

	jack = db.Get("jack")
	fmt.Println("Jack:", jack)

	newAge, err := db.Incr("john")
	if err != nil {
		log.Fatalf(err.Error())
	}
	fmt.Printf("John's new age is %s", newAge)

	newAge, err = db.IncrBy("john", 3)
	if err != nil {
		log.Fatalf(err.Error())
	}
	fmt.Printf("John's new age is %s\n", newAge)

	decrAge, err := db.Decr("john")
	if err != nil {
		log.Fatalf(err.Error())
	}
	fmt.Printf("John's decremented age is: %s\n", decrAge)

	decrAge, err = db.DecrBy("john", 3)
	if err != nil {
		log.Fatalf(err.Error())
	}
	fmt.Printf("John's decremented age is: %s\n", decrAge)

	exist := db.Exists("john")
	fmt.Println(exist)

	exist = db.Exists("jack")
	fmt.Println(exist)

	ok, err := db.Rename("john", "john john")
	if err != nil {
		log.Fatalf(err.Error())
	}
	fmt.Printf("key name changed: %v1\n", ok)

	keys := db.Keys()
	for _, k := range keys {
		fmt.Println(k)
	}

	err = db.Close() // Call while closing the database.
	if err != nil {
		log.Fatalf(err.Error())
	}
}

Server Usage

Server usage is so simple and short. You would call extra method, Open(), to start server. Default port is 1234 for kvs server. But, you can override it and specify another port number.

// Server runs on localhost:1234
db, _ := kvs.Create(":1234", "users", 2*time.Minute)

// The server is started
db.Open()

If you want to see full code, you can take a look /example/server/main.go. You can run this code directly without any configurations.

You can find the API Documentation from here .

Server Example

If you want to use as a server, you can just call two different functions. It creates endpoints for you.

package main

import (
	"github.com/gozeloglu/kvs"
	"log"
	"time"
)

func main() {
	db, err := kvs.Create(":1234", "users", 2*time.Minute)
	if err != nil {
		log.Fatalf(err.Error())
	}
	log.Printf("DB Created.")
	db.Open()
}

How to store data in file?

Key-value pairs store in files with .kvs extension. Data format is simple. There is = between key and value.

foo=bar
john=12
fizz=buzz

This is a sample data file.

NOTE

kvs is still under development stage, and it is created for experimental purposes.

LICENSE

MIT

Documentation

Overview

Package kvs is the in-memory key-value storage for Go. It has 2 basic features which are Get and Set. Basically, Set adds key-value pair in map and Get returns the value of the given key. If there is no such a key in map, it returns empty string.

Create Kvs object once before calling Get and Set methods:

db, _ := kvs.Create("", "users", 1*time.Minute)
db.Set("foo", "bar")
val := db.Get("foo")

Before diving into the package, you need to know that kvs package can be used in 2 different ways. As a first option, it can be used as a package that can be imported at the beginning of the code. Then, you can call the functions as above. As another way, you can create an HTTP server and call endpoints as defined in server.go. You can send requests to server as regular API call.

You can call endpoints like this:

	http://localhost:1234/set	--> POST
	Body:
	{
    	"data": [
        	{
            	"key": "joe",
            	"value": "13"
        	}
    	]
	}

	http://localhost:1234/get/joe	--> GET

	http://localhost:1234/save	--> PUT

With /set endpoint, you can add key-value pair(s) in memory, map. Multiple key-value pairs are allowed in "data" array.

With /get/<key> endpoint, you can get the value of <key>. It returns a JSON object that stores key, value, and result.

With /save endpoint, you can save the data that stores in memory to the disk. It returns result message.

Default port is assigned as :1234 for this server. Actually, it is not used for package usage, only is used for server usage.

While creating Kvs object, you need to specify database name. It is obligatory to pass it to Create function. If it is not specified, Create function returns error.

Here is the sample usage:

// Db name is "users"
db, err := kvs.Create(":1234", "users", 1*time.Minute)

// Returns error
db, err := kvs.Create(":1234", "", 1*time.Minute)

For the server usage, after creating Kvs object you need to call Open method to start server. Here is the usage:

func main() {
	db, err := kvs.Create(":1234", "users", 1*time.Minute)
	if err != nil {
		log.Fatalf(err.Error())
	}

	// Starts server on localhost:1234
	db.Open()
}

In Create function, there is third parameter named as duration. It provides saving data periodically in given interval time. For example, if you specify 2*time.Minute as parameter, the data in map would be saved every 2 minutes.

Index

• type Data
• type KeyValue
• type Kvs
  • func Create(addr string, dbName string, duration time.Duration) (*Kvs, error)
  • func (k *Kvs) Close() error
  • func (k *Kvs) Decr(key string) (string, error)
  • func (k *Kvs) DecrBy(key string, val int) (string, error)
  • func (k *Kvs) Del(key string)
  • func (k *Kvs) Exists(key string) bool
  • func (k *Kvs) Get(key string) string
  • func (k *Kvs) Incr(key string) (string, error)
  • func (k *Kvs) IncrBy(key string, val int) (string, error)
  • func (k *Kvs) Keys() []string
  • func (k *Kvs) Open()
  • func (k *Kvs) Rename(key string, newKey string) (bool, error)
  • func (k *Kvs) Set(key, value string)
• type Response

Types

type Data

type Data struct {
	Key   string `json:"key"`
	Value string `json:"value"`
}

Data is the element of array. It keeps Key and Value.

type KeyValue

type KeyValue struct {
	Data []Data `json:"data"`
}

KeyValue is used for unmarshalling JSON object in POST request.

type Kvs

type Kvs struct {

	// Addr is the server address.
	Addr string
	// contains filtered or unexported fields
}

Kvs keeps the essential variables.

func Create

func Create(addr string, dbName string, duration time.Duration) (*Kvs, error)

Create creates database and Kvs object. It creates database and returns Kvs object. If HTTP address is empty, localhost and default port is used. In contrast, dbName name needs to be specified. If it is not specified, it returns error and the database is not created. Kvs saves the data inside the map to the file periodically. User needs to specify the time interval as duration. For example, if 2*time.Minute is passed to duration parameter, the data that stores in memory, map, saves to the file.

func (*Kvs) Close

func (k *Kvs) Close() error

Close closes the file.

func (*Kvs) Decr

func (k *Kvs) Decr(key string) (string, error)

Decr decreases value of the given key by one. ıt is only applicable for integer convertable values. If the value is not able to convert integer, it error with empty string.

func (*Kvs) DecrBy

func (k *Kvs) DecrBy(key string, val int) (string, error)

DecrBy decreases the value by given value. If non-integer value is being tried to decrement, it returns error.

func (*Kvs) Del

func (k *Kvs) Del(key string)

Del deletes the key from the memory.

func (*Kvs) Exists

func (k *Kvs) Exists(key string) bool

Exists checks if the memory contains the key.

func (*Kvs) Get

func (k *Kvs) Get(key string) string

Get returns the value of the given key.

func (*Kvs) Incr

func (k *Kvs) Incr(key string) (string, error)

Incr increments value of the key by 1. It is only applicable for integer convertable values. If the value is not able to convert integer, it returns error with empty string.

func (*Kvs) IncrBy

func (k *Kvs) IncrBy(key string, val int) (string, error)

IncrBy increments the value by given value. If non-integer value is being tried to increment, it returns error.

func (*Kvs) Keys

func (k *Kvs) Keys() []string

Keys list the stored keys in a slice. If db is empty, empty slice is returned.

func (*Kvs) Open

func (k *Kvs) Open()

Open creates an HTTP connection. HTTP connection listens HTTP requests from client. Create function needs to be called before calling Open function.

func (*Kvs) Rename

func (k *Kvs) Rename(key string, newKey string) (bool, error)

Rename changes the name of the key. It deletes the old key-value pair. If the new key already exists, renaming cannot be done.

func (*Kvs) Set

func (k *Kvs) Set(key, value string)

Set assigns the value to key in map.

type Response

type Response struct {
	Key    string `json:"key"`
	Value  string `json:"value"`
	Result string `json:"result"`
}

Response is struct type for JSON response body. It is used for get and save.