[SQL-CVS] r2414 - SQLObject/docs

[<sub...@co...>]

Author: phd
Date: 2007-03-16 09:45:41 -0600 (Fri, 16 Mar 2007)
New Revision: 2414

Modified:
   SQLObject/docs/SQLObject.txt
Log:
Documentation update - connection pooling and transactions.


Modified: SQLObject/docs/SQLObject.txt
===================================================================
--- SQLObject/docs/SQLObject.txt	2007-03-15 19:37:51 UTC (rev 2413)
+++ SQLObject/docs/SQLObject.txt	2007-03-16 15:45:41 UTC (rev 2414)
@@ -1323,6 +1323,19 @@
 Similar to `MultipleJoin`, but returns just one object, not a list.
 
 
+Connection pooling
+------------------
+
+Connection object acquires a new low-level DB API connection from the pool
+and stores it; the low-level connection is removed from the pool;
+"releasing" means "return it to the pool". For single-threaded programs
+there is one connection in the pool.
+
+If the pool is empty a new low-level connection opened; if one has
+disabled pooling (by setting conn._pool = None) the connection will be
+closed instead of returning to the pool.
+
+
 Transactions
 ------------
 
@@ -1341,8 +1354,20 @@
 database connection, and `commit` and `rollback` just pass that
 message to the low-level connection.
 
-If you want to begin a new transaction after a .rollback() call .begin().
+One can call as much .commit()'s, but after a .rollback() one has to call
+.begin(). The last .commit() should be called as .commit(close=True) to
+release low-level connection.
 
+If you want to use transactions you should also turn `_cacheValues`
+off, like::
+
+    class Person(SQLObject):
+        _cacheValue = False
+
+This, though, makes attribute access very slow (SQLObject queries database
+for an every attribute access). If one wants to set `_cacheValue = True`
+one has to synchronize objects between threads herself.
+
 You can use SELECT FOR UPDATE in those databases that support it::
 
     Person.select(Person.q.name=="value", forUpdate=True)