harperdb 3.2.1 → 3.3.0

package/node_modules/lmdb-store/dependencies/lmdb/libraries/liblmdb/crypto.c

@@ -1,121 +1,121 @@
-/* crypto.c - LMDB encryption helper module */
-/*
- * Copyright 2020-2021 Howard Chu, Symas Corp.
- * All rights reserved.
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted only as authorized by the Symas
- * Dual-Use License.
- *
- * A copy of this license is available in the file LICENSE in the
- * source distribution.
- */
-#include <string.h>
-
-#include <openssl/engine.h>
-
-#include "lmdb.h"
-
-MDB_crypto_hooks MDB_crypto;
-
-static EVP_CIPHER *cipher;
-
-static int mcf_str2key(const char *passwd, MDB_val *key)
-{
-	unsigned int size;
-	EVP_MD_CTX *mdctx = EVP_MD_CTX_new();
-	EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL);
-	EVP_DigestUpdate(mdctx, "Just a Constant", sizeof("Just a Constant"));
-	EVP_DigestUpdate(mdctx, passwd, strlen(passwd));
-	EVP_DigestFinal_ex(mdctx, key->mv_data, &size);
-	EVP_MD_CTX_free(mdctx);
-	return 0;
-}
-
-/* cheats - internal OpenSSL 1.1 structures */
-typedef struct evp_cipher_ctx_st {
-    const EVP_CIPHER *cipher;
-    ENGINE *engine;             /* functional reference if 'cipher' is
-                                 * ENGINE-provided */
-    int encrypt;                /* encrypt or decrypt */
-    int buf_len;                /* number we have left */
-    unsigned char oiv[EVP_MAX_IV_LENGTH]; /* original iv */
-    unsigned char iv[EVP_MAX_IV_LENGTH]; /* working iv */
-    unsigned char buf[EVP_MAX_BLOCK_LENGTH]; /* saved partial block */
-    int num;                    /* used by cfb/ofb/ctr mode */
-    /* FIXME: Should this even exist? It appears unused */
-    void *app_data;             /* application stuff */
-    int key_len;                /* May change for variable length cipher */
-    unsigned long flags;        /* Various flags */
-    void *cipher_data;          /* per EVP data */
-    int final_used;
-    int block_mask;
-    unsigned char final[EVP_MAX_BLOCK_LENGTH]; /* possible final block */
-} EVP_CIPHER_CTX;
-
-#define	CHACHA_KEY_SIZE	32
-#define CHACHA_CTR_SIZE	16
-#define CHACHA_BLK_SIZE	64
-#define POLY1305_BLOCK_SIZE	16
-
-typedef struct {
-    union {
-        double align;   /* this ensures even sizeof(EVP_CHACHA_KEY)%8==0 */
-        unsigned int d[CHACHA_KEY_SIZE / 4];
-    } key;
-    unsigned int  counter[CHACHA_CTR_SIZE / 4];
-    unsigned char buf[CHACHA_BLK_SIZE];
-    unsigned int  partial_len;
-} EVP_CHACHA_KEY;
-
-typedef struct {
-    EVP_CHACHA_KEY key;
-    unsigned int nonce[12/4];
-    unsigned char tag[POLY1305_BLOCK_SIZE];
-    unsigned char tls_aad[POLY1305_BLOCK_SIZE];
-    struct { uint64_t aad, text; } len;
-    int aad, mac_inited, tag_len, nonce_len;
-    size_t tls_payload_length;
-} EVP_CHACHA_AEAD_CTX;
-
-static int mcf_encfunc(const MDB_val *src, MDB_val *dst, const MDB_val *key, int encdec)
-{
-	unsigned char iv[12];
-	int ivl, outl, rc;
-	mdb_size_t *ptr;
-	EVP_CIPHER_CTX ctx = {0};
-	EVP_CHACHA_AEAD_CTX cactx;
-
-	ctx.cipher_data = &cactx;
-	ptr = key[1].mv_data;
-	ivl = ptr[0] & 0xffffffff;
-	memcpy(iv, &ivl, 4);
-	memcpy(iv+4, ptr+1, sizeof(mdb_size_t));
-	EVP_CipherInit_ex(&ctx, cipher, NULL, key[0].mv_data, iv, encdec);
-	EVP_CIPHER_CTX_set_padding(&ctx, 0);
-	if (!encdec) {
-		EVP_CIPHER_CTX_ctrl(&ctx, EVP_CTRL_AEAD_SET_TAG, key[2].mv_size, key[2].mv_data);
-	}
-	rc = EVP_CipherUpdate(&ctx, dst->mv_data, &outl, src->mv_data, src->mv_size);
-	if (rc)
-		rc = EVP_CipherFinal_ex(&ctx, key[2].mv_data, &outl);
-	if (rc && encdec) {
-		EVP_CIPHER_CTX_ctrl(&ctx, EVP_CTRL_AEAD_GET_TAG, key[2].mv_size, key[2].mv_data);
-	}
-	return rc == 0;
-}
-
-static const MDB_crypto_funcs mcf_table = {
-	mcf_str2key,
-	mcf_encfunc,
-	NULL,
-	CHACHA_KEY_SIZE,
-	POLY1305_BLOCK_SIZE,
-	0
-};
-
-MDB_crypto_funcs *MDB_crypto()
-{
-	cipher = (EVP_CIPHER *)EVP_chacha20_poly1305();
-	return (MDB_crypto_funcs *)&mcf_table;
-}
+/* crypto.c - LMDB encryption helper module */
+/*
+ * Copyright 2020-2021 Howard Chu, Symas Corp.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted only as authorized by the Symas
+ * Dual-Use License.
+ *
+ * A copy of this license is available in the file LICENSE in the
+ * source distribution.
+ */
+#include <string.h>
+
+#include <openssl/engine.h>
+
+#include "lmdb.h"
+
+MDB_crypto_hooks MDB_crypto;
+
+static EVP_CIPHER *cipher;
+
+static int mcf_str2key(const char *passwd, MDB_val *key)
+{
+	unsigned int size;
+	EVP_MD_CTX *mdctx = EVP_MD_CTX_new();
+	EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL);
+	EVP_DigestUpdate(mdctx, "Just a Constant", sizeof("Just a Constant"));
+	EVP_DigestUpdate(mdctx, passwd, strlen(passwd));
+	EVP_DigestFinal_ex(mdctx, key->mv_data, &size);
+	EVP_MD_CTX_free(mdctx);
+	return 0;
+}
+
+/* cheats - internal OpenSSL 1.1 structures */
+typedef struct evp_cipher_ctx_st {
+    const EVP_CIPHER *cipher;
+    ENGINE *engine;             /* functional reference if 'cipher' is
+                                 * ENGINE-provided */
+    int encrypt;                /* encrypt or decrypt */
+    int buf_len;                /* number we have left */
+    unsigned char oiv[EVP_MAX_IV_LENGTH]; /* original iv */
+    unsigned char iv[EVP_MAX_IV_LENGTH]; /* working iv */
+    unsigned char buf[EVP_MAX_BLOCK_LENGTH]; /* saved partial block */
+    int num;                    /* used by cfb/ofb/ctr mode */
+    /* FIXME: Should this even exist? It appears unused */
+    void *app_data;             /* application stuff */
+    int key_len;                /* May change for variable length cipher */
+    unsigned long flags;        /* Various flags */
+    void *cipher_data;          /* per EVP data */
+    int final_used;
+    int block_mask;
+    unsigned char final[EVP_MAX_BLOCK_LENGTH]; /* possible final block */
+} EVP_CIPHER_CTX;
+
+#define	CHACHA_KEY_SIZE	32
+#define CHACHA_CTR_SIZE	16
+#define CHACHA_BLK_SIZE	64
+#define POLY1305_BLOCK_SIZE	16
+
+typedef struct {
+    union {
+        double align;   /* this ensures even sizeof(EVP_CHACHA_KEY)%8==0 */
+        unsigned int d[CHACHA_KEY_SIZE / 4];
+    } key;
+    unsigned int  counter[CHACHA_CTR_SIZE / 4];
+    unsigned char buf[CHACHA_BLK_SIZE];
+    unsigned int  partial_len;
+} EVP_CHACHA_KEY;
+
+typedef struct {
+    EVP_CHACHA_KEY key;
+    unsigned int nonce[12/4];
+    unsigned char tag[POLY1305_BLOCK_SIZE];
+    unsigned char tls_aad[POLY1305_BLOCK_SIZE];
+    struct { uint64_t aad, text; } len;
+    int aad, mac_inited, tag_len, nonce_len;
+    size_t tls_payload_length;
+} EVP_CHACHA_AEAD_CTX;
+
+static int mcf_encfunc(const MDB_val *src, MDB_val *dst, const MDB_val *key, int encdec)
+{
+	unsigned char iv[12];
+	int ivl, outl, rc;
+	mdb_size_t *ptr;
+	EVP_CIPHER_CTX ctx = {0};
+	EVP_CHACHA_AEAD_CTX cactx;
+
+	ctx.cipher_data = &cactx;
+	ptr = key[1].mv_data;
+	ivl = ptr[0] & 0xffffffff;
+	memcpy(iv, &ivl, 4);
+	memcpy(iv+4, ptr+1, sizeof(mdb_size_t));
+	EVP_CipherInit_ex(&ctx, cipher, NULL, key[0].mv_data, iv, encdec);
+	EVP_CIPHER_CTX_set_padding(&ctx, 0);
+	if (!encdec) {
+		EVP_CIPHER_CTX_ctrl(&ctx, EVP_CTRL_AEAD_SET_TAG, key[2].mv_size, key[2].mv_data);
+	}
+	rc = EVP_CipherUpdate(&ctx, dst->mv_data, &outl, src->mv_data, src->mv_size);
+	if (rc)
+		rc = EVP_CipherFinal_ex(&ctx, key[2].mv_data, &outl);
+	if (rc && encdec) {
+		EVP_CIPHER_CTX_ctrl(&ctx, EVP_CTRL_AEAD_GET_TAG, key[2].mv_size, key[2].mv_data);
+	}
+	return rc == 0;
+}
+
+static const MDB_crypto_funcs mcf_table = {
+	mcf_str2key,
+	mcf_encfunc,
+	NULL,
+	CHACHA_KEY_SIZE,
+	POLY1305_BLOCK_SIZE,
+	0
+};
+
+MDB_crypto_funcs *MDB_crypto()
+{
+	cipher = (EVP_CIPHER *)EVP_chacha20_poly1305();
+	return (MDB_crypto_funcs *)&mcf_table;
+}

