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

[Barry Warsaw]

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

Modified Files:
	README 
Log Message:
A bunch of updates for 1.0 beta 5.  Might could use one more pass.


=== StandaloneZODB/bsddb3Storage/README 1.3 => 1.4 ===
+Berkeley (bsddb3) Storage 1.0 beta 5 for ZODB/Zope
 
 
 Introduction
@@ -26,13 +26,12 @@
       garbage collection on the call to pack().  Thus it is not (yet)
       packless.  However, because Minimal shares code with the Full
       storage, and provides a more robust temporary commit log, this
-      is the wave of the future.  For 1.0 final release, Minimal will
-      be augmented to provide packless reclamation of reference
-      counted garbage, and will be integrated with automatic cyclic
-      garbage detection.
+      is the wave of the future.  Because of resource constraints
+      though, it is unlikely that Minimal will get much attention for
+      the 1.0 release.
 
     - Full.py is a complete storage implementation, supporting undo,
-      versions, automatic reference counting garbage collection.
+      versions, and automatic reference counting garbage collection.
       Packing this storage is only required in order to get rid of old
       object revisions.  Full storage provides some experimental
       support for cyclic garbage collection, although this will not be
@@ -59,9 +58,8 @@
 
     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.
+    work with Python 1.5.2.  It may or may not work with Python 2.2,
+    but it will be tested against Python 2.2 before the final 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
@@ -124,7 +122,7 @@
     Type "copyright", "credits" or "license" for more information.
     >>> import bsddb3Storage
     >>> bsddb3Storage.__version__
-    '1.0 beta 3'
+    '1.0 beta 5'
 
     See also docs/PacklessReadme.txt for alternative installation
     directions.
@@ -170,6 +168,31 @@
     ZEO, see the "start.txt" file in the ZEO release documentation.
 
 
+Using Berkeley storage outside of Zope
+
+    For StandaloneZODB applications that want to use bsddb3Storage,
+    the one thing you need to watch out for is that closing the
+    database is the responsibility of the application.  With a
+    Berkeley storage, if you do not explicitly close it before
+    application exit, you will leave the Berkeley database in a
+    corrupt (but recoverable) state.
+
+    By default, Full opens its Berkeley databases with the DB_RECOVER
+    flag, meaning if recovery is necessary (e.g. because you didn't
+    explicitly close it the last time you opened it), then recover
+    will be run automatically on database open.  You can also manually
+    recover the database by running Berkeley's db_recover program.
+
+    The upshot of this is that a database which was not gracefully
+    closed can usually be recovered automatically, but this will
+    greatly increase the time it takes to open the databases.  IOW,
+    you will see a long delay when instantiating a Full object, since
+    this is when the databases are opened.  The delay is proportional
+    to the size of your database.  To avoid this problem, always close
+    your Full storage when you're done with it (probably wrapped in a
+    try/finally clause).
+
+
 BerkeleyDB Files
 
     After Zope is started with one of the Berkeley storages, you will
@@ -183,7 +206,7 @@
     BerkeleyDB, and they are less important.  It's wise to back up all
     the files in this directory regularly.  BerkeleyDB supports
     "hot-backup".  Log files need to be archived and cleared on a
-    regular basis (a following section covers this).
+    regular basis (see below).
 
     You may also occasionally see some files with names that are long
     strings of hexadecimal digits.  These are "commit log" temporary
@@ -194,14 +217,14 @@
     Because of the semantics of BerkeleyDB's transactions, it is
     necessary to store the changes in this temporary file until a
     BerkeleyDB transaction can be committed.  Under normal operation,
-    the long hex-digit files should only exist during a ZODB
-    transaction.  However, if some fatal error occurs during a ZODB
-    transaction which is neither committed nor aborted, the
+    the long hex-digit files should only temporarily exist during a
+    ZODB transaction.  However, if some fatal error occurs during a
+    ZODB transaction which is neither committed nor aborted, the
     uncommitted changes will reside in this file.  Your storage will
     then refuse to allow new changes to the database until a recovery
     process is run (this is not the BerkeleyDB recovery process, and
-    unfortunately the recover script has not yet been written; it will
-    for the 1.0 final release).
+    unfortunately the recover script has not yet been written; we'll
+    get to it soon).
 
 
 BerkeleyDB Log Files
@@ -273,7 +296,7 @@
     provide the multiplied-by-2 numbers as arguments to
     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.
+    strategy, see http://www.sleepycat.com/docs/ref/lock/max.html
 
 
 Tuning BerkeleyDB