LMDBAL - Lightning Memory Data Base Abstraction Level

LMDBAL is a thin C++17 wrapper around LMDB that plays nicely with Qt. Storages are declared with templates, transactions are handled via RAII helpers, and the LMDB environment stays open only for as long as you keep an active session.

Prerequisites

• a C++17 compiler (GCC or Clang are tested);
• Qt 5 or 6 Core module (qt5-base or qt6-base);
• LMDB development headers and runtime library;
• CMake 3.16 or higher;
• Doxygen (optional, for documentation);
• GoogleTest (optional, for tests).

Using with CMake

As a system library

If you're using LMDBAL as a system library, you probably have no control over its build options. The easiest way to include the project is to add the following:

find_package(lmdbal CONFIG REQUIRED)
target_link_libraries(yourTarget PRIVATE LMDBAL::LMDBAL)

If you overrode LMDBAL_NAME while building the package, use ${LMDBAL_NAME}::${LMDBAL_NAME} instead of LMDBAL::LMDBAL.

As an embedded subproject

If you're using LMDBAL as an embedded library, you might want to control its build options, for example, you can run

set(LMDBAL_BUILD_STATIC ON CACHE BOOL "" FORCE)

... before including the library in your project. This will build the library as a static one.

Then you want to run something like this:

add_subdirectory(pathTo/yourEmbedded/libraries/lmdbal)
add_library(LMDBAL::LMDBAL ALIAS LMDBAL)    # optional

target_link_libraries(yourTarget PRIVATE LMDBAL::LMDBAL)

The headers are already exported as PUBLIC, so you usually do not need an extra target_include_directories call.

Usage

Creating a database no longer flips the environment into the opened state immediately.
LMDBAL::Base::open() returns a LMDBAL::Session object that keeps the environment alive while it exists.
Destroying the session (or calling session.close()) closes the database and aborts any remaining public transactions.

#include "base.h"
#include "storage.h"
#include "session.h"

LMDBAL::Base base(QDir(QDir::tempPath()).absoluteFilePath("myDataBase"));
auto* storage = base.addStorage<uint32_t, uint32_t>("storage");

LMDBAL::Session session = base.open();
storage->addRecord(54, 75);

session.close();  // optional – calling it explicitly can surface errors early

The first constructor argument is the directory path. Optionally provide a second QString for a human-readable name; if you omit it, the path is reused.

Make sure every storage or cache is registered before you open the database. addStorage accepts an optional duplicates flag when the same key may appear multiple times:

auto* withDuplicates = base.addStorage<int, int>("storageWithDuplicates", true);

Write operations can be grouped inside transactions:

#include "transaction.h"

LMDBAL::WriteTransaction txn = base.beginTransaction();
storage->addRecord(1, 2, txn);
storage->addRecord(3, 4, txn);
txn.commit();

Read-only access can be obtained through LMDBAL::Base::beginReadOnlyTransaction() to keep a stable snapshot while writers are active.

If Qt needs a specific QDataStream version to stay compatible with older releases, pick it at compile time:

#define LMDBAL_QDATASTREAM_VERSION_VALUE QDataStream::Qt_5_15
#include "base.h"

Alternatively provide a custom hook with #define LMDBAL_CUSTOM_QDATASTREAM_APPLY(stream) or disable the call entirely using #define LMDBAL_DISABLE_QDATASTREAM_VERSIONING before including LMDBAL headers.

Building

LMDBAL uses CMake as a build system.

Please check the prerequisites and install them before building.

Here is an easy way to build the project:

$ git clone https://git.macaw.me/blue/lmdbal
$ cd lmdbal
$ mkdir build
$ cd build
$ cmake .. [ *optional keys* ]
$ cmake --build .
$ cmake --install . --prefix install

This will create a lmdbal/build directory with intermediate files, and lmdbal/build/install with everything ready to be installed into your system.

After cmake .. you can specify keys to alter the building process.
In this context building keys are transferred like so:

cmake .. -D KEY1=VALUE1 -D KEY2=VALUE2 ...

List of keys

Here is the list of keys you can pass to configuration phase of cmake ..:

• CMAKE_BUILD_TYPE - Debug builds with symbols and run-time checks, Release builds with optimizations (default is Debug);
• LMDBAL_BUILD_STATIC - ON builds a static library, OFF builds a shared library (default is OFF);
• LMDBAL_BUILD_TESTS - ON builds unit tests, OFF skips them (default is OFF);
• LMDBAL_BUILD_DOC_MAN - ON builds the man page documentation (default is OFF);
• LMDBAL_BUILD_DOC_HTML - ON builds the HTML documentation (default is OFF);
• LMDBAL_BUILD_DOC_XML - ON builds the XML documentation (default is OFF);
• LMDBAL_BUILD_DOXYGEN_AWESOME - ON builds the Doxygen Awesome theme if any documentation is enabled (default is OFF);
• QT_VERSION_MAJOR - 5 links against Qt5, 6 links against Qt6, if not specified CMake tries to pick the best match;
• LMDBAL_NAME - overrides the main target name, the install directory will follow the lowercase version (useful for packaging variants like LMDBAL-QT6);
• LMDBAL_STRICT - ON enables extra warnings and treats them as errors (default is OFF);
• LMDBAL_ASAN - ON enables address sanitizer (GNU/Clang only, default is OFF);
• LMDBAL_TSAN - ON enables thread sanitizer (GNU/Clang only, default is OFF);
• LMDBAL_UBSAN - ON enables undefined behavior sanitizer (GNU/Clang only, default is OFF).

Running tests

If you built the library with -D LMDBAL_BUILD_TESTS=ON, then there will be a lmdbal/build/test/runUnitTests executable file. You can run it as

./test/runUnitTests

... if you're in the same directory with it. The tests assume they can create cache files under the current user's cache directory (QStandardPaths::CacheLocation), so adjust XDG_CACHE_HOME if your environment has that location locked down.

License

This project is available under the GPL-3.0 license or any later version. The file cmake/FindLMDB.cmake is available under the GPL-3.0 license only — see the LICENSE.md file for details.