[Checkins] SVN: relstorage/trunk/ Updated README and included it, along with CHANGES, in long_description

Shane Hathaway shane at hathawaymix.org
Tue Jan 27 00:00:02 EST 2009


Log message for revision 95067:
  Updated README and included it, along with CHANGES, in long_description
  

Changed:
  U   relstorage/trunk/CHANGES.txt
  U   relstorage/trunk/README.txt
  U   relstorage/trunk/setup.py

-=-
Modified: relstorage/trunk/CHANGES.txt
===================================================================
--- relstorage/trunk/CHANGES.txt	2009-01-27 03:41:51 UTC (rev 95066)
+++ relstorage/trunk/CHANGES.txt	2009-01-27 05:00:01 UTC (rev 95067)
@@ -1,4 +1,6 @@
+
 Next Release
+------------
 
 - When both cache-servers and poll-interval are set, we now poll the
   cache for changes on every request.  This makes it possible to use
@@ -22,6 +24,7 @@
 
 
 Version 1.1.1 (2008-12-27)
+--------------------------
 
 - Worked around MySQL performance bugs in packing.  Used temporary
   tables and another column in the pack_object table.  The
@@ -32,6 +35,7 @@
 
 
 Version 1.1 (2008-12-19)
+------------------------
 
 - Normalized poll-invalidation patches as Solaris' patch command would not
   accept the current format. The patches now apply with:
@@ -62,6 +66,7 @@
 
 
 Version 1.1c1
+-------------
 
 - Added optional memcache integration.  This is useful when the connection
   to the relational database has high latency.
@@ -72,6 +77,7 @@
 
 
 Version 1.1b2
+-------------
 
 - Made the MySQL locks database-specific rather than server-wide.  This is
   important for multi-database configurations.
@@ -85,6 +91,7 @@
 
 
 Version 1.1b1
+-------------
 
 - Fixed the use of setup.py without setuptools.  Thanks to Chris Withers.
 
@@ -106,6 +113,7 @@
 
 
 Version 1.0.1
+-------------
 
 - The speedtest script failed if run on a test database that has no tables.
   Now the script creates the tables if needed.  Thanks to Flavio Coelho
@@ -122,11 +130,13 @@
 
 
 Version 1.0
+-----------
 
 - Added a utility for converting between storages called zodbconvert.
 
 
 Version 1.0c1
+-------------
 
 - The previous fix for non-ASCII characters was incorrect.  Now transaction
   metadata is stored as raw bytes.  A schema migration is required; see
@@ -136,6 +146,7 @@
 
 
 Version 1.0 beta
+----------------
 
 - Renamed to reflect expanding database support.
 
@@ -190,6 +201,7 @@
 =================
 
 Version 0.4
+-----------
 
 - Began using the PostgreSQL LISTEN and NOTIFY statements as a shortcut
   for invalidation polling.
@@ -230,11 +242,13 @@
 
 
 Version 0.3
+-----------
 
 - Made compatible with Zope 3, although an undo bug apparently remains.
 
 
 Version 0.2
+-----------
 
 - Fixed concurrent commits, which were generating deadlocks.  Fixed by
   adding a special table, "commit_lock", which is used for

Modified: relstorage/trunk/README.txt
===================================================================
--- relstorage/trunk/README.txt	2009-01-27 03:41:51 UTC (rev 95066)
+++ relstorage/trunk/README.txt	2009-01-27 05:00:01 UTC (rev 95067)
@@ -1,11 +1,11 @@
 
-
 Overview
 ========
 
   RelStorage is a storage implementation for ZODB that stores pickles in a
 relational database.  PostgreSQL 8.1 and above (via psycopg2), MySQL 5.0.x (via
-MySQLdb), and Oracle 10g (via cx_Oracle) are currently supported.
+MySQLdb 1.2.2 and above), and Oracle 10g (via cx_Oracle) are currently
+supported.
 
   RelStorage replaces the PGStorage project.
 
