Documentation

Version information for LMDB. Two potentially different versions can be obtained: lmdb_version returns the version at the time of binding (via C preprocessor macros) and lmdb_dyn_version returns a version for the bound library.

These bindings to Haskell will refuse to open the database when the dynamic version of LMDB is different in the major or minor fields.

Version of LMDB when the Haskell-LMDB binding was compiled.

Version of LMDB linked to the current Haskell process.

LMDB_Error is the exception type thrown in case a function from the LMDB API does not return successfully. Clients should be prepared to catch exceptions from any LMDB operation.

Error codes from MDB. Note, however, that this API for MDB will mostly use exceptions for any non-successful return codes. This is mostly included because I feel the binding would be incomplete otherwise.

(The MDB_SUCCESS return value is excluded.)

Opaque structure for LMDB environment.

The environment additionally contains an MVar to enforce at most one lightweight Haskell thread is writing at a time. This is necessary so long as LMDB uses a long-lived mutex for writes, as in v0.9.10.

Handle for a database in the environment.

Handle for a database in the environment.

This variation is associated with unsafe FFI calls, with reduced overhead but no user-defined comparisons. I expect most code using LMDB could use this variation.

Opaque structure for LMDB transaction.

Identifier for a transaction.

Opaque structure for LMDB cursor.

Opaque structure for a cursor on an MDB_dbi' object. Cursors in this case also use the unsafe FFI calls.

A value stored in the database. Be cautious; committing the transaction that obtained a value should also invalidate it; avoid capturing MDB_val in a lazy value. A safe interface similar to STRef will be provided in another module.

User-defined comparison functions for keys.

Environment flags from lmdb.h

Note: MDB_NOTLS is implicit and enforced for this binding.

compiled write flags, corresponding to a [WriteFlag] list. Used because writes are frequent enough that we want to avoid building from a list on a per-write basis.

compile a list of write flags.

Allocate an environment object. This doesn't open the environment.

After creation, but before opening, please use:

mdb_env_set_mapsize mdb_env_set_maxreaders mdb_env_set_maxdbs

Then, just after opening, you should create all the databases your application will use.

In addition to normal LMDB errors, this operation may throw an MDB_VERSION_MISMATCH if the Haskell LMDB bindings doesn't match the dynamic version. If this happens, you'll need to rebuild the lmdb Haskell package, and ensure your lmdb-dev libraries are up to date.

open or build a database in the filesystem. The named directory must already exist and be writeable. Before opening, be sure to at least apply mdb_env_set_mapsize.

After opening the environment, you should open the databases:

Create the environment. Open a transaction. Open all DBI handles the app will need. Commit the transaction. Use those DBI handles in subsequent transactions

Copy the environment to an empty (but existing) directory.

Note: the LMDB copy operation temporarily grabs the writer mutex. Unfortunately, this greatly complicates the binding to Haskell. This interface, mdb_env_copy, conservatively blocks all writers in the same process for the entire duration of copy.

Recommendation: Don't use this function in the same process with writers. Consider use of the mdb_copy command line utility if you need hot copies.

obtain statistics for environment

obtain ad-hoc information about the environment.

Initiate synchronization of environment with disk. However, if the MDB_NOSYNC or MDB_MAPASYNC flags are active, this won't wait for the operation to finish. Cf. mdb_env_sync_flush.

Force buffered writes to disk before returning.

Close the environment. The MDB_env object should not be used by any operations during or after closing.

Set flags for the environment.

Unset flags for the environment.

View the current set of flags for the environment.

Obtain filesystem path for this environment.

Set the memory map size, in bytes, for this environment. This determines the maximum size for the environment and databases, but typically only a small fraction of the database is in memory at any given moment.

It is not a problem to set this to a very large number, hundreds of gigabytes or even terabytes, assuming a sufficiently large address space. It should be set to a multiple of page size.

The default map size is 1MB, intentionally set low to force developers to select something larger.

Set the maximum number of concurrent readers.

Get the maximum number of concurrent readers.

Set the maximum number of named databases. LMDB is designed to support a small handful of databases.

Key sizes in LMDB are determined by a compile-time constant, defaulting to 511 bytes. This function returns the maximum.

Begin a new transaction, possibly read-only, with a possible parent.

mdb_txn_begin env parent bReadOnly

A read-write transaction should be tethered to a specific Haskell thread, which MUST be a bound thread (via forkOS or runInBoundThread). A read only transaction is not so constrained.

The hierarchical transactions are useful for read-write transactions. They allow trying something out then aborting if it doesn't work. But only one child should be active at a time, all in the same OS thread.

An attempt to grab a writer transaction may block, potentially for a very long time. It's the responsibility of the software architects to ensure there is no need for long-running write operations.

Access environment for a transaction.

Commit a transaction. Don't use the transaction after this.

Abort a transaction. Don't use the transaction after this.

Open a database that supports user-defined comparisons, but has slightly more FFI overhead for reads and writes.

database statistics

review flags from database

close the database handle.

Note: the normal use-case for LMDB is to open all the database handles up front, then hold onto them until the application is closed or crashed. In that case, you don't need to bother with closing database handles.

remove the database and close the handle; don't use MDB_dbi after this

clear contents of database, reset to empty

Set a user-defined key comparison function for a database.

Set a user-defined data comparison operator for MDB_DUPSORT databases.

Access a value by key. Returns Nothing if the key is not found.

Add a (key,value) pair to the database.

Returns False on MDB_KEYEXIST, and True on MDB_SUCCESS. Any other return value results in an exception.

Delete a given key, or a specific (key,value) pair in case of MDB_DUPSORT. This function will return False on a MDB_NOTFOUND result.

Note: Ideally, LMDB would match the value even without MDB_DUPSORT. But it doesn't. Under the hood, the data is replaced by a null ptr if MDB_DUPSORT is not enabled (v0.9.10).

Allocate space for data under a given key. This space must be filled before the write transaction commits. The idea here is to avoid an extra allocation.

mdb_reserve flags txn dbi key byteCount

Note: not safe to use with MDB_DUPSORT. Note: MDB_KEYEXIST will result in an exception here.

compare two values as keys in a database

compare two values as data in an MDB_DUPSORT database

open a cursor for the database.

Low-level mdb_cursor_get operation, with direct control of how pointers to values are allocated, whether an argument is a nullPtr, and so on.

In this case, False is returned for MDB_NOTFOUND (in which case the cursor should not be moved), and True is returned for MDB_SUCCESS. Depending on the MDB_cursor_op, additional values may be returned via the pointers.

Low-level mdb_cursor_put operation.

As with mdb_put, this returns True on MDB_SUCCESS and False for MDB_KEYEXIST, and otherwise throws an exception.

Delete the value at the cursor.

Close a cursor. don't use after this. In general, cursors should be closed before their associated transaction is commited or aborted.

Access transaction associated with a cursor.

Access the database associated with a cursor.

count number of duplicate data items at cursor's current location.

Dump entries from reader lock table.

Check for stale readers, and return number of stale readers cleared.