Peta::LMDB::Env

📦 std

An LMDB environment: the file (or directory) a set of databases lives in, and what every transaction starts from.

Peta::LMDB::Env->new opens one; begin starts a transaction in it. An environment holds an unnamed database and, when opened with maxdbs, that many named ones. Its memory map has a fixed size, mapsize: a write that would grow the data past it fails with MDB_MAP_FULL, so open with room to spare - the size reserves address space, not disk or memory.

A file can be open in one environment per process: a second Peta::LMDB::Env->new of the same file croaks while the first is open. The environment closes when its last reference goes, or at close.

Synopsis

use Peta::LMDB qw(:flags);

my $env = Peta::LMDB::Env->new('data.lmdb', flags => MDB_NOSUBDIR,
                               mapsize => 1 << 30, maxdbs => 4);
my $txn = $env->begin;
# ...
$txn->commit;
print $env->stat->{entries}, "\n";

Functions

Environments

new

Open an environment: the file or directory $path, with options.

begin

Start a transaction: $env->begin for a write transaction, $env->begin(MDB_RDONLY) for a read one.

stat

The unnamed database’s statistics, as a hash reference: entries (the number of keys), depth of its tree, branch_pages, leaf_pages, overflow_pages, and the page size psize. A named database’s are $txn->stat($db).

info

The environment’s state, as a hash reference: mapsize, the map’s address mapaddr, the last page used last_pgno, the last committed transaction’s ID last_txnid, and the readers allowed and live, maxreaders and numreaders.

sync

Flush committed data to disk: needed only when the environment was opened with MDB_NOSYNC or MDB_MAPASYNC, as commits otherwise sync themselves. $env->sync(1) forces the flush even then.

copy

Copy the environment to $path while it is in use - a consistent backup of the last commit. $path is a directory, or with MDB_NOSUBDIR the copy’s file name, which must not exist. $env->copy($path, MDB_CP_COMPACT) leaves the free pages out, making a smaller copy.

path

The path the environment was opened with.

flags

The environment’s MDB_* flags, as a number to test with &.

set_flags

$env->set_flags($flags, $on): switch flags on (true $on) or off while open. Only MDB_NOSYNC, MDB_NOMETASYNC, MDB_MAPASYNC and MDB_NOMEMINIT can change; others croak Invalid argument.

maxkeysize

The longest key the environment takes, in bytes (511 with the usual liblmdb), which is also the longest value of an MDB_DUPSORT database. A longer one croaks MDB_BAD_VALSIZE.

reader_check

Free the reader slots of processes that died with a read transaction open; returns how many it freed. Such slots keep pages from being reused until cleared.

close

Close the environment now, rather than when its last reference goes. No transaction may be live: that croaks Peta::LMDB: the environment has live transactions. Using the environment afterwards croaks the environment is closed.