pogreb

README

Pogreb

Pogreb is an embedded key-only store for read-heavy workloads written in Go.

Key characteristics

• 100% Go.
• Optimized for fast random lookups and infrequent bulk inserts.
• Can store larger-than-memory data sets.
• Low memory usage.
• All DB methods are safe for concurrent use by multiple goroutines.

Installation

$ go get -u github.com/domaincrawler/pogreb

Usage

Opening a database

To open or create a new database, use the pogreb.Open() function:

package main

import (
	"log"

	"github.com/domaincrawler/pogreb"
)

func main() {
    db, err := pogreb.Open("pogreb.test", nil)
    if err != nil {
        log.Fatal(err)
        return
    }	
    defer db.Close()
}

Writing to a database

Use the DB.Put() function to insert a new key:

err := db.Put([]byte("testKey"))
if err != nil {
	log.Fatal(err)
}

Reading from a database

To retrieve the inserted value, use the DB.Has() function:

val, err := db.Has([]byte("testKey"))
if err != nil {
	log.Fatal(err)
}
log.Println(val)

Iterating over items

To iterate over items, use ItemIterator returned by DB.Items():

it := db.Items()
for {
    key, err := it.Next()
    if err == pogreb.ErrIterationDone {
    	break
    }
    if err != nil { 
        log.Fatal(err)
    }
    log.Printf("%s", key)
}

Documentation

Overview

Package pogreb implements an embedded key-value store for read-heavy workloads.

Example

package main

import (
	"log"

	"github.com/domaincrawler/pogreb"
)

func main() {
	db, err := pogreb.Open("pogreb.test", nil)
	if err != nil {
		log.Fatal(err)
		return
	}
	defer db.Close()

	// Insert a new key-value pair.
	if err := db.Put([]byte("testKey")); err != nil {
		log.Fatal(err)
	}

	// Retrieve the inserted value.
	val, err := db.Has([]byte("testKey"))
	if err != nil {
		log.Fatal(err)
	}
	log.Println(val)

	// Iterate over items.
	it := db.Items()
	for {
		key, err := it.Next()
		if err == pogreb.ErrIterationDone {
			break
		}
		if err != nil {
			log.Fatal(err)
		}
		log.Printf("%s", key)
	}
}

Index

• Constants
• Variables
• func SetLogger(l *log.Logger)
• type CompactionResult
• type DB
  • func Open(path string, opts *Options) (*DB, error)
  • func (db *DB) Close() error
  • func (db *DB) Compact() (CompactionResult, error)
  • func (db *DB) Count() uint32
  • func (db *DB) FileSize() (int64, error)
  • func (db *DB) Has(key []byte) (bool, error)
  • func (db *DB) HasOrPut(key []byte) (bool, error)
  • func (db *DB) Items() *ItemIterator
  • func (db *DB) Metrics() *Metrics
  • func (db *DB) Put(key []byte) error
  • func (db *DB) Sync() error
• type ItemIterator
  • func (it *ItemIterator) Next() ([]byte, error)
• type Metrics
• type Options

Examples

• Package

Constants

const (
	// MaxKeyLength is the maximum size of a key in bytes.
	MaxKeyLength = math.MaxUint16

	// MaxKeys is the maximum numbers of keys in the DB.
	MaxKeys = math.MaxUint32
)

Variables

var ErrIterationDone = errors.New("no more items in iterator")

ErrIterationDone is returned by ItemIterator.Next calls when there are no more items to return.

Functions

func SetLogger

func SetLogger(l *log.Logger)

SetLogger sets the global logger.

Types

type CompactionResult

type CompactionResult struct {
	CompactedSegments int
	ReclaimedRecords  int
	ReclaimedBytes    int
}

CompactionResult holds the compaction result.

type DB

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

DB represents the key-only storage. All DB methods are safe for concurrent use by multiple goroutines.

func Open

func Open(path string, opts *Options) (*DB, error)

Open opens or creates a new DB. The DB must be closed after use, by calling Close method.

func (*DB) Close

func (db *DB) Close() error

Close closes the DB.

func (*DB) Compact

func (db *DB) Compact() (CompactionResult, error)

Compact compacts the DB. Deleted and overwritten items are discarded. Returns an error if compaction is already in progress.

func (*DB) Count

func (db *DB) Count() uint32

Count returns the number of keys in the DB.

func (*DB) FileSize

func (db *DB) FileSize() (int64, error)

FileSize returns the total size of the disk storage used by the DB.

func (*DB) Has

func (db *DB) Has(key []byte) (bool, error)

Has returns true if the DB contains the given key.

func (*DB) HasOrPut

func (db *DB) HasOrPut(key []byte) (bool, error)

func (*DB) Items

func (db *DB) Items() *ItemIterator

Items returns a new ItemIterator.

func (*DB) Metrics

func (db *DB) Metrics() *Metrics

Metrics returns the DB metrics.

func (*DB) Put

func (db *DB) Put(key []byte) error

Put sets the value for the given key. It updates the value for the existing key.

func (*DB) Sync

func (db *DB) Sync() error

Sync commits the contents of the database to the backing FileSystem.

type ItemIterator

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

ItemIterator is an iterator over DB key-value pairs. It iterates the items in an unspecified order.

func (*ItemIterator) Next

func (it *ItemIterator) Next() ([]byte, error)

Next returns the next key-value pair if available, otherwise it returns ErrIterationDone error.

type Metrics

type Metrics struct {
	Puts expvar.Int
}

Metrics holds the DB metrics.

type Options

type Options struct {
	// BackgroundSyncInterval sets the amount of time between background Sync() calls.
	//
	// Setting the value to 0 disables the automatic background synchronization.
	// Setting the value to -1 makes the DB call Sync() after every write operation.
	BackgroundSyncInterval time.Duration

	// BackgroundCompactionInterval sets the amount of time between background Compact() calls.
	//
	// Setting the value to 0 disables the automatic background compaction.
	BackgroundCompactionInterval time.Duration

	// FileSystem sets the file system implementation.
	//
	// Default: fs.OSMMap.
	FileSystem fs.FileSystem
	// contains filtered or unexported fields
}

Options holds the optional DB parameters.