patroni.postgresql.validator module¶

class patroni.postgresql.validator.Bool(version_from: int, version_till: Optional[int] = None)¶

Bases: patroni.postgresql.validator._Transformable

_abc_impl = <_abc_data object>¶

transform(name: str, value: Any) → Optional[Any]¶

Verify that provided value is valid.

Parameters:	name – GUC’s name value – GUC’s value
Returns:	the value (sometimes clamped) or `None` if the value isn’t valid

class patroni.postgresql.validator.Enum(*, version_from: int, version_till: Optional[int] = None, possible_values: Tuple[str, ...])¶

Bases: patroni.postgresql.validator._Transformable

__init__(*, version_from: int, version_till: Optional[int] = None, possible_values: Tuple[str, ...]) → None¶: Initialize self. See help(type(self)) for accurate signature.

_abc_impl = <_abc_data object>¶

possible_values¶

transform(name: str, value: Optional[Any]) → Optional[Any]¶

Verify that provided value is valid.

Parameters:	name – GUC’s name value – GUC’s value
Returns:	the value (sometimes clamped) or `None` if the value isn’t valid

class patroni.postgresql.validator.EnumBool(*, version_from: int, version_till: Optional[int] = None, possible_values: Tuple[str, ...])¶

Bases: patroni.postgresql.validator.Enum

_abc_impl = <_abc_data object>¶

transform(name: str, value: Optional[Any]) → Optional[Any]¶

Verify that provided value is valid.

Parameters:	name – GUC’s name value – GUC’s value
Returns:	the value (sometimes clamped) or `None` if the value isn’t valid

class patroni.postgresql.validator.Integer(*, version_from: int, version_till: Optional[int] = None, min_val: Union[int, float], max_val: Union[int, float], unit: Optional[str] = None)¶

Bases: patroni.postgresql.validator.Number

_abc_impl = <_abc_data object>¶

static parse(value: Any, unit: Optional[str]) → Optional[int]¶: Convert provided value to unit.

exception patroni.postgresql.validator.InvalidGucValidatorsFile(value: Any)¶

Bases: patroni.exceptions.PatroniException

Raised when reading or parsing of a YAML file faces an issue.

class patroni.postgresql.validator.Number(*, version_from: int, version_till: Optional[int] = None, min_val: Union[int, float], max_val: Union[int, float], unit: Optional[str] = None)¶

Bases: patroni.postgresql.validator._Transformable

__init__(*, version_from: int, version_till: Optional[int] = None, min_val: Union[int, float], max_val: Union[int, float], unit: Optional[str] = None) → None¶: Initialize self. See help(type(self)) for accurate signature.

_abc_impl = <_abc_data object>¶

max_val¶

min_val¶

static parse(value: Any, unit: Optional[str]) → Optional[Any]¶: Convert provided value to unit.

transform(name: str, value: Any) → Union[int, float, None]¶

Verify that provided value is valid.

Parameters:	name – GUC’s name value – GUC’s value
Returns:	the value (sometimes clamped) or `None` if the value isn’t valid

unit¶

class patroni.postgresql.validator.Real(*, version_from: int, version_till: Optional[int] = None, min_val: Union[int, float], max_val: Union[int, float], unit: Optional[str] = None)¶

Bases: patroni.postgresql.validator.Number

_abc_impl = <_abc_data object>¶

static parse(value: Any, unit: Optional[str]) → Optional[float]¶: Convert provided value to unit.

class patroni.postgresql.validator.String(version_from: int, version_till: Optional[int] = None)¶

Bases: patroni.postgresql.validator._Transformable

_abc_impl = <_abc_data object>¶

transform(name: str, value: Optional[Any]) → Optional[Any]¶

Verify that provided value is valid.

Parameters:	name – GUC’s name value – GUC’s value
Returns:	the value (sometimes clamped) or `None` if the value isn’t valid

class patroni.postgresql.validator.ValidatorFactory¶

Bases: object

Factory class used to build Patroni validator objects based on the given specs.

