# 3.8.15. Workers connector

class buildbot.db.workers.WorkersConnectorComponent

  This class handles Buildbot’s notion of workers. The worker information is returned as a `WorkerModel` dataclass with the following fields:

  - `id`

  - `name` - the name of the worker

  - `workerinfo` - worker information as dictionary

  - `paused` - boolean indicating worker is paused and shall not take new builds

  - `pause_reason` - string indicating the reason for working being paused

  - `graceful` - boolean indicating worker will be shutdown as soon as build finished

  - `connected_to` - a list of masters, by ID, to which this worker is currently connected. This list will typically contain only one master, but in unusual circumstances the same worker may appear to be connected to multiple masters simultaneously

  - `configured_on` - a list of master-builder pairs, on which this worker is configured. Each pair is represented by a `BuilderMasterModel` with fields `buliderid` and `masterid`

  The worker information can be any JSON-able object. See `worker` for more detail.

  findWorkerId(name=name)
    Parameters:

      name (50-character identifier) – worker name

    Returns:

      worker ID via Deferred

    Get the ID for a worker, adding a new worker to the database if necessary. The worker information for a new worker is initialized to an empty dictionary.

  getWorkers(masterid=None, builderid=None)
    Parameters:

      - masterid (integer) – limit to workers configured on this master

      - builderid (integer) – limit to workers configured on this builder

    Returns:

      list of `WorkerModel`, via Deferred

    Get a list of workers. If either or both of the filtering parameters either specified, then the result is limited to workers configured to run on that master or builder. The `configured_on` results are limited by the filtering parameters as well. The `connected_to` results are limited by the `masterid` parameter.

  getWorker(workerid=None, name=None, masterid=None, builderid=None)
    Parameters:

      - name (string) – the name of the worker to retrieve

      - workerid (integer) – the ID of the worker to retrieve

      - masterid (integer) – limit to workers configured on this master

      - builderid (integer) – limit to workers configured on this builder

    Returns:

      `WorkerModel` or None, via Deferred

    Looks up the worker with the given name or ID, returning `None` if no matching worker is found. The `masterid` and `builderid` arguments function as they do for `getWorkers`.

  workerConnected(workerid, masterid, workerinfo)
    Parameters:

      - workerid (integer) – the ID of the worker

      - masterid (integer) – the ID of the master to which it connected

      - workerinfo (dict) – the new worker information dictionary

    Returns:

      Deferred

    Record the given worker as attached to the given master, and update its cached worker information. The supplied information completely replaces any existing information.

  workerDisconnected(workerid, masterid)
    Parameters:

      - workerid (integer) – the ID of the worker

      - masterid (integer) – the ID of the master to which it connected

    Returns:

      Deferred

    Record the given worker as no longer attached to the given master.

  workerConfigured(workerid, masterid, builderids)
    Parameters:

      - workerid (integer) – the ID of the worker

      - masterid (integer) – the ID of the master to which it configured

      - builderids (list of integer) – the ID of the builders to which it is configured

    Returns:

      Deferred

    Record the given worker as being configured on the given master and for given builders. This method will also remove any other builder that were configured previously for same (worker, master) combination.

  deconfigureAllWorkersForMaster(masterid)
    Parameters:

      masterid (integer) – the ID of the master to which it configured

    Returns:

      Deferred

    Unregister all the workers configured to a master for given builders. This shall happen when master is disabled or before reconfiguration.

  set_worker_paused(workerid, paused, pause_reason=None)
    Parameters:

      - workerid (integer) – the ID of the worker whose state is being changed

      - paused (integer) – the paused state

      - pause_reason (string) – the reason for pausing the worker.

    Returns:

      Deferred

    Changes the `paused` state of the worker (see definition of states above in worker dict description).

  set_worker_graceful(workerid, graceful)
    Parameters:

      - workerid (integer) – the ID of the worker whose state is being changed

      - graceful (integer) – the graceful state

    Returns:

      Deferred

    Changes the `graceful` state of the worker (see definition of states above in worker dict description).