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
- type DB
- 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
- type WValue
Constants ¶
This section is empty.
Variables ¶
var ( ErrKeyNotFound = errors.New("key not found") ErrKeyExist = errors.New("key already exists") ErrUnsupportedOpenFlags = errors.New("unsupported open flags") )
Error values.
Functions ¶
This section is empty.
Types ¶
type Bytes ¶
type Bytes []byte
Bytes implements RWValue on []byte.
func (Bytes) MarshalBinary ¶
MarshalBinary implements RValue and encoding.BinaryMarshaler.
func (*Bytes) UnmarshalBinary ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
First returns the first key/data pair in the database and initializes the cursor to reference it.
func (*DB) Get ¶
Get retrieves the key/data pair specified from the database. ErrKeyNotFound is returned if the key is not in the database.
func (*DB) Next ¶
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 ¶
Put stores the key/data pair in the database. Any previously existing key is replaced.
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 ¶
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 String ¶
type String string
String implements RWValue on string.
func (String) MarshalBinary ¶
MarshalBinary implements RValue and encoding.BinaryMarshaler.
func (*String) UnmarshalBinary ¶
UnmarshalBinary implements WValue and encoding.BinaryUnmarshaler.
type WValue ¶
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.
Source Files