Caution

This page documents the latest, unreleased version of Buildbot. For documentation for released versions, see http://docs.buildbot.net/current/.

3.8.1. Buildsets connector

class buildbot.db.buildsets.BuildsetsConnectorComponent

This class handles getting buildsets into and out of the database. Buildsets combine multiple build requests that were triggered together.

An instance of this class is available at master.db.buildsets.

Buildsets are indexed by bsid and their contents are represented as BuildSetModel dataclass with the following fields:

  • bsid

  • external_idstring (arbitrary string for mapping builds externally)

  • reason (string; reason these builds were triggered)

  • rebuilt_buildid (integer; id of a build which was rebuilt or None if there was no rebuild.

    In case of repeated rebuilds, only initial build id is tracked)

  • sourcestamps (list of sourcestamps for this buildset, by ID)

  • submitted_at (datetime object; time this buildset was created)

  • complete (boolean; true if all of the builds for this buildset are complete)

  • complete_at (datetime object; time this buildset was completed)

  • results (aggregate result of this buildset; see Build Result Codes)

  • parent_buildid (optional build id that is the parent for this buildset)

  • parent_relationship (relationship identifier for the parent)

addBuildset(sourcestamps, reason, properties, builderids, rebuilt_buildid=None, external_idstring=None, parent_buildid=None, parent_relationship=None)
Parameters:

  • sourcestamps (list) – sourcestamps for the new buildset; see below

  • reason (short unicode string) – reason for this buildset

  • properties (dictionary, where values are tuples of (value, source)) – properties for this buildset

  • builderids (list of int) – builderids specified by this buildset

  • external_idstring (unicode string) – external key to identify this buildset; defaults to None

  • submitted_at (datetime) – time this buildset was created; defaults to the current time

  • parent_buildid (int) – optional build id that is the parent for this buildset

  • parent_relationship (unicode) – relationship identifier for the parent. This is the configured relationship between the parent build and the child buildsets

  • rebuilt_buildid (int) – optional rebuilt build id

Returns:

buildset ID and buildrequest IDs, via a Deferred

Add a new buildset to the database, along with build requests for each builder, returning the resulting bsid via a Deferred. Arguments should be specified by keyword.

Each sourcestamp in the list of sourcestamps can be given either as an integer, assumed to be a sourcestamp ID, or a dictionary of keyword arguments to be passed to findSourceStampId.

The return value is a tuple (bsid, brids) where bsid is the inserted buildset ID and brids is a dictionary mapping builderids to build request IDs.

completeBuildset(bsid, results[, complete_at=XX])
Parameters:

  • bsid (integer) – buildset ID to complete

  • results (integer) – integer result code

  • complete_at (datetime) – time the buildset was completed

Returns:

Deferred

Raises:

KeyError if the buildset does not exist or is already complete

Complete a buildset, marking it with the given results and setting its completed_at to the current time, if the complete_at argument is omitted.

getBuildset(bsid)
Parameters:

bsid – buildset ID

Returns:

BuildSetModel or None, via Deferred

Get a BuildSetModel representing the given buildset, or None if no such buildset exists.

Note that buildsets are not cached, as the values in the database are not fixed.

getBuildsets(complete=None, resultSpec=None)
Parameters:

  • complete – if true, return only complete buildsets; if false, return only incomplete buildsets; if None or omitted, return all buildsets

  • resultSpec – result spec containing filters sorting and paging requests from data/REST API. If possible, the db layer can optimize the SQL query using this information.

Returns:

list of BuildSetModel, via Deferred

Get a list of BuildSetModel matching the given criteria.

getRecentBuildsets(count=None, branch=None, repository=None,
complete=None):
Parameters:

  • count (integer) – maximum number of buildsets to retrieve (required)

  • branch (string) – optional branch name. If specified, only buildsets affecting such branch will be returned

  • repository (string) – optional repository name. If specified, only buildsets affecting such repository will be returned

  • complete (Boolean) – if true, return only complete buildsets; if false, return only incomplete buildsets; if None or omitted, return all buildsets

Returns:

list of BuildSetModel, via Deferred

Get “recent” buildsets, as defined by their submitted_at times.

getBuildsetProperties(buildsetid)
Parameters:

bsid – buildset ID

Returns:

dictionary mapping property name to value, source, via Deferred

Return the properties for a buildset, in the same format they were given to addBuildset.

Note that this method does not distinguish a nonexistent buildset from a buildset with no properties, and returns {} in either case.