Untitled :: Tecnisys Docs

patroni.ctl module

Implement patronictl: a command-line application which utilises the REST API to perform cluster operations.

var CONFIG_DIR_PATH: path to Patroni configuration directory as per click.get_app_dir() output.
var CONFIG_FILE_PATH: default path to patronictl.yaml configuration file.
var DCS_DEFAULTS: auxiliary dictionary to build the DCS section of the configuration file. Mainly used to help parsing --dcs-url command-line option of patronictl.

Note

Most of the patronictl commands (restart/reinit/pause/resume/show-config/edit-config and similar) require the group argument and work only for that specific Citus group. If not specified in the command line the group might be taken from the configuration file. If it is also missing in the configuration file we assume that this is just a normal Patroni cluster (not Citus).

exception _patroni.ctl.PatroniCtlException(_message: str) View on GitHub 

Bases: ClickException + Raised upon issues faced by patronictl utility.

class _patroni.ctl.PatronictlPrettyTable(_header: str, *args: Any, **kwargs: Any) View on GitHub 

Bases: PrettyTable + Utilitary class to print pretty tables. + Extend PrettyTable to make it print custom information in the header line. The idea is to print a header line like this: + \'`+ ``+``+ +``+Cluster:+``+ +``+batman+``+ +``+--------+--------+---------+----+-----------`` ``\'+` + Instead of the default header line which would contain only dash and plus characters. +

__build_header(_line: str_) → str 

Build the custom header line for the table. + Note

  Expected to be called only against the very first header line of the table.
  +
  Parameters:::
    *line* – the original header line.
  Returns:::
    the modified header line.
+

__init\\__(header: str, *args: Any, **kwargs: Any) → None View on GitHub 

Create a PatronictlPrettyTable instance with the given header. +

Parameters: +

_get_hline() → str View on GitHub 

Get string representation of a header line. + Inject the custom header line, if processing the first header line. + Note

  Original implementation for injecting a custom header line, and is used up to `+prettytable+` 2.2.0. From `+prettytable+` 2.2.0 onwards link:#patroni.ctl.PatronictlPrettyTable._stringify_hrule[`+_stringify_hrule()+`] is used instead.
  +
  Returns:::
    string representing a header line.
+

property \\__hrule: str_

Get string representation of a header line. + Inject the custom header line, if processing the first header line. + Note

  Original implementation for injecting a custom header line, and is used up to `+prettytable+` 2.2.0. From `+prettytable+` 2.2.0 onwards link:#patroni.ctl.PatronictlPrettyTable._stringify_hrule[`+_stringify_hrule()+`] is used instead.
  +
  Returns:::
    string representing a header line.
+

_is_first_hline() → bool View on GitHub 

Check if the current line being processed is the very first line of the header. +

Returns: True if processing the first header line, False otherwise. +

set_hline(_value: str) → None View on GitHub 

Set header line string representation. +

Parameters: value – string representing a header line. +

stringify_hrule(*args: Any, _**kwargs: Any) → str View on GitHub 

Get the string representation of a header line. + Inject the custom header line, if processing the first header line. + Note

New implementation for injecting a custom header line, which is used from `+prettytable+` 2.2.0 onwards.
+
Returns:::
  string representation of a header line.

patroni.ctl.do_failover_or_switchover(_action: str, cluster_name: str, group: int | None, switchover_leader: str | None, candidate: str | None, force: bool, scheduled: str | None = None) → None View on GitHub 

Perform a failover or a switchover operation in the cluster. + Informational messages are printed in the console during the operation, as well as the list of members before and after the operation, so the user can follow the operation status. + Note

If not able to perform the operation through the REST API, write directly to the DCS as a fall back.
+
Parameters:;;
Raises:;;
  link:#patroni.ctl.PatroniCtlException[`+PatroniCtlException+`]: if:::

patroni.ctl._get_configuration() → Dict[ str, Any] View on GitHub 

Get configuration object. +

Returns:: configuration object from the current context.

patroni.ctl.apply_config_changes(before_editing: str, data: Dict[ str, Any], kvpairs: List[ str]) → Tuple[ str, Dict[ str, Any]] View on GitHub 

