# patroni.dcs.raft module

class patroni.dcs.raft.DynMemberSyncObj(selfAddress: str | None, partnerAddrs: Collection[str], conf: SyncObjConf, retry_timeout: int = 10)

  Bases: `SyncObj`

  __init__(selfAddress: str | None, partnerAddrs: Collection[str], conf: SyncObjConf, retry_timeout: int = 10) → None

    Main SyncObj class, you should inherit your own class from it.

    Parameters:

      - selfNode (Node or str) – object representing the self-node or address of the current node server ‘host:port’

      - otherNodes (iterable of Node or iterable of str) – objects representing the other nodes or addresses of partner nodes [‘host1:port1’, ‘host2:port2’, …]

      - conf (SyncObjConf) – configuration object

      - consumers (list of SyncObjConsumer inherited objects) – objects to be replicated

      - nodeClass (class) – class used for representation of nodes

      - transport (Transport or None) – transport object; if None, transportClass is used to initialise such an object

      - transportClass (class) – the Transport subclass to be used for transferring messages to and from other nodes

  _onTick(timeToWait: float = 0.0)
  getMembers(args: Any, callback: Callable[[Any, Any], Any]) → None

class patroni.dcs.raft.KVStoreTTL(on_ready: Callable[[...], Any] | None, on_set: Callable[[str, Dict[str, Any]], None] | None, on_delete: Callable[[str], None] | None, **config: Any)

  Bases: `DynMemberSyncObj`

  __check_requirements(**kwargs: Any) → bool
  __expire_keys() → None
  __init__(on_ready: Callable[[...], Any] | None, on_set: Callable[[str, Dict[str, Any]], None] | None, on_delete: Callable[[str], None] | None, **config: Any) → None

    Main SyncObj class, you should inherit your own class from it.

    Parameters:

      - selfNode (Node or str) – object representing the self-node or address of the current node server ‘host:port’

      - otherNodes (iterable of Node or iterable of str) – objects representing the other nodes or addresses of partner nodes [‘host1:port1’, ‘host2:port2’, …]

      - conf (SyncObjConf) – configuration object

      - consumers (list of SyncObjConsumer inherited objects) – objects to be replicated

      - nodeClass (class) – class used for representation of nodes

      - transport (Transport or None) – transport object; if None, transportClass is used to initialise such an object

      - transportClass (class) – the Transport subclass to be used for transferring messages to and from other nodes

  __pop(key: str) → None
  __values_match(new: Dict[str, Any]) → bool
  _autoTickThread() → None
  _delete(key: str, recursive: bool = False, **kwargs: Any) → bool
  _delete_v0(key: str, recursive: bool = False, **kwargs: Any) → bool
  _expire(key: str, value: Dict[str, Any], callback: Callable[[...], Any] | None = None) → None
  _expire_v0(key: str, value: Dict[str, Any], callback: Callable[[...], Any] | None = None) → None
  _onTick(timeToWait: float = 0.0) → None
  _set(key: str, value: Dict[str, Any], **kwargs: Any) → bool | Dict[str, Any]
  _set_v0(key: str, value: Dict[str, Any], **kwargs: Any) → bool | Dict[str, Any]
  delete(key: str, recursive: bool = False, **kwargs: Any) → bool
  destroy() → None

    Correctly destroy SyncObj. Stop autoTickThread, close connections, etc.

  get(key: str, recursive: bool = False) → Dict[str, Any] | None
  retry(func: Callable[[...], Any], *args: Any, **kwargs: Any) → Any
  set(key: str, value: str, ttl: int | None = None, handle_raft_error: bool = True, **kwargs: Any) → bool | Dict[str, Any]
  set_retry_timeout(retry_timeout: int) → None
  startAutoTick() → None

