trac.db.api – Trac DB abstraction layer

Interfaces

class trac.db.api.IDatabaseConnector

Bases: trac.core.Interface

Extension point interface for components that support the connection to relational databases.

See also trac.db.api.IDatabaseConnector extension point.

backup(dest)

Backup the database to a location defined by trac.backup_dir

db_exists(path, log=None, **kwargs)

Return True if the database exists.

destroy_db(path, log=None, **kwargs)

Destroy the database.

get_connection(path, log=None, **kwargs)

Create a new connection to the database.

get_exceptions()

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/).

get_supported_schemes()

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.

get_system_info()

Yield a sequence of (name, version) tuples describing the name and version information of external packages used by the connector.

init_db(path, schema=None, log=None, **kwargs)

Initialize the database.

to_sql(table)

Return the DDL statements necessary to create the specified table, including indices.

Classes

The following classes are not meant to be used directly, but rather via the Environment methods db_transaction and db_query.

class trac.db.api.QueryContextManager(env)

Bases: trac.db.api.DbContextManager

Database Context Manager for retrieving a read-only ConnectionWrapper.

class trac.db.api.TransactionContextManager(env)

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:

class trac.db.api.DbContextManager(env)

Bases: object

Database Context Manager

The outermost DbContextManager will close the connection.

execute(query, params=None)

Shortcut for directly executing a query.

executemany(query, params=None)

Shortcut for directly calling “executemany” on a query.

The API of database backend specific connection classes (like SQLiteConnection) is specified and documented in a base class, the ConnectionBase.

class trac.db.api.ConnectionBase

Bases: object

Abstract base class for database connection classes.

cast(column, type)

Returns a clause casting column as type.

concat(*args)

Returns a clause concatenating the sequence args.

drop_column(table, column)

Drops the column from table.

drop_table(table)

Drops the table.

get_column_names(table)

Returns the list of the column names in table.

get_last_id(cursor, table, column='id')

Returns the current value of the primary key sequence for table. The column of the primary key may be specified, which defaults to id.

get_sequence_names()

Returns a list of the sequence names.

get_table_names()

Returns a list of the table names.

has_table(table)

Returns whether the table exists.

like()

Returns a case-insensitive LIKE clause.

like_escape(text)

Returns text escaped for use in a LIKE clause.

prefix_match()

Return a case sensitive prefix-matching operator.

prefix_match_value(prefix)

Return a value for case sensitive prefix-matching operator.

quote(identifier)

Returns the quoted identifier.

reset_tables()

Deletes all data from the tables and resets autoincrement indexes.

Returns:list of names of the tables that were reset.
update_sequence(cursor, table, column='id')

Updates the current value of the primary key sequence for table. The column of the primary key may be specified, which defaults to id.

Components

class trac.db.api.DatabaseManager

Bases: trac.core.Component

Component used to manage the IDatabaseConnector implementations.

backup(dest=None)

Save a backup of the database.

Parameters:dest – base filename to write to.

Returns the file actually written.

backup_dir

Database backup location

connection_uri

Database connection [wiki:TracEnvironment#DatabaseConnectionStrings string] for this project

connectors

List of components that implement IDatabaseConnector

create_tables(schema)

Create the specified tables.

Parameters:schema – an iterable of table objects.
Since:version 1.0.2
debug_sql

Show the SQL queries in the Trac log, at DEBUG level.

drop_columns(table, columns)

Drops the specified columns from table.

Since:version 1.2
drop_tables(schema)

Drop the specified tables.

Parameters:schema – an iterable of Table objects or table names.
Since:version 1.0.2
get_column_names(table)

Returns a list of the column names for table.

Parameters:table – a Table object or table name.
Since:1.2
get_connection(readonly=False)

Get a database connection from the pool.

If readonly is True, the returned connection will purposely lack the rollback and commit methods.

get_database_version(name='database_version')

Returns the database version from the SYSTEM table as an int, or False if the entry is not found.

Parameters:name – The name of the entry that contains the database version in the SYSTEM table. Defaults to database_version, which contains the database version for Trac.
get_sequence_names()

Returns a list of the sequence names.

Since:1.3.2
get_table_names()

Returns a list of the table names.

Since:1.1.6
has_table(table)

Returns whether the table exists.

insert_into_tables(data_or_callable)

Insert data into existing tables.

Parameters:data_or_callable –

Nested tuples of table names, column names and row data:

(table1,
 (column1, column2),
 ((row1col1, row1col2),
  (row2col1, row2col2)),
 table2, ...)

or a callable that takes a single parameter db and returns the aforementioned nested tuple.
Since:version 1.1.3
needs_upgrade(version, name='database_version')

Checks the database version to determine if an upgrade is needed.

Parameters:
  • version – the expected integer database version.
  • name – the name of the entry in the SYSTEM table that contains the database version. Defaults to database_version, which contains the database version for Trac.
Returns:

True if the stored version is less than the expected version, False if it is equal to the expected version.
Raises:

TracError – if the stored version is greater than the expected version.
reset_tables()

Deletes all data from the tables and resets autoincrement indexes.

Returns:list of names of the tables that were reset.
Since:version 1.1.3
set_database_version(version, name='database_version')

Sets the database version in the SYSTEM table.

Parameters:
  • version – an integer database version.
  • name – The name of the entry that contains the database version in the SYSTEM table. Defaults to database_version, which contains the database version for Trac.
timeout

Timeout value for database connection, in seconds. Use ‘0’ to specify ‘’no timeout’‘.

upgrade(version, name='database_version', pkg=None)

Invokes do_upgrade(env, version, cursor) in module "%s/db%i.py" % (pkg, version), for each required version upgrade.

Parameters:
  • version – the expected integer database version.
  • name – the name of the entry in the SYSTEM table that contains the database version. Defaults to database_version, which contains the database version for Trac.
  • pkg – the package containing the upgrade modules.
Raises:

TracError – if the package or module doesn’t exist.
upgrade_tables(new_schema)

Upgrade table schema to new_schema, preserving data in columns that exist in the current schema and new_schema.

Parameters:new_schema – tuple or list of Table objects
Since:version 1.2

Functions

trac.db.api.get_column_names(cursor)

Retrieve column names from a cursor, if possible.

trac.db.api.parse_connection_uri(db_str)

Parse the database connection string.

The database connection string for an environment is specified through the database option in the [trac] section of trac.ini.

Returns:a tuple containing the scheme and a dictionary of attributes: user, password, host, port, path, params.
Since:1.1.3