Apply config changes specified as a list of key-value pairs. + Keys are interpreted as dotted paths into the configuration data structure. Except for paths beginning with postgresql.parameters where rest of the path is used directly to allow for PostgreSQL GUCs containing dots. Values are interpreted as YAML values. +

Parameters:
Returns:: tuple of human-readable, parsed data structure after changes.
Raises:: PatroniCtlException: if any entry in kvpairs is None or not in the expected format.

patroni.ctl.apply_yaml_file(data: Dict[ str, Any], filename: str) → Tuple[ str, Dict[ str, Any]] View on GitHub 

Apply changes from a YAML file to configuration. +

Parameters:
Returns:: tuple of human-readable and parsed data structure after changes.

patroni.ctl.check_response(response: HTTPResponse, member_name: str, action_name: str, silent_success: bool = False) → bool View on GitHub 

Check an HTTP response and print a status message. +

Parameters:
Returns:: True if the response indicates a sucessful operation (HTTP status < 400), False otherwise.

patroni.ctl.confirm_members_action(members: List[Member], force: bool, action: str, scheduled_at: datetime | None = None) → None View on GitHub 

Ask for confirmation if action should be taken by members. +

Parameters:: scheduled_at – timestamp at which the action should be scheduled to. If None action is taken immediately.
Raises:: PatroniCtlException: if the user aborted the action.

patroni.ctl.format_config_for_editing(data: Any, default_flow_style: bool = False) → str View on GitHub 

Format configuration as YAML for human consumption. +

Parameters:
Returns:: unicode YAML of the configuration.

patroni.ctl.format_pg_version(version: int) → str View on GitHub 

Format Postgres version for human consumption. +

Parameters:: version – Postgres version represented as an integer.
Returns:: Postgres version represented as a human-readable string.
Example:

>>> format_pg_version(90624)
'9.6.24'

>>> format_pg_version(100000)
'10.0'

>>> format_pg_version(140008)
'14.8'

patroni.ctl.generate_topology(level: int, member: Dict[ str, Any], topology: Dict[ str | None, List[ Dict[ str, Any]]]) → Iterator[ Dict[ str, Any]] View on GitHub 

Recursively yield members with their names adjusted according to their level in the cluster topology. + Note

The idea is to get a tree view of the members when printing their names. For example, suppose you have a cascading replication composed of 3 nodes, say `+postgresql0+`, `+postgresql1+`, and `+postgresql2+`. This function would adjust their names to be like this:

So, if you ever print their names line by line, you would see something like this:

postgresql0
+ postgresql1
  + postgresql2

+
Parameters:;;
Yields:;;
  the current member with its name changed. Besides that reyield values from recursive calls.

patroni.ctl.get_all_members(cluster: Cluster, group: int | None, role: str = 'leader') → Iterator[Member] View on GitHub 

Get all cluster members that have the given role. +

Parameters:
Yields:: members that have the given role.

patroni.ctl.get_all_members_leader_first(cluster: Cluster) → Iterator[Member] View on GitHub 

Get all cluster members, with the cluster leader being yielded first. + Note

Only yield members that have a `+restapi.connect_address+` configured.
+
Yields:;;
  all cluster members, with the leader first.

patroni.ctl.get_any_member(cluster: Cluster, group: int | None, role: str | None = None, member: str | None = None) → Member | None View on GitHub 

Get the first found cluster member that has the given role. +

Parameters:
Returns:: the first found cluster member that has the given role.
Raises:: PatroniCtlException: if both role and member are provided.

patroni.ctl.get_cluster_service_info(cluster: Dict[ str, Any]) → List[ str] View on GitHub 

Get complementary information about the cluster. +

Parameters:: cluster – a Patroni cluster represented as an object created through cluster_as_json().
Returns:: a list of 0 or more informational messages. They can be about:

Get a cursor object to execute queries against a member that has the given role or member_name. + Note

Besides what is passed through connect_parameters, this function also sets the following parameters:: +
Parameters:
Returns:: a cursor object to execute queries against the database. Can be either:

patroni.ctl.get_dcs(scope: str, group: int | None) → AbstractDCS View on GitHub 

Get the DCS object. +

Parameters:
Returns:: a subclass of AbstractDCS, according to the DCS technology that is configured.
Raises:: PatroniCtlException: if not suitable DCS configuration could be found.

