s3kv

S3KV

A lightweight wrapper around the S3 protocol that lets you use any S3-compatible storage as a simple yet powerful key-value database.

Available as:

• Library — embed s3kv directly into your Go application.
• HTTP Service — run it as a standalone service with a REST API, Binary and Docker Image

Features:

• List databases
• Remove database
• List keys
• Check key exists
• Get key
• Set key (single key transactions)
• Remove key
• Watch key

Library

Create connection

package main

import (
	"context"

	"github.com/0xB1a60/s3kv/pkg/s3kv"
)

func main() {
	s3kvConn, err := s3kv.New("s3.us-east-1.amazonaws.com",
		s3kv.WithAccessSecretKey("access-key", "secret-key"))
	if err != nil {
		//
	}
}

List databases

databases, err := s3kvConn.ListDatabase(context.Background())
if err != nil {
	//
}

Open database

database, err := s3kvConn.Database(context.Background(), "repositories")
if err != nil {
	//
}

Remove database

err := s3kvConn.RemoveDatabase(context.Background(), "repositories")
if err != nil { 
	//
}

List keys

keys, err := database.ListKeys(context.Background())
if err != nil {
	//
}

Exist key

version, err := database.Exist(context.Background(), "s3kv")
if err != nil {
	//
}

Get key

getRes, err := database.Get(context.Background(), "s3kv")
if err != nil {
    //
}

Watch key

watchCh := database.Watch(context.Background(), "s3kv", time.Second*15)

Set key

setRes, err := database.Set(context.Background(), "s3kv", []byte("https://github.com/0xB1a60/s3kv"))
if err != nil {
	//
}

Remove key

err := database.Remove(context.Background(), "s3kv")
if err != nil {
	//
}

HTTP Service

Start the HTTP service and local minio server:

docker compose up

Swagger docs are available at http://0.0.0.0:9999/swagger/index.html

List databases

curl http://0.0.0.0:9999/list/databases

List keys

curl http://0.0.0.0:9999/list/keys/docs

Exist key

curl --head http://0.0.0.0:9999/repositories/s3kv

Get key

curl http://0.0.0.0:9999/repositories/s3kv

Watch key

curl -X DELETE http://0.0.0.0:9999/repositories/s3kv

Set key

curl -X POST -H "Content-Type: application/json" -d 'https://github.com/0xB1a60/s3kv' http://0.0.0.0:9999/repositories/s3kv

Remove key

curl -X DELETE http://0.0.0.0:9999/repositories/s3kv

Remove database

curl -X DELETE http://0.0.0.0:9999/repositories

Limitations

• Database name length between 1 and 50 characters
• Key length between 1 and 1024 characters
• Value size between 1 byte and 5GB