patroni.postgresql.validator module

class patroni.postgresql.validator.Bool(version_from: int, version_till: int | None = None)View on GitHub 

Bases: _Transformable

_abc_impl = <_abc._abc_data object>

transform(name: str, value: Any) → Any | NoneView on GitHub 

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: int | None = None, possible_values: Tuple[str, ...])View on GitHub 

Bases: _Transformable

__init__(*, version_from: int, version_till: int | None = None, possible_values: Tuple[str, ...]) → NoneView on GitHub 

_abc_impl = <_abc._abc_data object>

property possible_values: Tuple[str, ...]

transform(name: str, value: Any | None) → Any | NoneView on GitHub 

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: int | None = None, possible_values: Tuple[str, ...])View on GitHub 

Bases: Enum

_abc_impl = <_abc._abc_data object>

transform(name: str, value: Any | None) → Any | NoneView on GitHub 

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: int | None = None, min_val: int | float, max_val: int | float, unit: str | None = None)View on GitHub 

Bases: Number

_abc_impl = <_abc._abc_data object>

static parse(value: Any, unit: str | None) → int | NoneView on GitHub : Convert provided value to unit.

exception patroni.postgresql.validator.InvalidGucValidatorsFile(value: Any)View on GitHub 

Bases: PatroniException

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

class patroni.postgresql.validator.Number(*, version_from: int, version_till: int | None = None, min_val: int | float, max_val: int | float, unit: str | None = None)View on GitHub 

Bases: _Transformable

__init__(*, version_from: int, version_till: int | None = None, min_val: int | float, max_val: int | float, unit: str | None = None) → NoneView on GitHub 

_abc_impl = <_abc._abc_data object>

property max_val: int | float

property min_val: int | float

abstract static parse(value: Any, unit: str | None) → Any | NoneView on GitHub : Convert provided value to unit.

transform(name: str, value: Any) → int | float | NoneView on GitHub 

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

property unit: str | None

class patroni.postgresql.validator.Real(*, version_from: int, version_till: int | None = None, min_val: int | float, max_val: int | float, unit: str | None = None)View on GitHub 

Bases: Number

_abc_impl = <_abc._abc_data object>

static parse(value: Any, unit: str | None) → float | NoneView on GitHub : Convert provided value to unit.

class patroni.postgresql.validator.String(version_from: int, version_till: int | None = None)View on GitHub 

Bases: _Transformable

_abc_impl = <_abc._abc_data object>

transform(name: str, value: Any | None) → Any | NoneView on GitHub 

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(validator: Dict[str, Any])View on GitHub 

Bases: object

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

TYPES: Dict[str, Type[_Transformable]] = {'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)View on GitHub 

Bases: PatroniException

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

exception patroni.postgresql.validator.ValidatorFactoryInvalidType(value: Any)View on GitHub 

Bases: PatroniException

Raised when a validator spec contains an invalid type.

exception patroni.postgresql.validator.ValidatorFactoryNoType(value: Any)View on GitHub 

Bases: PatroniException

Raised when a validator spec misses a type.

class patroni.postgresql.validator._Transformable(version_from: int, version_till: int | None = None)View on GitHub 

Bases: ABC

__init__(version_from: int, version_till: int | None = None) → NoneView on GitHub 

_abc_impl = <_abc._abc_data object>

classmethod get_subclasses() → Iterator[Type[_Transformable]]View on GitHub 

Recursively get all subclasses of _Transformable.

Yields:: each subclass of _Transformable.

abstract transform(name: str, value: Any) → Any | NoneView on GitHub 

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

property version_from: int

property version_till: int | None

patroni.postgresql.validator._get_postgres_guc_validators(config: Dict[str, Any], parameter: str) → Tuple[_Transformable, ...]View on GitHub 

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() → NoneView on GitHub 

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: Traversable) → Dict[str, Any]View on GitHub 

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[_Transformable, ...]], version: int, name: str, value: Any, available_gucs: CaseInsensitiveSet) → Any | NoneView on GitHub 

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 for a couple purposes:
- Disallow writing GUCs to postgresql.conf (or recovery.conf) that does not exist in Postgres version;
- 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 is present in available_gucs and has a validator in validators for the corresponding Postgres version; or
The own value if name is present in available_gucs but not in validators; or
None if name is not present in available_gucs.

patroni.postgresql.validator.transform_postgresql_parameter_value(version: int, name: str, value: Any, available_gucs: CaseInsensitiveSet) → Any | NoneView on GitHub 

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 for a couple purposes:
- Disallow writing GUCs to postgresql.conf that does not exist in Postgres version;
- 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: CaseInsensitiveSet) → Any | NoneView on GitHub 

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 for a couple purposes:
- Disallow writing GUCs to recovery.conf (or postgresql.conf depending on version), that does not
  exist in Postgres version;
- Avoid ignoring recovery GUC name if it does not have a validator in recovery_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().