TYPES = {'Bool': <class 'patroni.postgresql.validator.Bool'>, 'Enum': <class 'patroni.postgresql.validator.Enum'>, 'EnumBool': <class 'patroni.postgresql.validator.EnumBool'>, 'Integer': <class 'patroni.postgresql.validator.Integer'>, 'Number': <class 'patroni.postgresql.validator.Number'>, 'Real': <class 'patroni.postgresql.validator.Real'>, 'String': <class 'patroni.postgresql.validator.String'>}¶

exception patroni.postgresql.validator.ValidatorFactoryInvalidSpec(value: Any)¶

Bases: patroni.exceptions.PatroniException

Raised when a validator spec contains an invalid set of attributes.

exception patroni.postgresql.validator.ValidatorFactoryInvalidType(value: Any)¶

Bases: patroni.exceptions.PatroniException

Raised when a validator spec contains an invalid type.

exception patroni.postgresql.validator.ValidatorFactoryNoType(value: Any)¶

Bases: patroni.exceptions.PatroniException

Raised when a validator spec misses a type.

class patroni.postgresql.validator._Transformable(version_from: int, version_till: Optional[int] = None)¶

Bases: abc.ABC

__init__(version_from: int, version_till: Optional[int] = None) → None¶: Initialize self. See help(type(self)) for accurate signature.

_abc_impl = <_abc_data object>¶

classmethod get_subclasses() → Iterator[Type[patroni.postgresql.validator._Transformable]]¶

Recursively get all subclasses of _Transformable.

Yields:	each subclass of `_Transformable`.

transform(name: str, value: Any) → Optional[Any]¶

Verify that provided value is valid.

Parameters:	name – GUC’s name value – GUC’s value
Returns:	the value (sometimes clamped) or `None` if the value isn’t valid

version_from¶

version_till¶

patroni.postgresql.validator._get_postgres_guc_validators(config: Dict[str, Any], parameter: str) → Tuple[patroni.postgresql.validator._Transformable, ...]¶

Get all validators of parameter from config.

Loop over all validators specs of parameter and return them parsed as Patroni validators.

Parameters:	config – Python object corresponding to an YAML file, with values of either `parameters` or `recovery_parameters` key. parameter – name of the parameter found under config which validators should be parsed and returned.
Return type:	yields any exception that is faced while parsing a validator spec into a Patroni validator object.

patroni.postgresql.validator._load_postgres_gucs_validators() → None¶

Load all Postgres GUC validators from YAML files.

Recursively walk through available_parameters directory and load validators of each found YAML file into parameters and/or recovery_parameters variables.

Walk through directories in top-down fashion and for each of them:

Sort files by name;
Load validators from YAML files that were found.

Any problem faced while reading or parsing files will be logged as a WARNING by the child function, and the corresponding file or validator will be ignored.

By default, Patroni only ships the file 0_postgres.yml, which contains Community Postgres GUCs validators, but that behavior can be extended. For example: if a vendor wants to add GUC validators to Patroni for covering a custom Postgres build, then they can create their custom YAML files under available_parameters directory.

Each YAML file may contain either or both of these root attributes, here called sections:

parameters: general GUCs that would be written to postgresql.conf;
recovery_parameters: recovery related GUCs that would be written to recovery.conf (Patroni later

writes them to postgresql.conf if running PG 12 and above).

Then, each of these sections, if specified, may contain one or more attributes with the following structure:

key: the name of a GUC;

value: a list of validators. Each item in the list must contain a type attribute, which must be one among:

Bool; or

Integer; or

Real; or

Enum; or

EnumBool; or

String.

Besides the type attribute, it should also contain all the required attributes as per the corresponding class in this module.

See also

Bool;
Integer;
Real;
Enum;
EnumBool;
String.

Example:

This is a sample content for an YAML file based on Postgres GUCs, showing each of the supported types and sections:

