Mdbx.API

Thin wrappers over the low level API to provide MonadIO support and exception based error handling.

Keys

keyCmp :: MonadIO m => MdbxTxn -> MdbxDbi -> MdbxVal -> MdbxVal -> m Int

Compares two keys and returns -1, 0 or 1 if key1 is lower, equal or greater than key2.

Environment

envOpen :: (MonadIO m, MonadFail m) => String -> MdbxEnvGeometry -> [MdbxEnvFlags] -> m MdbxEnv

Opens an environment.

When using the multi-threaded runtime, the MdbxNotls flag is required at environment creation. Failing to include it in the list of flags will result in a random crash.

envClose :: (MonadIO m, MonadFail m) => MdbxEnv -> m ()

Close an environment.

Transaction

txnBegin :: (MonadIO m, MonadFail m) => MdbxEnv -> Maybe MdbxTxn -> [MdbxTxnFlags] -> m MdbxTxn

Begins a transaction.

txnCommit :: (MonadIO m, MonadFail m) => MdbxTxn -> m ()

Commits a transaction.

txnAbort :: (MonadIO m, MonadFail m) => MdbxTxn -> m ()

Aborts a transaction.

Database

dbiOpen :: (MonadIO m, MonadFail m) => MdbxEnv -> Maybe String -> [MdbxDbFlags] -> m MdbxDbi

Opens a database (table).

dbiClose :: (MonadIO m, MonadFail m) => MdbxEnv -> MdbxDbi -> m ()

Closes a database.

Data manipulation

itemPut :: (MonadIO m, MonadFail m) => MdbxTxn -> MdbxDbi -> MdbxVal -> MdbxVal -> [MdbxPutFlags] -> m ()

Saves the provided key/value pair.

itemGet :: (MonadIO m, MonadFail m) => MdbxTxn -> MdbxDbi -> MdbxVal -> m (Maybe MdbxVal)

Returns the value associated to the given key, if any.

itemDel :: (MonadIO m, MonadFail m) => MdbxTxn -> MdbxDbi -> MdbxVal -> Maybe MdbxVal -> m ()

Deletes the value associated with the given key, if any.

Cursors

cursorOpen :: (MonadIO m, MonadFail m) => MdbxTxn -> MdbxDbi -> m MdbxCursor

Opens a cursor.

cursorClose :: (MonadIO m, MonadFail m) => MdbxCursor -> m ()

Closes a cursor.

cursorPut :: (MonadIO m, MonadFail m) => MdbxCursor -> MdbxVal -> MdbxVal -> [MdbxPutFlags] -> m ()

Stores the provided value at the given key, positioning the cursor on it.

cursorDel :: (MonadIO m, MonadFail m) => MdbxCursor -> [MdbxPutFlags] -> m ()

Deletes the value at the current position.

cursorFirst :: (MonadIO m, MonadFail m) => MdbxCursor -> m (Maybe (MdbxVal, MdbxVal))

Moves to the first key on the database.

cursorLast :: (MonadIO m, MonadFail m) => MdbxCursor -> m (Maybe (MdbxVal, MdbxVal))

Moves to the last key on the database.

cursorAt :: (MonadIO m, MonadFail m) => MdbxCursor -> MdbxVal -> m (Maybe (MdbxVal, MdbxVal))

Moves to the given key.

cursorRange :: (MonadIO m, MonadFail m) => MdbxCursor -> MdbxVal -> m (Maybe (MdbxVal, MdbxVal))

Moves to the given key or first greater than it. Useful for searching.

cursorNext :: (MonadIO m, MonadFail m) => MdbxCursor -> m (Maybe (MdbxVal, MdbxVal))

Moves to the next key.

cursorPrev :: (MonadIO m, MonadFail m) => MdbxCursor -> m (Maybe (MdbxVal, MdbxVal))

Moves to the previous key.

cursorMove :: (MonadIO m, MonadFail m) => MdbxCursor -> MdbxVal -> MdbxCursorOp -> m (Maybe (MdbxVal, MdbxVal))

Moves the cursor using the provided operation.

Conversion for types used in keys

keyFromFloat :: Float -> Word32

Converts a Float value to an unsigned Word that can be used by libmdbx's compare function.

keyFromDouble :: Double -> Word64

Converts a Double value to an unsigned Word that can be used by libmdbx's compare function.

keyFromInt32 :: Int32 -> Word32

Converts a 32bits signed Int value to an unsigned Word that can be used by libmdbx's compare function.

keyFromInt64 :: Int64 -> Word64

Converts a 64bits signed Int value to an unsigned Word that can be used by libmdbx's compare function.

floatFromKey :: Word32 -> Float

Converts an unsigned Word to a Float value.

doubleFromKey :: Word64 -> Double

Converts an unsigned Word to a Double value.

int32FromKey :: Word32 -> Int32

Converts an unsigned Word value to a 32bits signed Int.

int64FromKey :: Word64 -> Int64

Converts an unsigned Word value to a 64bits signed Int.