db

Documentation

Overview

Package db defines the interfaces for a key/value store.

A DB's basic operations (Get, Set, Delete) should be self-explanatory. Get and Delete will return ErrNotFound if the requested key is not in the store. Callers are free to ignore this error.

A DB also allows for iterating over the key/value pairs in key order. If d is a DB, the code below prints all key/value pairs whose keys are 'greater than or equal to' k:

iter := d.Find(k)
for iter.Next() {
	fmt.Printf("key=%q value=%q\n", iter.Key(), iter.Value())
}
return iter.Close()

Other leveldb packages provide implementations of these interfaces. The Options struct in this package holds the optional parameters for these implementations, including a Comparer to define a 'less than' relationship over keys. It is always valid to pass a nil *Options, which means to use the default parameter values. Any zero field of a non-nil *Options also means to use the default value for that parameter. Thus, the code below uses a custom Comparer, but the default values for every other parameter:

db := memdb.New(&db.Options{
	Comparer: myComparer,
})

Index

• Variables
• func SharedPrefixLen(a, b []byte) int
• type Comparer
• type Compression
• type DB
• type Iterator
• type Options
  • func (o *Options) GetBlockRestartInterval() int
  • func (o *Options) GetBlockSize() int
  • func (o *Options) GetComparer() Comparer
  • func (o *Options) GetCompression() Compression
  • func (o *Options) GetVerifyChecksums() bool
• type ReadOptions
• type WriteOptions
  • func (o *WriteOptions) GetSync() bool

Variables

var ErrNotFound = errors.New("leveldb/db: not found")

ErrNotFound means that a get or delete call did not find the requested key.

Functions

func SharedPrefixLen

func SharedPrefixLen(a, b []byte) int

SharedPrefixLen returns the largest i such that a[:i] equals b[:i]. This function can be useful in implementing the Comparer interface.

Types

type Comparer

type Comparer interface {
	// Compare returns -1, 0, or +1 depending on whether a is 'less than',
	// 'equal to' or 'greater than' b. The two arguments can only be 'equal'
	// if their contents are exactly equal. Furthermore, the empty slice
	// must be 'less than' any non-empty slice.
	Compare(a, b []byte) int

	// AppendSeparator appends a sequence of bytes x to dst such that
	// a <= x && x < b, where 'less than' is consistent with Compare.
	// It returns the enlarged slice, like the built-in append function.
	//
	// Precondition: either a is 'less than' b, or b is an empty slice.
	// In the latter case, empty means 'positive infinity', and appending any
	// x such that a <= x will be valid.
	//
	// An implementation may simply be "return append(dst, a...)" but appending
	// fewer bytes will result in smaller tables.
	//
	// For example, if dst, a and b are the []byte equivalents of the strings
	// "aqua", "black" and "blue", then the result may be "aquablb".
	// Similarly, if the arguments were "aqua", "green" and "", then the result
	// may be "aquah".
	AppendSeparator(dst, a, b []byte) []byte
}

Comparer defines a total ordering over the space of []byte keys: a 'less than' relationship.

var DefaultComparer Comparer = defCmp{}

DefaultComparer is the default implementation of the Comparer interface. It uses the natural ordering, consistent with bytes.Compare.

type Compression

type Compression int

Compression is the per-block compression algorithm to use.

const (
	DefaultCompression Compression = iota
	NoCompression
	SnappyCompression
)

type DB

type DB interface {
	// Get gets the value for the given key. It returns ErrNotFound if the DB
	// does not contain the key.
	//
	// The caller should not modify the contents of the returned slice, but
	// it is safe to modify the contents of the argument after Get returns.
	Get(key []byte, o *ReadOptions) (value []byte, err error)

	// Set sets the value for the given key. It overwrites any previous value
	// for that key; a DB is not a multi-map.
	//
	// It is safe to modify the contents of the arguments after Set returns.
	Set(key, value []byte, o *WriteOptions) error

	// Delete deletes the value for the given key. It returns ErrNotFound if
	// the DB does not contain the key.
	//
	// It is safe to modify the contents of the arguments after Delete returns.
	Delete(key []byte, o *WriteOptions) error

	// Find returns an iterator positioned before the first key/value pair
	// whose key is 'greater than or equal to' the given key. There may be no
	// such pair, in which case the iterator will return false on Next.
	//
	// Any error encountered will be implicitly returned via the iterator. An
	// error-iterator will yield no key/value pairs and closing that iterator
	// will return that error.
	//
	// It is safe to modify the contents of the argument after Find returns.
	Find(key []byte, o *ReadOptions) Iterator

	// Close closes the DB. It may or may not close any underlying io.Reader
	// or io.Writer, depending on how the DB was created.
	//
	// It is not safe to close a DB until all outstanding iterators are closed.
	// It is valid to call Close multiple times. Other methods should not be
	// called after the DB has been closed.
	Close() error
}

