Package trac :: Package db :: Module api

Module api

source code

Extension point interface for components that support the connection to relational databases.
with_transaction(env, db=None)
Function decorator to emulate a context manager for database transactions.
source code
Get a database connection for reading only.
source code
get_column_names(cursor) source code
  __package__ = 'trac.db'

Imports: os, urllib, time, BoolOption, IntOption, Option, ConnectionPool, ThreadLocal, unicode_passwd, _, Component, ExtensionPoint, Interface, TracError, implements

Function Details

with_transaction(env, db=None)

source code 

Function decorator to emulate a context manager for database transactions.

>>> def api_method(p1, p2):
>>>     result[0] = value1
>>>     @with_transaction(env)
>>>     def implementation(db):
>>>         # implementation
>>>         result[0] = value2
>>>     return result[0]

In this example, the implementation() function is called automatically right after its definition, with a database connection as an argument. If the function completes, a COMMIT is issued on the connection. If the function raises an exception, a ROLLBACK is issued and the exception is re-raised. Nested transactions are supported, and a COMMIT will only be issued when the outermost transaction block in a thread exits.

This mechanism is intended to replace the current practice of getting a database connection with env.get_db_cnx() and issuing an explicit commit or rollback, for mutating database accesses. Its automatic handling of commit, rollback and nesting makes it much more robust.

This decorator will be replaced by a context manager once python 2.4 support is dropped.

The optional db argument is intended for legacy code and should not be used in new code.