# 3.8.8. Changes connector

class buildbot.db.changes.ChangesConnectorComponent

  This class handles changes in the Buildbot database, including pulling information from the changes sub-tables.

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

  Changes are indexed by changeid, and are represented by a `ChangeModel` dataclass, which has the following fields:

  - `changeid` (the ID of this change)

  - `parent_changeids` (list of ID; change’s parents)

  - `author` (unicode; the author of the change)

  - `committer` (unicode; the committer of the change)

  - `files` (list of unicode; source-code filenames changed)

  - `comments` (unicode; user comments)

  - `is_dir` (deprecated)

  - `links` (list of unicode; links for this change, e.g., to web views, review)

  - `revision` (unicode string; revision for this change, or `None` if unknown)

  - `when_timestamp` (datetime instance; time of the change)

  - `branch` (unicode string; branch on which the change took place, or `None` for the “default branch”, whatever that might mean)

  - `category` (unicode string; user-defined category of this change, or `None`)

  - `revlink` (unicode string; link to a web view of this change)

  - `properties` (user-specified properties for this change, represented as a dictionary mapping keys to (value, source))

  - `repository` (unicode string; repository where this change occurred)

  - `project` (unicode string; user-defined project to which this change corresponds)

  getParentChangeIds(branch, repository, project, codebase)
    Parameters:

      - branch (unicode string) – the branch of the change

      - repository (unicode string) – the repository in which this change took place

      - project (unicode string) – the project this change is a part of

      - codebase (unicode string)

    Returns:

      the last changeID that matches the branch, repository, project, or codebase

  addChange(author=None, committer=None, files=None, comments=None, is_dir=0, links=None, revision=None, when_timestamp=None, branch=None, category=None, revlink='', properties={}, repository='', project='', uid=None)
    Parameters:

      - author (unicode string) – the author of this change

      - committer (unicode string) – the committer of this change

      - files – a list of filenames that were changed

      - comments – user comments on the change

      - is_dir – deprecated

      - links (list of unicode strings) – a list of links related to this change, e.g., to web viewers or review pages

      - revision (unicode string) – the revision identifier for this change

      - when_timestamp (datetime instance or None) – when this change occurred, or the current time if None

      - branch (unicode string) – the branch on which this change took place

      - category (unicode string) – category for this change (arbitrary use by Buildbot users)

      - revlink (unicode string) – link to a web view of this revision

      - properties (dictionary) – properties to set on this change, where values are tuples of (value, source). At the moment, the source must be `'Change'`, although this may be relaxed in later versions

      - repository (unicode string) – the repository in which this change took place

      - project (unicode string) – the project this change is a part of

      - uid (integer) – uid generated for the change author

    Returns:

      new change’s ID via Deferred

    Add a Change with the given attributes to the database, returning the changeid via a Deferred. All arguments should be given as keyword arguments.

    The `project` and `repository` arguments must be strings; `None` is not allowed.

  getChange(changeid, no_cache=False)
    Parameters:

      - changeid – the id of the change instance to fetch

      - no_cache (boolean) – bypass cache and always fetch from database

    Returns:

      `ChangeModel` or None, via Deferred

    Get a `ChangeModel` for the given changeid, or `None` if no such change exists.

  getChangeUids(changeid)
    Parameters:

      changeid – the id of the change instance to fetch

    Returns:

      list of uids via Deferred

    Get the userids associated with the given changeid.

  getChanges(resultSpec=None)
    Parameters:

      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 `ChangeModel` via Deferred

    Get a list of the changes, represented as `ChangeModel`, matching the given criteria. if `resultSpec` is not provided, changes are sorted, and paged using generic data query options.

  getChangesCount()
    Returns:

      list of dictionaries via Deferred

    Get the number of changes that the query option would return if no paging option was set.

  getLatestChangeid()
    Returns:

      changeid via Deferred

    Get the most-recently-assigned changeid, or `None` if there are no changes at all.

  getChangesForBuild(buildid)
    Parameters:

      buildid – ID of the build

    Returns:

      list of `ChangeModel` via Deferred

    Get the “blame” list of changes for a build.

  getBuildsForChange(changeid)
    Parameters:

      changeid – ID of the change

    Returns:

      list of `ChangeModel` via Deferred

    Get builds related to a change.

  getChangeFromSSid(sourcestampid)
    Parameters:

      sourcestampid – ID of the sourcestampid

    Returns:

      `ChangeModel` via Deferred

    Returns the `ChangeModel` related to the sourcestamp ID.