class patroni.dcs.raft.Raft(config: Dict[str, Any], mpp: AbstractMPP)

  Bases: `AbstractDCS`

  __init__(config: Dict[str, Any], mpp: AbstractMPP) → None

    Prepare DCS paths, MPP object, initial values for state information and processing dependencies.

    Parameters:

      - config – `dict`, reference to config section of selected DCS. i.e.: `zookeeper` for zookeeper, `etcd` for etcd, etc…

      - mpp – an object implementing `AbstractMPP` interface.

  _abc_impl = <_abc._abc_data object>
  _cluster_from_nodes(nodes: Dict[str, Any]) → Cluster
  _delete_leader(leader: Leader) → bool

    Remove leader key from DCS.

    This method should remove leader key if current instance is the leader.

    Parameters:

      leader – `Leader` object with information about the leader.

    Returns:

      `True` if successfully committed to DCS.

  _load_cluster(path: str, loader: Callable[[str], Cluster | Dict[int, Cluster]]) → Cluster | Dict[int, Cluster]

    Main abstract method that implements the loading of `Cluster` instance.

    Note

    Internally this method should call the loader method that will build `Cluster` object which represents current state and topology of the cluster in DCS. This method supposed to be called only by the `get_cluster()` method.

    Parameters:

      - path – the path in DCS where to load Cluster(s) from.

      - loader – one of `_postgresql_cluster_loader()` or `_mpp_cluster_loader()`.

    Raise:

      `DCSError` in case of communication problems with DCS. If the current node was running as a primary and exception raised, instance would be demoted.

  _mpp_cluster_loader(path: str) → Dict[int, Cluster]

    Load and build all PostgreSQL clusters from a single MPP cluster.

    Parameters:

      path – the path in DCS where to load Cluster(s) from.

    Returns:

      all MPP groups as `dict`, with group IDs as keys and `Cluster` objects as values.

  _on_delete(key: str) → None
  _on_set(key: str, value: Dict[str, Any]) → None
  _postgresql_cluster_loader(path: str) → Cluster

    Load and build the `Cluster` object from DCS, which represents a single PostgreSQL cluster.

    Parameters:

      path – the path in DCS where to load `Cluster` from.

    Returns:

      `Cluster` instance.

  _update_leader(leader: Leader) → bool

    Update `leader` key (or session) ttl.

    Note

    You have to use CAS (Compare And Swap) operation in order to update leader key, for example for etcd `prevValue` parameter must be used.

    If update fails due to DCS not being accessible or because it is not able to process requests (hopefully temporary), the `DCSError` exception should be raised.

    Parameters:

      leader – a reference to a current `leader` object.

    Returns:

      `True` if `leader` key (or session) has been updated successfully.

  _write_failsafe(value: str) → bool

    Write current cluster topology to DCS that will be used by failsafe mechanism (if enabled).

    Parameters:

      value – failsafe topology serialized in JSON format.

    Returns:

      `True` if successfully committed to DCS.

  _write_leader_optime(last_lsn: str) → bool

    Write current WAL LSN into `/optime/leader` key in DCS.

    Parameters:

      last_lsn – absolute WAL LSN in bytes.

    Returns:

      `True` if successfully committed to DCS.

  _write_status(value: str) → bool

    Write current WAL LSN and `confirmed_flush_lsn` of permanent slots into the `/status` key in DCS.

    Parameters:

      value – status serialized in JSON format.

    Returns:

      `True` if successfully committed to DCS.

  attempt_to_acquire_leader() → bool

    Attempt to acquire leader lock.

    Note

    This method should create `/leader` key with the value `_name`.

    The key must be created atomically. In case the key already exists it should not be overwritten and `False` must be returned.

    If key creation fails due to DCS not being accessible or because it is not able to process requests (hopefully temporary), the `DCSError` exception should be raised.

    Returns:

      `True` if key has been created successfully.

  cancel_initialization() → bool

    Removes the `initialize` key for a cluster.

    Returns:

      `True` if successfully committed to DCS.

  delete_cluster() → bool

    Delete cluster from DCS.

    Returns:

      `True` if successfully committed to DCS.

  delete_sync_state(version: int | None = None) → bool

    Delete the synchronous state from DCS.

    Parameters:

      version – for conditional deletion of the key/object.

    Returns:

      `True` if delete successful.

  initialize(create_new: bool = True, sysid: str = '') → bool

    Race for cluster initialization.

    This method should atomically create `initialize` key and return `True`, otherwise it should return `False`.

    Parameters:

      - create_new – `False` if the key should already exist (in the case we are setting the system_id).

      - sysid – PostgreSQL cluster system identifier, if specified, is written to the key.

    Returns:

      `True` if key has been created successfully.

  static member(key: str, value: Dict[str, Any]) → Member
  reload_config(config: Config | Dict[str, Any]) → None

    Load and set relevant values from configuration.

    Sets `loop_wait`, `ttl` and `retry_timeout` properties.

    Parameters:

      config – Loaded configuration information object or dictionary of key value pairs.

  set_config_value(value: str, version: int | None = None) → bool

    Create or update `/config` key in DCS.

    Parameters:

      - value – new value to set in the `config` key.

      - version – for conditional update of the key/object.

    Returns:

      `True` if successfully committed to DCS.

  set_failover_value(value: str, version: int | None = None) → bool

    Create or update `/failover` key.

    Parameters:

      - value – value to set.

      - version – for conditional update of the key/object.

    Returns:

      `True` if successfully committed to DCS.

  set_history_value(value: str) → bool

    Set value for `history` in DCS.

    Parameters:

      value – new value of `history` key/object.

    Returns:

      `True` if successfully committed to DCS.

  set_retry_timeout(retry_timeout: int) → None

    Set the new value for retry_timeout.

  set_sync_state_value(value: str, version: int | None = None) → int | bool

    Set synchronous state in DCS.

    Parameters:

      - value – the new value of `/sync` key.

      - version – for conditional update of the key/object.

    Returns:

      version of the new object or `False` in case of error.

  set_ttl(ttl: int) → bool | None

    Set the new ttl value for DCS keys.

  take_leader() → bool

    Establish a new leader in DCS.

    Note

    This method should create leader key with value of `_name` and `ttl` of `ttl`.

    Since it could be called only on initial cluster bootstrap it could create this key regardless, overwriting the key if necessary.

    Returns:

      `True` if successfully committed to DCS.

  touch_member(data: Dict[str, Any]) → bool

    Update member key in DCS.

    Note

    This method should create or update key with the name with `/members/` + `_name` and the value of data in a given DCS.

    Parameters:

      data – information about an instance (including connection strings).

    Returns:

      `True` if successfully committed to DCS.

  property ttl: int

    Get current `ttl` value.

  watch(leader_version: int | None, timeout: float) → bool

    Sleep if the current node is a leader, otherwise, watch for changes of leader key with a given timeout.

    Parameters:

      - leader_version – version of a leader key.

      - timeout – timeout in seconds.

    Returns:

      if `True` this will reschedule the next run of the HA cycle.

