db

README

db

db is a Go package that provides a simple cgo wrapper to BSD's BSD's dbopen(3), which is an implementation of Berkeley DB 1.85.

Currently only the hash format (as described in hash(3)) is implemented (via OpenHash).

It was written to access the key3.db file used by Firefox to store passwords. It is sufficient for that kind of task (access to pre-existing databases) but there are probably much better choices when picking a database to use
for new applications where backwards compatibility with db is not required.

Online package documentation is available via https://godoc.org/bitbucket.org/dchapes/db.

To install:

	go get bitbucket.org/dchapes/db

or go build any Go code that imports it:

	import "bitbucket.org/dchapes/db"

Documentation

Overview

Package db is a simple cgo wrapper to BSD's dbopen(3), which is an implementation of Berkeley DB 1.85.

Currently only the hash format (as described in hash(3)) is implemented (via OpenHash).

This simple wrapper does not attempt to omptimize data copying. (E.g. each Get/Put/etc method likley copies it's data at least once more than strictly required due to using cgo's C.CBytes and C.GoBytes.)

Index

• Variables
• type Bytes
  • func (r Bytes) MarshalBinary() ([]byte, error)
  • func (r *Bytes) UnmarshalBinary(data []byte) error
• type DB
  • func OpenHash(path string, flags int, mode os.FileMode, info *HashInfo) (*DB, error)
  • func (db *DB) Close() error
  • func (db *DB) Cursor(key RWValue, data WValue) error
  • func (db *DB) Delete(key RValue) (bool, error)
  • func (db *DB) Fd() (uintptr, error)
  • func (db *DB) First(key, data WValue) error
  • func (db *DB) Get(key RValue, data WValue) error
  • func (db *DB) Next(key, data WValue) error
  • func (db *DB) Put(key, data RValue) error
  • func (db *DB) PutNew(key, data RValue) error
  • func (db *DB) Sync() error
• type HashInfo
• type RValue
• type RWValue
• type String
  • func (s String) MarshalBinary() ([]byte, error)
  • func (s *String) UnmarshalBinary(data []byte) error
• type WValue

Variables

var (
	ErrKeyNotFound          = errors.New("key not found")
	ErrKeyExist             = errors.New("key already exists")
	ErrUnsupportedOpenFlags = errors.New("unsupported open flags")
)

Error values.

Types

type Bytes

type Bytes []byte

Bytes implements RWValue on []byte.

func (Bytes) MarshalBinary

func (r Bytes) MarshalBinary() ([]byte, error)

MarshalBinary implements RValue and encoding.BinaryMarshaler.

func (*Bytes) UnmarshalBinary

func (r *Bytes) UnmarshalBinary(data []byte) error

UnmarshalBinary implements WValue.

Note, unsafe for use as encoding.BinaryUnmarshaler as it does not copy the data.

type DB

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

DB represents an open database file.

func OpenHash

func OpenHash(path string, flags int, mode os.FileMode, info *HashInfo) (*DB, error)

OpenHash opens the named file for reading and/or writing.

Files never intended to be preserved on disk may be created by setting the path argument to the empty string, "".

The flags and mode arguments are as specified to os.OpenFile, however, only the os.O_RDONLY, os.O_RDWR, os.O_CREATE, os.O_EXCL, os.O_SYNC, and os.O_TRUNC flags are supported. (Note, opening a database file os.O_WRONLY is not possible. Further note, unlike dbopen(3), O_EXLOCK, O_NOFOLLOW, O_NONBLOCK, and O_SHLOCK may not function.)

The info argument may be nil to use appropriate defaults. If the file already exists (and the os.O_TRUNC flag is not specified), any values specified in info for BucketSize, FillFactor, ByteOrder, and SizeHint are ignored and the values specified when the file was created are used.

func (*DB) Close

func (db *DB) Close() error

Close flushes any cached information to disk and closes the underlying file(s). Since key/data pairs may be cached in memory, failing to sync the database with Close or Sync may result in inconsistent or lost information.

func (*DB) Cursor

func (db *DB) Cursor(key RWValue, data WValue) error

Cursor retrievs the specified key/data pair from the database. Unlike Get this also initializes the cursor to the location of the key as well thus effecting future Next calls.

func (*DB) Delete

func (db *DB) Delete(key RValue) (bool, error)

Delete removes the key/data pair specified from the database.

