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._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
_abc_impl = <_abc._abc_data object>
property possible_values: Tuple[str, ...]
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._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._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
_abc_impl = <_abc._abc_data object>
property max_val: Union[int, float]
property min_val: Union[int, float]
abstract static parse(value: Any, unit: Optional[str]) Optional[Any]

Convert provided value to unit.

transform(name: str, value: Any) Optional[Union[int, float]]

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: Optional[str]
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._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._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(validator: Dict[str, Any])

Bases: object

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

TYPES: Dict[str, Type[patroni.postgresql.validator._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)

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
_abc_impl = <_abc._abc_data object>
classmethod get_subclasses() Iterator[Type[patroni.postgresql.validator._Transformable]]

Recursively get all subclasses of _Transformable.

Yields

each subclass of _Transformable.

abstract 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

property version_from: int
property version_till: Optional[int]
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

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: importlib.abc.Traversable) 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 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: 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 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: 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 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().