parameters:
  archive_command:
  - type: String
    version_from: 90300
    version_till: null
  archive_mode:
  - type: Bool
    version_from: 90300
    version_till: 90500
  - type: EnumBool
    version_from: 90500
    version_till: null
    possible_values:
    - always
  archive_timeout:
  - type: Integer
    version_from: 90300
    version_till: null
    min_val: 0
    max_val: 1073741823
    unit: s
  autovacuum_vacuum_cost_delay:
  - type: Integer
    version_from: 90300
    version_till: 120000
    min_val: -1
    max_val: 100
    unit: ms
  - type: Real
    version_from: 120000
    version_till: null
    min_val: -1
    max_val: 100
    unit: ms
  client_min_messages:
  - type: Enum
    version_from: 90300
    version_till: null
    possible_values:
    - debug5
    - debug4
    - debug3
    - debug2
    - debug1
    - log
    - notice
    - warning
    - error
recovery_parameters:
  archive_cleanup_command:
  - type: String
    version_from: 90300
    version_till: null

patroni.postgresql.validator._read_postgres_gucs_validators_file(file: pathlib.Path) → Dict[str, Any]¶

Read an YAML file and return the corresponding Python object.

Parameters:	file – path-like object to read from. It is expected to be encoded with `UTF-8`, and to be a YAML document.
Returns:	the YAML content parsed into a Python object. If any issue is faced while reading/parsing the file, then return `None`.
Raises:	`InvalidGucValidatorsFile`: if faces an issue while reading or parsing file.

patroni.postgresql.validator._transform_parameter_value(validators: MutableMapping[str, Tuple[patroni.postgresql.validator._Transformable, ...]], version: int, name: str, value: Any, available_gucs: patroni.collections.CaseInsensitiveSet) → Optional[Any]¶

Validate value of GUC name for Postgres version using defined validators and available_gucs.

Parameters:

validators – a dictionary of all GUCs across all Postgres versions. Each key is the name of a Postgres GUC, and the corresponding value is a variable length tuple of _Transformable. Each item is a validation rule for the GUC for a given range of Postgres versions. Should either contain recovery GUCs or general GUCs, not both.
version – Postgres version to validate the GUC against.
name – name of the Postgres GUC.
value – value of the Postgres GUC.
available_gucs – a set of all GUCs available in Postgres version. Each item is the name of a Postgres GUC. Used to avoid ignoring GUC name if it does not have a validator in validators, but is a valid GUC in Postgres version.

Returns:

the return value may be one among:

value transformed to the expected format for GUC name in Postgres version, if name has a validator in validators for the corresponding Postgres version; or
None if name does not have a validator in validators and is not present in available_gucs.

patroni.postgresql.validator.transform_postgresql_parameter_value(version: int, name: str, value: Any, available_gucs: patroni.collections.CaseInsensitiveSet) → Optional[Any]¶

Validate value of GUC name for Postgres version using parameters and available_gucs.

Parameters:

version – Postgres version to validate the GUC against.
name – name of the Postgres GUC.
value – value of the Postgres GUC.
available_gucs – a set of all GUCs available in Postgres version. Each item is the name of a Postgres GUC. Used to avoid ignoring GUC name if it does not have a validator in parameters, but is a valid GUC in Postgres version.

Returns:

The return value may be one among:

The original value if name seems to be an extension GUC (contains a period ‘.’); or
None if name is a recovery GUC; or
value transformed to the expected format for GUC name in Postgres version using validators defined in

parameters. Can also return None. See _transform_parameter_value().

patroni.postgresql.validator.transform_recovery_parameter_value(version: int, name: str, value: Any, available_gucs: patroni.collections.CaseInsensitiveSet) → Optional[Any]¶

Validate value of GUC name for Postgres version using recovery_parameters and available_gucs.

Parameters:

version – Postgres version to validate the recovery GUC against.
name – name of the Postgres recovery GUC.
value – value of the Postgres recovery GUC.
available_gucs – a set of all GUCs available in Postgres version. Each item is the name of a Postgres GUC. Used to avoid ignoring GUC name if it does not have a validator in parameters, but is a valid GUC in Postgres version.

Returns:

value transformed to the expected format for recovery GUC name in Postgres version using validators defined in recovery_parameters. It can also return None. See _transform_parameter_value().