# 3.8.4. Builds connector

class buildbot.db.builds.BuildsConnectorComponent

  This class handles builds. One build record is created for each build performed by a master. This record contains information on the status of the build, as well as links to the resources used in the build: builder, master, worker, etc.

  An instance of this class is available at `master.db.builds`.

  Builds are indexed by buildid and their contents represented as `BuildModel` dataclass, with the following fields:

  - `id` (the build ID, globally unique)

  - `number` (the build number, unique only within the builder)

  - `builderid` (the ID of the builder that performed this build)

  - `buildrequestid` (the ID of the build request that caused this build)

  - `workerid` (the ID of the worker on which this build was performed)

  - `masterid` (the ID of the master on which this build was performed)

  - `started_at` (datetime at which this build began)

  - `complete_at` (datetime at which this build finished, or None if it is ongoing)

  - `locks_duration_s` (the amount of time spent acquiring locks so far, not including any running steps)

  - `state_string` (short string describing the build’s state)

  - `results` (results of this build; see Build Result Codes)

  getBuild(buildid)
    Parameters:

      buildid (integer) – build id

    Returns:

      `BuildModel` or `None`, via Deferred

    Get a single build, in the format described above. Returns `None` if there is no such build.

  getBuildByNumber(builderid, number)
    Parameters:

      - builder (integer) – builder id

      - number (integer) – build number within that builder

    Returns:

      `BuildModel` or `None`, via Deferred

    Get a single build, in the format described above, specified by builder and number, rather than build id. Returns `None` if there is no such build.

  getPrevSuccessfulBuild(builderid, number, ssBuild)
    Parameters:

      - builderid (integer) – builder to get builds for

      - number (integer) – the current build number. Previous build will be taken from this number

      - ssBuild (list) – the list of sourcestamps for the current build number

    Returns:

      `BuildModel` or `None`, via Deferred

    Returns the last successful build from the current build number with the same repository, branch, or codebase.

  getBuilds(builderid=None, buildrequestid=None, complete=None, resultSpec=None)
    Parameters:

      - builderid (integer) – builder to get builds for

      - buildrequestid (integer) – buildrequest to get builds for

      - complete (boolean) – if not None, filters results based on completeness

      - 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 `BuildModel`, via Deferred

    Get a list of builds, in the format described above. Each of the parameters limits the resulting set of builds.

  addBuild(builderid, buildrequestid, workerid, masterid, state_string)
    Parameters:

      - builderid (integer) – builder to get builds for

      - buildrequestid (integer) – build request id

      - workerid (integer) – worker performing the build

      - masterid (integer) – master performing the build

      - state_string (unicode) – initial state of the build

    Returns:

      tuple of build ID and build number, via Deferred

    Add a new build to the db, recorded as having started at the current time. This will invent a new number for the build, unique within the context of the builder.

  setBuildStateString(buildid, state_string):
    Parameters:

      - buildid (integer) – build id

      - state_string (unicode) – updated state of the build

    Returns:

      Deferred

    Update the state strings for the given build.

  add_build_locks_duration(buildid, duration_s):
    Parameters:

      - buildid (integer) – build id

      - duration_s (integer) – time duration to add

    Returns:

      Deferred

    Adds the given duration to the `locks_duration_s` field of the build.

  finishBuild(buildid, results)
    Parameters:

      - buildid (integer) – build id

      - results (integer) – build result

    Returns:

      Deferred

    Mark the given build as finished, with `complete_at` set to the current time.

    Note

    This update is done unconditionally, even if the build is already finished.

  getBuildProperties(buildid, resultSpec=None)
    Parameters:

      - buildid – build ID

      - resultSpec – resultSpec

    Returns:

      dictionary mapping property name to `value, source`, via Deferred

    Return the properties for a build, in the same format they were given to `addBuild`. Optional filtering via resultSpec is available and optimized in the db layer.

    Note that this method does not distinguish a non-existent build from a build with no properties, and returns `{}` in either case.

  setBuildProperty(buildid, name, value, source)
    Parameters:

      - buildid (integer) – build ID

      - name (string) – Name of the property to set

      - value – Value of the property

      - source (string) – Source of the Property to set

    Returns:

      Deferred

    Set a build property. If no property with that name existed in that build, a new property will be created.