Changes between Version 11 and Version 12 of TracDev/DatabaseApi

Timestamp:

Sep 15, 2010, 7:32:50 PM (14 years ago)

Author:

Christian Boos

Comment:

present briefly the 0.12 API (@with_transaction)

TracDev/DatabaseApi

@@ -11 +11 @@
 
 == Accessing the Database ==
+=== API before Trac 0.12
 
 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.  
@@ -30 +31 @@
 (avoid in particular doing `cursor = env.get_db_cnx().cursor()`, see r8878).
 
+=== Trac 0.12 API
+
+{{{
+#!python
+from trac.env import Environment
+def myFunc():
+    env = Environment('/path/to/projenv')
+    @with_transaction(env)
+    def do_something(db):
+        cursor = db.cursor()
+        # Execute some SQL statements
+
+    return
+}}}
+
+This is slightly simpler and more robust than the previous API, as not only the `commit()` is performed in any successful case (i.e. the `Execute some SQL statements` code can `return` at any 
+place), but a `rollback` will be performed should an exception be triggered in that block.
+
+See more details in the [../ApiChanges/0.12#with_transaction] paragraph.
+
+=== Configuration
 The {{{get_db_cnx}}} method looks at the value of the {{{database}}} configuration option in [wiki:TracIni trac.ini], which should contain a database connection URI. The default value for this option tells Trac to use an SQLite database inside the environment directory:
 
@@ -41 +63 @@
 === 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}}}
+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, its `__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 ==