cfme.utils.db module

class cfme.utils.db.Db(hostname=None, credentials=None, port=None)[source]

Bases: _abcoll.Mapping

Helper class for interacting with a CFME database using SQLAlchemy

Parameters:
  • hostname – base url to be used (default is from current_appliance)
  • credentials – name of credentials to use from utils.conf.credentials (default database)

Provides convient attributes to common sqlalchemy objects related to this DB, as well as a Mapping interface to access and reflect database tables. Where possible, attributes are cached.

Db objects support getting tables by name via the mapping interface:

table = db['table_name']

Usage:

# Usually used to query the DB for info, here's a common query
for vm in db.session.query(db['vms']).all():
    print(vm.name)
    print(vm.guid)

# List comprehension to get all templates
[(vm.name, vm.guid) for vm in session.query(db['vms']).all() if vm.template is True]

# Use the transaction manager for write operations:
with db.transaction:
    db.session.query(db['vms']).all().delete()

Note

Creating a table object requires a call to the database so that SQLAlchemy can do reflection to determine the table’s structure (columns, keys, indices, etc). On a latent connection, this can be extremely slow, which will affect methods that return tables, like the mapping interface or values().

__contains__(table_name)[source]

Whether or not the named table is in this db

__eq__(other)[source]

Check if this db is equal to another db

__getitem__(table_name)[source]

Access tables as items contained in this db

Usage:

# To get a table called 'table_name':
db['table_name']

This may return None in the case where a table is found but reflection fails.

__iter__()[source]

Iterator of table names in this db

__len__()[source]

Number of tables in this db

__ne__(other)[source]

Check if this db is not equal to another db

copy()[source]

Copy this database instance, keeping the same credentials and hostname

db_url

The connection URL for this database, including credentials

engine

The Engine for this database

It uses pessimistic disconnection handling, checking that the database is still connected before executing commands.

get(table_name, default=None)[source]

table getter

Parameters:
  • table_name – Name of the table to get
  • default – Default value to return if table_name is not found.

Returns: a table if table_name exists, otherwise ‘None’ or the passed-in default

items()[source]

Iterator of (table_name, table) pairs

keys()[source]

Iterator of table names in this db

metadata

MetaData for this database

This can be used for introspection of reflected items.

Note

Tables that haven’t been reflected won’t show up in metadata. To reflect a table, use reflect_table().

reflect_table(table_name)[source]

Populate metadata with information on a table

Parameters:table_name – The name of a table to reflect
session

Returns a Session

This is used for database queries. For writing to the database, start a transaction().

Note

This attribute is cached. In cases where a new session needs to be explicitly created, use sessionmaker().

sessionmaker

A sessionmaker

Used to make new sessions with this database, as needed.

table_base

Base class for all tables returned by this database

This base class is created using declarative_base.

table_names

A sorted list of table names available in this database.

transaction

Context manager for simple transaction management

Sessions understand the concept of transactions, and provider context managers to handle conditionally committing or rolling back transactions as needed.

Note

Sessions automatically commit transactions by default. For predictable results when writing to the database, use the transaction manager.

Usage:

with db.transaction:
    db.session.do_something()
values()[source]

Iterator of tables in this db

cfme.utils.db.database_on_server(*args, **kwds)[source]
cfme.utils.db.ping_connection(dbapi_connection, connection_record, connection_proxy)[source]

ping_connection event hook, used to reconnect db sessions that time out

Note

See also: Connection Invalidation