[Zodb-checkins] CVS: StandaloneZODB/bsddb3Storage - README:1.3

[Barry Warsaw]

Update of /cvs-repository/StandaloneZODB/bsddb3Storage
In directory cvs.zope.org:/tmp/cvs-serv21626

Modified Files:
	README 
Log Message:
Updated a bunch of information, including some notes on tuning, the
need to use BerkeleyDB 3.3.11, etc.


=== StandaloneZODB/bsddb3Storage/README 1.2 => 1.3 ===
 
     This package contains implementations for Zope/ZODB storages based
-    on Sleepycat Software's BerkeleyDB 3.x and the PyBSDDB3 extension.
-    These storages save ZODB data to some number of BerkeleyDB tables,
-    relying on Berkeley's transaction machinery to provide reliability
-    and recoverability.
+    on Sleepycat Software's BerkeleyDB and the PyBSDDB3 extension
+    module.  These storages save ZODB data to some number of
+    BerkeleyDB tables, relying on Berkeley's transaction machinery to
+    provide reliability and recoverability.
 
 
 Contents
@@ -57,41 +57,54 @@
 
 Compatibility
 
-    The Full and Minimal storages have been tested with Python 2.0 and
-    2.1, but not with Python 1.5.2.  It's possible they work with
-    Python 1.5.2, but it's also not likely that Python 1.5.2 will be
-    explicitly supported.  Full storage has been tested with Zope
-    2.3.1 (running Python 2.1) and should work, except for undo as
-    described above.  Transactional undo support will work with Zope
-    2.4.  These storages have only been tested on Linux, and should
-    work for on Unix-like operating system.  Windows has been
-    partially tested, so it should work, but we're not making
-    promises.
+    The Full and Minimal storages have been tested with Python 2.1.1
+    but should work for any Python 2.x version.  It may or may not
+    work with Python 1.5.2.  It may or may not work with Python 2.2
+    alpha (as of this writing 05-Oct-2001), but it will be tested
+    against Python 2.2 when that is in beta release.
+
+    It's possible they work with Python 1.5.2, but it's also not
+    likely that Python 1.5.2 will be explicitly supported.  Full
+    storage has been tested with Zope 2.3.1 (running Python 2.1) and
+    should work, except for undo as described above.  Transactional
+    undo support will work with Zope 2.4.  These storages have only
+    been tested on Linux, and should work for on Unix-like operating
+    system.  Windows has been partially tested, so it should work, but
+    we're not making promises.
 
 
 Requirements
 
-    You must install Sleepcat BerkeleyDB 3.x and Robin Dunn's PyBSDDB
-    package separately.
+    You must install Sleepcat BerkeleyDB and Robin Dunn's PyBSDDB
+    package separately.  As of this writing, BerkeleyDB is at version
+    3.3.11 and PyBSDDB is at 3.3.1.  It is highly recommended that you
+    use at least these versions of the package, as we've seen locking
+    (and other) problems with earlier releases.
 
-    To obtain the latest source release of BerkeleyDB 3.x, see
-    http://www.sleepycat.com.  As of this writing the latest
-    BerkeleyDB release is 3.2.9, and this is the version these
-    storages have been tested with.  Before using BerkeleyDB, be sure
-    that you comply with its licensing requirements:
+    To obtain the latest source release of BerkeleyDB, see the
+    SleepyCat site:
 
-    http://www.sleepycat.com/licensing.html
+    http://www.sleepycat.com
 
     To obtain the latest source release of Robin Dunn's PyBSDDB
-    package, see http://pybsddb.sourceforge.net
+    package, see:
 
-    Install both BerkeleyDB and PyBSDDB as per the instructions which
+     http://pybsddb.sourceforge.net
+
+    Install both BerkeleyDB and PyBSDDB as per the instructions that
     they come with.  For BerkeleyDB, it's generally wise to accept the
     default "configure" options and do a "make install" as root.
     PyBSDDB comes with a distutils-based setup script which should
     allow you to place the package in a globally accessible directory
     which is in your PYTHONPATH (e.g. "site-packages/bsddb3").
 
+    Be sure to apply the BerkeleyDB patch that comes with PyBSDDB, and
+    do this /before/ you run the PyBSDDB test suite, otherwise your
+    tests will core dump and leave bogus artifacts behind which will
+    hang further tests.  If this happens, remove tests/db_home, apply
+    the BerkeleyDB patch and reinstall BerkeleyDB, and then re-run the
+    PyBSDDB tests.
+
     When you can run the tests which ship with PyBSDDB, you'll know
     you've been successful at both BerkeleyDB and PyBSDDB
     installation.
@@ -261,6 +274,21 @@
     set_lk_max_locks, set_lk_max_objects, and set_lk_max_lockers
     respectively in DB_CONFIG.  For detailed BerkeleyDB locking sizing
     strategy, see http://www.sleepycat.com/docs/ref/lock/max.html.
+
+
+Tuning BerkeleyDB
+
+    BerkeleyDB has lots of knobs you can twist to tune it for your
+    application.  Getting most of these knobs at the right setting is
+    an art, and will be different from system to system.  We're still
+    working on recommendations with respect to the Full storage, but
+    for the time being, you should at least read the following
+    Sleepycat pages:
+
+    http://www.sleepycat.com/docs/ref/am_conf/cachesize.html
+    http://www.sleepycat.com/docs/ref/am_misc/tune.html
+    http://www.sleepycat.com/docs/ref/transapp/tune.html
+    http://www.sleepycat.com/docs/ref/transapp/throughput.html
 
 
 Archival and Maintenance