mdb

README

gomdb

Go wrapper for OpenLDAP Lightning Memory-Mapped Database (LMDB). Read more about LMDB here: http://symas.com/mdb/

GoDoc available here: http://godoc.org/github.com/szferi/gomdb

Build

go get github.com/szferi/gomdb

There is no dependency on LMDB dynamic library.

TODO

• write more documentation
• write more unit test
• benchmark
• figure out how can you write go binding for MDB_comp_func and MDB_rel_func
• Handle go *Cursor close with txn.Commit and txn.Abort transparently

Documentation

Overview

A thin wrapper for the lmdb C library. These are low-level bindings for the C API. The C documentation should be used as a reference while developing (http://symas.com/mdb/doc/group__mdb.html).

Errors

The errors returned by the package API will with few exceptions be of type Errno or syscall.Errno. The only errors of type Errno returned are those defined in lmdb.h. Other errno values like EINVAL will by of type syscall.Errno.

Example

Most mdb functions/methods can return errors. This example ignores errors for brevity. Real code should check all return values.

// create a directory to hold the database
path, _ := ioutil.TempDir("", "mdb_test")
defer os.RemoveAll(path)

// open the db
env, _ := NewEnv()
env.SetMapSize(1 << 20) // max file size
env.Open(path, 0, 0664)
defer env.Close()
txn, _ := env.BeginTxn(nil, 0)
dbi, _ := txn.DBIOpen(nil, 0)
defer env.DBIClose(dbi)
txn.Commit()

// write some data
txn, _ = env.BeginTxn(nil, 0)
num_entries := 5
for i := 0; i < num_entries; i++ {
	key := fmt.Sprintf("Key-%d", i)
	val := fmt.Sprintf("Val-%d", i)
	txn.Put(dbi, []byte(key), []byte(val), 0)
}
txn.Commit()

// inspect the database
stat, _ := env.Stat()
fmt.Println(stat.Entries)

// scan the database
txn, _ = env.BeginTxn(nil, RDONLY)
defer txn.Abort()
cursor, _ := txn.CursorOpen(dbi)
defer cursor.Close()
for {
	bkey, bval, err := cursor.Get(nil, NEXT)
	if err == NotFound {
		break
	}
	if err != nil {
		panic(err)
	}
	fmt.Printf("%s: %s\n", bkey, bval)
}

// random access
bval, _ := txn.Get(dbi, []byte("Key-3"))
fmt.Println(string(bval))

Output:

5
Key-0: Val-0
Key-1: Val-1
Key-2: Val-2
Key-3: Val-3
Key-4: Val-4
Val-3

Index

• Constants
• func Version() string
• type Cursor
  • func (cursor *Cursor) Close() error
  • func (cursor *Cursor) Count() (uint64, error)
  • func (cursor *Cursor) DBI() DBI
  • func (cursor *Cursor) Del(flags uint) error
  • func (cursor *Cursor) Get(set_key []byte, op uint) (key, val []byte, err error)
  • func (cursor *Cursor) GetVal(key []byte, op uint) (Val, Val, error)
  • func (cursor *Cursor) MdbCursor() *C.MDB_cursor
  • func (cursor *Cursor) Put(key, val []byte, flags uint) error
  • func (cursor *Cursor) Txn() *Txn
• type DBI
• type Env
  • func NewEnv() (*Env, error)
  • func (env *Env) BeginTxn(parent *Txn, flags uint) (*Txn, error)
  • func (env *Env) Close() error
  • func (env *Env) Copy(path string) error
  • func (env *Env) DBIClose(dbi DBI)
  • func (env *Env) Flags() (uint, error)
  • func (env *Env) Info() (*Info, error)
  • func (env *Env) Open(path string, flags uint, mode uint) error
  • func (env *Env) Path() (string, error)
  • func (env *Env) SetFlags(flags uint, onoff int) error
  • func (env *Env) SetMapSize(size uint64) error
  • func (env *Env) SetMaxDBs(size DBI) error
  • func (env *Env) SetMaxReaders(size uint) error
  • func (env *Env) Stat() (*Stat, error)
  • func (env *Env) Sync(force int) error
• type Errno
  • func (e Errno) Error() string
• type Info
• type Stat
• type Txn
  • func (txn *Txn) Abort()
  • func (txn *Txn) Commit() error
  • func (txn *Txn) CursorOpen(dbi DBI) (*Cursor, error)
  • func (txn *Txn) CursorRenew(cursor *Cursor) error
  • func (txn *Txn) DBIOpen(name *string, flags uint) (DBI, error)
  • func (txn *Txn) Del(dbi DBI, key, val []byte) error
  • func (txn *Txn) Drop(dbi DBI, del int) error
  • func (txn *Txn) Get(dbi DBI, key []byte) ([]byte, error)
  • func (txn *Txn) GetVal(dbi DBI, key []byte) (Val, error)
  • func (txn *Txn) Put(dbi DBI, key []byte, val []byte, flags uint) error
  • func (txn *Txn) Renew() error
  • func (txn *Txn) Reset()
  • func (txn *Txn) Stat(dbi DBI) (*Stat, error)
• type Val
  • func Wrap(p []byte) Val
  • func (val Val) Bytes() []byte
  • func (val Val) String() string

Examples

• Package

Constants

const (
	FIRST = iota
	FIRST_DUP
	GET_BOTH
	GET_RANGE
	GET_CURRENT
	GET_MULTIPLE
	LAST
	LAST_DUP
	NEXT
	NEXT_DUP
	NEXT_MULTIPLE
	NEXT_NODUP
	PREV
	PREV_DUP
	PREV_NODUP
	SET
	SET_KEY
	SET_RANGE
)

MDB_cursor_op

const (
	FIXEDMAP   = C.MDB_FIXEDMAP   // mmap at a fixed address (experimental)
	NOSUBDIR   = C.MDB_NOSUBDIR   // no environment directory
	NOSYNC     = C.MDB_NOSYNC     // don't fsync after commit
	RDONLY     = C.MDB_RDONLY     // read only
	NOMETASYNC = C.MDB_NOMETASYNC // don't fsync metapage after commit
	WRITEMAP   = C.MDB_WRITEMAP   // use writable mmap
	MAPASYNC   = C.MDB_MAPASYNC   // use asynchronous msync when MDB_WRITEMAP is use
	NOTLS      = C.MDB_NOTLS      // tie reader locktable slots to Txn objects instead of threads
)

mdb_env Environment Flags

const (
	KeyExist        = Errno(C.MDB_KEYEXIST)
	NotFound        = Errno(C.MDB_NOTFOUND)
	PageNotFound    = Errno(C.MDB_PAGE_NOTFOUND)
	Corrupted       = Errno(C.MDB_CORRUPTED)
	Panic           = Errno(C.MDB_PANIC)
	VersionMismatch = Errno(C.MDB_VERSION_MISMATCH)
	Invalid         = Errno(C.MDB_INVALID)
	MapFull         = Errno(C.MDB_MAP_FULL)
	DbsFull         = Errno(C.MDB_DBS_FULL)
	ReadersFull     = Errno(C.MDB_READERS_FULL)
	TlsFull         = Errno(C.MDB_TLS_FULL)
	TxnFull         = Errno(C.MDB_TXN_FULL)
	CursorFull      = Errno(C.MDB_CURSOR_FULL)
	PageFull        = Errno(C.MDB_PAGE_FULL)
	MapResized      = Errno(C.MDB_MAP_RESIZED)
	Incompatibile   = Errno(C.MDB_INCOMPATIBLE)
)

error codes

const (
	REVERSEKEY = C.MDB_REVERSEKEY // use reverse string keys
	DUPSORT    = C.MDB_DUPSORT    // use sorted duplicates
	INTEGERKEY = C.MDB_INTEGERKEY // numeric keys in native byte order. The keys must all be of the same size.
	DUPFIXED   = C.MDB_DUPFIXED   // with DUPSORT, sorted dup items have fixed size
	INTEGERDUP = C.MDB_INTEGERDUP // with DUPSORT, dups are numeric in native byte order
	REVERSEDUP = C.MDB_REVERSEDUP // with DUPSORT, use reverse string dups
	CREATE     = C.MDB_CREATE     // create DB if not already existing
)

DBIOpen Database Flags

const (
	NODUPDATA   = C.MDB_NODUPDATA
	NOOVERWRITE = C.MDB_NOOVERWRITE
	RESERVE     = C.MDB_RESERVE
	APPEND      = C.MDB_APPEND
	APPENDDUP   = C.MDB_APPENDDUP
)

put flags

const SUCCESS = C.MDB_SUCCESS

Functions

func Version

func Version() string

Types

type Cursor

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

func (*Cursor) Close

func (cursor *Cursor) Close() error

func (*Cursor) Count

func (cursor *Cursor) Count() (uint64, error)

func (*Cursor) DBI

func (cursor *Cursor) DBI() DBI

func (*Cursor) Del

func (cursor *Cursor) Del(flags uint) error

func (*Cursor) Get

func (cursor *Cursor) Get(set_key []byte, op uint) (key, val []byte, err error)

func (*Cursor) GetVal

func (cursor *Cursor) GetVal(key []byte, op uint) (Val, Val, error)

func (*Cursor) MdbCursor

func (cursor *Cursor) MdbCursor() *C.MDB_cursor

Retrieves the low-level MDB cursor.

func (*Cursor) Put

func (cursor *Cursor) Put(key, val []byte, flags uint) error

func (*Cursor) Txn

func (cursor *Cursor) Txn() *Txn

type DBI

type DBI uint

type Env

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

Env is opaque structure for a database environment. A DB environment supports multiple databases, all residing in the same shared-memory map.

func NewEnv

func NewEnv() (*Env, error)

Create an MDB environment handle.

func (*Env) BeginTxn

func (env *Env) BeginTxn(parent *Txn, flags uint) (*Txn, error)

func (*Env) Close

func (env *Env) Close() error

func (*Env) Copy

func (env *Env) Copy(path string) error

func (*Env) DBIClose

func (env *Env) DBIClose(dbi DBI)

func (*Env) Flags

func (env *Env) Flags() (uint, error)

func (*Env) Info

func (env *Env) Info() (*Info, error)

func (*Env) Open

func (env *Env) Open(path string, flags uint, mode uint) error

Open an environment handle. If this function fails Close() must be called to discard the Env handle.

func (*Env) Path

func (env *Env) Path() (string, error)

func (*Env) SetFlags

func (env *Env) SetFlags(flags uint, onoff int) error

func (*Env) SetMapSize

func (env *Env) SetMapSize(size uint64) error

func (*Env) SetMaxDBs

func (env *Env) SetMaxDBs(size DBI) error

func (*Env) SetMaxReaders

func (env *Env) SetMaxReaders(size uint) error

func (*Env) Stat

func (env *Env) Stat() (*Stat, error)

func (*Env) Sync

func (env *Env) Sync(force int) error

type Errno

type Errno C.int

func (Errno) Error

func (e Errno) Error() string

type Info

type Info struct {
	MapSize    uint64 // Size of the data memory map
	LastPNO    uint64 // ID of the last used page
	LastTxnID  uint64 // ID of the last committed transaction
	MaxReaders uint   // maximum number of threads for the environment
	NumReaders uint   // maximum number of threads used in the environment
}

type Stat

type Stat struct {
	PSize         uint   // Size of a database page. This is currently the same for all databases.
	Depth         uint   // Depth (height) of the B-tree
	BranchPages   uint64 // Number of internal (non-leaf) pages
	LeafPages     uint64 // Number of leaf pages
	OverflowPages uint64 // Number of overflow pages
	Entries       uint64 // Number of data items
}

Statistics for a database in the environment

type Txn

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

Txn is Opaque structure for a transaction handle. All database operations require a transaction handle. Transactions may be read-only or read-write.

func (*Txn) Abort

func (txn *Txn) Abort()

func (*Txn) Commit

func (txn *Txn) Commit() error

func (*Txn) CursorOpen

func (txn *Txn) CursorOpen(dbi DBI) (*Cursor, error)

func (*Txn) CursorRenew

func (txn *Txn) CursorRenew(cursor *Cursor) error

func (*Txn) DBIOpen

func (txn *Txn) DBIOpen(name *string, flags uint) (DBI, error)

func (*Txn) Del

func (txn *Txn) Del(dbi DBI, key, val []byte) error

func (*Txn) Drop

func (txn *Txn) Drop(dbi DBI, del int) error

func (*Txn) Get

func (txn *Txn) Get(dbi DBI, key []byte) ([]byte, error)

func (*Txn) GetVal

func (txn *Txn) GetVal(dbi DBI, key []byte) (Val, error)

func (*Txn) Put

func (txn *Txn) Put(dbi DBI, key []byte, val []byte, flags uint) error

func (*Txn) Renew

func (txn *Txn) Renew() error

func (*Txn) Reset

func (txn *Txn) Reset()

func (*Txn) Stat

func (txn *Txn) Stat(dbi DBI) (*Stat, error)

type Val

type Val C.MDB_val

MDB_val

func Wrap

func Wrap(p []byte) Val

Create a Val that points to p's data. the Val's data must not be freed manually and C references must not survive the garbage collection of p (and the returned Val).

func (Val) Bytes

func (val Val) Bytes() []byte

If val is nil, a empty slice is retured.

func (Val) String

func (val Val) String() string

If val is nil, an empty string is returned.