Returns true if the key was found and removed, false if the key was not in the database.

func (*DB) Fd

func (db *DB) Fd() (uintptr, error)

Fd returns the integer Unix file descriptor representative of the underlying database. A file descriptor referencing the same file will be returned to all processes which call Open* with the same file name. This file descriptor may be safely used as an argument to the syscall.FcntlFlock and syscall.Flock locking functions. The file descriptor is not necessarily associated with any of the underlying files used by the access method. No file descriptor is available for in memory databases. The file descriptor is valid only until db.Close is called or db is garbage collected.

func (*DB) First

func (db *DB) First(key, data WValue) error

First returns the first key/data pair in the database and initializes the cursor to reference it.

func (*DB) Get

func (db *DB) Get(key RValue, data WValue) error

Get retrieves the key/data pair specified from the database. ErrKeyNotFound is returned if the key is not in the database.

func (*DB) Next

func (db *DB) Next(key, data WValue) error

Next retrieves the key/data pair immediately after the cursor (as set by the First or Cursor method). If the cursor is not yet set, this is the same as First. io.EOF is returned if there are no more key/data pairs.

func (*DB) Put

func (db *DB) Put(key, data RValue) error

Put stores the key/data pair in the database. Any previously existing key is replaced.

func (*DB) PutNew

func (db *DB) PutNew(key, data RValue) error

PutNew stores a new key/data pair in the database. If the key already exists, ErrKeyExist is returned.

func (*DB) Sync

func (db *DB) Sync() error

Sync flushes any cached infomration to disk. If the database is in memory only, this has no effect and will always succeed.

type HashInfo

type HashInfo struct {
	// BucketSize defines the hash table bucket size, and
	// is, by default, 4096 bytes. It may be preferable
	// to increase the page size for disk-resident
	// tables and tables with large data items.
	BucketSize int

	// FillFactor indicates a desired density within the hash
	// table. It is an approximation of the number of keys allowed
	// to accumulate in any one bucket, determining when the
	// hash table grows or shrinks. The default value is 65536.
	FillFactor int

	// SizeHint is an estimate of the final size of the hash
	// table. If not set or set too low, hash tables will expand
	// gracefully as keys are entered, although a slight performance
	// degradation may be noticed. The default value is 1.
	SizeHint int

	// CacheSize is a suggested maximum size, in bytes, of
	// the memory cache. This value is only advisory, and the
	// access method will allocate more memory rather than fail.
	CacheSize int

	// Hash is a user defined hash function. Since no hash function
	// performs equally well on all possible data, the user may
	// find that the built-in hash function does poorly on a
	// particular data set.
	//
	// Not supported.
	Hash func([]byte) uint32

	// ByteOrder is the byte order for integers in the stored
	// database metadata. The number should represent the
	// order as an integer; for example, big endian order
	// would be the number 4,321. If lorder is 0 (no order
	// is specified) the current host order is used. If the
	// file already exists, the specified value is ignored and
	// the value specified when the tree was created is used.
	ByteOrder int
}

HashInfo specifies access method options.

This is used to fill C.HASHINFO as described in the hash(3) manpage. If a field is left zero the C code uses an appropriate default.

type RValue

type RValue interface {
	MarshalBinary() ([]byte, error)
}

RValue is the interface implemented by an object that can marshal itself into a binary form suitable for use a database key or value.

Note this the same as the encoding.BinaryMarshaler interface.

type RWValue

type RWValue interface {
	MarshalBinary() ([]byte, error)
	UnmarshalBinary([]byte) error
}

RWValue is the interface that groups the RValue and WValue interfaces.

type String

type String string

String implements RWValue on string.

func (String) MarshalBinary

func (s String) MarshalBinary() ([]byte, error)

MarshalBinary implements RValue and encoding.BinaryMarshaler.

func (*String) UnmarshalBinary

func (s *String) UnmarshalBinary(data []byte) error

UnmarshalBinary implements WValue and encoding.BinaryUnmarshaler.

type WValue

type WValue interface {
	UnmarshalBinary([]byte) error
}

WValue is the interface implemented by an object that can unmarshal a binary representation of itself.

UnmarshalBinary must be able to decode the form generated by MarshalBinary.

For use as encoding.BinaryUnmarshaler, UnmarshalBinary must copy the data if it wishes to retain the data after returning.

Note this the same as the encoding.BinaryUnmarshaler interface.