patroni.ctl.get_members(cluster: Cluster, cluster_name: str, member_names: List[ str], role: str, force: bool, action: str, ask_confirmation: bool = True, group: int | None = None) → List[Member] View on GitHub 

Get the list of members based on the given filters. + Note

Contain some filtering and checks processing that are common to several actions that are exposed by patronictl, like:

\\__\\__
\\__\\__

Designed to handle both attended and unattended `+patronictl+` commands execution that need to retrieve and validate the members before doing anything.

In the very end may call link:#patroni.ctl.confirm_members_action[`+confirm_members_action()+`] to ask if the user would like to proceed with _action_ over the retrieved members. That won’t actually perform the action, but it works as the “last confirmation” before the _action_ is processed by the caller method.

Additional checks can also be implemented in the caller method, in which case you might want to pass `+ask_confirmation=False+`, and later call link:#patroni.ctl.confirm_members_action[`+confirm_members_action()+`] manually in the caller method. That way the workflow won’t look broken to the user that is interacting with `+patronictl+`.
+
Parameters:;;
  *ask_confirmation* – if `+False+`, then it won’t ask for the final confirmation regarding the _action_ before returning the list of members. Usually useful as `+False+` if you want to perform additional checks in the caller method besides the checks that are performed through this generic method.
  +
  *group* – filter which Citus group we should get members from. If `+None+` consider members from all groups.
Returns:;;
  a list of members that respect the given filters.
Raises:;;

PatroniCtlException: if

patroni.ctl.invoke_editor(before_editing: str, cluster_name: str) → Tuple[ str, Dict[ str, Any]] View on GitHub 

Start editor command to edit configuration in human readable format. + Note

Requires an editor program, and uses first found among:: +
Parameters:
Returns:: tuple of human-readable, parsed data structure after changes.
Raises:

PatroniCtlException: if

patroni.ctl.is_citus_cluster() → bool View on GitHub 

Check if we are working with Citus cluster. +

Returns:: True if configuration has citus section, otherwise False.

patroni.ctl.load_config(path: str, dcs_url: str | None) → Dict[ str, Any] View on GitHub 

Load configuration file from path and optionally override its DCS configuration with dcs_url. +

Parameters:
Returns:: a dictionary representing the configuration.
Raises:: PatroniCtlException: if path does not exist or is not readable.

patroni.ctl.output_members(cluster: Cluster, name: str, extended: bool = False, fmt: str = 'pretty', group: int | None = None) → None View on GitHub 

Print information about the Patroni cluster and its members. + Information is printed to console through print_output(), and contains: + __\\__ __\\__ +

Besides that it may also have:: + The 3 extended columns are always included if extended, even if the member has no value for a given column. If not extended, these columns may still be shown if any of the members has any information for them. +
Parameters:

patroni.ctl.parse_dcs(dcs: str | None) → Dict[ str, Any] | None View on GitHub 

Parse a DCS URL. +

Parameters:: dcs – + the DCS URL in the format DCS://HOST:PORT/NAMESPACE. DCS can be one among: + If DCS is not specified, assume etcd by default. If HOST is not specified, assume localhost by default. If PORT is not specified, assume the default port of the given DCS. If NAMESPACE is not specified, use whatever is in config.
Returns:: None if dcs is None, otherwise a dictionary. The dictionary represents dcs as if it were parsed from the Patroni configuration file. Additionally, if a namespace is specified in dcs, return a namespace key with the parsed value.
Raises:: PatroniCtlException: if the DCS name in dcs is not valid.
Example:

>>> parse_dcs('')
{'etcd': {'host': 'localhost:2379'}}

>>> parse_dcs('etcd://:2399')
{'etcd': {'host': 'localhost:2399'}}

>>> parse_dcs('etcd://test')
{'etcd': {'host': 'test:2379'}}

>>> parse_dcs('etcd3://random.com:2399')
{'etcd3': {'host': 'random.com:2399'}}

>>> parse_dcs('etcd3://random.com:2399/customnamespace')
{'etcd3': {'host': 'random.com:2399'}, 'namespace': '/customnamespace'}

patroni.ctl.parse_scheduled(scheduled: str | None) → datetime | None View on GitHub 

Parse a string scheduled timestamp as a datetime object. +

Parameters:: scheduled – string representation of the timestamp. May also be now.
Returns:: the corresponding datetime object, if scheduled is not now, otherwise None.
Raises:: PatroniCtlException: if unable to parse scheduled from str to datetime.
Example:

