# patroni.dcs.etcd3 module

exception patroni.dcs.etcd3.AuthFailed(code: int | None = None, error: str | None = None, status: int | None = None)

  Bases: `InvalidArgument`

  error = 'etcdserver: authentication failed, invalid user ID or password'

exception patroni.dcs.etcd3.AuthNotEnabled(code: int | None = None, error: str | None = None, status: int | None = None)

  Bases: `FailedPrecondition`

  error = 'etcdserver: authentication is not enabled'

exception patroni.dcs.etcd3.AuthOldRevision(code: int | None = None, error: str | None = None, status: int | None = None)

  Bases: `InvalidArgument`

  error = 'etcdserver: revision of auth store is old'

exception patroni.dcs.etcd3.DeadlineExceeded(code: int | None = None, error: str | None = None, status: int | None = None)

  Bases: `Etcd3ClientError`

  code = 4
  error = 'context deadline exceeded'

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

  Bases: `AbstractEtcd`

  __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>
  property _client: PatroniEtcd3Client

    return correct type of etcd client

  _cluster_from_nodes(nodes: Dict[str, Any]) → Cluster
  _delete_leader(*args: Any, **kwargs: Any) → Any

    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.

  _do_attempt_to_acquire_leader(retry: Retry) → bool
  _do_refresh_lease(force: bool = False, retry: Retry | None = None) → bool
  _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.

  _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(**kwargs: Any)

    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(*args: Any, **kwargs: Any) → Any

    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(*args: Any, **kwargs: Any) → Any

    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(*args: Any, **kwargs: Any) → Any

    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(**kwargs: Any)

    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(*args: Any, **kwargs: Any) → Any

    Removes the `initialize` key for a cluster.

    Returns:

      `True` if successfully committed to DCS.

  property cluster_prefix: str

    Construct the cluster prefix for the cluster.

    Returns:

      path in the DCS under which we store information about this Patroni cluster.

  create_lease() → None
  delete_cluster(*args: Any, **kwargs: Any) → Any

    Delete cluster from DCS.

    Returns:

      `True` if successfully committed to DCS.

  delete_sync_state(*args: Any, **kwargs: Any) → Any

    Delete the synchronous state from DCS.

    Parameters:

      version – for conditional deletion of the key/object.

    Returns:

      `True` if delete successful.

  initialize(*args: Any, **kwargs: Any) → Any

    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(node: Dict[str, str]) → Member
  refresh_lease() → bool
  set_config_value(*args: Any, **kwargs: Any) → Any

    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(*args: Any, **kwargs: Any) → Any

    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(*args: Any, **kwargs: Any) → Any

    Set value for `history` in DCS.

    Parameters:

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

    Returns:

      `True` if successfully committed to DCS.

  set_socket_options(sock: socket, socket_options: Collection[Tuple[int, int, int]] | None) → None
  set_sync_state_value(*args: Any, **kwargs: Any) → Any

    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(*args: Any, **kwargs: Any) → Any

    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(*args: Any, **kwargs: Any) → Any

    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.

  watch(leader_version: str | 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.

class patroni.dcs.etcd3.Etcd3Client(config: Dict[str, Any], dns_resolver: DnsCachingResolver, cache_ttl: int = 300)

  Bases: `AbstractEtcdClientWithFailover`

  ERROR_CLS

    alias of `Etcd3Error`

  __init__(config: Dict[str, Any], dns_resolver: DnsCachingResolver, cache_ttl: int = 300) → None
  _abc_impl = <_abc._abc_data object>
  _cluster_version: Tuple[int, ...]
  _do_auth_request(base_uri: str, kwargs: Dict[str, Any], method: str, fields: Dict[str, Any], retry: Retry | None = None) → Dict[str, Any]

    Special method for handling authentication when discovering cluster members.

    We can’t use call_rpc() method for this purpose because it may cause infinite recursion.

    Parameters:

      - base_uri – base url for authentication request, e.g. http://etcd:2379/v3

      - kwargs – common request parameters, e.g. headers.

      - method – /auth/authenticate

      - fields – authentication fields, e.g. {‘name’: ‘user’, ‘password’: ‘pass’}.

      - retry – optional retry configuration, ignored.

  _do_member_list_request(url: str, retry: Retry | None = None, **kwargs: Any) → Any

    Special method for handling member list requests.

    Parameters:

      - url – base url for member list request, e.g. http://etcd:2379/v3/cluster/member/list

      - kwargs – common request parameters, e.g. headers.

      - retry – optional retry configuration, ignored.

  _ensure_version_prefix(base_uri: str, **kwargs: Any) → None
  _get_headers() → Dict[str, str]
  _get_members(base_uri: str, **kwargs: Any) → List[str]

    returns: list of clientURLs

  _handle_server_response(response: HTTPResponse) → Dict[str, Any]

    Handles the server response

  _prepare_get_members(etcd_nodes: int) → Dict[str, Any]

    returns: request parameters

  _prepare_request(kwargs: Dict[str, Any], params: Dict[str, Any] | None = None, method: str | None = None) → Callable[[...], HTTPResponse]

    returns: request_executor

  authenticate(*, retry: Retry | None = None, auth_request_func: Callable[[...], Dict[str, Any]] | None = None) → bool

    Authenticate with the Etcd v3 cluster.

    Parameters:

      - retry – optional retry configuration.

      - auth_request_func – optional custom authentication request function, if not provided, call_rpc() method will be used.

  authenticate_on_start(auth_request_func: Callable[[...], Dict[str, Any]] | None = None)

    Authenticate with Etcd v3 at startup and exit on invalid credentials.

    Parameters:

      auth_request_func – optional custom authentication request function, if not provided, `call_rpc()` will be used.

  call_rpc(method: str, fields: Dict[str, Any], retry: Retry | None = None) → Dict[str, Any]
  deleteprefix(key: str, *, retry: Retry | None = None) → Dict[str, Any]
  deleterange(*args: Any, **kwargs: Any) → Any
  handle_auth_errors(func: Callable[[...], Any], *args: Any, auth_request_func: Callable[[...], Dict[str, Any]] | None = None, retry: Retry | None = None, **kwargs: Any) → Any

    Handle authentication errors for the given function.

    Parameters:

      - func – function to call.

      - args – positional arguments for the function.

      - auth_request_func – optional custom authentication request function, if not provided, call_rpc() method will be used.

      - retry – optional retry configuration.

      - kwargs – keyword arguments for the function.

  lease_grant(*args: Any, **kwargs: Any) → Any
  lease_keepalive(*args: Any, **kwargs: Any) → Any
  prefix(key: str, serializable: bool = True, *, retry: Retry | None = None) → Dict[str, Any]
  put(*args: Any, **kwargs: Any) → Any
  range(*args: Any, **kwargs: Any) → Any
  txn(*args: Any, **kwargs: Any) → Any
  watchprefix(key: str, start_revision: str | None = None, filters: List[Dict[str, Any]] | None = None, read_timeout: float | None = None) → HTTPResponse
  watchrange(key: str, range_end: bytes | str | None = None, start_revision: str | None = None, filters: List[Dict[str, Any]] | None = None, read_timeout: float | None = None) → HTTPResponse

    returns: response object

exception patroni.dcs.etcd3.Etcd3ClientError(code: int | None = None, error: str | None = None, status: int | None = None)

  Bases: `Etcd3Exception`

  __init__(code: int | None = None, error: str | None = None, status: int | None = None) → None
  as_dict() → Dict[str, Any]
  classmethod get_subclasses() → Iterator[Type[Etcd3ClientError]]

exception patroni.dcs.etcd3.Etcd3Error(value: Any)

  Bases: `DCSError`

exception patroni.dcs.etcd3.Etcd3Exception(message=None, payload=None)

  Bases: `EtcdException`

exception patroni.dcs.etcd3.Etcd3WatchCanceled(message=None, payload=None)

  Bases: `Etcd3Exception`

exception patroni.dcs.etcd3.FailedPrecondition(code: int | None = None, error: str | None = None, status: int | None = None)

  Bases: `Etcd3ClientError`

  code = 9

class patroni.dcs.etcd3.GRPCCode(*values)

  Bases: `IntEnum`

  Aborted = 10
  AlreadyExists = 6
  Canceled = 1
  DataLoss = 15
  DeadlineExceeded = 4
  FailedPrecondition = 9
  Internal = 13
  InvalidArgument = 3
  NotFound = 5
  OK = 0
  OutOfRange = 11
  PermissionDenied = 7
  ResourceExhausted = 8
  Unauthenticated = 16
  Unavailable = 14
  Unimplemented = 12
  Unknown = 2

exception patroni.dcs.etcd3.InvalidArgument(code: int | None = None, error: str | None = None, status: int | None = None)

  Bases: `Etcd3ClientError`

  code = 3

exception patroni.dcs.etcd3.InvalidAuthToken(code: int | None = None, error: str | None = None, status: int | None = None)

  Bases: `Etcd3ClientError`

  code = 16
  error = 'etcdserver: invalid auth token'

class patroni.dcs.etcd3.KVCache(dcs: Etcd3, client: PatroniEtcd3Client)

  Bases: `StaleEtcdNodeGuard`, `Thread`

  __init__(dcs: Etcd3, client: PatroniEtcd3Client) → None

    This constructor should always be called with keyword arguments. Arguments are:

    group should be None; reserved for future extension when a ThreadGroup class is implemented.

    target is the callable object to be invoked by the run() method. Defaults to None, meaning nothing is called.

    name is the thread name. By default, a unique name is constructed of the form “Thread-N” where N is a small decimal number.

    args is a list or tuple of arguments for the target invocation. Defaults to ().

    kwargs is a dictionary of keyword arguments for the target invocation. Defaults to {}.

    context is the contextvars.Context value to use for the thread. The default value is None, which means to check sys.flags.thread_inherit_context. If that flag is true, use a copy of the context of the caller. If false, use an empty context. To explicitly start with an empty context, pass a new instance of contextvars.Context(). To explicitly start with a copy of the current context, pass the value from contextvars.copy_context().

    If a subclass overrides the constructor, it must make sure to invoke the base class constructor (Thread.__init__()) before doing anything else to the thread.

  _build_cache() → None
  _do_watch(revision: str) → None
  static _finish_response(response: HTTPResponse) → None
  _process_event(event: Dict[str, Any]) → None
  _process_message(message: Dict[str, Any]) → None
  copy() → List[Dict[str, Any]]
  delete(name: str, mod_revision: str) → Tuple[bool, Dict[str, Any] | None]
  get(name: str) → Dict[str, Any] | None
  is_ready() → bool

    Must be called only when holding the lock on condition

  kill_stream() → None
  run() → None

    Method representing the thread’s activity.

    You may override this method in a subclass. The standard run() method invokes the callable object passed to the object’s constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.

  set(value: Dict[str, Any], overwrite: bool = False) → Tuple[bool, Dict[str, Any] | None]

exception patroni.dcs.etcd3.LeaseNotFound(code: int | None = None, error: str | None = None, status: int | None = None)

  Bases: `NotFound`

  error = 'etcdserver: requested lease not found'

exception patroni.dcs.etcd3.NotFound(code: int | None = None, error: str | None = None, status: int | None = None)

  Bases: `Etcd3ClientError`

  code = 5

class patroni.dcs.etcd3.PatroniEtcd3Client(*args: Any, **kwargs: Any)

  Bases: `Etcd3Client`

  __init__(*args: Any, **kwargs: Any) → None
  _abc_impl = <_abc._abc_data object>
  _restart_watcher() → None
  _wait_cache(timeout: float) → None
  call_rpc(method: str, fields: Dict[str, Any], retry: Retry | None = None) → Dict[str, Any]
  configure(etcd3: Etcd3) → None
  get_cluster(path: str) → List[Dict[str, Any]]
  set_base_uri(value: str) → None
  start_watcher() → None
  txn(compare: Dict[str, Any], success: Dict[str, Any], failure: Dict[str, Any] | None = None, *, retry: Retry | None = None) → Dict[str, Any]

exception patroni.dcs.etcd3.PermissionDenied(code: int | None = None, error: str | None = None, status: int | None = None)

  Bases: `Etcd3ClientError`

  code = 7
  error = 'etcdserver: permission denied'

exception patroni.dcs.etcd3.Unavailable(code: int | None = None, error: str | None = None, status: int | None = None)

  Bases: `Etcd3ClientError`

  code = 14

exception patroni.dcs.etcd3.Unknown(code: int | None = None, error: str | None = None, status: int | None = None)

  Bases: `Etcd3ClientError`

  code = 2

exception patroni.dcs.etcd3.UnsupportedEtcdVersion(value: Any)

  Bases: `PatroniException`

exception patroni.dcs.etcd3.UserEmpty(code: int | None = None, error: str | None = None, status: int | None = None)

  Bases: `InvalidArgument`

  error = 'etcdserver: user name is empty'

patroni.dcs.etcd3._handle_auth_errors(func: Callable[[...], Any]) → Any

patroni.dcs.etcd3._raise_for_data(data: bytes | str | Dict[str, Any], status_code: int | None = None) → Etcd3ClientError

patroni.dcs.etcd3.base64_decode(v: str) → str

patroni.dcs.etcd3.base64_encode(v: str | bytes) → str

patroni.dcs.etcd3.build_range_request(key: str, range_end: bytes | str | None = None) → Dict[str, Any]

patroni.dcs.etcd3.prefix_range_end(v: str) → bytes

patroni.dcs.etcd3.to_bytes(v: str | bytes) → bytes