exception patroni.dcs.raft.RaftError(value: Any)

  Bases: `DCSError`

class patroni.dcs.raft.SyncObjUtility(otherNodes: Collection[str | TCPNode], conf: SyncObjConf, retry_timeout: int = 10)

  Bases: `object`

  __init__(otherNodes: Collection[str | TCPNode], conf: SyncObjConf, retry_timeout: int = 10) → None
  executeCommand(command: List[Any]) → Any
  getMembers() → List[str] | None

class patroni.dcs.raft._TCPTransport(syncObj: DynMemberSyncObj, selfNode: TCPNode | None, otherNodes: Collection[TCPNode])

  Bases: `TCPTransport`

  __init__(syncObj: DynMemberSyncObj, selfNode: TCPNode | None, otherNodes: Collection[TCPNode]) → None

    Initialise the TCP transport. On normal (non-read-only) nodes, this will start a TCP server. On all nodes, it will initiate relevant connections to other nodes.

    Parameters:

      - syncObj (SyncObj) – SyncObj

      - selfNode (TCPNode or None) – current node (None if this is a read-only node)

      - otherNodes (iterable of TCPNode) – partner nodes

  _connectIfNecessarySingle(node: TCPNode) → bool

    Connect to a node if necessary.

    Parameters:

      node (Node) – node to connect to

patroni.dcs.raft.resolve_host(self: TCPNode) → str | None