mdbx 0.1.0.pre.20201217111933 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be5af4b8718ccda99471808092ab76ed497758add8a8c429d6eae16b9279c007
-  data.tar.gz: a183a3ba5019cc1b8cbda9ae45f803342c02011de762202728b6ab96c8f7d133
+  metadata.gz: c7cc7a297e0f41d6caa23aa581bd11b1013a64a63ec6b04e9f07daae06f153d4
+  data.tar.gz: b5a27168b461c29f88bbaf0c1fc45ec92f0fd121735ef483c76be66adef0750e
 SHA512:
-  metadata.gz: e7e463a36ed38653930e9894404431de494cc39e6efa2ae6993681d4198b28c9ecf0c160b09f01353d6296699e9a2ea780973f983a7a32b91b6630d76ad10e2a
-  data.tar.gz: 300534e3d3c342019d803840e956afdc7d4e3bb114d8fe4df95918cfb85808df146979ff56af539e23ae8bfbacf9f7acab1aaaef4742b0b16a162ad6364d7bba
+  metadata.gz: ea27eb32cb736c4cc5d0a154d445e9c7e53966a219ab61bdca7fd4bb886538320e47f40fb9d91569b14b0d6aacf69e0dcab045c5ba5c51416231e5abde8326cd
+  data.tar.gz: 0b5496433f6854926f90edc33aeccf9aba653fd76c6db6903ef1d5d95bbafca538957417eba1a90ee087f09faebc2df11eab0e6ceabb67846428ecc8635776c7

data/History.md

@@ -1,6 +1,10 @@
-# Release History for mdbx
+# Release History for MDBX
 
 ---
+## v0.1.0 [2021-03-14] Mahlon E. Smith <mahlon@martini.nu>
+
+Initial public release.
+
 
 ## v0.0.1 [2020-12-16] Mahlon E. Smith <mahlon@martini.nu>
 

data/README.md

@@ -1,4 +1,5 @@
-# Ruby MDBX
+
+# Ruby::MDBX
 
 home
 : https://code.martini.nu/ruby-mdbx
@@ -24,64 +25,333 @@ sourcehut:
 This is a Ruby (MRI) binding for the libmdbx database library.
 
 libmdbx is an extremely fast, compact, powerful, embedded, transactional
-key-value database, with permissive license. libmdbx has a specific set
+key-value database, with a permissive license. libmdbx has a specific set
 of properties and capabilities, focused on creating unique lightweight
 solutions.
 
