patroni.config module

Facilities related to Patroni configuration.

class patroni.config.Config(configfile: str, validator: ~typing.Callable[[~typing.Dict[str, ~typing.Any]], ~typing.List[str]] | None = <function default_validator>)

Bases: object

Handle Patroni configuration.

This class is responsible for:

  1. Building and giving access to effective_configuration from:

    • Config.__DEFAULT_CONFIG – some sane default values;

    • dynamic_configuration – configuration stored in DCS;

    • local_configuration – configuration from config.yml or environment.

  2. Saving and loading dynamic_configuration into ‘patroni.dynamic.json’ file located in local_configuration[‘postgresql’][‘data_dir’] directory. This is necessary to be able to restore dynamic_configuration if DCS was accidentally wiped.

  3. Loading of configuration file in the old format and converting it into new format.

  4. Mimicking some dict interfaces to make it possible to work with it as with the old config object.

Variables:

  • PATRONI_CONFIG_VARIABLE – name of the environment variable that can be used to load Patroni configuration from.

  • __CACHE_FILENAME – name of the file used to cache dynamic configuration under Postgres data directory.

  • __DEFAULT_CONFIG – default configuration values for some Patroni settings.

PATRONI_CONFIG_VARIABLE = 'PATRONI_CONFIGURATION'
__CACHE_FILENAME = 'patroni.dynamic.json'
__DEFAULT_CONFIG: Dict[str, Any] = {'loop_wait': 10, 'postgresql': {'parameters': <CaseInsensitiveDict{'wal_level': 'hot_standby', 'hot_standby': 'on', 'max_connections': 100, 'max_wal_senders': 10, 'max_prepared_transactions': 0, 'max_locks_per_transaction': 64, 'track_commit_timestamp': 'off', 'max_replication_slots': 10, 'max_worker_processes': 8, 'wal_log_hints': 'on'} at 72e033334b00>, 'use_slots': True}, 'retry_timeout': 10, 'standby_cluster': {'archive_cleanup_command': '', 'create_replica_methods': '', 'host': '', 'port': '', 'primary_slot_name': '', 'recovery_min_apply_delay': '', 'restore_command': ''}, 'ttl': 30}
__get_and_maybe_adjust_int_value(config: Dict[str, Any], param: str, min_value: int) → int

Get, validate and maybe adjust a param integer value from the config dict.

Parameters:

  • config – dict object with new global configuration.

  • param – name of the configuration parameter we want to read/validate/adjust.

  • min_value – the minimum possible value that a given param could have.

Returns:

an integer value which corresponds to a provided param.

__init__(configfile: str, validator: ~typing.Callable[[~typing.Dict[str, ~typing.Any]], ~typing.List[str]] | None = <function default_validator>) → None

Create a new instance of Config and validate the loaded configuration using validator.

Note

Patroni will read configuration from these locations in this order:

  • file or directory path passed as command-line argument (configfile), if it exists and the file or files found in the directory can be parsed (see _load_config_path()), otherwise

  • YAML file passed via the environment variable (see PATRONI_CONFIG_VARIABLE), if the referenced file exists and can be parsed, otherwise

  • from configuration values defined as environment variables, see _build_environment_configuration().

Parameters:

  • configfile – path to Patroni configuration file.

  • validator – function used to validate Patroni configuration. It should receive a dictionary which represents Patroni configuration, and return a list of zero or more error messages based on validation.

Raises:

ConfigParseError: if any issue is reported by validator.

_build_effective_configuration(dynamic_configuration: Dict[str, Any], local_configuration: Dict[str, Dict[str, Any] | Any]) → Dict[str, Any]

Build effective configuration by merging dynamic_configuration and local_configuration.

Note

local_configuration takes precedence over dynamic_configuration if a setting is defined in both.

Parameters:

  • dynamic_configuration – Patroni dynamic configuration.

  • local_configuration – Patroni local configuration.

Returns:

_description_

static _build_environment_configuration() → Dict[str, Any]

Get local configuration settings that were specified through environment variables.

Returns:

dictionary containing the found environment variables and their values, respecting the expected structure of Patroni configuration.

_load_cache() → None

Load dynamic configuration from patroni.dynamic.json.

_load_config_file() → Dict[str, Any]

Load configuration file(s) from filesystem and apply values which were set via environment variables.

Returns:

final configuration after merging configuration file(s) and environment variables.

_load_config_path(path: str) → Dict[str, Any]

Load Patroni configuration file(s) from path.

If path is a file, load the yml file pointed to by path. If path is a directory, load all yml files in that directory in alphabetical order.

Parameters:

path – path to either an YAML configuration file, or to a folder containing YAML configuration files.

Returns:

configuration after reading the configuration file(s) from path.

Raises:

ConfigParseError: if path is invalid. ConfigParseError: if path does not contain dict (empty file or no mapping values).

static _process_postgresql_parameters(parameters: Dict[str, Any], is_local: bool = False) → Dict[str, Any]

Process Postgres parameters.

Note

If is_local configuration discard any setting from parameters that is listed under CMDLINE_OPTIONS as those are supposed to be set only through dynamic configuration.

