utils.db module

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

Bases: _abcoll.Mapping

Helper class for interacting with a CFME database using SQLAlchemy

  • 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']


# 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, 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:


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


Copy this database instance, keeping the same credentials and hostname


The connection URL for this database, including credentials

This attribute is lazily evaluated and cached.


The Engine for this database

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

This attribute is lazily evaluated and cached.

get(table_name, default=None)[source]

table getter

  • 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


Iterator of (table_name, table) pairs


Iterator of table names in this db


MetaData for this database

This can be used for introspection of reflected items.


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

This attribute is lazily evaluated and cached.


Populate metadata with information on a table

Parameters:table_name – The name of a table to reflect

Returns a Session

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


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

This attribute is lazily evaluated and cached.


A sessionmaker

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

This attribute is lazily evaluated and cached.


Base class for all tables returned by this database

This base class is created using declarative_base.

This attribute is lazily evaluated and cached.


A sorted list of table names available in this database.

This attribute is lazily evaluated and cached.


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.


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


with db.transaction:

Iterator of tables in this db

utils.db.database_on_server(*args, **kwds)[source]
utils.db.db_yamls(db=None, guid=None)[source]

Returns the yamls from the db configuration table as a dict


# Get all the yaml configs
configs = db_yamls

# Get all the yaml names

# Retrieve a specific yaml (but you should use get_yaml_config here)
vmdb_config = configs['vmdb']
utils.db.get_yaml_config(config_name, db=None)[source]

Return a specific yaml from the db configuration table as a dict


# Retrieve a specific yaml
vmdb_config = get_yaml_config('vmdb')
utils.db.ping_connection(dbapi_connection, connection_record, connection_proxy)[source]

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


See also: Connection Invalidation

utils.db.set_yaml_config(config_name, data_dict, hostname=None)[source]

Given a yaml name, dictionary and hostname, set the configuration yaml on the server

The configuration yamls must be inserted into the DB using the ruby console, so this function uses SSH, not the database. It makes sense to be included here as a counterpart to get_yaml_config()

  • config_name – Name of the yaml configuration file
  • data_dict – Dictionary with data to set/change
  • hostname – Hostname/address of the server that we want to set up (default None)


If hostname is set to None, the default server set up for this session will be used. See :py:class:utils.ssh.SSHClient for details of the default setup.


Manually editing the config yamls is potentially dangerous. Furthermore, the rails runner doesn’t return useful information on the outcome of the set request, so errors that arise from the newly loading config file will go unreported.


# Update the appliance name, for example
vmbd_yaml = get_yaml_config('vmdb')
vmdb_yaml['server']['name'] = 'EVM IS AWESOME'
set_yaml_config('vmdb', vmdb_yaml, '')