LMDB_File(3pm)

📦

version 0.14 · 8 versions

okay bestie, this is LMDB_File(3pm) from the User Contributed Perl Documentation, and we're about to get you tied to LMDB in the comfiest way possible 💖

✨ NAME ✨

LMDB_File — Tie to LMDB (OpenLDAP's Lightning Memory-Mapped Database) 🌈

🎀 SYNOPSIS 🎀

so there are two vibes here, bestie: the quick-and-easy tie interface for when you're in a rush, and the full-power OO interface for when you're ready to be the main character 👑

# Simple TIE interface, when you're in a rush
use LMDB_File;

$db = tie %hash, 'LMDB_File', $path;

$hash{$key} = $value;
$value = $hash{$key};
each %hash;
keys %hash;
values %hash;
...

# The full power
use LMDB_File qw(:flags :cursor_op);

$env = LMDB::Env->new($path, {
    mapsize => 100 * 1024 * 1024 * 1024, # Plenty space, don't worry
    maxdbs => 20, # Some databases
    mode   => 0600,
    # More options
});

$txn = $env->BeginTxn(); # Open a new transaction

$DB = $txn->OpenDB( {    # Create a new database
    dbname => $dbname,
    flags => MDB_CREATE
});

$DB->put($key, $value);  # Simple put
$value = $DB->get($key); # Simple get

$DB->put($key, $value, MDB_NOOVERWITE); # Don't replace existing value

# Work with cursors
$cursor => $DB->Cursor;

$cursor->get($key, $value, MDB_FIRST); # First key/value in DB
$cursor->get($key, $value, MDB_NEXT);  # Next key/value in DB
$cursor->get($key, $value, MDB_LAST);  # Last key/value in DB
$cursor->get($key, $value, MDB_PREV);  # Previous key/value in DB

$DB->set_compare( sub { lc($a) cmp lc($b) } ); # Use my own key comparison function

🌸 DESCRIPTION 🌸

NOTE: This document is still under construction. Expect it to be incomplete in places. 🚧

LMDB_File is a Perl module that lets your Perl programs make use of all the facilities provided by OpenLDAP's Lightning Memory-Mapped Database, aka "LMDB" ✨

LMDB is a Btree-based database management library, lowkey modeled on the BerkeleyDB API, but much simplified and extremely fast 🔥

it's assumed that you have a copy of LMBD's documentation at hand while you're reading this, bestie. the interface defined here mirrors the C interface super closely, just with an OO approach 💅

this is implemented with a number of Perl classes:

A LMDB's environment handler (MDB_env* in C) will be wrapped in the LMDB::Env class.
A LMDB's transaction handler (MDB_txn* in C) will be wrapped in the LMDB::Txn class.
A LMDB's cursor handler (MDB_cursor* in C) will be wrapped in the LMDB::Cursor class.
A LMDB's Database handler (MDB_dbi in C) will be exposed as a simple integer, but because in LMDB all Database operations needs both a Transaction and a Database handler, LMDB_File provides you a convenient "LMDB_File" object that encapsulates both and mimic the syntax of other *_File modules.

💖 Error reporting 💖

In the C API, most functions return 0 on success and an error code on failure.

In this module, when a function fails, the package variable $die_on_err controls the course of action. When $die_on_err is set to TRUE, this causes LMDB_File to "die" with an error message that can be trapped by an eval { ... } block.

When FALSE, the function will return the error code, in this case you should check the return value of any function call.

By default $die_on_err is TRUE.

Regardless of the value of $die_on_err, the code of the last error can be found in the package variable $last_err. 🫶

👑 LMDB::Env

Okay so this class is literally the glow-up wrapper around an opened LMDB environment. That's the whole vibe.

When you construct it, the environment gets created (if it doesn't already exist) and opened. Two-for-one. Iconic.

Now, in the C API, when you're done you must call the mdb_env_close function to close it and free the memory that got allocated. But in Perl? Bestie, you just let the object fall out of scope. That's it. The garbage collector is your bestie fr fr 🫶.

🎀 Constructor

$Env = LMDB::Env->new ( $path [, ENVOPTIONS ] )

Creates a new LMDB::Env object and hands it back to you. It's doing double duty — it wraps both LMDB's mdb_env_create AND mdb_env_open functions. One call, two C functions, zero stress.

$path is the directory where the database files live. Heads up: this directory has to already exist, and it should be writable. No, it won't make it for you. Do that yourself, queen 🌸.

ENVOPTIONS, if you pass it, has to be a HASH Reference — and it can contain any of these:

mapsize => INT — the size of the memory map to use for this environment. And plot twist: the size of the memory map is also the maximum size of the database 💀. So pick it as big as you possibly can, because it needs to accommodate future growth of the database. Also, the size should be a multiple of the OS page size. The default is 1048576 bytes (1 MB).
maxreaders => INT — the maximum number of threads/reader slots for the environment. This is what defines the number of slots in the lock table that's used to track readers in the environment. The default is 126.
maxdbs => INT — the maximum number of named databases for the environment. You only need this if you're gonna use multiple databases inside the environment. Simpler apps that just use the environment as a single unnamed database can straight up ignore this option. The default is 0, i.e. no named databases allowed. Zero. None. Nada.
mode => INT — the UNIX permissions to set on created files. This parameter gets ignored on Windows (sorry Windows girlies 😭). It defaults to 0600.
flags => ENVFLAGS — set special options for this environment. If you provide it, you can specify it by OR'ing the following flags together:
- MDB_FIXEDMAP — use a fixed address for the mmap region. This flag must be specified when creating the environment, and it's stored persistently in the environment. If it works, the memory map will always live at the same virtual address and pointers used to reference data items in the database will be constant across multiple invocations. But — and this is a big but — this option may not always work, depending on how the operating system has allocated memory to shared libraries and other uses. Also the feature is highly experimental. You've been warned bestie 🙈.
- MDB_NOSUBDIR — by default, LMDB creates its environment in a directory whose pathname is given in $path, and it creates its data and lock files inside that directory. With this option, $path is used as-is for the database main data file. And the database lock file is just the $path with -lock appended onto it.
- MDB_RDONLY — open the environment in read-only mode. No write operations will be allowed. Periodt. LMDB will still modify the lock file though — except on read-only filesystems, where LMDB doesn't use locks at all.
- MDB_WRITEMAP — use a writeable memory map unless MDB_RDONLY is set. This is faster and it uses fewer mallocs, but you lose the protection from application bugs like wild pointer writes and other bad updates wandering into the database. Not compatible with nested transactions (also known as sub transactions). ✨
- MDB_NOMETASYNC — flush system buffers to disk only once per transaction, and omit the metadata flush. Defer that until the system flushes files to disk, or until the next non-MDB_RDONLY commit or $Env->sync(). This optimization maintains database integrity, but a system crash may undo the last committed transaction. I.e. it preserves the ACI (atomicity, consistency, isolation) but not D (durability) database property. This flag may be changed at any time using $Env->set_flags().
- MDB_NOSYNC — don't flush system buffers to disk when committing a transaction. This optimization means a system crash can corrupt the database or lose the last transactions if buffers haven't been flushed to disk yet 😭. The risk here is governed by how often the system flushes dirty buffers to disk and how often $Env->sync() is called. However, if the filesystem preserves write order and the MDB_WRITEMAP flag is not used, transactions exhibit ACI (atomicity, consistency, isolation) properties and only lose D (durability). I.e. database integrity is maintained, but a system crash may undo the final transactions. Note that MDB_NOSYNC | MDB_WRITEMAP leaves the system with no hint for when to write transactions to disk, unless $Env->sync() is called. MDB_MAPASYNC | MDB_WRITEMAP) may be preferable. This flag may be changed at any time using $Env->set_flags().
- MDB_MAPASYNC — when using MDB_WRITEMAP, use asynchronous flushes to disk. As with MDB_NOSYNC, a system crash can then corrupt the database or lose the last transactions. Calling $Env->sync() ensures on-disk database integrity until the next commit. This flag may be changed at any time using $Env->set_flags().
- MDB_NOTLS — don't use Thread-Local Storage. Tie reader locktable slots to LMDB::Txn objects instead of to threads. I.e. $Txn->reset() keeps the slot reserved for the LMDB::Txn object. A thread may use parallel read-only transactions. A read-only transaction may span threads if the user synchronizes its use. Applications that multiplex many user threads over individual OS threads need this option. Such an application must also serialize the write transactions in an OS thread, since LMDB's write locking is completely unaware of the user threads.

💅 Class methods

$Env->copy ( $path ) — copy an LMDB environment to the specified $path.
$Env->copyfd ( HANDLE ) — copy an LMDB environment to the specified HANDLE.
$status = $Env->stat — returns a HASH reference with statistics for the main, unnamed, database in the environment. That HASH contains the following keys:
- psize — Size of a database page.
- depth — Depth (height) of the B-Tree
- branch_pages — Number of internal (non-leaf) pages
- overflow_pages — Number of overflow pages
- entries — Number of data items
$info = $Env->info — returns a HASH reference with information about the environment, $info, with the following keys:
- mapaddr — Address of map, if fixed
- mapsize — Size of the data memory map
- last_pgno — ID of the last used page
- last_txnid — ID of the last committed transaction
- maxreaders — Max reader slots in the environment
- numreaders — Max reader slot used in the environment
$Env->sync ( BOOL ) — flush the data buffers to disk. Data is always written to disk when $Txn->commit() is called, but the operating system may keep it buffered. LMDB always flushes the OS buffers upon commit as well, unless the environment was opened with MDB_NOSYNC or in part MDB_NOMETASYNC. If BOOL is TRUE, force a synchronous flush. Otherwise, if the environment has the MDB_NOSYNC flag set, the flushes will be omitted — and with MDB_MAPASYNC they'll be asynchronous.
$Env->set_flags ( BITMASK, BOOL ) — as noted above, some environment flags can be changed at any time. BITMASK is the flags to change, bitwise OR'ed together. BOOL TRUE sets the flags, FALSE clears them.
$Env->get_flags ( $flags ) — returns in $flags the environment flags.
$Env->get_path ( $path ) — returns in $path the path that was used in LMDB::Env->new(...).
$Env->get_maxreaders ( $readers ) — returns in $readers the maximum number of threads/reader slots for the environment.
$mks = $Env->get_maxkeysize — returns the maximum size of a key for the environment.
$Txn = $Env->BeginTxn ( [ $tflags ] ) — returns a new Transaction. A simple wrapper over the constructor of LMDB::Txn. If provided, $tflags gets passed to the constructor; if it's not provided, this wrapper will propagate the environment's flag MDB_RDONLY, if it's set, to the transaction constructor. Obsessed with the convenience tbh 🦋.

✨ LMDB::Txn ✨

okay so bestie, here's the whole vibe: in LMDB, every operation (read or write) on a Database has to happen inside a transaction. Like, no transaction = no entry, periodt. 💅 This class is the wrapper around an LMDB transaction.

You must close out the transaction by calling either abort or commit. Once it's terminated, do not call any other method on it — except env. That's the one exception, okay? Don't test it. 🫶

And if you just let the object fall out of scope? By default, the transaction gets aborted. Yeah. It aborts itself. 😭 (Unless you've been messing with AutoCommit, we'll get there.)

🌸 Constructor 🌸

$Txn = LMDB::Txn->new ( $Env [, $tflags ] )

Makes you a brand-new transaction to use inside the environment. Easy. 🧚

👑 Class methods 👑

`$Txn->abort`

Abort the transaction — and bam, that terminates it. Done, dusted. 🌈

`$Txn->commit`

Commit the transaction — also terminates it, but this time the changes actually stay. Slay. ✨

`$Txn->reset`

Reset a read-only transaction.

So this aborts the transaction exactly like $Txn->abort() does, BUT it keeps the transaction handle sitting there in an inactive state so that $Txn->renew() can wake it back up. 💤➡️🔥

Why would you do that? Two reasons, and they're both about being efficient:

it saves allocation overhead if the process is gonna start a new read-only transaction real soon, and
it saves locking overhead if MDB_NOTLS is in use.

The reader table lock gets released, but the table slot stays tied to its thread or Transaction. Remember that. 🎀

When you're actually done with a reseted handle, use $Txn->abort() to discard it and to free its lock table slot if MDB_NOTLS is in use.

`$Txn->renew`

Renew a read-only transaction.

This grabs a fresh reader lock for a transaction handle that got inactivated by $Txn->reset(). It must be called before an inactive (reseted) transaction can be used again. No skip. ⚠️

And here's a lil Perl-specific detail just for you 🫶 — in this Perl implementation, if you call $Txn->renew() on a transaction that's still active, the method internally calls $Txn->reset() for you first. Convenient? Yes. Surprising? Also yes. 😭

`$Env = $Txn->env`

Returns the environment (an LMDB::Env object) that created the transaction — if it's still alive. If you call this on a terminated transaction, you get undef. 💀

`$SubTxn = $Txn->SubTxn ( [ $tflags ] )`

Creates and hands you a sub transaction — a.k.a. a nested transaction. 🪆

Why are these iconic? Because they're how you combine components that each want to create and commit their own transactions. Not a single modification is permanently stored until the highest level parent transaction gets committed. Nothing. Zero. Zilch.

The good news: nested transactions can be aborted without aborting the parent, and only the changes made inside that nested transaction get rolled back. Cute, right? 💖

The rest of the rules:

Aborting the parent transaction will abort and terminate all outstanding nested transactions.
Committing the parent transaction will, similarly, commit and terminate all outstanding nested transactions.

And unlike some other databases 👀 — in LMDB, changes made inside nested transactions are not visible to the parent transaction until the nested transaction is committed. Which is a whole way of saying: transactions are always isolated, even when they're nested. Periodt.

`$Txn->AutoCommit ( [ BOOL ] )`

When you pass a BOOL, this sets what the transaction does when it goes out of scope:

BOOL TRUE → makes arrangements for the transaction to be auto committed ✨
BOOL FALSE → back to the default behavior, which is to be aborted 💀

If you don't pass a BOOL, then you're just here for the gossip — you only wanna know the current value of this option, and it gets returned in every case. 👀

`$DB = $Txn->OpenDB ( [ DBOPTIONS ] )`

`$DB = $Txn->OpenDB ( [ $dbname [, DBFLAGS ]] )`

Opens a Database in the environment and returns an LMDB_File object that encapsulates both the Transaction and the Database handler. Two for one, bestie. 🫶

This is a convenience shortcut for:

LMDB_File->new( $Txn, $Txn->open(...) )

...for when you wanna use the hi-level LMDB_File's OO approach. Fancy.

DBOPTIONS, if you provide it, should be a HASH reference with any of these keys:

dbname => $dbname
flags => DBFLAGS

You can also just call this method with its values, $dbname and DBFLAGS, documented right ahead. ⬇️

`$dbi = $Txn->open ( [ $dbname [, DBFLAGS ]] )`

This one opens a Database in the environment and returns the low level Database handler, which is an integer. No OO, just a number. Raw. 🔥

If you pass $dbname, that'll be the name of a named Database in the environment. If you don't pass it (or if $dbname is undef), the opened Database will be the unnamed (the default) one.

DBFLAGS, if provided, sets special options for this Database, and you specify them by OR'ing together these flags:

MDB_REVERSEKEY — Keys are strings to be compared in reverse order.
MDB_DUPSORT — Duplicate keys may be used in the database. (Or, from another perspective, keys may have multiple data items, stored in sorted order.) By default keys must be unique and may have only a single data item.
MDB_INTEGERKEY — Keys are binary integers in native byte order.
MDB_DUPFIXED — This flag may only be used in combination with #MDB_DUPSORT. It tells the library that the data items for this database are all the same size, which allows further optimizations in storage and retrieval. When all data items are the same size, the #MDB_GET_MULTIPLE and #MDB_NEXT_MULTIPLE cursor operations may be used to retrieve multiple items at once. 🎀
MDB_INTEGERDUP — Duplicate data items are also integers, and should be sorted as such.
MDB_REVERSEDUP — Duplicate data items should be compared as strings in reverse order.
MDB_CREATE — Create the named database if it doesn't exist. This option is not allowed in a read-only transaction or a read-only environment. 🚫 After you successfully commit the transaction that created the Database, it stays opened in the Environment, so you can reuse $dbi in other transactions. Recycle that handle, bestie. ♻️

If you're gonna need that Database handler in more than one transaction, or you just want the more traditional (in LMDB's point of view) approach, this is the method you should use.