DB is a key/value store.

It is safe to call Get and Find from concurrent goroutines. It is not necessarily safe to do so for Set and Delete.

Some implementations may impose additional restrictions. For example:

• Set calls may need to be in increasing key order.
• a DB may be read-only or write-only.

type Iterator

type Iterator interface {
	// Next moves the iterator to the next key/value pair.
	// It returns whether the iterator is exhausted.
	Next() bool

	// Key returns the key of the current key/value pair, or nil if done.
	// The caller should not modify the contents of the returned slice, and
	// its contents may change on the next call to Next.
	Key() []byte

	// Value returns the value of the current key/value pair, or nil if done.
	// The caller should not modify the contents of the returned slice, and
	// its contents may change on the next call to Next.
	Value() []byte

	// Close closes the iterator and returns any accumulated error. Exhausting
	// all the key/value pairs in a table is not considered to be an error.
	// It is valid to call Close multiple times. Other methods should not be
	// called after the iterator has been closed.
	Close() error
}

Iterator iterates over a DB's key/value pairs in key order.

An iterator must be closed after use, but it is not necessary to read an iterator until exhaustion.

An iterator is not necessarily goroutine-safe, but it is safe to use multiple iterators concurrently, with each in a dedicated goroutine.

It is also safe to use an iterator concurrently with modifying its underlying DB, if that DB permits modification. However, the resultant key/value pairs are not guaranteed to be a consistent snapshot of that DB at a particular point in time.

type Options

type Options struct {
	// BlockRestartInterval is the number of keys between restart points
	// for delta encoding of keys.
	//
	// The default value is 16.
	BlockRestartInterval int

	// BlockSize is the minimum uncompressed size in bytes of each table block.
	//
	// The default value is 4096.
	BlockSize int

	// Comparer defines a total ordering over the space of []byte keys: a 'less
	// than' relationship. The same comparison algorithm must be used for reads
	// and writes over the lifetime of the DB.
	//
	// The default value uses the same ordering as bytes.Compare.
	Comparer Comparer

	// Compression defines the per-block compression to use.
	//
	// The default value (DefaultCompression) uses snappy compression.
	Compression Compression

	// VerifyChecksums is whether to verify the per-block checksums in a DB.
	//
	// The default value is false.
	VerifyChecksums bool
}

Options holds the optional parameters for leveldb's DB implementations. These options apply to the DB at large; per-query options are defined by the ReadOptions and WriteOptions types.

Options are typically passed to a constructor function as a struct literal. The GetXxx methods are used inside the DB implementations; they return the default parameter value if the *Options receiver is nil or the field value is zero.

Read/Write options:

• Comparer

Read options:

• VerifyChecksums

Write options:

• BlockRestartInterval
• BlockSize
• Compression

func (*Options) GetBlockRestartInterval

func (o *Options) GetBlockRestartInterval() int

func (*Options) GetBlockSize

func (o *Options) GetBlockSize() int

func (*Options) GetComparer

func (o *Options) GetComparer() Comparer

func (*Options) GetCompression

func (o *Options) GetCompression() Compression

func (*Options) GetVerifyChecksums

func (o *Options) GetVerifyChecksums() bool

type ReadOptions

type ReadOptions struct {
}

ReadOptions hold the optional per-query parameters for Get and Find operations.

Like Options, a nil *ReadOptions is valid and means to use the default values.

type WriteOptions

type WriteOptions struct {
	// Sync is whether to sync underlying writes from the OS buffer cache
	// through to actual disk, if applicable. Setting Sync can result in
	// slower writes.
	//
	// If false, and the machine crashes, then some recent writes may be lost.
	// Note that if it is just the process that crashes (and the machine does
	// not) then no writes will be lost.
	//
	// In other words, Sync being false has the same semantics as a write
	// system call. Sync being true means write followed by fsync.
	//
	// The default value is false.
	Sync bool
}

WriteOptions hold the optional per-query parameters for Set and Delete operations.

Like Options, a nil *WriteOptions is valid and means to use the default values.

func (*WriteOptions) GetSync

func (o *WriteOptions) GetSync() bool