# patroni.postgresql.validator module

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

  Bases: `_Transformable`

  _abc_impl = <_abc._abc_data object>
  transform(name: str, value: Any) → Any | 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

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

  Bases: `_Transformable`

  __init__(*, version_from: int, version_till: int | None = None, possible_values: Tuple[str, ...]) → None
  _abc_impl = <_abc._abc_data object>
  property possible_values: Tuple[str, ...]
  transform(name: str, value: Any | None) → Any | 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

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

  Bases: `Enum`

  _abc_impl = <_abc._abc_data object>
  transform(name: str, value: Any | None) → Any | 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

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)

  Bases: `Number`

  _abc_impl = <_abc._abc_data object>
  static parse(value: Any, unit: str | None) → int | None

    Convert provided value to unit.

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

  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)

  Bases: `_Transformable`

  __init__(*, version_from: int, version_till: int | None = None, min_val: int | float, max_val: int | float, unit: str | None = None) → None
  _abc_impl = <_abc._abc_data object>
  property max_val: int | float
  property min_val: int | float
  abstractmethod static parse(value: Any, unit: str | None) → Any | None

    Convert provided value to unit.

  transform(name: str, value: Any) → 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

  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)

  Bases: `Number`

  _abc_impl = <_abc._abc_data object>
  static parse(value: Any, unit: str | None) → float | None

    Convert provided value to unit.

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

  Bases: `_Transformable`

  _abc_impl = <_abc._abc_data object>
  transform(name: str, value: Any | None) → Any | 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

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[_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: `PatroniException`

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

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

  Bases: `PatroniException`

  Raised when a validator spec contains an invalid type.

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

  Bases: `PatroniException`

  Raised when a validator spec misses a type.

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

  Bases: `ABC`

  __init__(version_from: int, version_till: int | None = None) → None
  _abc_impl = <_abc._abc_data object>
  classmethod get_subclasses() → Iterator[Type[_Transformable]]

    Recursively get all subclasses of `_Transformable`.

    Yields:

      each subclass of `_Transformable`.

  abstractmethod transform(name: str, value: Any) → Any | 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

  property version_from: int
  property version_till: int | None

patroni.postgresql.validator._get_postgres_guc_validators(config: Dict[str, Any], parameter: str) → Tuple[_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: 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[_Transformable, ...]], version: int, name: str, value: Any, available_gucs: CaseInsensitiveSet) → Any | None

  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: CaseInsensitiveSet) → Any | None

  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: CaseInsensitiveSet) → Any | None

  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()`.