lmdb-go

README

#lmdb-go

Go bindings to the OpenLDAP Lightning Memory-Mapped Database (LMDB).

Packages

Functionality is logically divided into several packages. Applications will usually need to import lmdb but may import other packages on an as needed basis.

Packages in the exp/ directory are not stable and may change without warning. That said, they are generally usable if application dependencies are managed and pinned by tag/commit.

Developers concerned with package stability should consult the documentation.

####lmdb

import "github.com/bmatsuo/lmdb-go/lmdb"

Core bindings allowing low-level access to LMDB.

####exp/lmdbscan

import "github.com/bmatsuo/lmdb-go/exp/lmdbscan"

A utility package for scanning database ranges. The API is inspired by bufio.Scanner and the python cursor iterator implementation.

The lmdbscan package is unstable. The API is properly scoped and adequately tested. And no features that exist now will be removed without a similar substitute. See the versioning documentation for more information.

####exp/lmdbsync

import "github.com/bmatsuo/lmdb-go/exp/lmdbsync"

An experimental utility package that provides synchronization necessary to change an environment's map size after initialization. Facilities are provided to automatically manage database size, similar to BoltDB.

The lmdbsync package is usable for synchronization but its resizing behavior should be considered highly unstable and may change without notice between releases. Its use case is real but somewhat niche and requires much more feedback driven development before it can be considered stable.

Key Features

###Idiomatic API

API inspired by BoltDB with automatic commit/rollback of transactions. The goal of lmdb-go is to provide idiomatic, safe database interactions without compromising the flexibility of the C API.

###API coverage

The lmdb-go project aims for complete coverage of the LMDB C API (within reason). Some notable features and optimizations that are supported:

• Idiomatic subtransactions ("sub-updates") that do not disrupt thread locking.

• Batch IO on databases utilizing the MDB_DUPSORT and MDB_DUPFIXED flags.

• Reserved writes than can save in memory copies converting/buffering into []byte.

For tracking purposes a list of unsupported features is kept in an issue.

###Zero-copy reads

Applications with high performance requirements can opt-in to fast, zero-copy reads at the cost of runtime safety. Zero-copy behavior is specified at the transaction level to reduce instrumentation overhead.

err := lmdb.View(func(txn *lmdb.Txn) error {
    // RawRead enables zero-copy behavior with some serious caveats.
    // Read the documentation carefully before using.
    txn.RawRead = true

    val, err := txn.Get(dbi, []byte("largevalue"), 0)
    // ...
})

###Documentation

Comprehensive documentation and examples are provided to demonstrate safe usage of lmdb. In addition to godoc documentation, implementations of the standand LMDB commands (mdb_stat, etc) can be found in the cmd/ directory and some simple experimental commands can be found in the exp/cmd/ directory. Aside from providing minor utility these programs are provided as examples of lmdb in practice.

#Build

There is no dependency on shared libraries. So most users can simply install using go get.

go get github.com/bmatsuo/lmdb-go/lmdb

On FreeBSD 10, you must explicitly set CC (otherwise it will fail with a cryptic error), for example:

CC=clang go test -v ./...

Building commands and running tests can be done with go or with make

make bin
make test
make check
make all

#Documentation

##LMDB

The best source of documentation regarding the low-level usage of LMDB environments is the official LMDB C API documentation reachable through the LMDB homepage.

##Godoc

The "godoc" documentation available on godoc.org has all remaining developer documentation for lmdb-go. Godoc documentation covers specifics to the Go bindings, how methods differ from their underlying C counterparts, and lots of usage examples.

##Versioning and Stability

The lmdb-go project makes regular releases with IDs X.Y.Z. All packages outside of the exp/ directory are considered stable and adhere to the guidelines of semantic versioning.

Experimental packages (those packages in exp/) are not required to adhere to semantic versioning. However packages specifically declared to merely be "unstable" can be relied on more for long term use with less concern.

The API of an unstable package may change in subtle ways between minor release versions. But deprecations will be indicated at least one release in advance and all functionality will remain available through some method.

##License

Except where otherwise noted files in the lmdb-go project are licensed under the MIT open source license.

The LMDB C source is licensed under the OpenLDAP Public License.

#Links

####github.com/bmatsuo/raft-mdb (godoc)

An experimental backend for github.com/hashicorp/raft forked from github.com/hashicorp/raft-mdb.

####github.com/bmatsuo/cayley/graph/lmdb (godoc)

Experimental backend quad-store for github.com/google/cayley based off of the BoltDB implementation.