Changes between Version 9 and Version 10 of TracDev/DatabaseApi

Timestamp:

Apr 15, 2009, 11:49:38 PM (15 years ago)

Author:

jerry

Comment:

Add some information about pooled connections

TracDev/DatabaseApi

@@ -12 +12 @@
 == Accessing the Database ==
 
-Code accessing the database in Trac go through this layer simply by using the {{{Environment}}} method {{{get_db_cnx()}}}:
+Code accessing the database in Trac go through this layer simply by using the {{{Environment}}} method {{{get_db_cnx()}}} in order to get a pooled database connection.  A database cursor can be obtained from the pooled database connection, and the code uses the cursor in conjunction with SQL statements to implement the behavior.  
 
 {{{
 #!python
 from trac.env import Environment
+def myFunc():
+    env = Environment('/path/to/projenv')
+    db = env.get_db_cnx()
+    cursor = db.cursor()
+    # Execute some SQL statements
 
-env = Environment('/path/to/projenv')
-db = env.get_db_cnx()
-cursor = db.cursor()
-# Execute some SQL statements
-
-db.commit()
+    db.commit()
+    return
 }}}
 
@@ -34 +35 @@
 
  ''The connection URI syntax has been designed to be compatible with that provided by [http://sqlobject.org/docs/SQLObject.html#declaring-the-class SQLObject] (see also the Wiki page on SQLObject [http://wiki.sqlobject.org/connections.html connections]). The only supported URI schemes at this point are {{{sqlite}}} and {{{postgres}}}.''
+
+=== Pooled Connections ===
+
+The {{{Environment}}} method {{{get_db_cnx()}}} returns a connection from the pool of connections.  This connection needs to be returned, and Trac is written so that the return will happen automatically by the garbage collector if the code is written to follow a simple rule.  When the garbage collector determines the pooled database connection is no longer being used, it's __del__ method will return the pooled connection to the pool for reuse.  If you have set a lexical variable in the function's body to the pooled connection, this typically occurs when the function is returning.  In the example above of {{{myFunc}}} it occurs at the return statement since {{{db}}} is a variable local to {{{myFunc}}}
 
 == Rules for DB API Usage ==