benchbuild.utils.schema module

# Database schema for benchbuild

The schema should initialize itself on an empty database. For now, we do not support automatic upgrades on schema changes. You might encounter some roadbumps when using an older version of benchbuild.

Furthermore, for now, we are restricted to postgresql databases, although we already support arbitrary connection strings via config.

If you want to use reports that use one of our SQL functions, you need to initialize the functions first using the following command:

```bash
> BB_DB_CREATE_FUNCTIONS=true benchbuild run -E empty -l

```

After that you (normally) do not need to do this agains, unless we supply a new version that you are interested in. As soon as we have alembic running, we can provide automatic up/downgrade paths for you.

class benchbuild.utils.schema.Config(**kwargs)[source]

Bases: sqlalchemy.ext.declarative.api.Base

Store customized information about a run.

You can store arbitrary configuration information about a run here. Use it for extended filtering against the run table.

name
run_id
value
class benchbuild.utils.schema.Experiment(**kwargs)[source]

Bases: sqlalchemy.ext.declarative.api.Base

Store metadata about experiments.

begin
description
end
id
name
run_groups
runs
class benchbuild.utils.schema.GUID(*args, as_uuid=False, **kwargs)[source]

Bases: sqlalchemy.sql.type_api.TypeDecorator

Platform-independent GUID type.

Uses Postgresql’s UUID type, otherwise uses CHAR(32), storing as stringified hex values.

as_uuid = False
impl

alias of sqlalchemy.sql.sqltypes.CHAR

load_dialect_impl(dialect)[source]

Return a TypeEngine object corresponding to a dialect.

This is an end-user override hook that can be used to provide differing types depending on the given dialect. It is used by the TypeDecorator implementation of type_engine() to help determine what type should ultimately be returned for a given TypeDecorator.

By default returns self.impl.

process_bind_param(value, dialect)[source]

Receive a bound parameter value to be converted.

Subclasses override this method to return the value that should be passed along to the underlying TypeEngine object, and from there to the DBAPI execute() method.

The operation could be anything desired to perform custom behavior, such as transforming or serializing data. This could also be used as a hook for validating logic.

This operation should be designed with the reverse operation in mind, which would be the process_result_value method of this class.

Parameters:
  • value – Data to operate upon, of any type expected by this method in the subclass. Can be None.
  • dialect – the Dialect in use.
process_result_value(value, dialect)[source]

Receive a result-row column value to be converted.

Subclasses should implement this method to operate on data fetched from the database.

Subclasses override this method to return the value that should be passed back to the application, given a value that is already processed by the underlying TypeEngine object, originally from the DBAPI cursor method fetchone() or similar.

The operation could be anything desired to perform custom behavior, such as transforming or serializing data. This could also be used as a hook for validating logic.

Parameters:
  • value – Data to operate upon, of any type expected by this method in the subclass. Can be None.
  • dialect – the Dialect in use.

This operation should be designed to be reversible by the “process_bind_param” method of this class.

class benchbuild.utils.schema.Metadata(**kwargs)[source]

Bases: sqlalchemy.ext.declarative.api.Base

Store metadata information for every run.

If you happen to have some free-form data that belongs to the database, this is the place for it.

name
run_id
value
class benchbuild.utils.schema.Metric(**kwargs)[source]

Bases: sqlalchemy.ext.declarative.api.Base

Store default metrics, simple name value store.

name
run_id
value
class benchbuild.utils.schema.Project(**kwargs)[source]

Bases: sqlalchemy.ext.declarative.api.Base

Store project metadata.

description
domain
group_name
name
runs
src_url
version
class benchbuild.utils.schema.Run(**kwargs)[source]

Bases: sqlalchemy.ext.declarative.api.Base

Store a run for each executed test binary.

begin
command
configurations
end
experiment_group
experiment_name
id
logs
metrics
project_group
project_name
run_group
status
stored_data
class benchbuild.utils.schema.RunGroup(**kwargs)[source]

Bases: sqlalchemy.ext.declarative.api.Base

Store information about a run group.

begin
end
experiment
id
status
class benchbuild.utils.schema.RunLog(**kwargs)[source]

Bases: sqlalchemy.ext.declarative.api.Base

Store log information for every run.

Properties like, start time, finish time, exit code, stderr, stdout are stored here.

begin
config
end
run_id
status
stderr
stdout
benchbuild.utils.schema.Session()
class benchbuild.utils.schema.SessionManager[source]

Bases: object

configure_engine()[source]

Configure the databse connection.

Sets appropriate transaction isolation levels and handle errors.

Returns:True, if we did not encounter any unrecoverable errors, else False.
connect_engine()[source]

Establish a connection to the database.

Provides simple error handling for fatal errors.

Returns:True, if we could establish a connection, else False.
get()[source]
benchbuild.utils.schema.enforce_versioning(force=False)[source]

Install versioning on the db.

benchbuild.utils.schema.exceptions(error_is_fatal=True, error_messages=None)[source]

Handle SQLAlchemy exceptions in a sane way.

Parameters:
  • func – An arbitrary function to wrap.
  • error_is_fatal – Should we exit the program on exception?
  • reraise – Should we reraise the exception, after logging? Only makes sense if error_is_fatal is False.
  • error_messages – A dictionary that assigns an exception class to a customized error message.
benchbuild.utils.schema.get_version_data()[source]

Retreive migration information.

benchbuild.utils.schema.init_functions(connection)[source]

Initialize all SQL functions in the database.

benchbuild.utils.schema.maybe_update_db(repo_version, db_version)[source]
benchbuild.utils.schema.metadata()[source]
benchbuild.utils.schema.needed_schema(connection, meta)[source]
benchbuild.utils.schema.setup_versioning()[source]