kvstore

A simple, lightweight Go wrapper for key-value storage, powered by BadgerDB.

Features

• 🚀 Simple and intuitive API
• 💾 Persistent embedded storage
• 🔒 ACID transactions
• ⚡ High performance (backed by BadgerDB)
• 🔄 Built-in CRUD operations
• 📦 Easy store management (move, copy, drop)

Quick Start

package main

import (
    "fmt"
    "log"

    "github.com/PLabInitDev/kvstore"
)

func main() {
    // Create or open a store
    store, err := kvstore.New(kvstore.Options{Name: "my_database"})
    if err != nil {
        log.Fatal(err)
    }

    // Create an item
    item := store.Item([]byte("username"), []byte("john_doe"))
    if err := item.Create(); err != nil {
        log.Fatal(err)
    }

    // Retrieve an item
    retrieved, err := store.GetItem([]byte("username"))
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(string(retrieved.GetValue())) // Output: john_doe

    // Update an item
    if err := retrieved.Update([]byte("jane_doe")); err != nil {
        log.Fatal(err)
    }

    // Delete an item
    if err := retrieved.Delete(); err != nil {
        log.Fatal(err)
    }
}

Usage

Creating a Store

// Basic store (stored in home directory)
store, err := kvstore.New(kvstore.Options{Name: "my_db"})

// Store with custom path
store, err := kvstore.New(kvstore.Options{
    Name: "my_db",
    Path: "/path/to/storage",
})

// Store with custom BadgerDB options
badgerOpts := badger.DefaultOptions("")
store, err := kvstore.New(kvstore.Options{
    Name: "my_db",
    BadgerOptions: &badgerOpts,
})

CRUD Operations

Create

Creates a new item. Returns an error if the key already exists.

item := store.Item([]byte("key"), []byte("value"))
err := item.Create()

Read

Retrieves an item by key.

item, err := store.GetItem([]byte("key"))
if err != nil {
    // Handle error (key not found, etc.)
}
value := item.GetValue()

Update

Updates an existing item. Returns an error if the key doesn't exist.

item, _ := store.GetItem([]byte("key"))
err := item.Update([]byte("new_value"))

Upsert

Creates a new item or updates an existing one (no error if key exists).

item := store.Item([]byte("key"), []byte("value"))
err := item.Upsert()

Delete

// Method 1: Delete via item
item, _ := store.GetItem([]byte("key"))
err := item.Delete()

// Method 2: Delete directly from store
err := store.DeleteItem([]byte("key"))

Store Management

Check if Store Exists

exists, err := store.Exists()

Drop (Delete) a Store

Closes and permanently deletes the store from the filesystem.

err := store.Drop()

Move a Store

Moves the store to a new path. Blocks pending operations until complete.

err := store.Move("/new/path/to/store")

Copy a Store

Creates a backup copy at a new location. Doesn't block CRUD operations.

err := store.Copy("/backup/path/to/store")

Error Handling

The package provides specific error types for better error handling:

• KeyAlreadyExistsError - Key already exists (use Update() or Upsert())
• KeyNotFoundError - Key doesn't exist in the store
• TransactionConflictError - Concurrent update conflict
• EmptyKeyError - Key is empty or nil
• CopyInProgressError - Copy operation already in progress

item := store.Item([]byte("key"), []byte("value"))
if err := item.Create(); err != nil {
    switch err.(type) {
    case *kvstore.KeyAlreadyExistsError:
        // Handle duplicate key
    case *kvstore.EmptyKeyError:
        // Handle empty key
    default:
        // Handle other errors
    }
}

Testing

Run the test suite:

go test ./...

Examples

Check out the samples directory for complete examples:

• CRUD Sample - Demonstrates basic CRUD operations

API Reference

Store Interface

type Store interface {
    GetItem(key []byte) (Item, error)
    DeleteItem(key []byte) error
    Item(key []byte, value []byte) Item
    Exists() (bool, error)
    Drop() error
    Move(newPath string) error
    Copy(newPath string) error
}

Item Interface

type Item interface {
    GetValue() []byte
    GetKey() []byte
    Create() error
    Upsert() error
    Update(newValue []byte) error
    Delete() error
}

Requirements

• Go 1.18 or higher

License

This project uses BadgerDB as its underlying storage engine. Please refer to BadgerDB's license for details.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Acknowledgments

Built on top of BadgerDB - a fast key-value DB written in Go.