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
git clone -b mdb.master --single-branch git://git.openldap.org/openldap.git
make
make install
It will install to /usr/local
export LD_LIBRARY_PATH=/usr/local/lib
go test -v
TODO
- write more documentation
- write more unit test
- benchmark
- figure out how can you write go binding for
MDB_comp_funcandMDB_rel_func - Handle go
*Cursorclose withtxn.Commitandtxn.Aborttransparently
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 (env *Env) BeginTxn(parent *Txn, flags uint) (*Txn, error)
- func (env *Env) BeginTxnR(parent *Txn, flags uint, pinThreads bool) (*Txn, error)
- func (env *Env) Close() error
- func (env *Env) Copy(path string) error
- func (env *Env) CopyFd(fd int) 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
- 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
Examples ¶
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
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Cursor ¶
type Cursor struct {
// contains filtered or unexported fields
}
func (*Cursor) MdbCursor ¶
func (cursor *Cursor) MdbCursor() *C.MDB_cursor
Retrieves the low-level MDB cursor.
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 (*Env) BeginTxnR ¶
pinThreads parameter for whether manage LockOsThread now and release on restruction of this txn. Set it true unless you've already called LockOsThread for the current goroutine, and absolutely know what you're doing. LMDB uses threadlocal state for Txns and will have lots of errors and possibly deadlocks if you don't call LockOSThread properly.
func (*Env) Open ¶
Open an environment handle. If this function fails Close() must be called to discard the Env handle.
func (*Env) SetMapSize ¶
func (*Env) SetMaxReaders ¶
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) CursorRenew ¶
type Val ¶
MDB_val
func Wrap ¶
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).
Source Files