1LMDB_File(3)          User Contributed Perl Documentation         LMDB_File(3)
2
3
4

NAME

6       LMDB_File - Tie to LMDB (OpenLDAP's Lightning Memory-Mapped Database)
7

SYNOPSIS

9         # Simple TIE interface, when you're in a rush
10         use LMDB_File;
11
12         $db = tie %hash, 'LMDB_File', $path;
13
14         $hash{$key} = $value;
15         $value = $hash{$key};
16         each %hash;
17         keys %hash;
18         values %hash;
19         ...
20
21
22         # The full power
23         use LMDB_File qw(:flags :cursor_op);
24
25         $env = LMDB::Env->new($path, {
26             mapsize => 100 * 1024 * 1024 * 1024, # Plenty space, don't worry
27             maxdbs => 20, # Some databases
28             mode   => 0600,
29             # More options
30         });
31
32         $txn = $env->BeginTxn(); # Open a new transaction
33
34         $DB = $txn->OpenDB( {    # Create a new database
35             dbname => $dbname,
36             flags => MDB_CREATE
37         });
38
39         $DB->put($key, $value);  # Simple put
40         $value = $DB->get($key); # Simple get
41
42         $DB->put($key, $value, MDB_NOOVERWITE); # Don't replace existing value
43
44         # Work with cursors
45         $cursor => $DB->Cursor;
46
47         $cursor->get($key, $value, MDB_FIRST); # First key/value in DB
48         $cursor->get($key, $value, MDB_NEXT);  # Next key/value in DB
49         $cursor->get($key, $value, MDB_LAST);  # Last key/value in DB
50         $cursor->get($key, $value, MDB_PREV);  # Previous key/value in DB
51
52         $DB->set_compare( sub { lc($a) cmp lc($b) } ); # Use my own key comparison function
53

DESCRIPTION

55       NOTE: This document is still under construction. Expect it to be
56       incomplete in places.
57
58       LMDB_File is a Perl module which allows Perl programs to make use of
59       the facilities provided by OpenLDAP's Lightning Memory-Mapped Database
60       "LMDB".
61
62       LMDB is a Btree-based database management library modeled loosely on
63       the BerkeleyDB API, but much simplified and extremely fast.
64
65       It is assumed that you have a copy of LMBD's documentation at hand when
66       reading this documentation. The interface defined here mirrors the C
67       interface closely but with an OO approach.
68
69       This is implemented with a number of Perl classes.
70
71       A LMDB's environment handler (MDB_env* in C) will be wrapped in the
72       LMDB::Env class.
73
74       A LMDB's transaction handler (MDB_txn* in C) will be wrapped in the
75       LMDB::Txn class.
76
77       A LMDB's cursor handler (MDB_cursor* in C) will be wrapped in the
78       LMDB::Cursor class.
79
80       A LMDB's Database handler (MDB_dbi in C) will be exposed as a simple
81       integer, but because in LMDB all Database operations needs both a
82       Transaction and a Database handler, LMDB_File provides you a convenient
83       "LMDB_File" object that encapsulates both and mimic the syntax of other
84       *_File modules.
85

Error reporting

87       In the C API, most functions return 0 on success and an error code on
88       failure.
89
90       In this module, when a function fails, the package variable $die_on_err
91       controls the course of action. When $die_on_err is set to TRUE, this
92       causes LMDB_File to "die" with an error message that can be trapped by
93       an "eval { ... }" block.
94
95       When FALSE, the function will return the error code, in this case you
96       should check the return value of any function call.
97
98       By default $die_on_err is TRUE.
99
100       Regardless of the value of $die_on_err, the code of the last error can
101       be found in the package variable $last_err.
102

LMDB::Env

104       This class wraps an opened LMDB environment.
105
106       At construction time, the environment is created, if it does not exist,
107       and opened.
108
109       When you are finished using it, in the C API you must call the
110       "mdb_env_close" function to close it and free the memory allocated, but
111       in Perl you simply will let that the object get out of scope.
112
113   Constructor
114       $Env = LMDB::Env->new ( $path [, ENVOPTIONS ] )
115
116       Creates a new "LMDB::Env" object and returns it. It encapsulates both
117       LMDB's "mdb_env_create" and "mdb_env_open" functions.
118
119       $path is the directory in which the database files reside. This
120       directory must already exist and should be writable.
121
122       ENVOPTIONS, if provided, must be a HASH Reference with any of the
123       following options:
124
125       mapsize    => INT
126           The size of the memory map to use for this environment.
127
128           The size of the memory map is also the maximum size of the
129           database.  The value should be chosen as large as possible, to
130           accommodate future growth of the database. The size should be a
131           multiple of the OS page size.
132
133           The default is 1048576 bytes (1 MB).
134
135       maxreaders => INT
136           The maximum number of threads/reader slots for the environment.
137
138           This defines the number of slots in the lock table that is used to
139           track readers in the environment.
140
141           The default is 126.
142
143       maxdbs     => INT
144           The maximum number of named databases for the environment.
145
146           This option is only needed if multiple databases will be used in
147           the environment. Simpler applications that use the environment as a
148           single unnamed database can ignore this option.
149
150           The default is 0, i.e. no named databases allowed.
151
152       mode  => INT
153           The UNIX permissions to set on created files. This parameter is
154           ignored on Windows. It defaults to 0600
155
156       flags      => ENVFLAGS
157           Set special options for this environment. This option, if provided,
158           can be specified by OR'ing the following flags:
159
160           MDB_FIXEDMAP
161               Use a fixed address for the mmap region. This flag must be
162               specified when creating the environment, and is stored
163               persistently in the environment.  If successful, the memory map
164               will always reside at the same virtual address and pointers
165               used to reference data items in the database will be constant
166               across multiple invocations. This option may not always work,
167               depending on how the operating system has allocated memory to
168               shared libraries and other uses.  The feature is highly
169               experimental.
170
171           MDB_NOSUBDIR
172               By default, LMDB creates its environment in a directory whose
173               pathname is given in $path, and creates its data and lock files
174               under that directory. With this option, $path is used as-is for
175               the database main data file. The database lock file is the
176               $path with "-lock" appended.
177
178           MDB_RDONLY
179               Open the environment in read-only mode. No write operations
180               will be allowed. LMDB will still modify the lock file - except
181               on read-only filesystems, where LMDB does not use locks.
182
183           MDB_WRITEMAP
184               Use a writeable memory map unless "MDB_RDONLY" is set. This is
185               faster and uses fewer mallocs, but loses protection from
186               application bugs like wild pointer writes and other bad updates
187               into the database.
188
189               Incompatible with nested transactions (also known as sub
190               transactions).
191
192           MDB_NOMETASYNC
193               Flush system buffers to disk only once per transaction, omit
194               the metadata flush. Defer that until the system flushes files
195               to disk, or next non-MDB_RDONLY commit or "$Env->sync()". This
196               optimization maintains database integrity, but a system crash
197               may undo the last committed transaction. I.e. it preserves the
198               ACI (atomicity, consistency, isolation) but not D (durability)
199               database property.
200
201               This flag may be changed at any time using "$Env->set_flags()".
202
203           MDB_NOSYNC
204               Don't flush system buffers to disk when committing a
205               transaction.  This optimization means a system crash can
206               corrupt the database or lose the last transactions if buffers
207               are not yet flushed to disk.  The risk is governed by how often
208               the system flushes dirty buffers to disk and how often
209               "$Env->sync()" is called.  However, if the filesystem preserves
210               write order and the "MDB_WRITEMAP" flag is not used,
211               transactions exhibit ACI (atomicity, consistency, isolation)
212               properties and only lose D (durability).  I.e. database
213               integrity is maintained, but a system crash may undo the final
214               transactions.  Note that "MDB_NOSYNC | MDB_WRITEMAP" leaves the
215               system with no hint for when to write transactions to disk,
216               unless "$Env->sync()" is called. "MDB_MAPASYNC | MDB_WRITEMAP")
217               may be preferable.
218
219               This flag may be changed at any time using "$Env->set_flags()".
220
221           MDB_MAPASYNC
222               When using "MDB_WRITEMAP", use asynchronous flushes to disk.
223               As with "MDB_NOSYNC", a system crash can then corrupt the
224               database or lose the last transactions. Calling "$Env->sync()"
225               ensures on-disk database integrity until next commit.
226
227               This flag may be changed at any time using "$Env->set_flags()".
228
229           MDB_NOTLS
230               Don't use Thread-Local Storage. Tie reader locktable slots to
231               "LMDB::Txn" objects instead of to threads. I.e. "$Txn->reset()"
232               keeps the slot reserved for the "LMDB::Txn" object. A thread
233               may use parallel read-only transactions. A read-only
234               transaction may span threads if the user synchronizes its use.
235               Applications that multiplex many user threads over individual
236               OS threads need this option. Such an application must also
237               serialize the write transactions in an OS thread, since LMDB's
238               write locking is unaware of the user threads.
239
240   Class methods
241       $Env->copy ( $path )
242           Copy an LMDB environment to the specified $path
243
244       $Env->copyfd ( HANDLE )
245           Copy an LMDB environment to the specified HANDLE.
246
247       $status = $Env->stat
248           Returns a HASH reference with statistics for the main, unnamed,
249           database in the environment, the HASH contains the following keys:
250
251           psize Size of a database page.
252           depth Depth (height) of the B-Tree
253           branch_pages Number of internal (non-leaf) pages
254           overflow_pages Number of overflow pages
255           entries Number of data items
256       $info = $Env->info
257           Returns a HASH reference with information about the environment,
258           $info, with the following keys:
259
260           mapaddr Address of map, if fixed
261           mapsize Size of the data memory map
262           last_pgno ID of the last used page
263           last_txnid ID of the last committed transaction
264           maxreaders Max reader slots in the environment
265           numreaders Max reader slot used in the environment
266       $Env->sync ( BOOL )
267           Flush the data buffers to disk.
268
269           Data is always written to disk when "$Txn->commit()" is called, but
270           the operating system may keep it buffered. LMDB always flushes the
271           OS buffers upon commit as well, unless the environment was opened
272           with "MDB_NOSYNC" or in part "MDB_NOMETASYNC".
273
274           If BOOL is TRUE force a synchronous flush.  Otherwise if the
275           environment has the "MDB_NOSYNC" flag set the flushes will be
276           omitted, and with "MDB_MAPASYNC" they will be asynchronous.
277
278       $Env->set_flags ( BITMASK, BOOL )
279           As noted above, some environment flags can be changed at any time.
280
281           BITMASK is the flags to change, bitwise OR'ed together.  BOOL TRUE
282           set the flags, FALSE clears them.
283
284       $Env->get_flags ( $flags )
285           Returns in $flags the environment flags.
286
287       $Env->get_path ( $path )
288           Returns in $path the path that was used in "LMDB::Env->new(...)"
289
290       $Env->get_maxreaders ( $readers )
291           Returns in $readers the maximum number of threads/reader slots for
292           the environment
293
294       $mks = $Env->get_maxkeysize
295           Returns the maximum size of a key for the environment.
296
297       $Txn = $Env->BeginTxn ( [ $tflags ] )
298           Returns a new Transaction. A simple wrapper over the constructor of
299           "LMDB::Txn".
300
301           If provided, $tflags will be passed to the constructor, if not
302           provided, this wrapper will propagate the environment's flag
303           "MDB_RDONLY", if set, to the transaction constructor.
304

