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
orrecovery_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.
- config – Python object corresponding to an YAML file, with values of either
-
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 intoparameters
and/orrecovery_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 underavailable_parameters
directory.- Each YAML file may contain either or both of these root attributes, here called sections:
parameters
: general GUCs that would be written topostgresql.conf
;recovery_parameters
: recovery related GUCs that would be written torecovery.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
; orInteger
; orReal
; orEnum
; orEnumBool
; orString
.
Besides the
type
attribute, it should also contain all the required attributes as per the corresponding class in this module.
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) → Optional[Any]¶ Validate value of GUC name for Postgres version using defined validators.
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.
- Disallow writing GUCs to
postgresql.conf
(orrecovery.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.
- Disallow writing GUCs to
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.
- 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
-
patroni.postgresql.validator.
transform_postgresql_parameter_value
(version: int, name: str, value: Any) → Optional[Any]¶ Validate value of GUC name for Postgres version using
parameters
.Parameters: - version – Postgres version to validate the GUC against.
- name – name of the Postgres GUC.
- value – value of the Postgres GUC.
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 returnNone
. See_transform_parameter_value()
.
-
patroni.postgresql.validator.
transform_recovery_parameter_value
(version: int, name: str, value: Any) → Optional[Any]¶ Validate value of GUC name for Postgres version using
recovery_parameters
.Parameters: - version – Postgres version to validate the recovery GUC against.
- name – name of the Postgres recovery GUC.
- value – value of the Postgres recovery GUC.
Returns: value transformed to the expected format for recovery GUC name in Postgres version using validators defined in
recovery_parameters
. It can also returnNone
. See_transform_parameter_value()
.