package/node_modules/lmdb-store/dependencies/lmdb/libraries/liblmdb/intro.doc

@@ -1,192 +1,192 @@
-/*
- * Copyright 2015-2021 Howard Chu, Symas Corp.
- * All rights reserved.
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted only as authorized by the OpenLDAP
- * Public License.
- *
- * A copy of this license is available in the file LICENSE in the
- * top-level directory of the distribution or, alternatively, at
- * <http://www.OpenLDAP.org/license.html>.
- */
-/** @page starting Getting Started
-
-LMDB is compact, fast, powerful, and robust and implements a simplified
-variant of the BerkeleyDB (BDB) API. (BDB is also very powerful, and verbosely
-documented in its own right.) After reading this page, the main
-\ref mdb documentation should make sense. Thanks to Bert Hubert
-for creating the
-<a href="https://github.com/ahupowerdns/ahutils/blob/master/lmdb-semantics.md">
-initial version</a> of this writeup.
-
-Everything starts with an environment, created by #mdb_env_create().
-Once created, this environment must also be opened with #mdb_env_open().
-
-#mdb_env_open() gets passed a name which is interpreted as a directory
-path. Note that this directory must exist already, it is not created
-for you. Within that directory, a lock file and a storage file will be
-generated. If you don't want to use a directory, you can pass the
-#MDB_NOSUBDIR option, in which case the path you provided is used
-directly as the data file, and another file with a "-lock" suffix
-added will be used for the lock file.
-
-Once the environment is open, a transaction can be created within it
-using #mdb_txn_begin(). Transactions may be read-write or read-only,
-and read-write transactions may be nested. A transaction must only
-be used by one thread at a time. Transactions are always required,
-even for read-only access. The transaction provides a consistent
-view of the data.
-
-Once a transaction has been created, a database can be opened within it
-using #mdb_dbi_open(). If only one database will ever be used in the
-environment, a NULL can be passed as the database name. For named
-databases, the #MDB_CREATE flag must be used to create the database
-if it doesn't already exist. Also, #mdb_env_set_maxdbs() must be
-called after #mdb_env_create() and before #mdb_env_open() to set the
-maximum number of named databases you want to support.
-
-Note: a single transaction can open multiple databases. Generally
-databases should only be opened once, by the first transaction in
-the process. After the first transaction completes, the database
-handles can freely be used by all subsequent transactions.
-
-Within a transaction, #mdb_get() and #mdb_put() can store single
-key/value pairs if that is all you need to do (but see \ref Cursors
-below if you want to do more).
-
-A key/value pair is expressed as two #MDB_val structures. This struct
-has two fields, \c mv_size and \c mv_data. The data is a \c void pointer to
-an array of \c mv_size bytes.
-
-Because LMDB is very efficient (and usually zero-copy), the data returned
-in an #MDB_val structure may be memory-mapped straight from disk. In
-other words <b>look but do not touch</b> (or free() for that matter).
-Once a transaction is closed, the values can no longer be used, so
-make a copy if you need to keep them after that.
-
-@section Cursors Cursors
-
-To do more powerful things, we must use a cursor.
-
-Within the transaction, a cursor can be created with #mdb_cursor_open().
-With this cursor we can store/retrieve/delete (multiple) values using
-#mdb_cursor_get(), #mdb_cursor_put(), and #mdb_cursor_del().
-
-#mdb_cursor_get() positions itself depending on the cursor operation
-requested, and for some operations, on the supplied key. For example,
-to list all key/value pairs in a database, use operation #MDB_FIRST for
-the first call to #mdb_cursor_get(), and #MDB_NEXT on subsequent calls,
-until the end is hit.
-
-To retrieve all keys starting from a specified key value, use #MDB_SET.
-For more cursor operations, see the \ref mdb docs.
-
-When using #mdb_cursor_put(), either the function will position the
-cursor for you based on the \b key, or you can use operation
-#MDB_CURRENT to use the current position of the cursor. Note that
-\b key must then match the current position's key.
-
-@subsection summary Summarizing the Opening
-
-So we have a cursor in a transaction which opened a database in an
-environment which is opened from a filesystem after it was
-separately created.
-
-Or, we create an environment, open it from a filesystem, create a
-transaction within it, open a database within that transaction,
-and create a cursor within all of the above.
-
-Got it?
-
-@section thrproc Threads and Processes
-
-LMDB uses POSIX locks on files, and these locks have issues if one
-process opens a file multiple times. Because of this, do not
-#mdb_env_open() a file multiple times from a single process. Instead,
-share the LMDB environment that has opened the file across all threads.
-Otherwise, if a single process opens the same environment multiple times,
-closing it once will remove all the locks held on it, and the other
-instances will be vulnerable to corruption from other processes.
-
-Also note that a transaction is tied to one thread by default using
-Thread Local Storage. If you want to pass read-only transactions across
-threads, you can use the #MDB_NOTLS option on the environment.
-
-@section txns Transactions, Rollbacks, etc.
-
-To actually get anything done, a transaction must be committed using
-#mdb_txn_commit(). Alternatively, all of a transaction's operations
-can be discarded using #mdb_txn_abort(). In a read-only transaction,
-any cursors will \b not automatically be freed. In a read-write
-transaction, all cursors will be freed and must not be used again.
-
-For read-only transactions, obviously there is nothing to commit to
-storage. The transaction still must eventually be aborted to close
-any database handle(s) opened in it, or committed to keep the
-database handles around for reuse in new transactions.
-
-In addition, as long as a transaction is open, a consistent view of
-the database is kept alive, which requires storage. A read-only
-transaction that no longer requires this consistent view should
-be terminated (committed or aborted) when the view is no longer
-needed (but see below for an optimization).
-
-There can be multiple simultaneously active read-only transactions
-but only one that can write. Once a single read-write transaction
-is opened, all further attempts to begin one will block until the
-first one is committed or aborted. This has no effect on read-only
-transactions, however, and they may continue to be opened at any time.
-
-@section dupkeys Duplicate Keys
-
-#mdb_get() and #mdb_put() respectively have no and only some support
-for multiple key/value pairs with identical keys. If there are multiple
-values for a key, #mdb_get() will only return the first value.
-
-When multiple values for one key are required, pass the #MDB_DUPSORT
-flag to #mdb_dbi_open(). In an #MDB_DUPSORT database, by default
-#mdb_put() will not replace the value for a key if the key existed
-already. Instead it will add the new value to the key. In addition,
-#mdb_del() will pay attention to the value field too, allowing for
-specific values of a key to be deleted.
-
-Finally, additional cursor operations become available for
-traversing through and retrieving duplicate values.
-
-@section optim Some Optimization
-
-If you frequently begin and abort read-only transactions, as an
-optimization, it is possible to only reset and renew a transaction.
-
-#mdb_txn_reset() releases any old copies of data kept around for
-a read-only transaction. To reuse this reset transaction, call
-#mdb_txn_renew() on it. Any cursors in this transaction must also
-be renewed using #mdb_cursor_renew().
-
-Note that #mdb_txn_reset() is similar to #mdb_txn_abort() and will
-close any databases you opened within the transaction.
-
-To permanently free a transaction, reset or not, use #mdb_txn_abort().
-
-@section cleanup Cleaning Up
-
-For read-only transactions, any cursors created within it must
-be closed using #mdb_cursor_close().
-
-It is very rarely necessary to close a database handle, and in
-general they should just be left open.
-
-@section onward The Full API
-
-The full \ref mdb documentation lists further details, like how to:
-
-  \li size a database (the default limits are intentionally small)
-  \li drop and clean a database
-  \li detect and report errors
-  \li optimize (bulk) loading speed
-  \li (temporarily) reduce robustness to gain even more speed
-  \li gather statistics about the database
-  \li define custom sort orders
-
-*/
+/*
+ * Copyright 2015-2021 Howard Chu, Symas Corp.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted only as authorized by the OpenLDAP
+ * Public License.
+ *
+ * A copy of this license is available in the file LICENSE in the
+ * top-level directory of the distribution or, alternatively, at
+ * <http://www.OpenLDAP.org/license.html>.
+ */
+/** @page starting Getting Started
+
+LMDB is compact, fast, powerful, and robust and implements a simplified
+variant of the BerkeleyDB (BDB) API. (BDB is also very powerful, and verbosely
+documented in its own right.) After reading this page, the main
+\ref mdb documentation should make sense. Thanks to Bert Hubert
+for creating the
+<a href="https://github.com/ahupowerdns/ahutils/blob/master/lmdb-semantics.md">
+initial version</a> of this writeup.
+
+Everything starts with an environment, created by #mdb_env_create().
+Once created, this environment must also be opened with #mdb_env_open().
+
+#mdb_env_open() gets passed a name which is interpreted as a directory
+path. Note that this directory must exist already, it is not created
+for you. Within that directory, a lock file and a storage file will be
+generated. If you don't want to use a directory, you can pass the
+#MDB_NOSUBDIR option, in which case the path you provided is used
+directly as the data file, and another file with a "-lock" suffix
+added will be used for the lock file.
+
+Once the environment is open, a transaction can be created within it
+using #mdb_txn_begin(). Transactions may be read-write or read-only,
+and read-write transactions may be nested. A transaction must only
+be used by one thread at a time. Transactions are always required,
+even for read-only access. The transaction provides a consistent
+view of the data.
+
+Once a transaction has been created, a database can be opened within it
+using #mdb_dbi_open(). If only one database will ever be used in the
+environment, a NULL can be passed as the database name. For named
+databases, the #MDB_CREATE flag must be used to create the database
+if it doesn't already exist. Also, #mdb_env_set_maxdbs() must be
+called after #mdb_env_create() and before #mdb_env_open() to set the
+maximum number of named databases you want to support.
+
+Note: a single transaction can open multiple databases. Generally
+databases should only be opened once, by the first transaction in
+the process. After the first transaction completes, the database
+handles can freely be used by all subsequent transactions.
+
+Within a transaction, #mdb_get() and #mdb_put() can store single
+key/value pairs if that is all you need to do (but see \ref Cursors
+below if you want to do more).
+
+A key/value pair is expressed as two #MDB_val structures. This struct
+has two fields, \c mv_size and \c mv_data. The data is a \c void pointer to
+an array of \c mv_size bytes.
+
+Because LMDB is very efficient (and usually zero-copy), the data returned
+in an #MDB_val structure may be memory-mapped straight from disk. In
+other words <b>look but do not touch</b> (or free() for that matter).
+Once a transaction is closed, the values can no longer be used, so
+make a copy if you need to keep them after that.
+
+@section Cursors Cursors
+
+To do more powerful things, we must use a cursor.
+
+Within the transaction, a cursor can be created with #mdb_cursor_open().
+With this cursor we can store/retrieve/delete (multiple) values using
+#mdb_cursor_get(), #mdb_cursor_put(), and #mdb_cursor_del().
+
+#mdb_cursor_get() positions itself depending on the cursor operation
+requested, and for some operations, on the supplied key. For example,
+to list all key/value pairs in a database, use operation #MDB_FIRST for
+the first call to #mdb_cursor_get(), and #MDB_NEXT on subsequent calls,
+until the end is hit.
+
+To retrieve all keys starting from a specified key value, use #MDB_SET.
+For more cursor operations, see the \ref mdb docs.
+
+When using #mdb_cursor_put(), either the function will position the
+cursor for you based on the \b key, or you can use operation
+#MDB_CURRENT to use the current position of the cursor. Note that
+\b key must then match the current position's key.
+
+@subsection summary Summarizing the Opening
+
+So we have a cursor in a transaction which opened a database in an
+environment which is opened from a filesystem after it was
+separately created.
+
+Or, we create an environment, open it from a filesystem, create a
+transaction within it, open a database within that transaction,
+and create a cursor within all of the above.
+
+Got it?
+
+@section thrproc Threads and Processes
+
+LMDB uses POSIX locks on files, and these locks have issues if one
+process opens a file multiple times. Because of this, do not
+#mdb_env_open() a file multiple times from a single process. Instead,
+share the LMDB environment that has opened the file across all threads.
+Otherwise, if a single process opens the same environment multiple times,
+closing it once will remove all the locks held on it, and the other
+instances will be vulnerable to corruption from other processes.
+
+Also note that a transaction is tied to one thread by default using
+Thread Local Storage. If you want to pass read-only transactions across
+threads, you can use the #MDB_NOTLS option on the environment.
+
+@section txns Transactions, Rollbacks, etc.
+
+To actually get anything done, a transaction must be committed using
+#mdb_txn_commit(). Alternatively, all of a transaction's operations
+can be discarded using #mdb_txn_abort(). In a read-only transaction,
+any cursors will \b not automatically be freed. In a read-write
+transaction, all cursors will be freed and must not be used again.
+
+For read-only transactions, obviously there is nothing to commit to
+storage. The transaction still must eventually be aborted to close
+any database handle(s) opened in it, or committed to keep the
+database handles around for reuse in new transactions.
+
+In addition, as long as a transaction is open, a consistent view of
+the database is kept alive, which requires storage. A read-only
+transaction that no longer requires this consistent view should
+be terminated (committed or aborted) when the view is no longer
+needed (but see below for an optimization).
+
+There can be multiple simultaneously active read-only transactions
+but only one that can write. Once a single read-write transaction
+is opened, all further attempts to begin one will block until the
+first one is committed or aborted. This has no effect on read-only
+transactions, however, and they may continue to be opened at any time.
+
+@section dupkeys Duplicate Keys
+
+#mdb_get() and #mdb_put() respectively have no and only some support
+for multiple key/value pairs with identical keys. If there are multiple
+values for a key, #mdb_get() will only return the first value.
+
+When multiple values for one key are required, pass the #MDB_DUPSORT
+flag to #mdb_dbi_open(). In an #MDB_DUPSORT database, by default
+#mdb_put() will not replace the value for a key if the key existed
+already. Instead it will add the new value to the key. In addition,
+#mdb_del() will pay attention to the value field too, allowing for
+specific values of a key to be deleted.
+
+Finally, additional cursor operations become available for
+traversing through and retrieving duplicate values.
+
+@section optim Some Optimization
+
+If you frequently begin and abort read-only transactions, as an
+optimization, it is possible to only reset and renew a transaction.
+
+#mdb_txn_reset() releases any old copies of data kept around for
+a read-only transaction. To reuse this reset transaction, call
+#mdb_txn_renew() on it. Any cursors in this transaction must also
+be renewed using #mdb_cursor_renew().
+
+Note that #mdb_txn_reset() is similar to #mdb_txn_abort() and will
+close any databases you opened within the transaction.
+
+To permanently free a transaction, reset or not, use #mdb_txn_abort().
+
+@section cleanup Cleaning Up
+
+For read-only transactions, any cursors created within it must
+be closed using #mdb_cursor_close().
+
+It is very rarely necessary to close a database handle, and in
+general they should just be left open.
+
+@section onward The Full API
+
+The full \ref mdb documentation lists further details, like how to:
+
+  \li size a database (the default limits are intentionally small)
+  \li drop and clean a database
+  \li detect and report errors
+  \li optimize (bulk) loading speed
+  \li (temporarily) reduce robustness to gain even more speed
+  \li gather statistics about the database
+  \li define custom sort orders
+
+*/