When setting parameters from CMDLINE_OPTIONS through dynamic configuration their value will be validated as per the validator defined in that very same attribute entry. If the given value cannot be validated, a warning will be logged and the default value of the GUC will be used instead.

Some parameters from CMDLINE_OPTIONS cannot be set even if not is_local configuration:

  • listen_addresses: inferred from postgresql.listen local configuration or from

    PATRONI_POSTGRESQL_LISTEN environment variable;

  • port: inferred from postgresql.listen local configuration or from

    PATRONI_POSTGRESQL_LISTEN environment variable;

  • cluster_name: set through scope local configuration or through PATRONI_SCOPE environment

    variable;

  • hot_standby: always enabled;

Parameters:

  • parameters – Postgres parameters to be processed. Should be the parsed YAML value of postgresql.parameters configuration, either from local or from dynamic configuration.

  • is_local – should be True if parameters refers to local configuration, or False if parameters refers to dynamic configuration.

Returns:

new value for postgresql.parameters after processing and validating parameters.

_safe_copy_dynamic_configuration(dynamic_configuration: Dict[str, Any]) → Dict[str, Any]

Create a copy of dynamic_configuration.

Merge dynamic_configuration with __DEFAULT_CONFIG (dynamic_configuration takes precedence), and process postgresql.parameters from dynamic_configuration through _process_postgresql_parameters(), if present.

Note

The following settings are not allowed in postgresql section as they are intended to be local configuration, and are removed if present:

  • connect_address;

  • proxy_address;

  • listen;

  • config_dir;

  • data_dir;

  • pgpass;

  • authentication;

Besides that any setting present in dynamic_configuration but absent from __DEFAULT_CONFIG is discarded.

Parameters:

dynamic_configuration – Patroni dynamic configuration.

Returns:

copy of dynamic_configuration, merged with default dynamic configuration and with some sanity checks performed over it.

_validate_and_adjust_timeouts(config: Dict[str, Any]) → None

Validate and adjust loop_wait, retry_timeout, and ttl values if necessary.

Minimum values:

  • loop_wait: 1 second;

  • retry_timeout: 3 seconds.

  • ttl: 20 seconds;

Maximum values: In case if values don’t fulfill the following rule, retry_timeout and loop_wait are reduced so that the rule is fulfilled:

loop_wait + 2 * retry_timeout <= ttl
Parameters:

config – dict object with new global configuration.

_validate_contradictory_tags() → None

Check boolean/priority tags’ config and warn user if it’s contradictory.

Note

To preserve sanity (and backwards compatibility) the nofailover/nosync tag will still exist. A contradictory configuration is one where nofailover/nosync is True but failover_priority > 0/sync_priority > 0, or where nofailover/nosync is False, but failover_priority <= 0/sync_priority <= 0. Essentially, nofailover/nosync and failover_priority/sync_priority are communicating different things. This checks for this edge case (which is a misconfiguration on the part of the user) and warns them. The behaviour is as if failover_priority/sync_priority were not provided (i.e nofailover/nosync is the bedrock source of truth).

property config_file: str | None

Path to Patroni configuration file, if any, else None.

copy() → Dict[str, Any]

Get a deep copy of effective Patroni configuration.

Returns:

a deep copy of the Patroni configuration.

property dynamic_configuration: Dict[str, Any]

Deep copy of cached Patroni dynamic configuration.

get(key: str, default: Any | None = None) → Any

Get effective value of key setting from Patroni configuration root.

Designed to work the same way as dict.get().

Parameters:

  • key – name of the setting.

  • default – default value if key is not present in the effective configuration.

Returns:

value of key, if present in the effective configuration, otherwise default.

classmethod get_default_config() → Dict[str, Any]

Deep copy default configuration.

Returns:

copy of __DEFAULT_CONFIG

property local_configuration: Dict[str, Any]

Deep copy of cached Patroni local configuration.

Returns:

copy of _local_configuration

reload_local_configuration() → bool | None

Reload configuration values from the configuration file(s).

Note

Designed to be used when user applies changes to configuration file(s), so Patroni can use the new values with a reload instead of a restart.

Returns:

True if changes have been detected between current local configuration

save_cache() → None

Save dynamic configuration to patroni.dynamic.json under Postgres data directory.

Note

patroni.dynamic.jsonXXXXXX is created as a temporary file and than renamed to patroni.dynamic.json, where XXXXXX is a random suffix.

set_dynamic_configuration(configuration: ClusterConfig | Dict[str, Any]) → bool

Set dynamic configuration values with given configuration.

Parameters:

configuration – new dynamic configuration values. Supports dict for backward compatibility.

Returns:

True if changes have been detected between current dynamic configuration and the new dynamic configuration, False otherwise.

patroni.config.default_validator(conf: Dict[str, Any]) → List[str]

Ensure conf is not empty.

Designed to be used as default validator for Config objects, if no specific validator is provided.

Parameters:

conf – configuration to be validated.

Returns:

an empty list – Config expects the validator to return a list of 0 or more issues found while validating the configuration.

Raises:

ConfigParseError: if conf is empty.