To actually operate on the opened database with the returned $dbi handler, you can use the methods described below ⬇️, or call LMDB_File->new(...) to get yourself an LMDB_File object and operate the database in a particular transaction.

`$Txn->put ( $dbi, $key, $data [, WRITEFLAGS [, $length ] )`

Store items into the database $dbi. 💾

Provided for when your main concern is raw speed. Zoom zoom. 🏎️

For details on the other arguments, go peep the method of the same name in LMDB_File below.

`$Txn->get ( $dbi, $key, $data )`

Get items from the database $dbi.

Also provided for when your main concern is raw speed. Same deal.

For details on the other arguments, again — method of the same name in LMDB_File below. 👇

`$Txn->id ()`

Returns the transaction's ID. 🪪

This is the identifier associated with this transaction. For a read-only transaction, it corresponds to the snapshot being read — which means concurrent readers will frequently have the same transaction ID. Not a bug, just how it be. ✨

🦋 LMDB_File 🦋

So in the LMDB C API, all Database operations need both an active Transaction and a Database handler. Keeping track of two things? Exhausting. 😮‍💨 So to simplify all that and stay syntax compatible with the other *_File modules, this Perl API gives you an LMDB_File object that encapsulates both, plus it implements some hi-level extensions. Iconic behavior, honestly.

