Environment object, needed for all the operations.

Transaction instance. Needed for all operations with data, even reading.

Database instance. Represents a logical table in the database.

Cursor instance. Used for efficient navigation in a database.

Binary blob representing a key or value in the database.

UNIX permissions to set on created files. Zero value means to open existing, but do not create.

Flags for opening an environment.

Flags for a transaction.

Flags for a database.

Flags for all data related operations.

Flags for cursor operations.

Geometry of the database. The most important parameter is the maximum size, that defaults to 1024Mb. All other values default to -1, meaning the current value will be kept.

Converts an instance to/from the representation needed by libmdbx. This type is used for both keys and values. The fields on the type must be strict, otherwise unexpected crashes due to lazy IO delaying low level memory access may happen.

Only ByteString, Text instances are provided, since they are commonly used as the key when storing/retrieving a value.

For your own types, in general, you will want to use a serialization library such as binary, and apply the newtype deriving via trick.

MdbxItemBinary is provided to simplify using Binary instances as keys or values with libmdbx, while MdbxItemStore provides the same functionality for Store instances. With those helpers, creating custom types compatible with libmdbx is easy:

data User = User {
  _username :: !Text,
  _password :: !Text
} deriving (Eq, Show, Generic, Store)

deriving via (MdbxItemBinary User) instance MdbxItem User

Note 1: if you plan on using a custom type as the key, be careful if it contains Text or ByteString instances, since these types have a length field which is serialized before the data. This causes issues when using libmdbx, since it depends on key ordering and the length field will make shorter instances lower than longer ones, even if the content indicates the opposite. You can use the provided NullByteString or NullText types if your data type is an instance of Binary or Store. Otherwise, it is simpler to use Text or ByteString as the key.

Note 2: If your key type contains Word16 or longer fields, you should make it an instance of Binary, not Store, since Store uses platform dependent endianess and this affects libmdbx's comparison functions. Given Binary uses network order (big endian) for encoding, the comparison functions will work as expected. Failing to do this may cause unexpected issues when retrieving data, in particular when using cursors.

Note 3: The behavior when using signed integers or floating point numbers as part of the key is undefined. To be able to use these types in the key, you should store them as a Word of the appropriate size and convert them with the conversion functions included in API.

Newtype wrapping a ByteString that provides a Binary instance using NULL terminated C strings, which allows for using them as part of a custom data type representing a key.

This is not possible with regular ByteString and Text instances since their Binary instances are serialized with the size field first. Given that libmdbx compares keys as an unstructured sequence of bytes, this can cause issues since longer strings are considered greater than shorter ones, even if their content indicates otherwise.

Newtype wrapping a Text that provides a Binary instance using NULL terminated C strings, which allows for using them as part of a custom data type representing a key.

Check NullByteString for the rationale.