# [LMDB](http://www.lmdb.tech/doc/index.html) bindings for lua
license: MIT

## errors
operations that can fail will return `nil, error, errno` on failure.

## functions
### `lmdb.open(path, opt)`
create a new environment handle and open the database at the `path`. returns the environment handle (`env`) on success.

`opt` is an optional table of options:

* `maxdbs`: number: the maximum number of databases in the environment. must be set if multiple databases will be used.
* `mapsize`: number: the memory map size used for this environment. this is also the maximum size of the database. default: 1GiB (`1024^3`).
* `rdonly`: boolean: open the environment in read-only mode.
* `nosubdir`: boolean: the `path` is used for the database file itself and not its containing directory.
* `nosync`: boolean: don't flush buffers to disk when committing.
* `nolock`: boolean: turn off locking. the application must manage all concurrency.

### `lmdb.version()`
returns the LMDB version as `major, minor, patch`.

### `lmdb.next(db, key)`
returns the next key-value pair after `key` in the database handle `db`, or the first key-value pair if `key` is `nil`. keys are ordered lexicographically. unlike `next`, this function does not work for traversal if, during traversal, keys are set to `nil`. (TODO: fix this somehow)

### `env:txn_begin(write_enabled)`
create a new transaction in the environment. if `write_enabled` is true, then the transaction may make modifications to the database. returns the transaction handle (`txn`) on success.

### `env:copy(path)`
copy the environment to the specified `path`. return `true` on success.

### `env:sync(force)`
flush buffers to disk. if `force` is `true`, a synchronous flush is performed even if `nosync` is set. return `true` on success.

### `env:close()`
close the environment.

### `txn:open(name, create)`
open a database in the environment. if multiple databases are to be used in the environment, `name` is the name of the database to open. otherwise, it should not be supplied. if `create` is true, the database is created if it does not exist. returns a database handle (`db`) on success.

### `txn:drop(name)`
delete the database `name` from the environment. (or clear the database, if `name` is not supplied)

### `txn:abort()`
abandon all operations performed in the transaction.

### `txn:commit()`
commit all operations of the transaction into the database.

### `txn:txn_begin()`
create a nested transaction in the parent transaction.

### `db[key]`
read the value of `key` from the database.

### `db[key] = value`
write `value` as the value of `key` into the database.

### `pairs(db)`, `lmdb.pairs(db)`
returns `lmdb.next, db, nil`, allowing iteration through all the key-value pairs of a database. the `lmdb.pairs` form works even on lua 5.1, which doesn't support the `__pairs` metamethod.

### `#db`
return the number of entries in the database.