>>> parse_scheduled(None) is None
True

>>> parse_scheduled('now') is None
True

>>> parse_scheduled('2023-05-29T04:32:31')
datetime.datetime(2023, 5, 29, 4, 32, 31, tzinfo=tzlocal())

>>> parse_scheduled('2023-05-29T04:32:31-3')
datetime.datetime(2023, 5, 29, 4, 32, 31, tzinfo=tzoffset(None, -10800))

patroni.ctl.print_output(columns: List[ str] | None, rows: List[ List[ Any]], alignment: Dict[ str, str] | None = None, fmt: str = 'pretty', header: str = '', delimiter: str = '\t') → None View on GitHub 

Print tabular information. +

Parameters:

A key in the dictionary is only required for a column that needs a specific alignment. Only apply when fmt is either pretty or topology. + fmt – + the printing format. Can be one among: +

json: to print as a JSON string – array of objects;
yaml or yml: to print as a YAML string;
tsv: to print a table of separated values, by default by tab;
pretty: to print a pretty table;
topology: similar to pretty, but with a topology view when printing cluster members. + header – a string to be included in the first line of the table header, typically the cluster name. Only apply when fmt is either pretty or topology. + delimiter – the character to be used as delimiter when fmt is tsv.

Execute SQL command against a member. +

Parameters:
Returns:: a tuple composed of two items: + If an error occurs while executing command, then returns the following values in the tuple: + None.

patroni.ctl.request_patroni(member: Member, method: str = 'GET', endpoint: str | None = None, data: Any | None = None) → HTTPResponse View on GitHub 

Perform a request to Patroni REST API. +

Parameters:
Returns:: the response for the request.

patroni.ctl.show_diff(before_editing: str, after_editing: str) → None View on GitHub 

Show a diff between two strings. + Inputs are expected to be unicode strings. + If the output is to a tty the diff will be colored. + Note

If tty it requires a pager program, and uses first found among:: +
Parameters:
Raises:: PatroniCtlException: if no suitable pager can be found when printing diff output to a tty.

patroni.ctl.temporary_file(contents: bytes, suffix: str = '', prefix: str = 'tmp') → Iterator[ str] View on GitHub 

Create a temporary file with specified contents that persists for the context. +

Parameters:
Yields:: path of the created file.

patroni.ctl.timestamp(precision: int = 6) → str View on GitHub 

Get current timestamp with given precision as a string. +

Parameters:: precision – Amount of digits to be present in the precision.
Returns:: the current timestamp with given precision.

patroni.ctl.toggle_pause(cluster_name: str, group: int | None, paused: bool, wait: bool) → None View on GitHub 

Toggle the pause state in the cluster members. +

Parameters:
Raises:

PatroniCtlException: if

patroni.ctl.topology_sort(members: List[ Dict[ str, Any]]) → Iterator[ Dict[ str, Any]] View on GitHub 

Sort members according to their level in the replication topology tree. +

Parameters:: members – + list of members in the cluster. Each item should countain at least these keys: + Cascading replicas are identified through tags → replicatefrom value – if that is set, and they are in fact attached to another replica. + Besides name, role and tags keys, it may contain other keys, which although ignored by this function, will be yielded as part of the resulting object. The value of key name is changed through generate_topology().
Yields:: members sorted by level in the topology, and with a new name value according to their level in the topology.

patroni.ctl.wait_until_pause_is_applied(dcs: AbstractDCS, paused: bool, old_cluster: Cluster) → None View on GitHub 

Wait for all members in the cluster to have pause state set to paused. +

Parameters:

patroni.ctl.watching(w: bool, watch: int | None, max_count: int | None = None, clear: bool = True) → Iterator[ int] View on GitHub 

Yield a value every watch seconds. + Used to run a command with a watch-based approach. +

Parameters:
Yields:: 0 each time watch seconds have passed.
Example:

>>> len(list(watching(True, 1, 0)))
1
>>> len(list(watching(True, 1, 1)))
2
>>> len(list(watching(True, None, 0)))
1

Previous Next

Built with Sphinx using a theme provided by Read the Docs.

Read the Docs v: latest

bugfix-readthedocs

Project Home

+ Builds