riverdb

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 28, 2023 License: MIT Imports: 30 Imported by: 0

README

RiverDB

 ███████   ██                         ███████   ██████
░██░░░░██ ░░             To the moon ░██░░░░██ ░█░░░░██
░██   ░██  ██ ██    ██  █████  ██████░██    ░██░█   ░██
░███████  ░██░██   ░██ ██░░░██░░██░░█░██    ░██░██████
░██░░░██  ░██░░██ ░██ ░███████ ░██ ░ ░██    ░██░█░░░░ ██
░██  ░░██ ░██ ░░████  ░██░░░░  ░██   ░██    ██ ░█    ░██
░██   ░░██░██  ░░██   ░░██████░███   ░███████  ░███████
░░     ░░ ░░    ░░     ░░░░░░ ░░░    ░░░░░░░   ░░░░░░░

RiverDB is a light-weight embeddable key-value nosql database, it is base on bitcask model. Features as follows:

  • Using memory for data indexing
  • Using WAL to store actual data on disk
  • Support for ACID transactions
  • Support zip backup and recover from zip
  • Support data ttl
  • Support custom sorting rules
  • Support range matching and iteration
  • Support event watcher

RiverDB can be used as a standalone database or as an underlying storage engine.

The project is still under testing and stability cannot be guaranteed

install

it is a embeddable db, so you can use it in your code without network transportation.

go get -u github.com/246859/river

use

this is a simple example for use put and get operation.

import (
	"fmt"
	riverdb "github.com/246859/river"
)

func main() {
	// open the river db
	db, err := riverdb.Open(riverdb.DefaultOptions, riverdb.WithDir("riverdb"))
	if err != nil {
		panic(err)
	}
    defer db.Close()
	// put key-value pairs
	err = db.Put([]byte("key"), []byte("value"), 0)
	if err != nil {
		panic(err)
	}

	// get value from key
	value, err := db.Get([]byte("key"))
	if err != nil {
		panic(err)
	}
	fmt.Println(string(value))
}

simple use for transaction by Begin, Commit, RollBack APIs.

import (
	"errors"
	"fmt"
	riverdb "github.com/246859/river"
)

func main() {
	// open the river db
	db, err := riverdb.Open(riverdb.DefaultOptions, riverdb.WithDir("riverdb"))
	if err != nil {
		panic(err)
	}
	defer db.Close()
	txn, err := db.Begin(true)
	if err != nil {
		panic(err)
	}
	_, err = txn.Get([]byte("notfund"))
	if errors.Is(err, riverdb.ErrKeyNotFound) {
		fmt.Println("key not found")
	}else {
		txn.RollBack()
	}
	txn.Commit()
}

Remember to close db after used up.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrKeyNotFound    = errors.New("key not found")
	ErrNilKey         = entry.ErrNilKey
	ErrDBClosed       = errors.New("db is already closed")
	ErrDirAlreadyUsed = errors.New("dir already used by another process")
)
View Source 
var (
	ErrTxnClosed   = errors.New("transaction is closed")
	ErrTxnReadonly = errors.New("transaction is read-only")
	ErrTxnConflict = errors.New("transaction is conflict")
)
View Source 
var DefaultOptions = Options{
	MaxSize:        defaultMaxFileSize,
	BlockCache:     defaultMaxFileSize / file.MB,
	Fsync:          false,
	FsyncThreshold: blockSize * (defaultMaxFileSize / file.MB),
	Compare:        index.DefaultCompare,
	WatchSize:      2000,
	WatchEvents:    []EventType{PutEvent, DelEvent},
}
View Source 
var (
	ErrMergedNotFinished = errors.New("merged not finished")
)
View Source 
var (
	ErrWatcherDisabled = errors.New("event watcher disabled")
)

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 instance

func OpenWithCtx added in v0.1.0 

func OpenWithCtx(ctx context.Context, options Options, opts ...Option) (*DB, error)

OpenWithCtx returns a river db instance with context

func (*DB) Backup added in v0.1.0 

func (db *DB) Backup(destpath string) error

Backup use tar gzip to compress data wal files to dest path

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 Once the db is closed, it can no longer be used

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(domerge bool) error

Merge clean the redundant data entry in db, shrinking the db size if domerge 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) Recover added in v0.1.0 

func (db *DB) Recover(srcpath string) error

Recover recovers wal files from specified targz archive. it will purge current data, and overwrite by the backup.

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

func (*DB) Watch added in v0.1.0 

func (db *DB) Watch() (<-chan *Event, error)

type Event added in v0.1.0 

type Event struct {
	Type  EventType
	Value any
}

Event represents a push event

type EventType added in v0.1.0 

type EventType uint
const (
	PutEvent EventType = 1 + iota
	DelEvent
	RollbackEvent
	MergeEvent
	BackupEvent
	RecoverEvent
)

type Key 

type Key = []byte

Key db key type

type Mask added in v0.1.0 

type Mask uint32

Mask 32-bit mask is used to store different status information

func (*Mask) CheckAny added in v0.1.0 

func (m *Mask) CheckAny(ms ...uint32) bool

func (*Mask) CheckSome added in v0.1.0 

func (m *Mask) CheckSome(ms ...uint32) bool

func (*Mask) Remove added in v0.1.0 

func (m *Mask) Remove(ms ...uint32)

func (*Mask) Store added in v0.1.0 

func (m *Mask) Store(ms ...uint32)

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

func WithWatchEvent added in v0.1.0 

func WithWatchEvent(events ...EventType) Option

func WithWatchSize added in v0.1.0 

func WithWatchSize(size int) 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
	// kv put/get events size for watch queue, disabled if is 0
	WatchSize int
	// specified events to watch
	WatchEvents []EventType
	// 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

Source Files

View all Source files

Directories

Path Synopsis
pkg
crc
str
syncx

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.