kvdb

package module
v0.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 4, 2024 License: MIT Imports: 10 Imported by: 0

README

Overview

kvdb is an in-memory key-value store written in the Go programming language.

It uses a simple client-server model and is designed to be easy to use. It can be used as a database, session storage, or cache. It may not be suitable for complex needs.

Data is stored at keys of different types. You can store data ranging from basic string values to large objects.

Instances are easily configurable with environment variables and a simple YAML file.

Components:

  • kvdbserver - The server process
  • kvdb-cli - CLI tool to manage the server

Note! This project is in early development.

Data types

Currently supported data types:

  • String
  • HashMap

Documentation

Releases

Release notes are available here.

Binaries are available for download. Multiple platforms supported. You can download them here.

However, it is recommended to build the binaries from source. Instructions on how to build from source below.

Releases are managed with GoReleaser.

Build binaries

To build the binaries, you first need to install Go. Minimum version required is go1.22.

Instructions for installing Go can be found here.

You may also need tools to work with gRPC and Protocol Buffers in Go. This is needed if you want to compile .proto files and generate Go code.

If you just want to compile the binaries then installing only Go is enough.

After you have successfully installed go, clone this repository.

Cloning with git:

git clone https://github.com/hollowdll/kvdb.git

Note: You can also download the source code for a specific release here.

Change directory to the project root:

cd kvdb

Get the dependencies:

go mod tidy

Build the server:

go build -o ./bin/kvdbserver/ ./cmd/kvdbserver/

Build the CLI:

go build -o ./bin/kvdb-cli/ ./cmd/kvdb-cli/

These will build the binaries to bin/ directory in the project root. You can change the output directory and binary names to whatever you like by modifying the path with -o flag.

For more advanced build, use go help build to see more build options.

Docker

Images are available in Docker Hub with multiple tags. Links below.

Pull the server image

docker pull hakj/kvdb

Build the server image

Make sure to be in the project root

cd kvdb

Latest tag

docker build -f "./Dockerfile.bookworm" -t kvdb:latest .

Debian based image

docker build -f "./Dockerfile.bookworm" -t kvdb:bookworm .

Alpine Linux based image

docker build -f "./Dockerfile.alpine" -t kvdb:alpine .

These commands build the image only for a single architecture. If you want to build multi-arch images for other platforms, read this.

Start a container

Example of starting a container

docker run -p 12345:12345 --rm -it kvdb

This binds the host's port 12345 to the container's port 12345 so you can access the server outside the container.

Running tests

Change directory to the project root:

cd kvdb

Run all tests:

go test ./...

Run only integration tests:

go test ./tests/integration

Integration test environment variables

Integration test environment is configurable. Below is a list of environment variables that can be used when running integration tests.

  • KVDB_PORT: Test server TCP/IP port. Default port is 12345.
  • KVDB_HOST: Test server address. The test client will try to connect to this. Default address is localhost.

License

This project is licensed under MIT license. It is free and open source software.

Documentation

Index

Constants

View Source 
const (
	// DbNameMaxSize is the maximum length of a database name in bytes.
	DbNameMaxSize int = 64
	// DbKeyMaxSize is the maximum length of a database key in bytes.
	DbKeyMaxSize int = 1024
)

Variables

This section is empty.

Functions

func ValidateDatabaseKey added in v0.7.1 

func ValidateDatabaseKey(key DatabaseKey) error

ValidateDatabaseKey validates database key. Returns error if validation error is matched.

func ValidateDatabaseName added in v0.7.1 

func ValidateDatabaseName(name string) error

ValidateDatabaseName validates database name. Returns error if validation error is matched.

Types

type Database 

type Database struct {
	// The name of the database.
	Name string
	// UTC timestamp describing when the database was created.
	CreatedAt time.Time
	// UTC timestamp describing when the database was updated.
	UpdatedAt time.Time
	// contains filtered or unexported fields
}

Database containing key-value pairs of data.

func CreateDatabase 

func CreateDatabase(name string) *Database

CreateDatabase creates a new database with a name.

func (*Database) DeleteAllKeys added in v0.5.0 

func (db *Database) DeleteAllKeys()

DeleteAllKeys deletes all the keys.

func (*Database) DeleteHashMapFields added in v0.8.0 

func (db *Database) DeleteHashMapFields(key DatabaseKey, fields []string) (uint32, bool)

DeleteHashMapFields removes fields from a HashMap using a key. Returns the number of removed fields. The returned bool is true if the key exists and holds a HashMap.

func (*Database) DeleteKey 

func (db *Database) DeleteKey(key DatabaseKey) bool

DeleteKey deletes a key and the value it is holding. Returns true if the key exists and it was deleted. Returns false if the key doesn't exist.

func (*Database) GetAllHashMapFieldsAndValues added in v0.9.0 

func (db *Database) GetAllHashMapFieldsAndValues(key DatabaseKey) (map[string]string, bool)

GetAllHashMapFieldsAndValues returns all the fields and values of a HashMap. The returned map is empty if the key doesn't exist. The returned bool is true if the key exists and holds a HashMap.

