# 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.