1LMDB_File(3) User Contributed Perl Documentation LMDB_File(3)
2
6 LMDB_File - Tie to LMDB (OpenLDAP's Lightning Memory-Mapped Database)
7
9 # Simple TIE interface, when you're in a rush
10 use LMDB_File;
11 $db = tie %hash, 'LMDB_File', $path;
13 $hash{$key} = $value;
15 $value = $hash{$key};
16 each %hash;
17 keys %hash;
18 values %hash;
19 ...
20 # The full power
23 use LMDB_File qw(:flags :cursor_op);
24 $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 $txn = $env->BeginTxn(); # Open a new transaction
33 $DB = $txn->OpenDB( { # Create a new database
35 dbname => $dbname,
36 flags => MDB_CREATE
37 });
38 $DB->put($key, $value); # Simple put
40 $value = $DB->get($key); # Simple get
41 $DB->put($key, $value, MDB_NOOVERWITE); # Don't replace existing value
43 # Work with cursors
45 $cursor => $DB->Cursor;
46 $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 $DB->set_compare( sub { lc($a) cmp lc($b) } ); # Use my own key comparison function
53
55 NOTE: This document is still under construction. Expect it to be
56 incomplete in places.
57 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 LMDB is a Btree-based database management library modeled loosely on
63 the BerkeleyDB API, but much simplified and extremely fast.
64 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 This is implemented with a number of Perl classes.
70 A LMDB's environment handler (MDB_env* in C) will be wrapped in the
72 LMDB::Env class.
73 A LMDB's transaction handler (MDB_txn* in C) will be wrapped in the
75 LMDB::Txn class.
76 A LMDB's cursor handler (MDB_cursor* in C) will be wrapped in the
78 LMDB::Cursor class.
79 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
87 In the C API, most functions return 0 on success and an error code on
88 failure.
89 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 When FALSE, the function will return the error code, in this case you
96 should check the return value of any function call.
97 By default $die_on_err is TRUE.
99 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
104 This class wraps an opened LMDB environment.
105 At construction time, the environment is created, if it does not exist,
107 and opened.
108 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 Constructor
114 $Env = LMDB::Env->new ( $path [, ENVOPTIONS ] )
115 Creates a new "LMDB::Env" object and returns it. It encapsulates both
117 LMDB's "mdb_env_create" and "mdb_env_open" functions.
118 $path is the directory in which the database files reside. This
120 directory must already exist and should be writable.
121 ENVOPTIONS, if provided, must be a HASH Reference with any of the
123 following options:
124 mapsize => INT
126 The size of the memory map to use for this environment.
127 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 The default is 1048576 bytes (1 MB).
134 maxreaders => INT
136 The maximum number of threads/reader slots for the environment.
137 This defines the number of slots in the lock table that is used to
139 track readers in the environment.
140 The default is 126.
142 maxdbs => INT
144 The maximum number of named databases for the environment.
145 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 The default is 0, i.e. no named databases allowed.
151 mode => INT
153 The UNIX permissions to set on created files. This parameter is
154 ignored on Windows. It defaults to 0600
155 flags => ENVFLAGS
157 Set special options for this environment. This option, if provided,
158 can be specified by OR'ing the following flags:
159 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 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 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 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 Incompatible with nested transactions (also known as sub
190 transactions).
191 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 This flag may be changed at any time using "$Env->set_flags()".
202 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 This flag may be changed at any time using "$Env->set_flags()".
220 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 This flag may be changed at any time using "$Env->set_flags()".
228 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 Class methods
241 $Env->copy ( $path )
242 Copy an LMDB environment to the specified $path
243 $Env->copyfd ( HANDLE )
245 Copy an LMDB environment to the specified HANDLE.
246 $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 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 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 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 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 $Env->set_flags ( BITMASK, BOOL )
279 As noted above, some environment flags can be changed at any time.
280 BITMASK is the flags to change, bitwise OR'ed together. BOOL TRUE
282 set the flags, FALSE clears them.
283 $Env->get_flags ( $flags )
285 Returns in $flags the environment flags.
286 $Env->get_path ( $path )
288 Returns in $path the path that was used in "LMDB::Env->new(...)"
289 $Env->get_maxreaders ( $readers )
291 Returns in $readers the maximum number of threads/reader slots for
292 the environment
293 $mks = $Env->get_maxkeysize
295 Returns the maximum size of a key for the environment.
296 $Txn = $Env->BeginTxn ( [ $tflags ] )
298 Returns a new Transaction. A simple wrapper over the constructor of
299 "LMDB::Txn".
300 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
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 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 If you let an object of this class get out of scope, by default the
314 transaction will be aborted.
315 Constructor
317 $Txn = LMDB::Txn->new ( $Env [, $tflags ] )
318 Create a new transaction for use in the environment.
320 Class methods
322 $Txn->abort
323 Abort the transaction, terminating the transaction.
324 $Txn->commit
326 Commit the transaction, terminating the transaction.
327 $Txn->reset
329 Reset a read-only transaction.
330 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 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 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 $Txn->renew
344 Renew a read-only transaction.
345 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 In this Perl implementation if you call "$Txn->renew()" in an
351 active Transaction the method internally calls "$Txn->reset()" for
352 you.
353 $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 $SubTxn = $Txn->SubTxn ( [ $tflags ] )
360 Creates and returns a sub transaction (also known as a nested
361 transaction).
362 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 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 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 $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 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 $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 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 DBOPTIONS, if provided, should be a HASH reference with any of the
400 following keys:
401 dbname => $dbname
403 flags => DBFLAGS
404 You can also call this method using its values, $dbname and
406 DBFLAGS, documented ahead.
407 $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 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 DBFLAGS, if provided, will set special options for this Database
417 and can be specified by OR'ing the following flags:
418 MDB_REVERSEKEY
420 Keys are strings to be compared in reverse order
421 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 MDB_INTEGERKEY
429 Keys are binary integers in native byte order.
430 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 MDB_INTEGERDUP
441 This option specifies that duplicate data items are also
442 integers, and should be sorted as such.
443 MDB_REVERSEDUP
445 This option specifies that duplicate data items should be
446 compared as strings in reverse order.
447 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 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 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 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 $Txn->put ( $dbi, $key, $data [, WRITEFLAGS [, $length ] )
467 Store items into the database $dbi
468 Provided for when your main concern is the raw speed.
470 For details of the other arguments, please see the method of the
472 same name in LMDB_File below.
473 $Txn->get ( $dbi, $key, $data )
475 Get items from the database $dbi
476 Provided for when your main concern is the raw speed.
478 For details of the other arguments, please see the method of the
480 same name in LMDB_File below.
481 $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
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 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 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 $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 Class methods
508 $DB->put ( $key, $data [, WRITEFLAGS [, $length ] ] )
509 Store items into a database.
510 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 $key is the key to store in the database and $data the data to
517 store.
518 WRITEFLAGS, if provided, will set special options for this
520 operation and can be one of following flags:
521 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 MDB_NOOVERWRITE
530 Enter the new key/data pair only if the key does not already
531 appear in the database.
532 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 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 In this particular case, you need to pass the extra $length
547 parameter to specify how many bytes to reserve.
548 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 MDB_APPEND
554 Append the given key/data pair to the end of the database.
555 No key comparisons are performed. This option allows fast bulk
557 loading when keys are already known to be in the correct order.
558 NOTE: Loading unsorted keys with this flag will cause data
560 corruption.
561 MDB_APPENDDUP
563 As above, but for sorted duplicated data.
564 $DB->get ( $key, $data )
566 $data = $DB->get ( $key )
567 Get items from a database.
568 This method retrieves key/data pairs from the database.
570 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 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 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 $DB->del ( $key [, $data ] )
584 Delete items from the database.
585 This function removes key/data pairs from the database.
587 If the database does not support sorted duplicate data items,
589 (MDB_DUPSORT) the $data parameter is optional and is ignored.
590 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 $DB->set_compare ( CODE )
597 Set a custom key comparison function referenced by CODE for a
598 database.
599 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 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 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 $flags = $DB->flags
617 Retrieve the DB flags for the associated database.
618 $status = $DB->stat
620 Returns a HASH reference with statistics for the associated
621 database, the hash will contain the following keys:
622 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 $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 $Cursor = $DB->Cursor
638 Creates a new LMDB::Cursor object to work in the database, see
639 "LMDB::Cursor"
640 $txn = $DB->Txn
642 Returns the transaction, an "LMDB::Txn" object, associated with
643 $DB.
644 $DB->Txn->commit; # Commit the current transaction.
646 If the method "$DB->Alive" has returned FALSE before, this method
648 will return "undef".
649 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 $DB->Txn->commit; # Commit current
656 $DB->Alive; # FALSE
657 ...
658 $DB->Txn = $Env->BeginTxn; # Start another, with same Database
659 ...
660 $dbi = $DB->dbi
662 Returns the low level Database handler associated with $DB
663 You can use "$DB->dbi" as an lvalue to switch the associated
665 Datbase hander:
666 $DB->dbi = $other_dbi;
668 $DB->ReadMode ( [ MODE ] )
670 This method allows you to modify the behavior of "get" (read)
671 operations on the database.
672 The C documentation for the "mdb_get" function states that:
674 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 So this module implements two modes of operation for its "get"
681 methods and you can select between them with this method.
682 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 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 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 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 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 $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 Returns the previous value.
719 By default, all values in LMDB are simple byte buffers of certain
721 fixed length.
722 So if you are storing binary data in your database all works as
724 expected: what you put is what you get.
725 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 use Encoding;
732 ...
733 $DB->put($key, Encode::encode($my_encoding, $characters));
735 $characters = Encode::decode($my_encoding, $DB->get($key));
737 For any value of $my_encoding, see Encode for the gory details.
739 But if you use for interchange the UTF-8 encoding, with this method
741 you can avoid all that typing.
742 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 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
756 To construct a cursor you should call the "Cursor" method of the
757 "LMDB_File" class:
758 $cursor = $DB->Cursor
760 Class methods
762 $cursor->get($key, $data, CURSOR_OP)
763 This function retrieves key/data pairs from the database.
764 The variables $key and $data are used to return the values found.
766 CURSOR_OP determines the key/data to be retrieved and must be one
768 of the following:
769 MDB_FIRST
771 Position at first key/data item.
772 MDB_FIRST_DUP
774 Position at first data item of current key. Only for
775 "MDB_DUPSORT"
776 MDB_GET_BOTH
778 Position at key/data pair. Only for "MDB_DUPSORT"
779 MDB_GET_BOTH_RANGE
781 Position at key, nearest data. Only for "MDB_DUPSORT"
782 MDB_GET_CURRENT
784 Return key/data at current cursor position.
785 MDB_GET_MULTIPLE
787 Return all the duplicate data items at the current cursor
788 position. Only for "MDB_DUPFIXED"
789 MDB_LAST
791 Position at last key/data item.
792 MDB_LAST_DUP
794 Position at last data item of current key. Only for
795 "MDB_DUPSORT"
796 MDB_NEXT
798 Position at next data item.
799 MDB_NEXT_DUP
801 Position at next data item of current key. Only for
802 "MDB_DUPSORT"
803 MDB_NEXT_MULTIPLE
805 Return all duplicate data items at the next cursor position.
806 Only for "MDB_DUPFIXED"
807 MDB_NEXT_NODUP
809 Position at first data item of next key.
810 MDB_PREV
812 Position at previous data item.
813 MDB_PREV_DUP
815 Position at previous data item of current key. Only for
816 "MDB_DUPSORT"
817 MDB_PREV_NODUP
819 Position at last data item of previous key.
820 MDB_SET
822 Position at specified key.
823 MDB_SET_KEY
825 Position at specified key, return key + data.
826 MDB_SET_RANGE
828 Position at first key greater than or equal to specified key.
829 $cursor->put($key, $data, WRITEFLAGS)
831 This function stores key/data pairs into the database.
832 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 If the function fails for any reason, the state of the cursor will
838 undetermined.
839 NOTE: Earlier documentation incorrectly said errors would leave the
841 state of the cursor unchanged.
842 $cursor->del( [ DELFLAGS ] )
844 This function deletes the key/data pair to which the cursor refers.
845 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
851 At "use" time you can import into your namespace the following
852 constants, grouped by their tags.
853 Environment flags ":envflags"
855 MDB_FIXEDMAP MDB_NOSUBDIR MDB_NOSYNC MDB_RDONLY MDB_NOMETASYNC
856 MDB_WRITEMAP MDB_MAPASYNC MDB_NOTLS
857 Data base flags ":dbflags"
859 MDB_REVERSEKEY MDB_DUPSORT MDB_INTEGERKEY MDB_DUPFIXED
860 MDB_INTEGERDUP MDB_REVERSEDUP MDB_CREATE
861 Write flags ":writeflags"
863 MDB_NOOVERWRITE MDB_NODUPDATA MDB_CURRENT MDB_RESERVE
864 MDB_APPEND MDB_APPENDDUP MDB_MULTIPLE
865 All flags ":flags"
867 All of ":envflags", ":dbflags" and ":writeflags"
868 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 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 Version information ":version"
882 MDB_VERSION_FULL MDB_VERSION_MAJOR MDB_VERSION_MINOR
883 MDB_VERSION_PATCH MDB_VERSION_STRING MDB_VERSION_DATE
884
886 The simplest interface to LMDB is using "tie" in perlfunc.
887 The TIE interface of LMDB_File can take several forms that depend on
889 the data at hand.
890 tie %hash, 'LMDB_File', $path [, $options ]
892 The most simple form.
893 tie %hash, 'LMDB_File', $path, $flags, $mode
895 For compatibility with other DBM modules.
896 tie %hash, 'LMDB_File', $Txn [, DBOPTIONS ]
898 When you have a Transaction object $Txn at hand.
899 tie %hash, 'LMDB_File', $Env [, DBOPTIONS ]
901 When you have an Environment object $Env at hand.
902 tie %hash, $DB
904 When you have an opened Transaction encapsulated database.
905 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 If provided, $options must be a HASH reference with options for both
910 the Environment and the database.
911 Valid keys for $option are any described above for ENVOPTIONS and
913 DBOPTIONS.
914 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 In the forms that needs to create a Transaction, this is setted for
920 Autocommit mode.
921
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 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.
931perl v5.32.0 2020-07-28 LMDB_File(3)