<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from Peta/LMDB/Env.rs. Do not edit. -->

```{index} single: Peta::LMDB::Env
```

# Peta::LMDB::Env

```{pperl-module-badges} Peta::LMDB::Env
```

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

```perl
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`](Env/new)

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

#### [`begin`](Env/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`.

```{toctree}
:hidden:
:maxdepth: 1

Env/new
Env/begin
```