riverdb

README

river

light-weight kv database base on bitcask

Documentation

Index

• Variables
• func FastRand() uint32
• type DB
  • func Open(options Options, opts ...Option) (*DB, error)
  • func (db *DB) Begin(readonly bool) (*Txn, error)
  • func (db *DB) Close() error
  • func (db *DB) Del(key Key) error
  • func (db *DB) Expire(key Key, ttl time.Duration) error
  • func (db *DB) Get(key Key) (Value, error)
  • func (db *DB) Merge(transfer bool) error
  • func (db *DB) Purge() error
  • func (db *DB) Put(key Key, value Value, ttl time.Duration) error
  • func (db *DB) Range(option RangeOptions, handler RangeHandler) error
  • func (db *DB) Sync() error
  • func (db *DB) TTL(key Key) (time.Duration, error)
• type Key
• type Option
  • func WithBlockCache(block uint32) Option
  • func WithClosedGc(gc bool) Option
  • func WithCompare(compare index.Compare) Option
  • func WithDir(dir string) Option
  • func WithFsync(sync bool) Option
  • func WithFsyncThreshold(threshold int64) Option
  • func WithMaxSize(size int64) Option
• type Options
• type RangeHandler
• type RangeOptions
• type Txn
  • func (txn *Txn) Commit() error
  • func (txn *Txn) Del(key Key) error
  • func (txn *Txn) Expire(key Key, ttl time.Duration) error
  • func (txn *Txn) Get(key Key) (Value, error)
  • func (txn *Txn) Put(key Key, value Value, ttl time.Duration) error
  • func (txn *Txn) Range(opt RangeOptions, handler RangeHandler) error
  • func (txn *Txn) RollBack() error
  • func (txn *Txn) TTL(key Key) (time.Duration, error)
• type Value

Variables

var (
	ErrKeyNotFound    = errors.New("key not found")
	ErrNilKey         = entry.ErrNilKey
	ErrDBClosed       = errors.New("db is already closed")
	ErrDBMerging      = errors.New("db is merging data")
	ErrDirAlreadyUsed = errors.New("dir already used by another process")
)

var (
	ErrTxnClosed   = errors.New("transaction is closed")
	ErrTxnReadonly = errors.New("transaction is read-only")
	ErrTxnConflict = errors.New("transaction is conflict")
)

var DefaultOptions = Options{
	MaxSize:        defaultMaxFileSize,
	BlockCache:     defaultMaxFileSize / file.MB,
	Fsync:          false,
	FsyncThreshold: blockSize * (defaultMaxFileSize / file.MB),
	Compare:        index.DefaultCompare,
}

var (
	ErrMergedNotFinished = errors.New("merged not finished")
)

Functions

func FastRand

func FastRand() uint32

FastRand is a fast thread local random function.

Types

type DB

type DB struct {
	// contains filtered or unexported fields
}

DB represents a db instance, which stores wal file in a specific data directory

func Open

func Open(options Options, opts ...Option) (*DB, error)

Open returns a river db database

func (*DB) Begin

func (db *DB) Begin(readonly bool) (*Txn, error)

Begin begins a new transaction

func (*DB) Close

func (db *DB) Close() error

Close closes db

func (*DB) Del

func (db *DB) Del(key Key) error

Del remove the key-value pair match the give key from db. it will return nil if key not exist

func (*DB) Expire

func (db *DB) Expire(key Key, ttl time.Duration) error

Expire update ttl of the specified key if ttl <= 0, the key will never expired

func (*DB) Get

func (db *DB) Get(key Key) (Value, error)

Get returns value match the given key

func (*DB) Merge

func (db *DB) Merge(transfer bool) error

Merge clean the redundant data entry in db, shrinking the db size if transfer is false, it will only record of merged data, will not replace them to data dir

func (*DB) Purge

func (db *DB) Purge() error

Purge remove all entries from data wal

func (*DB) Put

func (db *DB) Put(key Key, value Value, ttl time.Duration) error

Put puts a key-value pair into db, overwrite value if key already exists. nil key is invalid, but nil value is allowed. if tll == 0, key will be persisted, or ttl < 0, key will apply the previous ttl.

func (*DB) Range

func (db *DB) Range(option RangeOptions, handler RangeHandler) error

Range iterates over all the keys that match the given RangeOption and call handler for each key-value

func (*DB) Sync

func (db *DB) Sync() error

Sync syncs written buffer to disk

func (*DB) TTL

func (db *DB) TTL(key Key) (time.Duration, error)

TTL returns left live time of the specified key

type Key

type Key = []byte

Key db key type

type Option

type Option func(option *Options)

Option applying changes to the given option

func WithBlockCache

func WithBlockCache(block uint32) Option

func WithClosedGc

func WithClosedGc(gc bool) Option

func WithCompare

func WithCompare(compare index.Compare) Option

func WithDir

func WithDir(dir string) Option

func WithFsync

func WithFsync(sync bool) Option

func WithFsyncThreshold

func WithFsyncThreshold(threshold int64) Option

func WithMaxSize

func WithMaxSize(size int64) Option

type Options

type Options struct {
	// data dir that stores data files
	Dir string
	// max bytes size of the single data file can hold
	MaxSize int64
	// wal block cache size
	BlockCache uint32
	// call sync per write
	Fsync bool
	// call sync when reach the threshold
	FsyncThreshold int64
	// decide how to sort keys
	Compare index.Compare
	// manually gc after closed db
	ClosedGc bool
	// contains filtered or unexported fields
}

Options represent db configuration

type RangeHandler

type RangeHandler = func(key Key) bool

RangeHandler iterate over key-value in db

type RangeOptions

type RangeOptions = index.RangeOption

type Txn

type Txn struct {
	// contains filtered or unexported fields
}

Txn represents a transaction

func (*Txn) Commit

func (txn *Txn) Commit() error

func (*Txn) Del

func (txn *Txn) Del(key Key) error

func (*Txn) Expire

func (txn *Txn) Expire(key Key, ttl time.Duration) error

func (*Txn) Get

func (txn *Txn) Get(key Key) (Value, error)

func (*Txn) Put

func (txn *Txn) Put(key Key, value Value, ttl time.Duration) error

func (*Txn) Range

func (txn *Txn) Range(opt RangeOptions, handler RangeHandler) error

func (*Txn) RollBack

func (txn *Txn) RollBack() error

func (*Txn) TTL

func (txn *Txn) TTL(key Key) (time.Duration, error)

type Value

type Value = []byte

Value db value type