lmdb++
lmdb++: a C++11 wrapper for LMDB

This is a comprehensive C++ wrapper for the LMDB embedded database library, offering both an error-checked procedural interface and an object-oriented resource interface with RAII semantics.

Example

Here follows a simple motivating example demonstrating basic use of the object-oriented resource interface:

#include <cstdio>
#include <cstdlib>
#include <lmdb++.h>

int main() {
  /* Create and open the LMDB environment: */
  auto env = lmdb::env::create();
  env.open("./example.mdb", 0, 0664);

  /* Insert some key/value pairs in a write transaction: */
  auto wtxn = lmdb::txn::begin(env);
  auto dbi = lmdb::dbi::open(wtxn, nullptr);
  dbi.put(wtxn, "username", "jhacker");
  dbi.put(wtxn, "email", "jhacker@example.org");
  dbi.put(wtxn, "fullname", "J. Random Hacker");
  wtxn.commit();

  /* Fetch key/value pairs in a read-only transaction: */
  auto rtxn = lmdb::txn::begin(env, nullptr, MDB_RDONLY);
  auto cursor = lmdb::cursor::open(rtxn, dbi);
  std::string key, value;
  while (cursor.get(key, value, MDB_NEXT)) {
    std::printf("key: '%s', value: '%s'\n", key.c_str(), value.c_str());
  }
  cursor.close();
  rtxn.abort();

  /* The enviroment is closed automatically. */

  return EXIT_SUCCESS;
}

Should any operation in the above fail, an lmdb::error exception will be thrown and terminate the program since we don't specify an exception handler. All resources will regardless get automatically cleaned up due to RAII semantics.

note

In order to run this example, you must first manually create the ./example.mdb directory. This is a basic characteristic of LMDB: the given environment path must already exist, as LMDB will not attempt to automatically create it.

Features

Requirements

The <lmdb++.h> header file requires a C++11 compiler and standard library. Recent releases of Clang or GCC will work fine.

In addition, for your application to build and run, the underlying <lmdb.h> header file shipped with LMDB must be available in the preprocessor's include path, and you must link with the liblmdb native library. On Ubuntu Linux 14.04 and newer, these prerequisites can be satisfied by installing the liblmdb-dev package.

Overview

This wrapper offers both an error-checked procedural interface and an object-oriented resource interface with RAII semantics. The former will be useful for easily retrofitting existing projects that currently use the raw C interface, but we recommend the latter for all new projects due to the exception safety afforded by RAII semantics.

Resource Interface

The high-level resource interface wraps LMDB handles in a loving RAII embrace. This way, you can ensure e.g. that a transaction will get automatically aborted when exiting a lexical scope, regardless of whether the escape happened normally or by throwing an exception.

C handleC++ wrapper class
MDB_env*lmdb::env
MDB_txn*lmdb::txn
MDB_dbilmdb::dbi
MDB_cursor*lmdb::cursor
MDB_vallmdb::val

The methods available on these C++ classes are named consistently with the procedural interface, below, with the obvious difference of omitting the handle type prefix which is already implied by the class in question.

Procedural Interface

The low-level procedural interface wraps LMDB functions with error-checking code that will throw an instance of a corresponding C++ exception class in case of failure. This interface doesn't offer any convenience overloads as does the resource interface; the parameter types are exactly the same as for the raw C interface offered by LMDB itself. The return type is generally void for these functions since the wrapper eats the error code returned by the underlying C function, throwing an exception in case of failure and otherwise returning values in the same output parameters as the C interface.

This interface is implemented entirely using static inline functions, so there are no hidden extra costs to using these wrapper functions so long as you have a decent compiler capable of basic inlining optimization.

C functionC++ wrapper function
mdb_version()N/A
mdb_strerror()N/A
mdb_env_create()lmdb::env_create()
mdb_env_open()lmdb::env_open()
mdb_env_copy()lmdb::env_copy() [1]
mdb_env_copyfd()lmdb::env_copy_fd() [2]
mdb_env_copy2()lmdb::env_copy() [3]
mdb_env_copyfd2()lmdb::env_copy_fd() [4]
mdb_env_stat()lmdb::env_stat()
mdb_env_info()lmdb::env_info()
mdb_env_sync()lmdb::env_sync()
mdb_env_close()lmdb::env_close()
mdb_env_set_flags()lmdb::env_set_flags()
mdb_env_get_flags()lmdb::env_get_flags()
mdb_env_get_path()lmdb::env_get_path()
mdb_env_get_fd()lmdb::env_get_fd()
mdb_env_set_mapsize()lmdb::env_set_mapsize()
mdb_env_set_maxreaders()lmdb::env_set_max_readers()
mdb_env_get_maxreaders()lmdb::env_get_max_readers()
mdb_env_set_maxdbs()lmdb::env_set_max_dbs()
mdb_env_get_maxkeysize()lmdb::env_get_max_keysize()
mdb_env_set_userctx()lmdb::env_set_userctx() [5]
mdb_env_get_userctx()lmdb::env_get_userctx() [6]
mdb_env_set_assert()N/A
mdb_txn_begin()lmdb::txn_begin()
mdb_txn_env()lmdb::txn_env()
mdb_txn_commit()lmdb::txn_commit()
mdb_txn_abort()lmdb::txn_abort()
mdb_txn_reset()lmdb::txn_reset()
mdb_txn_renew()lmdb::txn_renew()
mdb_dbi_open()lmdb::dbi_open()
mdb_stat()lmdb::dbi_stat() [7]
mdb_dbi_flags()lmdb::dbi_flags()
mdb_dbi_close()lmdb::dbi_close()
mdb_drop()lmdb::dbi_drop() [8]
mdb_set_compare()lmdb::dbi_set_compare() [9]
mdb_set_dupsort()lmdb::dbi_set_dupsort() [10]
mdb_set_relfunc()lmdb::dbi_set_relfunc() [11]
mdb_set_relctx()lmdb::dbi_set_relctx() [12]
mdb_get()lmdb::dbi_get() [13]
mdb_put()lmdb::dbi_put() [14]
mdb_del()lmdb::dbi_del() [15]
mdb_cursor_open()lmdb::cursor_open()
mdb_cursor_close()lmdb::cursor_close()
mdb_cursor_renew()lmdb::cursor_renew()
mdb_cursor_txn()lmdb::cursor_txn()
mdb_cursor_dbi()lmdb::cursor_dbi()
mdb_cursor_get()lmdb::cursor_get()
mdb_cursor_put()lmdb::cursor_put()
mdb_cursor_del()lmdb::cursor_del()
mdb_cursor_count()lmdb::cursor_count()
mdb_cmp()N/A
mdb_dcmp()N/A
mdb_reader_list()TODO
mdb_reader_check()TODO

