Extension point interface for components that support the connection to relational databases.
See also trac.db.api.IDatabaseConnector extension point.
Backup the database to a location defined by trac.backup_dir
Create a new connection to the database.
Return an object (typically a module) containing all the backend-specific exception types as attributes, named according to the Python Database API (http://www.python.org/dev/peps/pep-0249/).
Return the connection URL schemes supported by the connector, and their relative priorities as an iterable of (scheme, priority) tuples.
If priority is a negative number, this is indicative of an error condition with the connector. An error message should be attached to the error attribute of the connector.
Initialize the database.
Return the DDL statements necessary to create the specified table, including indices.
The following classes are not meant to be used directly, but rather via the Environment methods db_transaction and db_query.
Bases: trac.db.api.DbContextManager
Database Context Manager for retrieving a read-only ConnectionWrapper.
Bases: trac.db.api.DbContextManager
Transactioned Database Context Manager for retrieving a ConnectionWrapper.
The outermost such context manager will perform a commit upon normal exit or a rollback after an exception.
The above are both subclasses of DbContextManager:
Database Context Manager
The outermost DbContextManager will close the connection.
Shortcut for directly executing a query.
Shortcut for directly calling “executemany” on a query.
Component used to manage the IDatabaseConnector implementations.
Save a backup of the database.
| Parameters: | dest – base filename to write to. |
|---|
Returns the file actually written.
Database backup location
Database connection [wiki:TracEnvironment#DatabaseConnectionStrings string] for this project
List of components that implement IDatabaseConnector
Create the specified tables.
| Parameters: | schema – an iterable of table objects. |
|---|---|
| Since: | version 1.0.2 |
Show the SQL queries in the Trac log, at DEBUG level. ‘’(Since 0.11.5)’‘
Drop the specified tables.
| Parameters: | schema – an iterable of Table objects or table names. |
|---|---|
| Since: | version 1.0.2 |
Get a database connection from the pool.
If readonly is True, the returned connection will purposely lack the rollback and commit methods.
Timeout value for database connection, in seconds. Use ‘0’ to specify ‘’no timeout’‘. ‘’(Since 0.11)’‘
Retrieve column names from a cursor, if possible.
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 former 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.
The optional db argument is intended for legacy code and should not be used in new code.
| Deprecated: | This decorator is in turn deprecated in favor of context managers now that python 2.4 support has been dropped. It will be removed in Trac 1.3.1. Use instead the new context managers, QueryContextManager and TransactionContextManager, which make for much simpler to write code: |
|---|
>>> def api_method(p1, p2):
>>> result = value1
>>> with env.db_transaction as db:
>>> # implementation
>>> result = value2
>>> return result