LMDB::Txn

306       In LMDB every operation (read or write) on a Database needs to be
307       inside a transaction. This class wraps an LMDB transaction.
308
309       You must terminate the transaction by either the "abort" or "commit"
310       methods. After a transaction is terminated, you should not call any
311       other method on it, except "env".
312
313       If you let an object of this class get out of scope, by default the
314       transaction will be aborted.
315
316   Constructor
317        $Txn = LMDB::Txn->new ( $Env [, $tflags ] )
318
319       Create a new transaction for use in the environment.
320
321   Class methods
322       $Txn->abort
323           Abort the transaction, terminating the transaction.
324
325       $Txn->commit
326           Commit the transaction, terminating the transaction.
327
328       $Txn->reset
329           Reset a read-only transaction.
330
331           Abort the transaction like "$Txn->abort()", but keep the
332           transaction handle in the inactive state so "$Txn->renew()" may
333           reactivate the handle.
334
335           This saves allocation overhead if the process will start a new
336           read-only transaction soon, and also saves locking overhead if
337           MDB_NOTLS is in use.
338
339           The reader table lock is released, but the table slot stays tied to
340           its thread or Transaction. Use "$Txn->abort()" to discard a reseted
341           handle, and to free its lock table slot if MDB_NOTLS is in use.
342
343       $Txn->renew
344           Renew a read-only transaction.
345
346           This acquires a new reader lock for a transaction handle that had
347           been inactivated by "$Txn->reset()". It must be called before an
348           inactive (reseted) transaction may be used again.
349
350           In this Perl implementation if you call "$Txn->renew()" in an
351           active Transaction the method internally calls "$Txn->reset()" for
352           you.
353
354       $Env = $Txn->env
355           Returns the environment (an LMDB::Env object) that created the
356           transaction, if it is still alive, or "undef" if called on a
357           terminated transaction.
358
359       $SubTxn = $Txn->SubTxn ( [ $tflags ] )
360           Creates and returns a sub transaction (also known as a nested
361           transaction).
362
363           Nested transactions are useful for combining components that create
364           and commit transactions. No modifications are permanently stored
365           until the highest level "parent" transaction is committed. Nested
366           transactions can be aborted without aborting the parent transaction
367           and only the changes made in the nested transaction will be rolled-
368           back.
369
370           Aborting the parent transaction will abort and terminate all
371           outstanding nested transactions. Committing the parent transaction
372           will similarly commit and terminate all outstanding nested
373           transactions.
374
375           Unlike some other databases, in LMDB changes made inside nested
376           transactions are not visible to the parent transaction until the
377           nested transaction is committed. In other words, transactions are
378           always isolated, even when they are nested.
379
380       $Txn->AutoCommit ( [ BOOL ] )
381           When BOOL is provided, it sets the behavior of the transaction when
382           going out of scope: BOOL TRUE makes arrangements for the
383           transaction to be auto committed and BOOL FALSE returns to the
384           default behavior: to be aborted.
385
386           If you don't provide BOOL, you are only interested in knowing the
387           current value of this option, which is returned in every case.
388
389       $DB = $Txn->OpenDB ( [ DBOPTIONS ] )
390       $DB = $Txn->OpenDB ( [ $dbname [, DBFLAGS ]] )
391           This method opens a Database in the environment and returns a
392           "LMDB_File" object that encapsulates both the Transaction and the
393           Database handler.
394
395           This is a convenience shortcut for "LMDB_File->new( $Txn,
396           $Txn->open(...) )" for use when you want to use the hi-level
397           LMDB_File's OO approach.
398
399           DBOPTIONS, if provided,  should be a HASH reference with any of the
400           following keys:
401
402           dbname => $dbname
403           flags => DBFLAGS
404
405           You can also call this method using its values, $dbname and
406           DBFLAGS, documented ahead.
407
408       $dbi = $Txn->open ( [ $dbname [, DBFLAGS ]] )
409           This method open a Database in the environment and returns the low
410           level Database handler, an integer.
411
412           If provided $dbname, will be the name of a named Database in the
413           environment, if not provided (or if $dbname is "undef"), the opened
414           Database will be the unnamed (the default) one.
415
416           DBFLAGS, if provided, will set special options for this Database
417           and can be specified by OR'ing the following flags:
418
419           MDB_REVERSEKEY
420               Keys are strings to be compared in reverse order
421
422           MDB_DUPSORT
423               Duplicate keys may be used in the database. (Or, from another
424               perspective, keys may have multiple data items, stored in
425               sorted order.) By default keys must be unique and may have only
426               a single data item.
427
428           MDB_INTEGERKEY
429               Keys are binary integers in native byte order.
430
431           MDB_DUPFIXED
432               This flag may only be used in combination with #MDB_DUPSORT.
433               This option tells the library that the data items for this
434               database are all the same size, which allows further
435               optimizations in storage and retrieval. When all data items are
436               the same size, the #MDB_GET_MULTIPLE and #MDB_NEXT_MULTIPLE
437               cursor operations may be used to retrieve multiple items at
438               once.
439
440           MDB_INTEGERDUP
441               This option specifies that duplicate data items are also
442               integers, and should be sorted as such.
443
444           MDB_REVERSEDUP
445               This option specifies that duplicate data items should be
446               compared as strings in reverse order.
447
448           MDB_CREATE
449               Create the named database if it doesn't exist. This option is
450               not allowed in a read-only transaction or a read-only
451               environment.
452
453               After successfully commit the transaction that created the
454               Database, it will remains opened in the Environment so you can
455               reuse $dbi in other transactions.
456
457           If you will need to use that Database handler in more than one
458           transaction or want to use a more traditional (in LMDB's point of
459           view) approach, this the method you should use.
460
461           To operate in the opened database with the returned $dbi handler
462           you can use the methods described bellow or call
463           "LMDB_File->new(...)" to obtain a "LMDB_File" object to operate the
464           database in a particular transaction.
465
466       $Txn->put ( $dbi, $key, $data [, WRITEFLAGS [, $length ] )
467           Store items into the database $dbi
468
469           Provided for when your main concern is the raw speed.
470
471           For details of the other arguments, please see the method of the
472           same name in LMDB_File below.
473
474       $Txn->get ( $dbi, $key, $data )
475           Get items from the database $dbi
476
477           Provided for when your main concern is the raw speed.
478
479           For details of the other arguments, please see the method of the
480           same name in LMDB_File below.
481
482       $Txn->id ()
483           Return the transaction's ID.  This returns the identifier
484           associated with this transaction. For a read-only transaction, this
485           corresponds to the snapshot being read; concurrent readers will
486           frequently have the same transaction ID.
487

LMDB_File

489       In the LMDB C API all Database operations need both an active
490       Transaction and a Database handler. To simplify those operations and be
491       syntax compatible with others *_File modules, this Perl API provides
492       you a LMDB_File object that encapsulates both and implements some hi-
493       level extensions.
494
495       LMDB_File's methods, in contrast to the LMDB::Txn's ones of the same
496       name, perform some checks before calling the low-level C API.
497
498   Constructors
499       $DB = LMDB_File->new( $Txn, $dbi )
500           Associates a Transaction $Txn with a previously opened Database
501           handler $dbi to use this OO API
502
503       $DB = LMDB_File->open ( $Txn [, $dbname [, DBFLAGS ] ] )
504           An alternative to "$Txn->OpenDB(...)" for open a Database and
505           associate it with a Transaction in one call.
506
507   Class methods
508       $DB->put ( $key, $data [, WRITEFLAGS [, $length ] ] )
509           Store items into a database.
510
511           This function stores key/data pairs in the database. The default
512           behavior is to enter the new key/data pair, replacing any
513           previously existing key if duplicates are disallowed, or adding a
514           duplicate data item if duplicates are allowed
515
516           $key is the key to store in the database and $data the data to
517           store.
518
519           WRITEFLAGS, if provided, will set special options for this
520           operation and can be one of following flags:
521
522           MDB_NODUPDATA
523               Enter the new key/data pair only if it does not   already
524               appear in the database.  This flag may only be specified    if
525               the database was opened with #MDB_DUPSORT.  The function will
526               fail with MDB_KEYEXIST if the key/data pair already appears in
527               the database.
528
529           MDB_NOOVERWRITE
530               Enter the new key/data pair only if the key does not already
531               appear in the database.
532
533               The function will return MDB_KEYEXIST if the key already
534               appears in the database, even if   the database supports
535               duplicates (#MDB_DUPSORT). The $data parameter will be set to
536               the existing item.
537
538           MDB_RESERVE
539               Reserve space for data of the given size in $length, but don't
540               copy anything.  Instead, return in $data a magical scalar with
541               a pointer to the reserved space, which the caller can fill in
542               later, but before the next update operation or the transaction
543               ends. This saves an extra memcpy if the data is being generated
544               later.
545
546               In this particular case, you need to pass the extra $length
547               parameter to specify how many bytes to reserve.
548
549               Please read about the "$DB->ReadMode" method caveats bellow for
550               details that apply to the magical scalar returned in $data in
551               this case.
552
553           MDB_APPEND
554               Append the given key/data pair to the end of the database.
555
556               No key comparisons are performed. This option allows fast bulk
557               loading when keys are already known to be in the correct order.
558
559               NOTE: Loading unsorted keys with this flag will cause data
560               corruption.
561
562           MDB_APPENDDUP
563               As above, but for sorted duplicated data.
564
565       $DB->get ( $key, $data )
566       $data = $DB->get ( $key )
567           Get items from a database.
568
569           This method retrieves key/data pairs from the database.
570
571           If the database supports duplicate keys (#MDB_DUPSORT) then the
572           first data item for the key will be returned. Retrieval of other
573           items requires the use of the "LMBD::Cursor->get()" method.
574
575           The two-argument form, closer to the C API, returns in the provided
576           argument $data the value associated with $key in the database if it
577           exists or reports an error if not.
578
579           In the simpler, more "perlish" one-argument form, the method
580           returns the value associated with $key in the database or "undef"
581           if no such value exists.
582
583       $DB->del ( $key [, $data ] )
584           Delete items from the database.
585
586           This function removes key/data pairs from the database.
587
588           If the database does not support sorted duplicate data items,
589           (MDB_DUPSORT) the $data parameter is optional and is ignored.
590
591           If the database supports sorted duplicates and the $data parameter
592           is "undef" or not provided, all of the duplicate data items for the
593           $key will be deleted. Otherwise, if the $data parameter is provided
594           only the matching data item will be deleted.
595
596       $DB->set_compare ( CODE )
597           Set a custom key comparison function referenced by CODE for a
598           database.
599
600           CODE should be a subroutine reference or an anonymous subroutine,
601           that like Perl's "sort" in perlfunc, will receive the values to
602           compare in the global variables $a and $b.
603
604           The comparison function is called whenever it is necessary to
605           compare a key specified by the application with a key currently
606           stored in the database.  If no comparison function is specified,
607           and no special key flags were specified in "LMDB_File->open()", the
608           keys are compared lexically, with shorter keys collating before
609           longer keys.
610
611           Warning: This function must be called before any data access
612           functions are used, otherwise data corruption may occur. The same
613           comparison function must be used by every program accessing the
614           database, every time the database is used.
615
616       $flags = $DB->flags
617           Retrieve the DB flags for the associated database.
618
619       $status = $DB->stat
620           Returns a HASH reference with statistics for the associated
621           database, the hash will contain the following keys:
622
623           psize Size of a database page.
624           depth Depth (height) of the B-Tree
625           branch_pages Number of internal (non-leaf) pages
626           overflow_pages Number of overflow pages
627           entries Number of data items
628       $DB->drop( [ REMOVE ] )
629           If REMOVE isn't provided or FALSE, the database is emptied. If
630           REMOVE is TRUE the database is closed and removed from the
631           Environment.
632
633       $DB->Alive
634           Returns a TRUE value if the associated transaction is still alive,
635           i.e.  not commited nor aborted yet, and FALSE otherwise.
636
637       $Cursor = $DB->Cursor
638           Creates a new LMDB::Cursor object to work in the database, see
639           "LMDB::Cursor"
640
641       $txn = $DB->Txn
642           Returns the transaction, an "LMDB::Txn" object, associated with
643           $DB.
644
645               $DB->Txn->commit; # Commit the current transaction.
646
647           If the method "$DB->Alive" has returned FALSE before, this method
648           will return "undef".
649
650           You can use "$DB->Txn" as an lvalue to change the associated
651           Transaction, but remember that, if $DB is holding the last
652           reference of the current transaction, that transaction will be
653           terminated.
654
655               $DB->Txn->commit; # Commit current
656               $DB->Alive;       # FALSE
657               ...
658               $DB->Txn = $Env->BeginTxn; # Start another, with same Database
659               ...
660
661       $dbi = $DB->dbi
662           Returns the low level Database handler associated with $DB
663
664           You can use "$DB->dbi" as an lvalue to switch the associated
665           Datbase hander:
666
667             $DB->dbi = $other_dbi;
668
669       $DB->ReadMode ( [ MODE ] )
670           This method allows you to modify the behavior of "get" (read)
671           operations on the database.
672
673           The C documentation for the "mdb_get" function states that:
674
675             The memory pointed to by the returned values is owned by the
676             database. The caller need not dispose of the memory, and may not
677             modify it in any way. For values returned in a read-only transaction
678             any modification attempts will cause a SIGSEGV.
679
680           So this module implements two modes of operation for its "get"
681           methods and you can select between them with this method.
682
683           When MODE is 0 (or any FALSE value) a default "safe" mode is used
684           in which the data value found in the database is copied to the
685           scalar returned, so you can do anything you want to that scalar
686           without side effects.
687
688           But when MODE is 1 (or, in the current implementation, any TRUE
689           value) a sort of hack is used to avoid the memory copy and a
690           magical scalar returned that hold only a pointer to the data value
691           found. This is much faster and uses less memory, especially when
692           used with large values.
693
694           In a environment opened with MDB_WRITEMAP and in a transaction
695           without the MDB_RDONLY flag, you are allowed to modify the returned
696           scalar, and the modifications are reflected to the associated
697           memory block and preserved in the database when the transaction is
698           commited. Otherwise the magical scalar is marked READ-ONLY and any
699           attempt to modify it (other than reuse it in another "$DB->get" ),
700           will cause perl to croak.
701
702           CAVEATS: In a read-only transaction the value is valid only until
703           the end of the transaction, and in a read-write transaction the
704           value is valid only until the next write operation (because any
705           write operation can potentially modify the in-memory btree). In the
706           current implementation, you are responsible for the proper timing
707           of usage.
708
709           NOTE: In order to achieve the zero-copy behavior desired by setting
710           ReadMode to TRUE, you must use the two-argument form of get
711           ("$DB->get ( $key, $data )"), use the new "$DB->Rget( $key )" or
712           use the cursor get method described below.
713
714       $DB->UTF8 ( [ MODE ] )
715           Instructs LDMB_File to use the UTF-8 encoding for the associated
716           database when MODE is 1 or revert to raw bytes when 0.
717
718           Returns the previous value.
719
720           By default, all values in LMDB are simple byte buffers of certain
721           fixed length.
722
723           So if you are storing binary data in your database all works as
724           expected: what you put is what you get.
725
726           But when you need to store some arbitrary Unicode text value,
727           remember that internally perl stores your strings in either the
728           native eight-bit character set or in UTF-8, and to warrant a
729           consistent encoding in your database you should do something like:
730
731               use Encoding;
732               ...
733
734               $DB->put($key, Encode::encode($my_encoding, $characters));
735
736               $characters = Encode::decode($my_encoding, $DB->get($key));
737
738           For any value of $my_encoding, see Encode for the gory details.
739
740           But if you use for interchange the UTF-8 encoding, with this method
741           you can avoid all that typing.
742
743           When MODE is 1, all values that you put in the Database will be
744           encoded in UTF-8, And all get calls will expect UTF-8 data and it
745           will be verified and decoded.  In this mode, if malformed data is
746           found, a warning will be emitted, the decode attempt aborted and
747           the raw bytes returned.
748
749           In this mode, a "$foo->get(...)" call interacts with the bytes
750           pragma in a special way: In the lexical scope under the effects of
751           "use bytes", any get call skips the decode step, returning the
752           fetched encoded UTF-8 data as bytes, i.e. with the internal perl
753           UTF8 flag off, as expected by modules like JSON::XS.
754

LMDB::Cursor

756       To construct a cursor you should call the "Cursor" method of the
757       "LMDB_File" class:
758
759        $cursor = $DB->Cursor
760
761   Class methods
762       $cursor->get($key, $data, CURSOR_OP)
763           This function retrieves key/data pairs from the database.
764
765           The variables $key and $data are used to return the values found.
766
767           CURSOR_OP determines the key/data to be retrieved and must be one
768           of the following:
769
770           MDB_FIRST
771               Position at first key/data item.
772
773           MDB_FIRST_DUP
774               Position at first data item of current key. Only for
775               "MDB_DUPSORT"
776
777           MDB_GET_BOTH
778               Position at key/data pair. Only for "MDB_DUPSORT"
779
780           MDB_GET_BOTH_RANGE
781               Position at key, nearest data. Only for "MDB_DUPSORT"
782
783           MDB_GET_CURRENT
784               Return key/data at current cursor position.
785
786           MDB_GET_MULTIPLE
787               Return all the duplicate data items at the current cursor
788               position.  Only for "MDB_DUPFIXED"
789
790           MDB_LAST
791               Position at last key/data item.
792
793           MDB_LAST_DUP
794               Position at last data item of current key. Only for
795               "MDB_DUPSORT"
796
797           MDB_NEXT
798               Position at next data item.
799
800           MDB_NEXT_DUP
801               Position at next data item of current key.  Only for
802               "MDB_DUPSORT"
803
804           MDB_NEXT_MULTIPLE
805               Return all duplicate data items at the next cursor position.
806               Only for "MDB_DUPFIXED"
807
808           MDB_NEXT_NODUP
809               Position at first data item of next key.
810
811           MDB_PREV
812               Position at previous data item.
813
814           MDB_PREV_DUP
815               Position at previous data item of current key. Only for
816               "MDB_DUPSORT"
817
818           MDB_PREV_NODUP
819               Position at last data item of previous key.
820
821           MDB_SET
822               Position at specified key.
823
824           MDB_SET_KEY
825               Position at specified key, return key + data.
826
827           MDB_SET_RANGE
828               Position at first key greater than or equal to specified key.
829
830       $cursor->put($key, $data, WRITEFLAGS)
831           This function stores key/data pairs into the database.
832
833           If the function succeeds and an item is inserted into the database,
834           the cursor is always positioned to refer to the newly inserted
835           item.
836
837           If the function fails for any reason, the state of the cursor will
838           undetermined.
839
840           NOTE: Earlier documentation incorrectly said errors would leave the
841           state of the cursor unchanged.
842
843       $cursor->del( [ DELFLAGS ] )
844           This function deletes the key/data pair to which the cursor refers.
845
846           If the database was opened with "MDB_DUPSORT", the optional
847           parameter DELFLAGS can be "MDB_NODUPDATA" to deletes all of the
848           data items for the current key.
849

Exportable constants

851       At "use" time you can import into your namespace the following
852       constants, grouped by their tags.
853
854   Environment flags ":envflags"
855        MDB_FIXEDMAP MDB_NOSUBDIR MDB_NOSYNC MDB_RDONLY MDB_NOMETASYNC
856        MDB_WRITEMAP MDB_MAPASYNC MDB_NOTLS
857
858   Data base flags ":dbflags"
859        MDB_REVERSEKEY MDB_DUPSORT MDB_INTEGERKEY MDB_DUPFIXED
860        MDB_INTEGERDUP MDB_REVERSEDUP MDB_CREATE
861
862   Write flags ":writeflags"
863        MDB_NOOVERWRITE MDB_NODUPDATA MDB_CURRENT MDB_RESERVE
864        MDB_APPEND MDB_APPENDDUP MDB_MULTIPLE
865
866   All flags ":flags"
867       All of ":envflags", ":dbflags" and ":writeflags"
868
869   Cursor operations ":cursor_op"
870        MDB_FIRST MDB_FIRST_DUP MDB_GET_BOTH MDB_GET_BOTH_RANGE
871        MDB_GET_CURRENT MDB_GET_MULTIPLE MDB_NEXT MDB_NEXT_DUP MDB_NEXT_MULTIPLE
872        MDB_NEXT_NODUP MDB_PREV MDB_PREV_DUP MDB_PREV_NODUP MDB_LAST MDB_LAST_DUP
873        MDB_SET MDB_SET_KEY MDB_SET_RANGE
874
875   Error codes ":error"
876        MDB_SUCCESS MDB_KEYEXIST MDB_NOTFOUND MDB_PAGE_NOTFOUND MDB_CORRUPTED
877        MDB_PANIC MDB_VERSION_MISMATCH MDB_INVALID MDB_MAP_FULL MDB_DBS_FULL
878        MDB_READERS_FULL MDB_TLS_FULL MDB_TXN_FULL MDB_CURSOR_FULL MDB_PAGE_FULL
879        MDB_MAP_RESIZED MDB_INCOMPATIBLE MDB_BAD_RSLOT MDB_LAST_ERRCODE
880
881   Version information ":version"
882        MDB_VERSION_FULL MDB_VERSION_MAJOR MDB_VERSION_MINOR
883        MDB_VERSION_PATCH MDB_VERSION_STRING MDB_VERSION_DATE
884

TIE Interface

886       The simplest interface to LMDB is using "tie" in perlfunc.
887
888       The TIE interface of LMDB_File can take several forms that depend on
889       the data at hand.
890
891       tie %hash, 'LMDB_File', $path [, $options ]
892           The most simple form.
893
894       tie %hash, 'LMDB_File', $path, $flags, $mode
895           For compatibility with other DBM modules.
896
897       tie %hash, 'LMDB_File', $Txn [, DBOPTIONS ]
898           When you have a Transaction object $Txn at hand.
899
900       tie %hash, 'LMDB_File', $Env [, DBOPTIONS ]
901           When you have an Environment object $Env at hand.
902
903       tie %hash, $DB
904           When you have an opened Transaction encapsulated database.
905
906       The first two forms will create and/or open the Environment at $path,
907       create a new Transaction and open a Database in the Transaction.
908
909       If provided, $options must be a HASH reference with options for both
910       the Environment and the database.
911
912       Valid keys for $option are any described above for ENVOPTIONS and
913       DBOPTIONS.
914
915       In the case that you have already created a transaction or an
916       environment, you can provide a HASH reference in DBOPTIONS for options
917       exclusively for the database.
918
919       In the forms that needs to create a Transaction, this is setted for
920       Autocommit mode.
921

AUTHOR

923       Salvador Ortiz Garcia, <sortiz@cpan.org>
924
926        Copyright (C) 2013-2014 by Salvador Ortiz García
927        Copyright (C) 2013-2014 by Matías Software Group, S.A. de C.V.
928
929       This library is free software; you can redistribute it and/or modify it
930       under the terms of the Artistic License version 2.0, see LICENSE.
931
932
933
934perl v5.30.0                      2019-07-26                      LMDB_File(3)
Impressum