kv

README

Charm KV

Example

package main

import (
	"fmt"

	"github.com/charmbracelet/charm/kv"
	"github.com/dgraph-io/badger/v3"
)

func main() {
	// Open a kv store with the name "charm.sh.test.db" and local path ./db
	db, err := kv.OpenWithDefaults("charm.sh.test.db")
	if err != nil {
		panic(err)
	}

	// Get the latest updates from the Charm Cloud
	db.Sync()

	// Quickly set a value
	err = db.Set([]byte("dog"), []byte("food"))
	if err != nil {
		panic(err)
	}

	// Quickly get a value
	v, err := db.Get([]byte("dog"))
	if err != nil {
		panic(err)
	}
	fmt.Printf("got value: %s\n", string(v))

	// Go full-blown Badger and use transactions to list values and keys
	db.View(func(txn *badger.Txn) error {
		opts := badger.DefaultIteratorOptions
		opts.PrefetchSize = 10
		it := txn.NewIterator(opts)
		defer it.Close() //nolint:errcheck
		for it.Rewind(); it.Valid(); it.Next() {
			item := it.Item()
			k := item.Key()
			err := item.Value(func(v []byte) error {
				fmt.Printf("%s - %s\n", k, v)
				return nil
			})
			if err != nil {
				panic(err)
			}
		}
		return nil
	})
}

Deleting a Database

1. Find the database in charm fs ls /
2. Delete the database with charm fs rm db-name
3. Locate the local copy of the database. To see where your charm-related data lives, run charm to start up with GUI, then select Backup
4. Run rm ~/path/to/cloud.charm.sh/kv/db-name to remove the local copy of your charm-kv database

Documentation

Overview

Package kv provides a Charm Cloud backed BadgerDB.

Index

• func OptionsWithEncryption(opt badger.Options, encKey []byte, cacheSize int64) (badger.Options, error)
• type KV
  • func Open(cc *client.Client, name string, opt badger.Options) (*KV, error)
  • func OpenWithDefaults(name string) (*KV, error)
  • func (kv *KV) Client() *client.Client
  • func (kv *KV) Close() error
  • func (kv *KV) Commit(txn *badger.Txn, callback func(error)) error
  • func (kv *KV) Delete(key []byte) error
  • func (kv *KV) Get(key []byte) ([]byte, error)
  • func (kv *KV) Keys() ([][]byte, error)
  • func (kv *KV) NewStream() *badger.Stream
  • func (kv *KV) NewTransaction(update bool) (*badger.Txn, error)
  • func (kv *KV) Reset() error
  • func (kv *KV) Set(key []byte, value []byte) error
  • func (kv *KV) SetReader(key []byte, value io.Reader) error
  • func (kv *KV) Sync() error
  • func (kv *KV) View(fn func(txn *badger.Txn) error) error

Functions

func OptionsWithEncryption

func OptionsWithEncryption(opt badger.Options, encKey []byte, cacheSize int64) (badger.Options, error)

OptionsWithEncryption returns badger.Options with all required encryption settings enabled for a given encryption key.

Types

type KV

type KV struct {
	DB *badger.DB
	// contains filtered or unexported fields
}

KV provides a Charm Cloud backed BadgerDB key-value store.

KV supports regular Badger transactions, and backs up the data to the Charm Cloud. It will allow for syncing across machines linked with a Charm account. All data is encrypted by Badger on the local disk using a Charm user's encryption keys. Diffs are also encrypted locally before being synced to the Charm Cloud.

func Open

func Open(cc *client.Client, name string, opt badger.Options) (*KV, error)

Open a Charm Cloud managed Badger DB instance with badger.Options and *client.Client.

func OpenWithDefaults

func OpenWithDefaults(name string) (*KV, error)

OpenWithDefaults opens a Charm Cloud managed Badger DB instance with the default settings pulled from environment variables.

func (*KV) Client

func (kv *KV) Client() *client.Client

Client returns the underlying *client.Client.

func (*KV) Close

func (kv *KV) Close() error

Close closes the underlying Badger DB.

func (*KV) Commit

func (kv *KV) Commit(txn *badger.Txn, callback func(error)) error

Commit commits a *badger.Txn and syncs the diff to the Charm Cloud.

func (*KV) Delete

func (kv *KV) Delete(key []byte) error

Delete is a convenience method for deleting a value from the key value store.

func (*KV) Get

func (kv *KV) Get(key []byte) ([]byte, error)

Get is a convenience method for getting a value from the key value store.

func (*KV) Keys

func (kv *KV) Keys() ([][]byte, error)

Keys returns a list of all keys for this key value store.

func (*KV) NewStream

func (kv *KV) NewStream() *badger.Stream

NewStream returns a new *badger.Stream from the underlying Badger DB.

func (*KV) NewTransaction

func (kv *KV) NewTransaction(update bool) (*badger.Txn, error)

NewTransaction creates a new *badger.Txn with a Charm Cloud managed timestamp.

func (*KV) Reset

func (kv *KV) Reset() error

Reset deletes the local copy of the Badger DB and rebuilds with a fresh sync from the Charm Cloud.

func (*KV) Set

func (kv *KV) Set(key []byte, value []byte) error

Set is a convenience method for setting a key and value. It creates and commits a new transaction for the update.

func (*KV) SetReader

func (kv *KV) SetReader(key []byte, value io.Reader) error

SetReader is a convenience method to set the value for a key to the data read from the provided io.Reader.

func (*KV) Sync

func (kv *KV) Sync() error

Sync synchronizes the local Badger DB with any updates from the Charm Cloud.

func (*KV) View

func (kv *KV) View(fn func(txn *badger.Txn) error) error

View wraps the View() method for the underlying Badger DB.