db

Documentation

Overview

Package db is an wrapper of key-value database implementations. Currently, this supports badgerdb (https://github.com/dgraph-io/badger).

Basic Usage

You can create database using a newdb func like this

database := NewDB(BadgerImpl, "./test")

A first argument is a backend db type to use, and a second is a root directory to store db files. After creating db, you can write, read or delete single key-value using funcs in DB interface.

// write data
database.Set([]byte("key"), []byte("val"))

// read data
read := Get([]byte("key"))

// delete data
database.Delete([]byte("key"))

Transaction

A Transaction is a bulk set of operations to ensure atomic success or fail.

// create a new transaction
tx := database.NewTX(true)

// reserve writing
tx.Set([]byte("keyA"), []byte("valA"))
tx.Set([]byte("keyB"), []byte("valB"))

// Get will return a value reserved to write in this transaction
mustBeValA := tx.Get([]byte("keyA"))

// Perform writing
tx.Commit()

If you want to cancel and discard operations in tx, then you must call Discard() func to prevent a memory leack

// If you create a tx, but do not commit, than you have to call this
tx.Discard()

Iterator

An iteractor provides a way to get all keys sequentially.

 // create an iterator that covers all range
 for iter := database.Iterator(nil, nil); iter.Valid(); iter.Next() {
	 // print each key-value pair
	 fmt.Printf("%s = %s", string(iter.Key()), string(iter.Value()))
 }

You can find more detail usages at a db_test.go file

Index

• type Bulk
• type DB
  • func NewBadgerDB(dir string) (DB, error)
  • func NewDB(dbimpltype ImplType, dir string) DB
  • func NewLevelDB(dir string) (DB, error)
  • func NewMemoryDB(dir string) (DB, error)
• type ImplType
• type Iterator
• type Transaction

Types

type Bulk

type Bulk interface {
	Set(key, value []byte)
	Delete(key []byte)
	Flush()
	DiscardLast()
}

Bulk is used to batch multiple transactions This will internally commit transactions when reach maximum tx size

type DB

type DB interface {
	Type() string
	Set(key, value []byte)
	Delete(key []byte)
	Get(key []byte) []byte
	Exist(key []byte) bool
	Iterator(start, end []byte) Iterator
	NewTx() Transaction
	NewBulk() Bulk
	Close()
}

DB is an general interface to access at storage data

func NewBadgerDB

func NewBadgerDB(dir string) (DB, error)

NewBadgerDB create a DB instance that uses badger db and implements DB interface. An input parameter, dir, is a root directory to store db files.

func NewDB

func NewDB(dbimpltype ImplType, dir string) DB

NewDB creates new database or load existing database in the directory

func NewLevelDB

func NewLevelDB(dir string) (DB, error)

func NewMemoryDB

func NewMemoryDB(dir string) (DB, error)

type ImplType

type ImplType string

ImplType represents implementators of a DB interface

const (
	// BadgerImpl represents a name of DB interface implementation using badgerdb
	BadgerImpl ImplType = "badgerdb"

	// LevelImpl represents a name of DB interface implementation using leveldb
	LevelImpl ImplType = "leveldb"

	// MemoryImpl represents a name of DB interface implementation in memory
	MemoryImpl ImplType = "memorydb"
)

type Iterator

type Iterator interface {
	Next()
	Valid() bool
	Key() []byte
	Value() []byte
}

Iterator is used to navigate specific key ranges

type Transaction

type Transaction interface {
	//	Get(key []byte) []byte
	Set(key, value []byte)
	Delete(key []byte)
	Commit()
	Discard()
}

Transaction is used to batch multiple operations