-  - Allows a swarm of multi-threaded processes to ACIDly read and update
-  several key-value maps and multimaps in a locally-shared database.
+For more information about libmdbx (features, limitations, etc), see the
+[introduction](https://erthink.github.io/libmdbx/intro.html).
 
-  - Provides extraordinary performance, minimal overhead through
-  Memory-Mapping and Olog(N) operations costs by virtue of B+ tree.
 
-  - Requires no maintenance and no crash recovery since it doesn't use
-  WAL, but that might be a caveat for write-intensive workloads with
-  durability requirements.
+## Prerequisites
 
-  - Compact and friendly for fully embedding. Only ≈25KLOC of C11,
-  ≈64K x86 binary code of core, no internal threads neither server
-  process(es), but implements a simplified variant of the Berkeley DB
-  and dbm API.
+* Ruby 2.6+
+* [libmdbx](https://github.com/erthink/libmdbx)
 
-  - Enforces serializability for writers just by single mutex and
-  affords wait-free for parallel readers without atomic/interlocked
-  operations, while writing and reading transactions do not block each
-  other.
 
-  - Guarantee data integrity after crash unless this was explicitly
-  neglected in favour of write performance.
+## Installation
 
-  - Supports Linux, Windows, MacOS, Android, iOS, FreeBSD, DragonFly,
-  Solaris, OpenSolaris, OpenIndiana, NetBSD, OpenBSD and other systems
-  compliant with POSIX.1-2008.
+    $ gem install mdbx
 
-  - Historically, libmdbx is a deeply revised and extended descendant
-  of the amazing Lightning Memory-Mapped Database. libmdbx inherits
-  all benefits from LMDB, but resolves some issues and adds a set of
-  improvements.
+You may need to be specific if the libmdbx headers are located in a
+nonstandard location for your operating system:
 
+	$ gem install mdbx -- --with-opt-dir=/usr/local
 
-### Examples
 
-[forthcoming]
+## Usage
 
+Some quick concepts:
 
-## Prerequisites
+  - A **database** is contained in a file, normally contained in directory
+    with it's associated lockfile.
+  - Each database can optionally contain multiple named **collections**,
+    which can be thought of as distinct namespaces.
+  - Each collection can contain any number of **keys**, and their associated
+    **values**. 
+  - A **snapshot** is a self-consistent read-only view of the database.
+    It remains consistent even if another thread or process writes changes.
+  - A **transaction** is a writable snapshot.  Changes made within a
+    transaction are not seen by other snapshots until committed. 
 
-* Ruby 2.6+
-* libmdbx (https://github.com/erthink/libmdbx)
+### Open (and close) a database handle
 
+Open a database handle, creating an empty one if not already present.
 
-## Installation
+```ruby
+db = MDBX::Database.open( "/path/to/file", options )
+db.close
+```
 
-    $ gem install mdbx
+In block form, the handle is automatically closed.
+
+```ruby
+MDBX::Database.open( 'database' ) do |db|
+    puts db[ 'key1' ]
+end # closed database
+```
+
+
+### Read data
+
+You can use the database handle as a hash. Reading a value automatically
+creates a snapshot, retrieves the value, and closes the snapshot before
+returning it.
+
+```ruby
+db[ 'key1' ] #=> val
+```
+
+All data reads require a snapshot (or transaction).
+
+The `snapshot` method creates a long-running snapshot manually.  In
+block form, the snapshot is automatically closed when the block exits.
+Sharing a snapshot between reads is significantly faster when fetching
+many values or in tight loops.
+
+```ruby
+# read-only block
+db.snapshot do
+    db[ 'key1' ] #=> val
+    ...
+end # snapshot closed
+```
+
+You can also open and close a snapshot manually.
+
+```ruby
+db.snapshot
+db.values_at( 'key1', 'key2' ) #=> [ value, value ]
+db.rollback
+```
+
+Technically, `snapshot` just sets the internal state and returns the
+database handle - the handle is also yielded when using blocks.  The
+following 3 examples are identical, use whatever form you prefer.
+
+```ruby
+snap = db.snapshot
+snap[ 'key1' ]
+snap.abort
+
+db.snapshot do |snap|
+    snap[ 'key1' ]
+end
+
+db.snapshot do
+    db[ 'key1' ]
+end
+```
+
+Attempting writes while within an open snapshot is an exception.
+
+
+### Write data
+
+Writing data is also hash-like.  Assigning a value to a key
+automatically opens a writable transaction, stores the value, and
+commits the transaction before returning.
+
+All keys are strings, or converted to a string automatically.
+
+```ruby
+db[ 'key1' ] = val
+db[ :key1 ] == db[ 'key1' ] #=> true
+```
+
+All data writes require a transaction.
+
+The `transaction` method creates a long-running transaction manually.  In
+block form, the transaction is automatically closed when the block exits.
+Sharing a transaction between writes is significantly faster when
+storing many values or in tight loops.
+
+```ruby
+# read/write block
+db.transaction do
+    db[ 'key1' ] = val
+end # transaction committed and closed
+```
+
+You can also open and close a transaction manually.
+
+```ruby
+db.transaction
+db[ 'key1' ] = val
+db.commit
+```
+
+Like snapshots, `transaction` just sets the internal state and returns
+the database handle - the handle is also yielded when using blocks.  The
+following 3 examples are identical, use whatever form you prefer.
+
+```ruby
+txn = db.transaction
+txn[ 'key1' ] = true
+txn.save
+
+db.transaction do |txn|
+    txn[ 'key1' ] = true
+end
+
+db.transaction do
+    db[ 'key1' ] = true
+end
+```
+
+### Delete data
+
+Just write a `nil` value to remove a key entirely, or like Hash, use the
+`#delete` method:
+
+```ruby
+db[ 'key1' ] = nil
+```
+
+```ruby
+oldval = db.delete( 'key1' )
+```
+
+
+### Transactions
+
+Transactions are largely modelled after the
+[Sequel](https://sequel.jeremyevans.net/rdoc/files/doc/transactions_rdoc.html)
+transaction basics.
+
+While in a transaction block, if no exception is raised, the
+transaction is automatically committed and closed when the block exits.
+
+```ruby
+db[ 'key' ] = false
+
+db.transaction do # BEGIN
+    db[ 'key' ] = true
+end # COMMIT
+
+db[ 'key' ] #=> true
+```
+
+If the block raises a MDBX::Rollback exception, the transaction is
+rolled back, but no exception is raised outside the block:
+
+```ruby
+db[ 'key' ] = false
+
+db.transaction do # BEGIN
+    db[ 'key' ] = true
+    raise MDBX::Rollback
+end # ROLLBACK
+
+db[ 'key' ] #=> false
+```
+
+If any other exception is raised, the transaction is rolled back, and
+the exception is raised outside the block:
+
+```ruby
+db[ 'key' ] = false
+
+db.transaction do # BEGIN
+    db[ 'key' ] = true
+    raise ArgumentError
+end # ROLLBACK
+
+# ArgumentError raised
+```
+
+
+If you want to check whether you are currently in a transaction, use the
+Database#in_transaction? method:
+
+```ruby
+db.in_transaction? #=> false
+db.transaction do
+    db.in_transaction? #=> true
+end
+```
+
+MDBX writes are strongly serialized, and an open transaction blocks
+other writers until it has completed.  Snapshots have no such
+serialization, and readers from separate processes do not interfere with
+each other.  Be aware of libmdbx behaviors while in open transactions.
+
+
+### Collections
+
+A MDBX collection is a sub-database, or a namespace.  In order to use
+this feature, the database must be opened with the `max_collections`
+option:
+
+```ruby
+db = MDBX::Database.open( "/path/to/file", max_collections: 10 )
+```
+
+Afterwards, you can switch collections at will.
+
+```ruby
+db.collection( 'sub' )
+db.collection #=> 'sub'
+db[ :key ] = true
+db.main # switch to the top level
+db[ :key ] #=> nil
+```
+
+In block form, the collection is reverted to the current collection when
+the block was started:
+
+```ruby
+db.collection( 'sub1' )
+db.collection( 'sub2' ) do
+    db[ :key ] = true
+end # the collection is reverted to 'sub1'
+```
+
+Collections cannot be switched while a snapshot or transaction is open.
+
+Collection names are stored in the top-level database as keys.  Attempts
+to use these keys as regular values, or switching to a key that is not
+a collection will result in an incompatibility error.  While using
+collections, It's probably wise to not store regular key/value data in a
+top-level database to avoid this ambiguity.
+
+
+### Value Serialization
+
+By default, all values are stored as Marshal data - this is the most
+"Ruby" behavior, as you can store any Ruby object directly that supports
+`Marshal.dump`.
+
+```ruby
+db.serializer   = ->( v ) { Marshal.dump( v ) }
+db.deserializer = ->( v ) { Marshal.load( v ) }
+```
+
+For compatibility with databases used by other languages, or if your
+needs are more specific, you can disable or override the default
+serialization behaviors after opening the database.
+
+```ruby
+# All values are JSON strings
+db.serializer   = ->( v ) { JSON.generate( v ) }
+db.deserializer = ->( v ) { JSON.parse( v ) }
+```
+
+```ruby
+# Disable all automatic serialization
+db.serializer   = nil
+db.deserializer = nil
+```
+
+### Introspection
+
+Calling `statistics` on a database handle will provide a subset of
+information about the build environment, the database environment, and
+the currently connected clients.
+
+
+## TODO
+
+  - Expose more database/collection information to statistics
+  - Support libmdbx multiple values per key DUPSORT via `put`, `get`
+    Enumerators, and a 'value' argument for `delete`.
 
 
 ## Contributing
 
 You can check out the current development source with Mercurial via its
 [home repo](https://code.martini.nu/ruby-mdbx), or with Git at its
-[project page](https://gitlab.com/mahlon/ruby-mdbx).
+[project mirror](https://gitlab.com/mahlon/ruby-mdbx).
 
 After checking out the source, run:
 
@@ -99,7 +369,7 @@ development.
 
 ## License
 
-Copyright (c) 2020, Mahlon E. Smith
+Copyright (c) 2020-2021 Mahlon E. Smith
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

data/ext/mdbx_ext/database.c

@@ -2,42 +2,18 @@
 
 #include "mdbx_ext.h"
 
-/* VALUE str = rb_sprintf( "path: %+"PRIsVALUE", opts: %+"PRIsVALUE, path, opts ); */
-/* printf( "%s\n", StringValueCStr(str) ); */
-
-VALUE rmdbx_cDatabase;
-
-
 /* Shortcut for fetching current DB variables.
- *
  */
 #define UNWRAP_DB( val, db ) \
 	rmdbx_db_t *db; \
 	TypedData_Get_Struct( val, rmdbx_db_t, &rmdbx_db_data, db );
 
 
-/*
- * A struct encapsulating an instance's DB state.
- */
-struct rmdbx_db {
-	MDBX_env *env;
-	MDBX_dbi dbi;
-	MDBX_txn *txn;
-	MDBX_cursor *cursor;
-	int env_flags;
-	int mode;
-	int open;
-	int max_collections;
-	char *path;
-	char *subdb;
-};
-typedef struct rmdbx_db rmdbx_db_t;
-
+VALUE rmdbx_cDatabase;
 
 /*
  * Ruby allocation hook.
  */
-void rmdbx_free( void *db );  /* forward declaration */
 static const rb_data_type_t rmdbx_db_data = {
 	.wrap_struct_name = "MDBX::Database::Data",
 	.function = { .dfree = rmdbx_free },
@@ -61,13 +37,27 @@ rmdbx_alloc( VALUE klass )
  * removed.
  */
 void
-rmdbx_close_all( rmdbx_db_t* db )
+rmdbx_close_all( rmdbx_db_t *db )
 {
 	if ( db->cursor ) mdbx_cursor_close( db->cursor );
 	if ( db->txn )    mdbx_txn_abort( db->txn );
 	if ( db->dbi )    mdbx_dbi_close( db->env, db->dbi );
 	if ( db->env )    mdbx_env_close( db->env );
-	db->open = 0;
+	db->state.open = 0;
+}
+
+
+/*
+ * Close any open database handle.  Will be automatically
+ * re-opened on next transaction.  This is primarily useful for
+ * switching between subdatabases.
+ */
+void
+rmdbx_close_dbi( rmdbx_db_t *db )
+{
+	if ( ! db->dbi ) return;
+	mdbx_dbi_close( db->env, db->dbi );
+	db->dbi = 0;
 }
 
 
@@ -79,13 +69,13 @@ rmdbx_free( void *db )
 {
 	if ( db ) {
 		rmdbx_close_all( db );
-		free( db );
+		xfree( db );
 	}
 }
 
 
 /*
- * Cleanly close an opened database from Ruby.
+ * Cleanly close an opened database.
  */
 VALUE
 rmdbx_close( VALUE self )
@@ -96,8 +86,38 @@ rmdbx_close( VALUE self )
 }
 
 
+/*
+ * call-seq:
+ *    db.closed? => false
+ *
+ * Predicate: return true if the database environment is closed.
+ */
+VALUE
+rmdbx_closed_p( VALUE self )
+{
+	UNWRAP_DB( self, db );
+	return db->state.open == 1 ? Qfalse : Qtrue;
+}
+
+
+/*
+ * call-seq:
+ *    db.in_transaction? => false
+ *
+ * Predicate: return true if a transaction (or snapshot)
+ * is currently open.
+ */
+VALUE
+rmdbx_in_transaction_p( VALUE self )
+{
+	UNWRAP_DB( self, db );
+	return db->txn ? Qtrue : Qfalse;
+}
+
+
 /*
  * Open the DB environment handle.
+ *
  */
 VALUE
 rmdbx_open_env( VALUE self )
@@ -113,48 +133,60 @@ rmdbx_open_env( VALUE self )
 		rb_raise( rmdbx_eDatabaseError, "mdbx_env_create: (%d) %s", rc, mdbx_strerror(rc) );
 
 	/* Set the maximum number of named databases for the environment. */
-	// FIXME: potenially more env setups here?  maxreaders, pagesize?
-	mdbx_env_set_maxdbs( db->env, db->max_collections );
+	mdbx_env_set_maxdbs( db->env, db->settings.max_collections );
+
+	/* Customize the maximum number of simultaneous readers. */
+	if ( db->settings.max_readers )
+		mdbx_env_set_maxreaders( db->env, db->settings.max_readers );
 
-	rc = mdbx_env_open( db->env, db->path, db->env_flags, db->mode );
+	/* Set an upper boundary (in bytes) for the database map size. */
+	if ( db->settings.max_size )
+		mdbx_env_set_geometry( db->env, -1, -1, db->settings.max_size, -1, -1, -1 );
+
+	rc = mdbx_env_open( db->env, db->path, db->settings.env_flags, db->settings.mode );
 	if ( rc != MDBX_SUCCESS ) {
-		rmdbx_close( self );
+		rmdbx_close_all( db );
 		rb_raise( rmdbx_eDatabaseError, "mdbx_env_open: (%d) %s", rc, mdbx_strerror(rc) );
 	}
-	db->open = 1;
+	db->state.open = 1;
 
 	return Qtrue;
 }
 
 
 /*
- * call-seq:
- *    db.closed? #=> false
- *
- * Predicate: return true if the database environment is closed.
+ * Open a cursor for iteration.
  */
-VALUE
-rmdbx_closed_p( VALUE self )
+void
+rmdbx_open_cursor( rmdbx_db_t *db )
 {
-	UNWRAP_DB( self, db );
-	return db->open == 1 ? Qfalse : Qtrue;
+	if ( ! db->state.open ) rb_raise( rmdbx_eDatabaseError, "Closed database." );
+	if ( ! db->txn ) rb_raise( rmdbx_eDatabaseError, "No snapshot or transaction currently open." );
+
+	int rc = mdbx_cursor_open( db->txn, db->dbi, &db->cursor );
+	if ( rc != MDBX_SUCCESS ) {
+		rmdbx_close_all( db );
+		rb_raise( rmdbx_eDatabaseError, "Unable to open cursor: (%d) %s", rc, mdbx_strerror(rc) );
+	}
+
+	return;
 }
 
 
 /*
- * Open a new database transaction.
+ * Open a new database transaction.  If a transaction is already
+ * open, this is a no-op.
  *
  * +rwflag+ must be either MDBX_TXN_RDONLY or MDBX_TXN_READWRITE.
  */
 void
-rmdbx_open_txn( VALUE self, int rwflag )
+rmdbx_open_txn( rmdbx_db_t *db, int rwflag )
 {
-	int rc;
-	UNWRAP_DB( self, db );
+	if ( db->txn ) return;
 
-	rc = mdbx_txn_begin( db->env, NULL, rwflag, &db->txn);
+	int rc = mdbx_txn_begin( db->env, NULL, rwflag, &db->txn );
 	if ( rc != MDBX_SUCCESS ) {
-		rmdbx_close( self );
+		rmdbx_close_all( db );
 		rb_raise( rmdbx_eDatabaseError, "mdbx_txn_begin: (%d) %s", rc, mdbx_strerror(rc) );
 	}
 
@@ -162,7 +194,7 @@ rmdbx_open_txn( VALUE self, int rwflag )
 		// FIXME: dbi_flags
 		rc = mdbx_dbi_open( db->txn, db->subdb, MDBX_CREATE, &db->dbi );
 		if ( rc != MDBX_SUCCESS ) {
-			rmdbx_close( self );
+			rmdbx_close_all( db );
 			rb_raise( rmdbx_eDatabaseError, "mdbx_dbi_open: (%d) %s", rc, mdbx_strerror(rc) );
 		}
 	}
@@ -171,24 +203,90 @@ rmdbx_open_txn( VALUE self, int rwflag )
 }
 
 
+/*
+ * Close any existing database transaction. If there is no
+ * active transaction, this is a no-op.  If there is a long
+ * running transaction open, this is a no-op.
+ *
+ * +txnflag must either be RMDBX_TXN_ROLLBACK or RMDBX_TXN_COMMIT.
+ */
+void
+rmdbx_close_txn( rmdbx_db_t *db, int txnflag )
+{
+	if ( ! db->txn || db->state.retain_txn > -1 ) return;
+
+	switch ( txnflag ) {
+		case RMDBX_TXN_COMMIT:
+			mdbx_txn_commit( db->txn );
+		default:
+			mdbx_txn_abort( db->txn );
+	}
+
+	db->txn = 0;
+	return;
+}
+
+
+/*
+ * call-seq:
+ *    db.open_transaction( mode )
+ *
+ * Open a new long-running transaction.  If +mode+ is true,
+ * it is opened read/write.
+ *
+ */
+VALUE
+rmdbx_rb_opentxn( VALUE self, VALUE mode )
+{
+	UNWRAP_DB( self, db );
+
+	rmdbx_open_txn( db, RTEST(mode) ? MDBX_TXN_READWRITE : MDBX_TXN_RDONLY );
+	db->state.retain_txn = RTEST(mode) ? 1 : 0;
+
+	return Qtrue;
+}
+
+
+/*
+ * call-seq:
+ *    db.close_transaction( mode )
+ *
+ * Close a long-running transaction.  If +write+ is true,
+ * the transaction is committed.  Otherwise, rolled back.
+ *
+ */
+VALUE
+rmdbx_rb_closetxn( VALUE self, VALUE write )
+{
+	UNWRAP_DB( self, db );
+
+	db->state.retain_txn = -1;
+	rmdbx_close_txn( db, RTEST(write) ? RMDBX_TXN_COMMIT : RMDBX_TXN_ROLLBACK );
+
+	return Qtrue;
+}
+
+
 /*
  * call-seq:
  *    db.clear
  *
- * Empty the database (or collection) on disk.  Unrecoverable!
+ * Empty the current collection on disk.  If collections are not enabled
+ * or the database handle is set to the top-level (main) db - this
+ * deletes *all records* from the database.  This is not recoverable!
  */
 VALUE
 rmdbx_clear( VALUE self )
 {
 	UNWRAP_DB( self, db );
 
-	rmdbx_open_txn( self, MDBX_TXN_READWRITE );
+	rmdbx_open_txn( db, MDBX_TXN_READWRITE );
 	int rc = mdbx_drop( db->txn, db->dbi, true );
 
 	if ( rc != MDBX_SUCCESS )
 		rb_raise( rmdbx_eDatabaseError, "mdbx_drop: (%d) %s", rc, mdbx_strerror(rc) );
 
-	mdbx_txn_commit( db->txn );
+	rmdbx_close_txn( db, RMDBX_TXN_COMMIT );
 
 	/* Refresh the environment handles. */
 	rmdbx_open_env( self );
@@ -236,72 +334,161 @@ rmdbx_val_for( VALUE self, VALUE arg )
 }
 
 
+/*
+ * Deserialize and return a value.
+ */
+VALUE
+rmdbx_deserialize( VALUE self, VALUE val )
+{
+	VALUE deserialize_proc = rb_iv_get( self, "@deserializer" );
+	if ( ! NIL_P( deserialize_proc ) )
+		val = rb_funcall( deserialize_proc, rb_intern("call"), 1, val );
+
+	return val;
+}
+
+
 /* call-seq:
- *    db.keys #=> [ 'key1', 'key2', ... ]
+ *    db.each_key {|key| block } => self
  *
- * Return an array of all keys in the current collection.
+ * Calls the block once for each key, returning self.
+ * A transaction must be opened prior to use.
  */
 VALUE
-rmdbx_keys( VALUE self )
+rmdbx_each_key( VALUE self )
 {
 	UNWRAP_DB( self, db );
-	VALUE rv = rb_ary_new();
 	MDBX_val key, data;
-	int rc;
 
-	if ( ! db->open ) rb_raise( rmdbx_eDatabaseError, "Closed database." );
+	rmdbx_open_cursor( db );
+	RETURN_ENUMERATOR( self, 0, 0 );
 
-	rmdbx_open_txn( self, MDBX_TXN_RDONLY );
-	rc = mdbx_cursor_open( db->txn, db->dbi, &db->cursor);
+	if ( mdbx_cursor_get( db->cursor, &key, &data, MDBX_FIRST ) == MDBX_SUCCESS ) {
+		rb_yield( rb_str_new( key.iov_base, key.iov_len ) );
+		while ( mdbx_cursor_get( db->cursor, &key, &data, MDBX_NEXT ) == MDBX_SUCCESS ) {
+			rb_yield( rb_str_new( key.iov_base, key.iov_len ) );
+		}
+	}
 
-	if ( rc != MDBX_SUCCESS ) {
-		rmdbx_close( self );
-		rb_raise( rmdbx_eDatabaseError, "Unable to open cursor: (%d) %s", rc, mdbx_strerror(rc) );
+	mdbx_cursor_close( db->cursor );
+	db->cursor = NULL;
+	return self;
+}
+
+
+/* call-seq:
+ *    db.each_value {|value| block } => self
+ *
+ * Calls the block once for each value, returning self.
+ * A transaction must be opened prior to use.
+ */
+VALUE
+rmdbx_each_value( VALUE self )
+{
+	UNWRAP_DB( self, db );
+	MDBX_val key, data;
+
+	rmdbx_open_cursor( db );
+	RETURN_ENUMERATOR( self, 0, 0 );
+
+	if ( mdbx_cursor_get( db->cursor, &key, &data, MDBX_FIRST ) == MDBX_SUCCESS ) {
+		VALUE rv = rb_str_new( data.iov_base, data.iov_len );
+		rb_yield( rmdbx_deserialize( self, rv ) );
+
+		while ( mdbx_cursor_get( db->cursor, &key, &data, MDBX_NEXT ) == MDBX_SUCCESS ) {
+			rv = rb_str_new( data.iov_base, data.iov_len );
+			rb_yield( rmdbx_deserialize( self, rv ) );
+		}
 	}
 
-	rc = mdbx_cursor_get( db->cursor, &key, &data, MDBX_FIRST );
-	if ( rc == MDBX_SUCCESS ) {
-		rb_ary_push( rv, rb_str_new( key.iov_base, key.iov_len ) );
-		while ( mdbx_cursor_get( db->cursor, &key, &data, MDBX_NEXT ) == 0 ) {
-			rb_ary_push( rv, rb_str_new( key.iov_base, key.iov_len ) );
+	mdbx_cursor_close( db->cursor );
+	db->cursor = NULL;
+	return self;
+}
+
+
+/* call-seq:
+ *    db.each_pair {|key, value| block } => self
+ *
+ * Calls the block once for each key and value, returning self.
+ * A transaction must be opened prior to use.
+ */
+VALUE
+rmdbx_each_pair( VALUE self )
+{
+	UNWRAP_DB( self, db );
+	MDBX_val key, data;
+
+	rmdbx_open_cursor( db );
+	RETURN_ENUMERATOR( self, 0, 0 );
+
+	if ( mdbx_cursor_get( db->cursor, &key, &data, MDBX_FIRST ) == MDBX_SUCCESS ) {
+		VALUE rkey = rb_str_new( key.iov_base, key.iov_len );
+		VALUE rval = rb_str_new( data.iov_base, data.iov_len );
+		rb_yield( rb_assoc_new( rkey, rmdbx_deserialize( self, rval ) ) );
+
+		while ( mdbx_cursor_get( db->cursor, &key, &data, MDBX_NEXT ) == MDBX_SUCCESS ) {
+			rkey = rb_str_new( key.iov_base, key.iov_len );
+			rval = rb_str_new( data.iov_base, data.iov_len );
+			rb_yield( rb_assoc_new( rkey, rmdbx_deserialize( self, rval ) ) );
 		}
 	}
 
 	mdbx_cursor_close( db->cursor );
 	db->cursor = NULL;
-	mdbx_txn_abort( db->txn );
+	return self;
+}
+
+
+/* call-seq:
+ *    db.length -> Integer
+ *
+ * Returns the count of keys in the currently selected collection.
+ */
+VALUE
+rmdbx_length( VALUE self )
+{
+	UNWRAP_DB( self, db );
+	MDBX_stat mstat;
+
+	if ( ! db->state.open ) rb_raise( rmdbx_eDatabaseError, "Closed database." );
+	rmdbx_open_txn( db, MDBX_TXN_RDONLY );
+
+	int rc = mdbx_dbi_stat( db->txn, db->dbi, &mstat, sizeof(mstat) );
+	if ( rc != MDBX_SUCCESS )
+		rb_raise( rmdbx_eDatabaseError, "mdbx_dbi_stat: (%d) %s", rc, mdbx_strerror(rc) );
+
+	VALUE rv = LONG2FIX( mstat.ms_entries );
+	rmdbx_close_txn( db, RMDBX_TXN_ROLLBACK );
+
 	return rv;
 }
 
 
 /* call-seq:
- *    db[ 'key' ]  #=> value
+ *    db[ 'key' ] => value
  *
- * Convenience method:  return a single value for +key+ immediately.
+ * Return a single value for +key+ immediately.
  */
 VALUE
 rmdbx_get_val( VALUE self, VALUE key )
 {
 	int rc;
-	VALUE deserialize_proc;
 	UNWRAP_DB( self, db );
 
-	if ( ! db->open ) rb_raise( rmdbx_eDatabaseError, "Closed database." );
-
-	rmdbx_open_txn( self, MDBX_TXN_RDONLY );
+	if ( ! db->state.open ) rb_raise( rmdbx_eDatabaseError, "Closed database." );
+	rmdbx_open_txn( db, MDBX_TXN_RDONLY );
 
 	MDBX_val ckey = rmdbx_key_for( key );
 	MDBX_val data;
+	VALUE rv;
 	rc = mdbx_get( db->txn, db->dbi, &ckey, &data );
-	mdbx_txn_abort( db->txn );
+	rmdbx_close_txn( db, RMDBX_TXN_ROLLBACK );
 
 	switch ( rc ) {
 		case MDBX_SUCCESS:
-			deserialize_proc = rb_iv_get( self, "@deserializer" );
-			VALUE rv = rb_str_new( data.iov_base, data.iov_len );
-			if ( ! NIL_P( deserialize_proc ) )
-				return rb_funcall( deserialize_proc, rb_intern("call"), 1, rv );
-			return rv;
+			rv = rb_str_new( data.iov_base, data.iov_len );
+			return rmdbx_deserialize( self, rv );
 
 		case MDBX_NOTFOUND:
 			return Qnil;
@@ -314,9 +501,9 @@ rmdbx_get_val( VALUE self, VALUE key )
 
 
 /* call-seq:
- *    db[ 'key' ] = value #=> value
+ *    db[ 'key' ] = value
  *
- * Convenience method:  set a single value for +key+
+ * Set a single value for +key+.
  */
 VALUE
 rmdbx_put_val( VALUE self, VALUE key, VALUE val )
@@ -324,9 +511,8 @@ rmdbx_put_val( VALUE self, VALUE key, VALUE val )
 	int rc;
 	UNWRAP_DB( self, db );
 
-	if ( ! db->open ) rb_raise( rmdbx_eDatabaseError, "Closed database." );
-
-	rmdbx_open_txn( self, MDBX_TXN_READWRITE );
+	if ( ! db->state.open ) rb_raise( rmdbx_eDatabaseError, "Closed database." );
+	rmdbx_open_txn( db, MDBX_TXN_READWRITE );
 
 	MDBX_val ckey = rmdbx_key_for( key );
 
@@ -341,7 +527,7 @@ rmdbx_put_val( VALUE self, VALUE key, VALUE val )
 		rc = mdbx_replace( db->txn, db->dbi, &ckey, &data, &old, 0 );
 	}
 
-	mdbx_txn_commit( db->txn );
+	rmdbx_close_txn( db, RMDBX_TXN_COMMIT );
 
 	switch ( rc ) {
 		case MDBX_SUCCESS:
@@ -356,38 +542,85 @@ rmdbx_put_val( VALUE self, VALUE key, VALUE val )
 
 /*
  * call-seq:
- *    db.collection( 'collection_name' ) # => db
- *    db.collection( nil ) # => db (main)
+ *    db.statistics => (hash of stats)
+ *
+ * Returns a hash populated with various metadata for the opened
+ * database.
+ *
+ */
+VALUE
+rmdbx_stats( VALUE self )
+{
+	UNWRAP_DB( self, db );
+	if ( ! db->state.open ) rb_raise( rmdbx_eDatabaseError, "Closed database." );
+
+	return rmdbx_gather_stats( db );
+}
+
+
+/*
+ * call-seq:
+ *    db.collection -> (collection name, or nil if in main)
+ *    db.collection( 'collection_name' ) -> db
+ *    db.collection( nil ) -> db (main)
  *
- * Operate on a sub-database "collection".  Passing +nil+
- * sets the database to the main, top-level namespace.
+ * Gets or sets the sub-database "collection" that read/write
+ * operations apply to.
+ * Passing +nil+ sets the database to the main, top-level namespace.
+ * If a block is passed, the collection automatically reverts to the
+ * prior collection when it exits.
+ *
+ *    db.collection( 'collection_name' ) do
+ *        [ ... ]
+ *    end # reverts to the previous collection name
  *
  */
 VALUE
 rmdbx_set_subdb( int argc, VALUE *argv, VALUE self )
 {
 	UNWRAP_DB( self, db );
-	VALUE subdb;
+	VALUE subdb, block;
+	char *prev_db = NULL;
 
-	rb_scan_args( argc, argv, "01", &subdb );
+	rb_scan_args( argc, argv, "01&", &subdb, &block );
 	if ( argc == 0 ) {
 		if ( db->subdb == NULL ) return Qnil;
 		return rb_str_new_cstr( db->subdb );
 	}
 
-	rb_iv_set( self, "@collection", subdb );
+	/* Provide a friendlier error message if max_collections is 0. */
+	if ( db->settings.max_collections == 0 )
+		rb_raise( rmdbx_eDatabaseError, "Unable to change collection: collections are not enabled." );
+
+	/* All transactions must be closed when switching database handles. */
+	if ( db->txn )
+		rb_raise( rmdbx_eDatabaseError, "Unable to change collection: transaction open" );
+
+	/* Retain the prior database collection if a block was passed.
+	 */
+	if ( rb_block_given_p() && db->subdb != NULL ) {
+		prev_db = (char *) malloc( strlen(db->subdb) + 1 );
+		strcpy( prev_db, db->subdb );
+	}
+
 	db->subdb = NIL_P( subdb ) ? NULL : StringValueCStr( subdb );
+	rmdbx_close_dbi( db );
 
-	/* Close any currently open dbi handle, to be re-opened with
-	 * the new collection on next access.
-	 *
+	/*
 	  FIXME:  Immediate transaction write to auto-create new env?
 	  Fetching from here at the moment causes an error if you
-	  haven't written anything yet.
+	  haven't written anything to the new collection yet.
 	 */
-	if ( db->dbi ) {
-		mdbx_dbi_close( db->env, db->dbi );
-		db->dbi = 0;
+
+	/* Revert to the previous collection after the block is done.
+	 */
+	if ( rb_block_given_p() ) {
+		rb_yield( self );
+		if ( db->subdb != prev_db ) {
+			db->subdb = prev_db;
+			rmdbx_close_dbi( db );
+		}
+		xfree( prev_db );
 	}
 
 	return self;
@@ -395,25 +628,20 @@ rmdbx_set_subdb( int argc, VALUE *argv, VALUE self )
 
 
 /*
- * call-seq:
+ * Open an existing (or create a new) mdbx database at filesystem
+ * +path+.  In block form, the database is automatically closed.
+ *
  *    MDBX::Database.open( path ) -> db
  *    MDBX::Database.open( path, options ) -> db
  *    MDBX::Database.open( path, options ) do |db|
- *    		db...
+ *        db...
  *    end
  *
- * Open an existing (or create a new) mdbx database at filesystem
- * +path+.  In block form, the database is automatically closed.
- *
  */
 VALUE
 rmdbx_database_initialize( int argc, VALUE *argv, VALUE self )
 {
-	int mode            = 0644;
-	int max_collections = 0;
-	int env_flags       = MDBX_ENV_DEFAULTS;
 	VALUE path, opts, opt;
-
 	rb_scan_args( argc, argv, "11", &path, &opts );
 
 	/* Ensure options is a hash if it was passed in.
@@ -426,52 +654,59 @@ rmdbx_database_initialize( int argc, VALUE *argv, VALUE self )
 	}
 	rb_hash_freeze( opts );
 
+	/* Initialize the DB vals.
+	 */
+	UNWRAP_DB( self, db );
+	db->env    = NULL;
+	db->dbi    = 0;
+	db->txn    = NULL;
+	db->cursor = NULL;
+	db->path   = StringValueCStr( path );
+	db->subdb  = NULL;
+	db->state.open       = 0;
+	db->state.retain_txn = -1;
+	db->settings.env_flags       = MDBX_ENV_DEFAULTS;
+	db->settings.mode            = 0644;
+	db->settings.max_collections = 0;
+	db->settings.max_readers     = 0;
+	db->settings.max_size        = 0;
+
 	/* Options setup, overrides.
 	 */
 	opt = rb_hash_aref( opts, ID2SYM( rb_intern("mode") ) );
-	if ( ! NIL_P(opt) ) mode = FIX2INT( opt );
+	if ( ! NIL_P(opt) ) db->settings.mode = FIX2INT( opt );
 	opt = rb_hash_aref( opts, ID2SYM( rb_intern("max_collections") ) );
-	if ( ! NIL_P(opt) ) max_collections = FIX2INT( opt );
+	if ( ! NIL_P(opt) ) db->settings.max_collections = FIX2INT( opt );
+	opt = rb_hash_aref( opts, ID2SYM( rb_intern("max_readers") ) );
+	if ( ! NIL_P(opt) ) db->settings.max_readers = FIX2INT( opt );
+	opt = rb_hash_aref( opts, ID2SYM( rb_intern("max_size") ) );
+	if ( ! NIL_P(opt) ) db->settings.max_size = NUM2LONG( opt );
 	opt = rb_hash_aref( opts, ID2SYM( rb_intern("nosubdir") ) );
-	if ( RTEST(opt) ) env_flags = env_flags | MDBX_NOSUBDIR;
+	if ( RTEST(opt) ) db->settings.env_flags = db->settings.env_flags | MDBX_NOSUBDIR;
 	opt = rb_hash_aref( opts, ID2SYM( rb_intern("readonly") ) );
-	if ( RTEST(opt) ) env_flags = env_flags | MDBX_RDONLY;
+	if ( RTEST(opt) ) db->settings.env_flags = db->settings.env_flags | MDBX_RDONLY;
 	opt = rb_hash_aref( opts, ID2SYM( rb_intern("exclusive") ) );
-	if ( RTEST(opt) ) env_flags = env_flags | MDBX_EXCLUSIVE;
+	if ( RTEST(opt) ) db->settings.env_flags = db->settings.env_flags | MDBX_EXCLUSIVE;
 	opt = rb_hash_aref( opts, ID2SYM( rb_intern("compat") ) );
-	if ( RTEST(opt) ) env_flags = env_flags | MDBX_ACCEDE;
+	if ( RTEST(opt) ) db->settings.env_flags = db->settings.env_flags | MDBX_ACCEDE;
 	opt = rb_hash_aref( opts, ID2SYM( rb_intern("writemap") ) );
-	if ( RTEST(opt) ) env_flags = env_flags | MDBX_WRITEMAP;
+	if ( RTEST(opt) ) db->settings.env_flags = db->settings.env_flags | MDBX_WRITEMAP;
 	opt = rb_hash_aref( opts, ID2SYM( rb_intern("no_threadlocal") ) );
-	if ( RTEST(opt) ) env_flags = env_flags | MDBX_NOTLS;
+	if ( RTEST(opt) ) db->settings.env_flags = db->settings.env_flags | MDBX_NOTLS;
 	opt = rb_hash_aref( opts, ID2SYM( rb_intern("no_readahead") ) );
-	if ( RTEST(opt) ) env_flags = env_flags | MDBX_NORDAHEAD;
+	if ( RTEST(opt) ) db->settings.env_flags = db->settings.env_flags | MDBX_NORDAHEAD;
 	opt = rb_hash_aref( opts, ID2SYM( rb_intern("no_memory_init") ) );
-	if ( RTEST(opt) ) env_flags = env_flags | MDBX_NOMEMINIT;
+	if ( RTEST(opt) ) db->settings.env_flags = db->settings.env_flags | MDBX_NOMEMINIT;
 	opt = rb_hash_aref( opts, ID2SYM( rb_intern("coalesce") ) );
-	if ( RTEST(opt) ) env_flags = env_flags | MDBX_COALESCE;
+	if ( RTEST(opt) ) db->settings.env_flags = db->settings.env_flags | MDBX_COALESCE;
 	opt = rb_hash_aref( opts, ID2SYM( rb_intern("lifo_reclaim") ) );
-	if ( RTEST(opt) ) env_flags = env_flags | MDBX_LIFORECLAIM;
+	if ( RTEST(opt) ) db->settings.env_flags = db->settings.env_flags | MDBX_LIFORECLAIM;
 	opt = rb_hash_aref( opts, ID2SYM( rb_intern("no_metasync") ) );
-	if ( RTEST(opt) ) env_flags = env_flags | MDBX_NOMETASYNC;
+	if ( RTEST(opt) ) db->settings.env_flags = db->settings.env_flags | MDBX_NOMETASYNC;
 
 	/* Duplicate keys, on mdbx_dbi_open, maybe set here? */
 	/* MDBX_DUPSORT = UINT32_C(0x04), */
 
-	/* Initialize the DB vals.
-	 */
-	UNWRAP_DB( self, db );
-	db->env       = NULL;
-	db->dbi       = 0;
-	db->txn       = NULL;
-	db->cursor    = NULL;
-	db->env_flags = env_flags;
-	db->mode      = mode;
-	db->max_collections = max_collections;
-	db->path      = StringValueCStr( path );
-	db->open      = 0;
-	db->subdb     = NULL;
-
 	/* Set instance variables.
 	 */
 	rb_iv_set( self, "@path", path );
@@ -501,11 +736,21 @@ rmdbx_init_database()
 	rb_define_method( rmdbx_cDatabase, "close", rmdbx_close, 0 );
 	rb_define_method( rmdbx_cDatabase, "reopen", rmdbx_open_env, 0 );
 	rb_define_method( rmdbx_cDatabase, "closed?", rmdbx_closed_p, 0 );
+	rb_define_method( rmdbx_cDatabase, "in_transaction?", rmdbx_in_transaction_p, 0 );
 	rb_define_method( rmdbx_cDatabase, "clear", rmdbx_clear, 0 );
-	rb_define_method( rmdbx_cDatabase, "keys", rmdbx_keys, 0 );
+	rb_define_method( rmdbx_cDatabase, "each_key", rmdbx_each_key, 0 );
+	rb_define_method( rmdbx_cDatabase, "each_value", rmdbx_each_value, 0 );
+	rb_define_method( rmdbx_cDatabase, "each_pair", rmdbx_each_pair, 0 );
+	rb_define_method( rmdbx_cDatabase, "length", rmdbx_length, 0 );
 	rb_define_method( rmdbx_cDatabase, "[]", rmdbx_get_val, 1 );
 	rb_define_method( rmdbx_cDatabase, "[]=", rmdbx_put_val, 2 );
 
+	/* Manually open/close transactions from ruby. */
+	rb_define_protected_method( rmdbx_cDatabase, "open_transaction",  rmdbx_rb_opentxn, 1 );
+	rb_define_protected_method( rmdbx_cDatabase, "close_transaction", rmdbx_rb_closetxn, 1 );
+
+	rb_define_protected_method( rmdbx_cDatabase, "raw_stats", rmdbx_stats, 0 );
+
 	rb_require( "mdbx/database" );
 }