```{index} single: Peta::LMDB::Txn ``` # Peta::LMDB::Txn ```{pperl-module-badges} Peta::LMDB::Txn ``` A transaction: everything read from or written to an LMDB environment happens in one. `$env->begin` starts a write transaction, `$env->begin(MDB_RDONLY)` a read one. A read transaction sees the data as it was when it began, never waits and never blocks a writer. A write transaction sees its own writes; nothing it writes is visible elsewhere until `commit` makes all of it durable at once, and `abort` - or the transaction going out of scope - discards all of it. There is one write transaction at a time across all processes using the file. Keys and values are byte strings: a string with characters over 255 croaks `Wide character`. In a database opened with `MDB_INTEGERKEY` the keys are unsigned integers, and with `MDB_DUPSORT|MDB_INTEGERDUP` the values. ## Synopsis ```perl my $txn = $env->begin; my $db = $txn->open_db('users', MDB_CREATE); $txn->put($db, alice => 'admin'); print $txn->get($db, 'alice'), "\n"; # admin $txn->commit; ``` ## Edge cases - After `commit` or `abort` the transaction is over: using it croaks `Peta::LMDB: the transaction has ended`. - While a child transaction (`begin` on a transaction) is live, using its parent croaks `the transaction has a live child transaction`. ## Functions ### Reading and writing #### [`get`](Txn/get) Look up a key; the value, or undef when the key is not stored. #### [`get_view`](Txn/get_view) Look up a key and make a variable the value itself, without copying it: for large values read once. #### [`put`](Txn/put) Store a value under a key. #### `del` Delete a key - in an `MDB_DUPSORT` database all its values - or, with a value, just that one value: `$txn->del($db, $key)`, `$txn->del($db, $key, $value)`. True when something was deleted, false when there was nothing to delete. #### `cursor` Open a cursor on a database: `$txn->cursor($db)`, a `Peta::LMDB::Cursor` that walks the keys in order. It ends with the transaction; a read transaction's cursor can be moved to another read transaction with `renew`. ### Databases #### [`open_db`](Txn/open_db) Open a database of the environment, for this and later transactions. #### `stat` A database's statistics, as a hash reference: `entries` (the number of items), `depth`, `branch_pages`, `leaf_pages`, `overflow_pages`, `psize`. #### `drop` Empty a database: `$txn->drop($db)`. `$txn->drop($db, 1)` deletes the database itself, after which its handle is no longer valid. #### `db_flags` The `MDB_*` flags a database was created with, as a number to test with `&`. #### `cmp` Compare two keys as the database orders them - by its `set_compare` sub, or LMDB's order for its flags: `-1`, `0` or `1`, as `cmp` returns. #### `dcmp` Compare two values as an `MDB_DUPSORT` database orders a key's values - by its `set_dupsort` sub, or LMDB's order: `-1`, `0` or `1`. ### Ending a transaction #### `commit` Make the transaction's writes durable and visible, and end it. A failure croaks; the transaction is over either way. Committing a read transaction ends it, keeping the databases it opened. #### `abort` Discard the transaction's writes and end it. Ending a transaction that has already ended does nothing. A transaction that goes out of scope is aborted. #### `reset` Let a read transaction's snapshot go, keeping the transaction for `renew`: cheaper than ending and beginning, for a reader that pauses. A write transaction croaks `reset needs a read transaction`. #### `renew` Give a `reset` read transaction a fresh snapshot of the data as it is now. ### Nesting #### `begin` Start a child transaction inside a write transaction: `$txn->begin`. Its writes join the parent's at its `commit`, or vanish at its `abort`, while the parent's other writes stand. The parent cannot be used until the child ends. A read transaction cannot have children. ### Information #### `id` The transaction's ID: for a write transaction its own, for a read one the ID of the commit its snapshot shows. #### `env` The transaction's environment, a `Peta::LMDB::Env`. ```{toctree} :hidden: :maxdepth: 1 Txn/get Txn/get_view Txn/put Txn/open_db ```