Footnotes

Caveats

Error Handling

This wrapper draws a careful distinction between three different classes of possible LMDB error conditions:

note

The distinction between logic errors and runtime errors mirrors that found in the C++11 standard library, where the <stdexcept> header defines the standard exception base classes std::logic_error and std::runtime_error. The standard exception class std::bad_alloc, on the other hand, is a representative example of a fatal error.

Error codeException classException type
MDB_KEYEXISTlmdb::key_exist_errorruntime
MDB_NOTFOUNDlmdb::not_found_errorruntime
MDB_CORRUPTEDlmdb::corrupted_errorfatal
MDB_PANIClmdb::panic_errorfatal
MDB_VERSION_MISMATCHlmdb::version_mismatch_errorfatal
MDB_MAP_FULLlmdb::map_full_errorruntime
MDB_BAD_DBIlmdb::bad_dbi_errorruntime [16]
(others)lmdb::runtime_errorruntime

Footnotes

note

MDB_KEYEXIST and MDB_NOTFOUND are handled specially by some functions.

Versioning Policy

The lmdb++ version tracks the upstream LMDB release (x.y.z) that it is compatible with, and appends a sub-patch-level version (x.y.z.N) to indicate changes to the wrapper itself.

For example, an lmdb++ release of 0.9.14.2 would indicate that it is designed for compatibility with LMDB 0.9.14, and is the third wrapper release (the first being .0, and the second .1) for that upstream target.

note

To the extent that LMDB will preserve API and ABI compatibility going forward, older versions of the wrapper should work with newer versions of LMDB; and newer versions of the wrapper will generally work with older versions of LMDB by using the preprocessor to conditionalize the visibility of newer symbols–see, for example, the preprocessor guards around the definition of lmdb::env_set_userctx().

Installation

lmdb++ is currently available as a package/port in the following operating system distributions and package management systems:

DistributionPackage NameInstallation Hint
Arch Linux AURliblmdb++yaourt -Sa liblmdb++
Fink [17]lmdb++sudo fink install lmdb++
MacPortslmdbxxsudo port install lmdbxx
Portage [18]lmdb++sudo emerge --ask lmdb++

Footnotes

Support

To report a bug or submit a patch for lmdb++, please file an issue in the issue tracker on GitHub.

Questions and discussions about LMDB itself should be directed to the OpenLDAP mailing lists.

Elsewhere

Find this project at: GitHub, Bitbucket, Open Hub, SourceForge, Travis CI, and Coverity Scan.

The API documentation is published at: http://lmdbxx.sourceforge.net/

Author

Arto Bendiken - http://ar.to/

License

This is free and unencumbered public domain software. For more information, see http://unlicense.org/ or the accompanying UNLICENSE file.

[1] Three-parameter signature available since LMDB 0.9.14 (2014/09/20).

[2] Three-parameter signature available since LMDB 0.9.14 (2014/09/20).

[3] Three-parameter signature available since LMDB 0.9.14 (2014/09/20).

[4] Three-parameter signature available since LMDB 0.9.14 (2014/09/20).

[5] Only available since LMDB 0.9.11 (2014/01/15).

[6] Only available since LMDB 0.9.11 (2014/01/15).

[7] Note the difference in naming. (See below.)

[8] Note the difference in naming. (See below.)

[9] Note the difference in naming. (See below.)

[10] Note the difference in naming. (See below.)

[11] Note the difference in naming. (See below.)

[12] Note the difference in naming. (See below.)

[13] Note the difference in naming. (See below.)

[14] Note the difference in naming. (See below.)

[15] Note the difference in naming. (See below.)

[16] Available since LMDB 0.9.14 (2014/09/20).

[17] Still pending review.

[18] Compatible with Gentoo Linux, Funtoo Linux, and Sabayon Linux.