And heads up 🫶 — LMDB_File's methods, in contrast to LMDB::Txn's methods of the same name, do some checks before calling the low-level C API. So they're the safe, hand-holding version. No cap.

🎀 Constructors 🎀

`$DB = LMDB_File->new( $Txn, $dbi )`

Associates a Transaction $Txn with a previously opened Database handler $dbi, so you can use this OO API. Matchmaker energy. 💖

`$DB = LMDB_File->open ( $Txn [, $dbname [, DBFLAGS ] ] )`

An alternative to $Txn->OpenDB(...) — opens a Database and associates it with a Transaction in a single call. One and done. 🌸

⭐ Class methods ⭐

`$DB->put ( $key, $data [, WRITEFLAGS [, $length ] ] )`

Store items into a database. 💾

This function stores key/data pairs in the database. The default behavior is to enter the new key/data pair, replacing any previously existing key if duplicates are disallowed, or adding a duplicate data item if duplicates are allowed.

$key is the key to store in the database, and $data is the data to store.

WRITEFLAGS, if provided, sets special options for this operation, and it can be one of these flags:

MDB_NODUPDATA — Enter the new key/data pair only if it does not already appear in the database. This flag may only be specified if the database was opened with #MDB_DUPSORT. The function will fail with MDB_KEYEXIST if the key/data pair already appears in the database.
MDB_NOOVERWRITE — Enter the new key/data pair only if the key does not already appear in the database. The function will return MDB_KEYEXIST if the key already appears in the database — even if the database supports duplicates (#MDB_DUPSORT). The $data parameter will be set to the existing item. So you get the old one back. Surprise gift. 🎁
MDB_RESERVE — Reserve space for data of the given size in $length, but don't copy anything. Instead, return in $data a magical scalar with a pointer to the reserved space 🪄, which the caller can fill in later — but before the next update operation or the transaction ends. This saves an extra memcpy if the data is being generated later. In this particular case, you need to pass the extra $length parameter to specify how many bytes to reserve. Please read about the $DB->ReadMode method caveats below for details that apply to the magical scalar returned in $data in this case. No, seriously, read them. 🙈
MDB_APPEND — Append the given key/data pair to the end of the database. No key comparisons are performed. This option allows fast bulk loading when the keys are already known to be in the correct order. ⚡

NOTE: Loading unsorted keys with this flag will cause data corruption. Like, actually. Do not. 💀

MDB_APPENDDUP — As above, but for sorted duplicated data.

`$DB->get ( $key, $data )`

`$data = $DB->get ( $key )`

Get items from a database.

This method retrieves key/data pairs from the database. 🎣

If the database supports duplicate keys (#MDB_DUPSORT), then the first data item for the key will be returned. Retrieval of other items requires the use of the LMBD::Cursor->get() method. Yeah, you need the cursor for the rest. 🖱️

The two-argument form — closer to the C API — returns in the provided argument $data the value associated with $key in the database if it exists, or reports an error if not. Simple as that. ✨

In the simpler, more "perlish" one-argument form, the method returns the value associated with $key in the database or undef if no such value exists. bestie literally just hands you the value, or hands you nothing, no drama 💅

`$DB->del ( $key [, $data ] )`

Delete items from the database. bye felicia 👋

This function removes key/data pairs from the database.

If the database does not support sorted duplicate data items, (MDB_DUPSORT) the $data parameter is optional and is ignored. (it rly does not care)
If the database supports sorted duplicates and the $data parameter is undef or not provided, all of the duplicate data items for the $key will be deleted. Otherwise, if the $data parameter is provided, only the matching data item will be deleted.

`$DB->set_compare ( CODE )`

Set a custom key comparison function referenced by CODE for a database.

CODE should be a subroutine reference or an anonymous subroutine, that like Perl's sort in perlfunc, will receive the values to compare in the global variables $a and $b. iconic teamwork fr fr 🫶

The comparison function is called whenever it is necessary to compare a key specified by the application with a key currently stored in the database. If no comparison function is specified, and no special key flags were specified in LMDB_File->open(), the keys are compared lexically, with shorter keys collating before longer keys.

Warning: This function must be called before any data access functions are used, otherwise data corruption may occur 😭💀. The same comparison function must be used by every program accessing the database, every time the database is used. no cap, everybody gotta agree on this one.

`$flags = $DB->flags`

Retrieve the DB flags for the associated database. little peek at the settings 🎀

`$status = $DB->stat`

Returns a HASH reference with statistics for the associated database, the hash will contain the following keys:

psize — Size of a database page.
depth — Depth (height) of the B-Tree
branch_pages — Number of internal (non-leaf) pages
overflow_pages — Number of overflow pages
entries — Number of data items

`$DB->drop( [ REMOVE ] )`

If REMOVE isn't provided or FALSE, the database is emptied. If REMOVE is TRUE the database is closed and removed from the Environment. choose your fighter 🥊

`$DB->Alive`

Returns a TRUE value if the associated transaction is still alive, i.e. not commited nor aborted yet, and FALSE otherwise. vibe check on ur txn ✅

`$Cursor = $DB->Cursor`

Creates a new LMDB::Cursor object to work in the database, see LMDB::Cursor. new bestie unlocked 🦋

`$txn = $DB->Txn`

Returns the transaction, an LMDB::Txn object, associated with $DB.

    $DB->Txn->commit; # Commit the current transaction.

If the method $DB->Alive has returned FALSE before, this method will return undef. (oof, ghosted)

You can use $DB->Txn as an lvalue to change the associated Transaction, but remember that, if $DB is holding the last reference of the current transaction, that transaction will be terminated.

    $DB->Txn->commit; # Commit current
    $DB->Alive;       # FALSE
    ...
    $DB->Txn = $Env->BeginTxn; # Start another, with same Database
    ...

`$dbi = $DB->dbi`

Returns the low level Database handler associated with $DB

You can use $DB->dbi as an lvalue to switch the associated Datbase hander:

  $DB->dbi = $other_dbi;

`$DB->ReadMode ( [ MODE ] )`

This method allows you to modify the behavior of get (read) operations on the database.

The C documentation for the mdb_get function states that:

  The memory pointed to by the returned values is owned by the
  database. The caller need not dispose of the memory, and may not
  modify it in any way. For values returned in a read-only transaction
  any modification attempts will cause a SIGSEGV.

So this module implements two modes of operation for its get methods and you can select between them with this method.

When MODE is 0 (or any FALSE value) a default "safe" mode is used in which the data value found in the database is copied to the scalar returned, so you can do anything you want to that scalar without side effects. do whatever, it's yours 💖

But when MODE is 1 (or, in the current implementation, any TRUE value) a sort of hack is used to avoid the memory copy and a magical scalar returned that hold only a pointer to the data value found. This is much faster and uses less memory, especially when used with large values. zero-copy slay ✨

In a environment opened with MDB_WRITEMAP and in a transaction without the MDB_RDONLY flag, you are allowed to modify the returned scalar, and the modifications are reflected to the associated memory block and preserved in the database when the transaction is commited. Otherwise the magical scalar is marked READ-ONLY and any attempt to modify it (other than reuse it in another $DB->get), will cause perl to croak. 🙈

CAVEATS: In a read-only transaction the value is valid only until the end of the transaction, and in a read-write transaction the value is valid only until the next write operation (because any write operation can potentially modify the in-memory btree). In the current implementation, you are responsible for the proper timing of usage. keep an eye on the clock bestie ⏰

NOTE: In order to achieve the zero-copy behavior desired by setting ReadMode to TRUE, you must use the two-argument form of get ($DB->get ( $key, $data )), use the new $DB->Rget( $key ) or use the cursor get method described below.

`$DB->UTF8 ( [ MODE ] )`

Instructs LDMB_File to use the UTF-8 encoding for the associated database when MODE is 1 or revert to raw bytes when 0.

Returns the previous value.

By default, all values in LMDB are simple byte buffers of certain fixed length.

So if you are storing binary data in your database all works as expected: what you put is what you get. 💯

But when you need to store some arbitrary Unicode text value, remember that internally perl stores your strings in either the native eight-bit character set or in UTF-8, and to warrant a consistent encoding in your database you should do something like:

    use Encoding;
    ...

    $DB->put($key, Encode::encode($my_encoding, $characters));

    $characters = Encode::decode($my_encoding, $DB->get($key));

For any value of $my_encoding, see Encode for the gory details. the gory details ikyk 😭

But if you use for interchange the UTF-8 encoding, with this method you can avoid all that typing. lazy girl win 🎀

When MODE is 1, all values that you put in the Database will be encoded in UTF-8, And all get calls will expect UTF-8 data and it will be verified and decoded. In this mode, if malformed data is found, a warning will be emitted, the decode attempt aborted and the raw bytes returned. graceful little bail-out

In this mode, a $foo->get(...) call interacts with the bytes pragma in a special way: In the lexical scope under the effects of use bytes, any get call skips the decode step, returning the fetched encoded UTF-8 data as bytes, i.e. with the internal perl UTF8 flag off, as expected by modules like JSON::XS. 🌈

🌸 LMDB::Cursor 🌸

To construct a cursor you should call the Cursor method of the LMDB_File class:

 $cursor = $DB->Cursor

✨ Class methods ✨

`$cursor->get($key, $data, CURSOR_OP)`

This function retrieves key/data pairs from the database.

The variables $key and $data are used to return the values found.

CURSOR_OP determines the key/data to be retrieved and must be one of the following:

MDB_FIRST — Position at first key/data item.
MDB_FIRST_DUP — Position at first data item of current key. Only for MDB_DUPSORT
MDB_GET_BOTH — Position at key/data pair. Only for MDB_DUPSORT
MDB_GET_BOTH_RANGE — Position at key, nearest data. Only for MDB_DUPSORT
MDB_GET_CURRENT — Return key/data at current cursor position.
MDB_GET_MULTIPLE — Return all the duplicate data items at the current cursor position. Only for MDB_DUPFIXED
MDB_LAST — Position at last key/data item.
MDB_LAST_DUP — Position at last data item of current key. Only for MDB_DUPSORT
MDB_NEXT — Position at next data item.
MDB_NEXT_DUP — Position at next data item of current key. Only for MDB_DUPSORT
MDB_NEXT_MULTIPLE — Return all duplicate data items at the next cursor position. Only for MDB_DUPFIXED
MDB_NEXT_NODUP — Position at first data item of next key.
MDB_PREV — Position at previous data item.
MDB_PREV_DUP — Position at previous data item of current key. Only for MDB_DUPSORT
MDB_PREV_NODUP — Position at last data item of previous key.
MDB_SET — Position at specified key.
MDB_SET_KEY — Position at specified key, return key + data.
MDB_SET_RANGE — Position at first key greater than or equal to specified key.

`$cursor->put($key, $data, WRITEFLAGS)`

This function stores key/data pairs into the database.

If the function succeeds and an item is inserted into the database, the cursor is always positioned to refer to the newly inserted item. 🫶

If the function fails for any reason, the state of the cursor will undetermined. (undetermined, bestie — do not trust it)

NOTE: Earlier documentation incorrectly said errors would leave the state of the cursor unchanged. that was a lie, we don't do that here 📢

`$cursor->del( [ DELFLAGS ] )`

This function deletes the key/data pair to which the cursor refers.

If the database was opened with MDB_DUPSORT, the optional parameter DELFLAGS can be MDB_NODUPDATA to deletes all of the data items for the current key. (yes, "to deletes" — we keep it exactly as written, periodt) 💅

✨ Exportable constants ✨

At use time you can import into your namespace the following constants, grouped by their tags. (Turns out tags are the moment, bestie 💅)

🌸 Environment flags `":envflags"`

MDB_FIXEDMAP
MDB_NOSUBDIR
MDB_NOSYNC
MDB_RDONLY
MDB_NOMETASYNC
MDB_WRITEMAP
MDB_MAPASYNC
MDB_NOTLS

🍓 Data base flags `":dbflags"`

MDB_REVERSEKEY
MDB_DUPSORT
MDB_INTEGERKEY
MDB_DUPFIXED
MDB_INTEGERDUP
MDB_REVERSEDUP
MDB_CREATE

🔥 Write flags `":writeflags"`

MDB_NOOVERWRITE
MDB_NODUPDATA
MDB_CURRENT
MDB_RESERVE
MDB_APPEND
MDB_APPENDDUP
MDB_MULTIPLE

👑 All flags `":flags"`

All of ":envflags", ":dbflags" and ":writeflags" — literally the whole squad, no one left out, we love a complete set 🫶

🦋 Cursor operations `":cursor_op"`

MDB_FIRST
MDB_FIRST_DUP
MDB_GET_BOTH
MDB_GET_BOTH_RANGE
MDB_GET_CURRENT
MDB_GET_MULTIPLE
MDB_NEXT
MDB_NEXT_DUP
MDB_NEXT_MULTIPLE
MDB_NEXT_NODUP
MDB_PREV
MDB_PREV_DUP
MDB_PREV_NODUP
MDB_LAST
MDB_LAST_DUP
MDB_SET
MDB_SET_KEY
MDB_SET_RANGE

💀 Error codes `":error"`

MDB_SUCCESS
MDB_KEYEXIST
MDB_NOTFOUND
MDB_PAGE_NOTFOUND
MDB_CORRUPTED
MDB_PANIC
MDB_VERSION_MISMATCH
MDB_INVALID
MDB_MAP_FULL
MDB_DBS_FULL
MDB_READERS_FULL
MDB_TLS_FULL
MDB_TXN_FULL
MDB_CURSOR_FULL
MDB_PAGE_FULL
MDB_MAP_RESIZED
MDB_INCOMPATIBLE
MDB_BAD_RSLOT
MDB_LAST_ERRCODE

⭐ Version information `":version"`

MDB_VERSION_FULL
MDB_VERSION_MAJOR
MDB_VERSION_MINOR
MDB_VERSION_PATCH
MDB_VERSION_STRING
MDB_VERSION_DATE

🎀 TIE Interface

The simplest interface to LMDB is using tie in perlfunc. Yes bestie, the classic <lore>tie</lore> — it's giving "old money Perl" and honestly? Iconic. ✨

The TIE interface of LMDB_File can take several forms that depend on the data at hand. Pick your fighter:

tie %hash, 'LMDB_File', $path [, $options ]

The most simple form. Baby's first tie 💖

tie %hash, 'LMDB_File', $path, $flags, $mode

For compatibility with other DBM modules. Blending in with the crowd, we love a team player.

tie %hash, 'LMDB_File', $Txn [, DBOPTIONS ]

When you have a Transaction object $Txn at hand.

tie %hash, 'LMDB_File', $Env [, DBOPTIONS ]

When you have an Environment object $Env at hand.

tie %hash, $DB

When you have an opened Transaction encapsulated database.

The first two forms will create and/or open the Environment at $path, create a new Transaction and open a Database in the Transaction.

If provided, $options must be a HASH reference with options for both the Environment and the database.

Valid keys for $option are any described above for ENVOPTIONS and DBOPTIONS.

In the case that you have already created a transaction or an environment, you can provide a HASH reference in DBOPTIONS for options exclusively for the database.

heads up bestie 🫶 In the forms that needs to create a Transaction, this is setted for Autocommit mode.

💜 AUTHOR

Salvador Ortiz Garcia, <sortiz@cpan.org>

🌈 COPYRIGHT AND LICENSE

Copyright (C) 2013-2021 by Salvador Ortiz García
Copyright (C) 2013-2021 by Matías Software Group, S.A. de C.V.

This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License version 2.0, see LICENSE.

and that's the whole page, bestie, we ate and left absolutely no crumbs 👑💅

perl v5.42.3 · dated 2026-08-19 · and yes, this is LMDB_File(3pm) — go forth and slay your key-value store fr fr 🦋🌸

📦 where this page comes from

ubuntu stonking: liblmdb-file-perl 0.14-1build1 · Artistic-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

LMDB_File(3pm)

✨ NAME ✨

🎀 SYNOPSIS 🎀

🌸 DESCRIPTION 🌸

💖 Error reporting 💖

👑 LMDB::Env

🎀 Constructor

💅 Class methods

✨ LMDB::Txn ✨

🌸 Constructor 🌸

👑 Class methods 👑

$Txn->abort

$Txn->commit

$Txn->reset

$Txn->renew

$Env = $Txn->env

$SubTxn = $Txn->SubTxn ( [ $tflags ] )

$Txn->AutoCommit ( [ BOOL ] )

$DB = $Txn->OpenDB ( [ DBOPTIONS ] )

$DB = $Txn->OpenDB ( [ $dbname [, DBFLAGS ]] )

$dbi = $Txn->open ( [ $dbname [, DBFLAGS ]] )

$Txn->put ( $dbi, $key, $data [, WRITEFLAGS [, $length ] )

$Txn->get ( $dbi, $key, $data )

$Txn->id ()

🦋 LMDB_File 🦋

🎀 Constructors 🎀

$DB = LMDB_File->new( $Txn, $dbi )

$DB = LMDB_File->open ( $Txn [, $dbname [, DBFLAGS ] ] )

⭐ Class methods ⭐

$DB->put ( $key, $data [, WRITEFLAGS [, $length ] ] )

$DB->get ( $key, $data )

$data = $DB->get ( $key )

$DB->del ( $key [, $data ] )

$DB->set_compare ( CODE )

$flags = $DB->flags

$status = $DB->stat

$DB->drop( [ REMOVE ] )

$DB->Alive

$Cursor = $DB->Cursor

$txn = $DB->Txn

$dbi = $DB->dbi

$DB->ReadMode ( [ MODE ] )

$DB->UTF8 ( [ MODE ] )