@@ -48,13 +48,13 @@
 
     python2.4 setup.py install --install-lib=${INSTANCE_HOME}/lib/python
 
-  Before you can use RelStorage, ZODB must have the invalidation polling patch
-applied.  Get it from Subversion (http://svn.zope.org/relstorage/trunk/). 
-There are two versions of the patch: one for ZODB 3.7.1 (which is part of Zope
-2.10.5) and one for ZODB 3.8.0 (which is part of Zope 2.11).  The patch has no
-effect on ZODB except when using RelStorage.  Hopefully, a future release of
-ZODB will include the feature.
+  RelStorage requires a version of ZODB with the invalidation polling patch
+applied.  You can get versions of ZODB with the patch already applied here:
 
+    http://packages.willowrise.org
+
+  The patches are also included in the source distribution of RelStorage.
+
   You need the Python database adapter that corresponds with your database. 
 Install psycopg2, MySQLdb 1.2.2+, or cx_Oracle 4.3+.  Note that Debian Etch
 ships MySQLdb 1.2.1, but that version has a bug in BLOB handling that manifests
@@ -132,21 +132,31 @@
   Sometimes RelStorage needs a schema modification along with a software
 upgrade.  Hopefully, this will not often be necessary.
 
-  To migrate from version 1.0 beta to version 1.0c1, see:
+  To migrate from version 1.1.1 to version 1.1.2, see:
 
-    migrate-1.0-beta.txt_
+    migrate-to-1.1.2.txt_
 
-    .. _migrate-1.0-beta.txt:
-http://svn.zope.org/*checkout*/relstorage/trunk/notes/migrate-1.0-beta.txt
+    .. _migrate-to-1.1.2.txt: http://svn.zope.org/*checkout*/relstorage/trunk/notes/migrate-to-1.1.2.txt
 
+  To migrate from version 1.1 to version 1.1.1, see:
+
+    migrate-to-1.1.1.txt_
+
+    .. _migrate-to-1.1.1.txt: http://svn.zope.org/*checkout*/relstorage/trunk/notes/migrate-to-1.1.1.txt
+
   To migrate from version 1.0.1 to version 1.1, see:
 
-    migrate-1.0.1.txt_
+    migrate-to-1.1.txt_
 
-    .. _migrate-1.0.1.txt:
-http://svn.zope.org/*checkout*/relstorage/branches/1.1/notes/migrate-1.0.1.txt
+    .. _migrate-to-1.1.txt: http://svn.zope.org/*checkout*/relstorage/trunk/notes/migrate-to-1.1.txt
 
+  To migrate from version 1.0 beta to version 1.0c1 through 1.0.1, see:
 
+    migrate-to-1.0.txt_
+
+    .. _migrate-to-1.0.txt: http://svn.zope.org/*checkout*/relstorage/trunk/notes/migrate-to-1.0.txt
+
+
 Optional Features
 =================
 
@@ -154,18 +164,26 @@
 
     poll-interval
 
-        Defer polling the database for the specified maximum time interval.
-        Set to 0 (the default) to always poll.  Fractional seconds are
-        allowed.
+        Defer polling the database for the specified maximum time interval,
+        in seconds.  Set to 0 (the default) to always poll.  Fractional
+        seconds are allowed.  Use this to lighten the database load on
+        servers with high read volume and low write volume.
 
-        Use this to lighten the database load on servers with high read
-        volume and low write volume.  A setting of 1-5 seconds is sufficient
-        for most systems.
+        The poll-interval option works best in conjunction with
+        the cache-servers option.  If both are enabled, RelStorage will
+        poll a single cache key for changes on every request.
+        The database will not be polled unless the cache indicates
+        there have been changes, or the timeout specified by poll-interval
+        has expired.  This configuration keeps clients fully up to date,
+        while removing much of the polling burden from the database.
+        A good cluster configuration is to use memcache servers
+        and a high poll-interval (say, 60 seconds).
 
-        While this setting should not affect database integrity,
-        it increases the probability of basing transactions on stale data,
-        leading to conflicts.  Thus a nonzero setting can hurt
-        the performance of servers with high write volume.
+        This option can be used without the cache-servers option,
+        but a large poll-interval without cache-servers increases the
+        probability of basing transactions on stale data, which does not
+        affect database consistency, but does increase the probability
+        of conflict errors, leading to low performance.
 
     pack-gc
 
@@ -181,6 +199,14 @@
         Disabling garbage collection is also a hack that ensures
         inter-database references never break.
 
+    pack-dry-run
+
+        If pack-dry-run is true, pack operations perform a full analysis
+        of what to pack, but no data is actually removed.  After a dry run,
+        the pack_object, pack_state, and pack_state_tid tables are filled
+        with the list of object states and objects that would have been
+        removed.
+
     pack-batch-timeout
 
         Packing occurs in batches of transactions; this specifies the
@@ -226,8 +252,9 @@
     cache-module-name
 
         Specifies which Python memcache module to use.  The default is
-        "memcache", a pure Python module.  An alternative module is
-        "cmemcache".  This setting has no effect unless cache-servers is set.
+        "memcache", a pure Python module.  There are several alternative
+        modules available through PyPI.  This setting has no effect unless
+        cache-servers is set.
 
 Development
 ===========
@@ -245,10 +272,10 @@
 
 
 
-Probable FAQs
-==============
+FAQs
+====
 
-  Q: How can I help?
+  Q: How can I help improve RelStorage?
 
     A: The best way to help is to test and to provide database-specific
 expertise.  Ask questions about RelStorage on the zodb-dev mailing list.

Modified: relstorage/trunk/setup.py
===================================================================
--- relstorage/trunk/setup.py	2009-01-27 03:41:51 UTC (rev 95066)
+++ relstorage/trunk/setup.py	2009-01-27 05:00:01 UTC (rev 95067)
@@ -11,24 +11,15 @@
 # FOR A PARTICULAR PURPOSE.
 #
 ##############################################################################
-"""A backend for ZODB that stores pickles in a relational database.
+"""A backend for ZODB that stores pickles in a relational database."""
 
-This is designed to be a drop-in replacement for the standard ZODB
-combination of FileStorage and ZEO.  Multiple ZODB clients can
-share the same database without any additional configuration.
-Supports undo, historical database views, packing, and lossless
-migration between FileStorage and RelStorage instances.
+VERSION = "1.2dev"
 
-The supported relational databases are PostgreSQL 8.1 and above
-(using the psycopg2 Python module), MySQL 5.0 and above (using the
-MySQLdb 1.2.2 Python module), and Oracle 10g (using cx_Oracle 4.3).
+# The choices for the Trove Development Status line:
+# Development Status :: 5 - Production/Stable
+# Development Status :: 4 - Beta
+# Development Status :: 3 - Alpha
 
-A small patch to ZODB is required.  See the patch files distributed
-with RelStorage.
-"""
-
-VERSION = "1.2dev"
-
 classifiers = """\
 Development Status :: 4 - Beta
 Intended Audience :: Developers
@@ -40,6 +31,7 @@
 Operating System :: Unix
 """
 
+import os
 try:
     from setuptools import setup
 except ImportError:
@@ -64,6 +56,11 @@
 
 doclines = __doc__.split("\n")
 
+def read_file(*path):
+    base_dir = os.path.dirname(__file__)
+    file_path = (base_dir, ) + tuple(path)
+    return file(os.path.join(*file_path)).read()
+
 setup(
     name="RelStorage",
     version=VERSION,
@@ -78,6 +75,10 @@
     platforms=["any"],
     description=doclines[0],
     classifiers=filter(None, classifiers.split("\n")),
-    long_description = "\n".join(doclines[2:]),
+    long_description = (
+        read_file("README.txt") + "\n\n" +
+        "Changes\n" +
+        "=======\n\n" +
+        read_file("CHANGES.txt")),
     **setuptools_args
     )



More information about the Checkins mailing list