Caution

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

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.