func (*Database) GetHashMapFieldValue added in v0.7.0 

func (db *Database) GetHashMapFieldValue(key DatabaseKey, field string) (string, bool)

GetHashMapFieldValue returns a single HashMap field value using a key. The returned bool is true if the field exists in the HashMap, or false if the key or field doesn't exist.

func (*Database) GetKeyCount 

func (db *Database) GetKeyCount() uint32

GetKeyCount returns the number of keys in the database.

func (*Database) GetKeys added in v0.5.0 

func (db *Database) GetKeys() []string

GetKeys returns all the keys.

func (*Database) GetName 

func (db *Database) GetName() string

GetName returns the name of the database.

func (*Database) GetStoredSizeBytes 

func (db *Database) GetStoredSizeBytes() uint64

GetStoredSizeBytes returns the size of stored data in bytes.

func (*Database) GetString 

func (db *Database) GetString(key DatabaseKey) (DatabaseStringValue, bool)

GetString retrieves a string value using a key. The returned bool is true if the key exists.

func (*Database) GetTypeOfKey added in v0.8.0 

func (db *Database) GetTypeOfKey(key DatabaseKey) (string, bool)

GetTypeOfKey returns the data type of the key if it exists. The returned bool is true if the key exists and false if it doesn't.

func (*Database) SetHashMap added in v0.7.0 

func (db *Database) SetHashMap(key DatabaseKey, fields map[string]string)

SetHashMap sets fields in a HashMap value using a key, overwriting previous fields. Creates the key if it doesn't exist.

func (*Database) SetString 

func (db *Database) SetString(key DatabaseKey, value DatabaseStringValue)

SetString sets a string value using a key, overwriting previous value. Creates the key if it doesn't exist.

type DatabaseKey 

type DatabaseKey string

DatabaseKey represents key-value pair key. Key is stored as string.

type DatabaseStringValue 

type DatabaseStringValue string

DatabaseStringValue represents key-value pair string value. Value is stored as string.

type DefaultLogger 

type DefaultLogger struct {
	Logger     *log.Logger
	FileLogger *log.Logger
	// contains filtered or unexported fields
}

DefaultLogger is a default implementation of the Logger interface. Log output defaults to standard error stream. Debug logs are disabled by default. Call EnableDebug to enable them.

func NewDefaultLogger 

func NewDefaultLogger() *DefaultLogger

func (*DefaultLogger) ClearFlags 

func (l *DefaultLogger) ClearFlags()

func (*DefaultLogger) CloseLogFile added in v0.6.0 

func (l *DefaultLogger) CloseLogFile() error

func (*DefaultLogger) Debug 

func (l *DefaultLogger) Debug(v ...any)

func (*DefaultLogger) Debugf 

func (l *DefaultLogger) Debugf(format string, v ...any)

func (*DefaultLogger) Disable 

func (l *DefaultLogger) Disable()

func (*DefaultLogger) EnableDebug 

func (l *DefaultLogger) EnableDebug()

func (*DefaultLogger) EnableLogFile added in v0.6.0 

func (l *DefaultLogger) EnableLogFile(filePath string) error

func (*DefaultLogger) Error 

func (l *DefaultLogger) Error(v ...any)

func (*DefaultLogger) Errorf 

func (l *DefaultLogger) Errorf(format string, v ...any)

func (*DefaultLogger) Fatal 

func (l *DefaultLogger) Fatal(v ...any)

func (*DefaultLogger) Fatalf 

func (l *DefaultLogger) Fatalf(format string, v ...any)

func (*DefaultLogger) Info 

func (l *DefaultLogger) Info(v ...any)

func (*DefaultLogger) Infof 

func (l *DefaultLogger) Infof(format string, v ...any)

func (*DefaultLogger) Warning 

func (l *DefaultLogger) Warning(v ...any)

func (*DefaultLogger) Warningf 

func (l *DefaultLogger) Warningf(format string, v ...any)

type Logger 

type Logger interface {
	Debug(v ...any)
	Debugf(format string, v ...any)

	Info(v ...any)
	Infof(format string, v ...any)

	Error(v ...any)
	Errorf(format string, v ...any)

	Warning(v ...any)
	Warningf(format string, v ...any)

	Fatal(v ...any)
	Fatalf(format string, v ...any)

	// EnableDebug enables debug logs.
	EnableDebug()
	// EnableLogFile enables log file.
	EnableLogFile(filePath string) error
	// CloseLogFile closes the log file for I/O operations.
	CloseLogFile() error
	// ClearFlags clears all default logger output flags.
	ClearFlags()
	// Disable disables all log outputs.
	Disable()
}

Source Files

View all Source files

Directories

Path Synopsis
cmd
kvdb-cli
kvdb-cli/client
kvdb-cli/cmd
kvdb-cli/cmd/connect
kvdb-cli/cmd/db
kvdb-cli/cmd/hashmap
kvdb-cli/config
kvdbserver
kvdbserver/server
internal
common
kvdbtesting
proto
kvdbserver

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.