[Zodb-checkins] SVN: ZODB/branches/pycon-multidb/src/ZODB/tests/multidb.txt Added an overview.

[Tim Peters]

Log message for revision 29600:
  Added an overview.
  
  Redid the start of the test to build from an empty
  .databases dict, since I expect that will be how this
  gets used in reality.
  
  Added some tests showing the keys in the mappings.
  

Changed:
  U   ZODB/branches/pycon-multidb/src/ZODB/tests/multidb.txt

-=-
Modified: ZODB/branches/pycon-multidb/src/ZODB/tests/multidb.txt
===================================================================
--- ZODB/branches/pycon-multidb/src/ZODB/tests/multidb.txt	2005-03-20 22:14:52 UTC (rev 29599)
+++ ZODB/branches/pycon-multidb/src/ZODB/tests/multidb.txt	2005-03-20 22:18:10 UTC (rev 29600)
@@ -16,13 +16,43 @@
 ====================
 
 Multi-database support adds the ability to tie multiple databases into a
-collection.
+collection.  The original proposal is in the fishbowl:
 
+    http://www.zope.org/Wikis/ZODB/MultiDatabases/
+
+It was implemented during the PyCon 2005 sprints, but in a simpler form,
+by Jim Fulton, Christian Theune,and Tim Peters.  Overview:
+
+No private attributes were added, and one new method was introduced.
+
+DB:
+
+- a new .database_name attribute holds the name of this database
+
+- a new .databases attribute maps from database name to DB object; all DBs
+  in a multi-database collection share the same .databases object
+
+- the DB constructor has new optional arguments with the same names
+  (database_name= and databases=).
+
+Connection:
+
+- a new .connections attribute maps from database name to a Connection for
+  the database with that name; the .connections mapping object is also
+  shared among databases in a collection
+
+- a new .get_connection(database_name) method returns a Connection for a
+  database in the collection; if a connection is already open, it's returned
+  (this is the value .connections[database_name]), else a new connection is
+  opened (and stored as .connections[database_name])
+
+
 Creating a multi-database starts with creating a named DB:
 
     >>> from ZODB.tests.test_storage import MinimalMemoryStorage
     >>> from ZODB import DB
-    >>> db = DB(MinimalMemoryStorage(), database_name='root')
+    >>> dbmap = {}
+    >>> db = DB(MinimalMemoryStorage(), database_name='root', databases=dbmap)
 
 The database name is accessible afterwards and in a newly created collection:
 
@@ -30,25 +60,29 @@
     'root'
     >>> db.databases        # doctest: +ELLIPSIS
     {'root': <ZODB.DB.DB object at ...>}
+    >>> db.databases is dbmap
+    True
 
-Adding a new database works like this:
+Adding another database to the collection works like this:
 
     >>> db2 = DB(MinimalMemoryStorage(),
     ...     database_name='notroot',
-    ...     databases=db.databases)
+    ...     databases=dbmap)
 
 The new db2 now shares the 'databases' dictionary with db and has two entries:
 
-    >>> db2.databases is db.databases
+    >>> db2.databases is db.databases is dbmap
     True
     >>> len(db2.databases)
     2
+    >>> names = dbmap.keys(); names.sort(); print names
+    ['notroot', 'root']
 
-Trying to insert a database with a name that is already in use will not work:
+It's an error to try to insert a database with a name already in use:
 
     >>> db3 = DB(MinimalMemoryStorage(),
     ...     database_name='root',
-    ...     databases=db.databases)
+    ...     databases=dbmap)
     Traceback (most recent call last):
         ...
     ValueError: database_name 'root' already in databases
@@ -83,6 +117,8 @@
     True
     >>> len(cn2.connections)
     2
+    >>> names = cn.connections.keys(); names.sort(); print names
+    ['notroot', 'root']
 
 So long as this database group remains open, the same Connection objects
 are returned:
@@ -106,5 +142,5 @@
 
 Clean up:
 
-    >>> for a_db in db.databases.values():
+    >>> for a_db in dbmap.values():
     ...     a_db.close()