https://github.com/kostya-zero/kvdb
Lightweight key‑value store written in Go.
https://github.com/kostya-zero/kvdb
Last synced: about 1 year ago
JSON representation
Lightweight key‑value store written in Go.
- Host: GitHub
- URL: https://github.com/kostya-zero/kvdb
- Owner: kostya-zero
- License: mit
- Created: 2025-04-16T04:23:31.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-07-19T12:21:51.000Z (about 1 year ago)
- Last Synced: 2025-07-19T16:56:18.559Z (about 1 year ago)
- Language: Go
- Homepage:
- Size: 68.4 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# `KVDB`
KVDB is a lightweight key‑value store written in Go. It keeps data in
named maps so multiple services can share a single server without clobbering
each other's keys. The server exposes a plain TCP protocol and can optionally
persist all updates to a file.
## Installation
#### GitHub Releases
Download an archive from [GitHub Releases]("https://github.com/kostya-zero/kvdb/releases") and extract the KVDB binary
to directory that is added to `PATH`.
#### Docker
Clone this repository and use Docker CLI to build and run container.
```shell
docker build -t kvdb .
docker run -p 5511:5511 kvdb
```
## Usage
Run the server with the `serve` command.
```shell
kvdb serve
```
All options for KVDB should be provided as environment variables. Available variables:
- `KVDB_PORT` - TCP port to bind to (default `5511`).
- `KVDB_DATABASE` - path to the database file. When omitted, data is kept in memory only.
- `KVDB_SAVE_INTERVAL` - the save interval in milliseconds. After this time, KVDB will run save if it is needed.
Examples:
```shell
# Start with defaults (port 5511, in-memory database)
kvdb serve
# Persist data to kvdb.db and expose on custom port
export KVDB_PORT=7777
export KVDB_DATABASE/var/lib/kvdb/kvdb.db
kvdb serve
```
## API overview
The server communicates over plain TCP.
Each request is a single line command and the response is a text string.
Thebasic commands are:
- `CREATEDB ` – create a new database map.
- `REMOVE DB ` – remove a database.
- `REMOVE KEY .` – delete a key.
- `SET . ""` – add a new key with value.
- `GET .` – return the value for a key.
- `UPDATE . ""` – replace the current value.
Responses are either `OK` or one of the following error codes: `ALREADY_EXISTS`, `DATABASE_NOT_FOUND`, `KEY_NOT_FOUND`,
`KEY_NOT_PROVIDED`, `ILLEGAL_CHARACTERS`, or `BAD_QUERY`.
You can test the server with tools like `nc`:
```shell
$ nc 127.0.0.1 5511
CREATEDB users
SET users.alice "alice@example.com"
GET users.alice
```
## License
KVDB is licensed under MIT License. Learn more in [LICENSE](LICENSE) file.