patroni.validator module¶
Patroni configuration validation helpers.
This module contains facilities for validating configuration of Patroni processes.
- var schema
configuration schema of the daemon launched by
patroni
command.
-
class
patroni.validator.
BinDirectory
(contains: Optional[List[str]] = None, contains_executable: Optional[List[str]] = None)¶ Bases:
patroni.validator.Directory
Check if a Postgres binary directory contains the expected files.
It is a subclass of
Directory
with an extended capability: translatingBINARIES
according to configuredpostgresql.bin_name
, if any.- Variables
BINARIES – list of executable files that should exist directly under a given Postgres binary directory.
-
BINARIES
= ['pg_ctl', 'initdb', 'pg_controldata', 'pg_basebackup', 'postgres', 'pg_isready']¶
-
validate
(name: str) → Iterator[patroni.validator.Result]¶ Check if the expected executables can be found under name binary directory.
- Parameters
name – path to the base directory against which executables will be validated. Check against PATH if name is not provided.
- Yields
objects with the error message related to the failure, if any check fails.
-
class
patroni.validator.
Case
(schema: Dict[str, Any])¶ Bases:
object
Map how a list of available configuration options should be validated.
-
class
patroni.validator.
Directory
(contains: Optional[List[str]] = None, contains_executable: Optional[List[str]] = None)¶ Bases:
object
Check if a directory contains the expected files.
The attributes of objects of this class are used by their
validate()
method.- Parameters
contains – list of paths that should exist relative to a given directory.
contains_executable – list of executable files that should exist directly under a given directory.
-
validate
(name: str) → Iterator[patroni.validator.Result]¶ Check if the expected paths and executables can be found under name directory.
- Parameters
name – path to the base directory against which paths and executables will be validated. Check against
PATH
if name is not provided.- Yields
objects with the error message related to the failure, if any check fails.
-
class
patroni.validator.
EnumValidator
(allowed_values: Tuple[str, …], case_sensitive: bool = False, raise_assert: bool = False)¶ Bases:
object
Validate enum setting
- Variables
allowed_values – a
set
orCaseInsensitiveSet
object with allowed enum values.raise_assert – if an
assert
call should be performed regarding expected type and valid range.
-
class
patroni.validator.
IntValidator
(min: Optional[int] = None, max: Optional[int] = None, base_unit: Optional[str] = None, raise_assert: bool = False)¶ Bases:
object
Validate an integer setting.
- Variables
expected_type – the expected Python type for an integer setting (
int
).min – minimum allowed value for the setting, if any.
max – maximum allowed value for the setting, if any.
base_unit – the base unit to convert the value to before checking if it’s within min and max range.
raise_assert – if an
assert
test should be performed regarding expected type and valid range.
-
class
patroni.validator.
Optional
(name: str, default: Optional[Any] = None)¶ Bases:
object
Mark a configuration option as optional.
- Variables
name – name of the configuration option.
default – value to set if the configuration option is not explicitly provided
-
class
patroni.validator.
Or
(*args: Any)¶ Bases:
object
Represent the list of options that are available.
It can represent either a list of configuration options that are available in a given scope, or a list of validation functions and/or expected types for a given configuration option.
-
class
patroni.validator.
Result
(status: bool, error: Optional[str] = "didn't pass validation", level: int = 0, path: str = '', data: Any = '')¶ Bases:
object
Represent the result of a given validation that was performed.
-
class
patroni.validator.
Schema
(validator: Any)¶ Bases:
object
Define a configuration schema.
It contains all the configuration options that are available in each scope, including the validation(s) that should be performed against each one of them. The validations will be performed whenever the
Schema
object is called, or itsvalidate()
method is called.- Variables
validator of the configuration schema. Can be any of these:
str
: defines that a string value is required; ortype
: any subclass oftype
, defines that a value of the given type is required; orcallable
: any callable object, defines that validation will follow the code defined in the callable object. If the callable object contains anexpected_type
attribute, then it will check if the configuration value is of the expected type before calling the code of the callable object; orlist
: list representing one or more values in the configuration; ordict
: dictionary representing the YAML configuration tree.
-
iter
() → Iterator[patroni.validator.Result]¶ Iterate over
validator
, if it is an iterable object, to validate the corresponding entries indata
.Only
dict
,list
,Directory
andOr
objects are considered iterable objects.- Yields
objects with the error message related to the failure, if any check fails.
-
iter_dict
() → Iterator[patroni.validator.Result]¶ Iterate over a
dict
basedvalidator
to validate the corresponding entries indata
.- Yields
objects with the error message related to the failure, if any check fails.
-
iter_or
() → Iterator[patroni.validator.Result]¶ Perform all validations defined in an
Or
object for a given configuration option.This method can be only called against leaf nodes in the configuration tree.
Or
objects defined in thevalidator
keys will be handled byiter_dict()
method.- Yields
objects with the error message related to the failure, if any check fails.
-
validate
(data: Any) → Iterator[patroni.validator.Result]¶ Perform all validations from the schema against the given configuration.
It first checks that data argument type is compliant with the type of
validator
attribute.- Additionally:
- If
validator
attribute is a callable object, calls it to validate data argument. Before doing so, if validator contains an
expected_type
attribute, check if data argument is compliant with that expected type.
- If
- Parameters
data – configuration to be validated against
validator
.- Yields
objects with the error message related to the failure, if any check fails.
-
patroni.validator.
assert_
(condition: bool, message: str = 'Wrong value') → None¶ Assert that a given condition is
True
.If the assertion fails, then throw a message.
- Parameters
condition – result of a condition to be asserted.
message – message to be thrown if the condition is
False
.
-
patroni.validator.
comma_separated_host_port
(string: str) → bool¶ Validate a list of host and port items.
Call
validate_host_port_list()
with a list represented by the CSV string.- Parameters
string – comma-separated list of host and port items.
- Returns
True
if all items in the CSV string are valid.
-
patroni.validator.
data_directory_empty
(data_dir: str) → bool¶ Check if PostgreSQL data directory is empty.
- Parameters
data_dir – path to the PostgreSQL data directory to be checked.
- Returns
True
if the data directory is empty.
-
patroni.validator.
get_bin_name
(bin_name: str) → str¶ Get the value of
postgresql.bin_name[*bin_name*]
configuration option.- Parameters
bin_name – a key to be retrieved from
postgresql.bin_name
configuration.- Returns
value of
postgresql.bin_name[*bin_name*]
, if present, otherwise bin_name.
-
patroni.validator.
get_major_version
(bin_dir: Optional[str] = None) → str¶ Get the major version of PostgreSQL.
It is based on the output of
postgres --version
.- Parameters
bin_dir – path to PostgreSQL binaries directory. If
None
it will use the firstpostgres
binary that is found by subprocess in thePATH
.- Returns
the PostgreSQL major version.
- Example
Returns 9.6 for PostgreSQL 9.6.24
Returns 15 for PostgreSQL 15.2
-
patroni.validator.
is_ipv4_address
(ip: str) → bool¶ Check if ip is a valid IPv4 address.
- Parameters
ip – the IP to be checked.
- Returns
True
if the IP is an IPv4 address.- Raises
ConfigParseError
: if ip is not a valid IPv4 address.
-
patroni.validator.
is_ipv6_address
(ip: str) → bool¶ Check if ip is a valid IPv6 address.
- Parameters
ip – the IP to be checked.
- Returns
True
if the IP is an IPv6 address.- Raises
ConfigParseError
: if ip is not a valid IPv6 address.
-
patroni.validator.
validate_binary_name
(bin_name: str) → bool¶ Validate the value of
postgresql.binary_name[*bin_name*]
configuration option.If
postgresql.bin_dir
is set and the value of the bin_name meets these conditions:The path join of
postgresql.bin_dir
plus the bin_name value exists; andThe path join as above is executable
If
postgresql.bin_dir
is not set, then validate that the value of bin_name meets this condition:Is found in the system PATH using
which
- Parameters
bin_name – the value of the
postgresql.bin_name[*bin_name*]
- Returns
True
if the conditions are true- Raises
ConfigParseError
if:bin_name is not set; or
the path join of the
postgresql.bin_dir
plus bin_name does not exist; orthe path join as above is not executable; or
the bin_name cannot be found in the system PATH
-
patroni.validator.
validate_connect_address
(address: str) → bool¶ Check if options related to connection address were properly configured.
- Parameters
address – address to be validated in the format
host:ip
.- Returns
True
if the address is valid.- Raises
ConfigParseError
:If the address is not in the expected format; or
If the host is set to not allowed values (
127.0.0.1
,0.0.0.0
,*
,::1
, orlocalhost
).
-
patroni.validator.
validate_data_dir
(data_dir: str) → bool¶ Validate the value of
postgresql.data_dir
configuration option.It requires that
postgresql.data_dir
is set and match one of following conditions:Point to a path that does not exist yet; or
Point to an empty directory; or
Point to a non-empty directory that seems to contain a valid PostgreSQL data directory.
- Parameters
data_dir – the value of
postgresql.data_dir
configuration option.- Returns
True
if the PostgreSQL data directory is valid.- Raises
ConfigParseError
:If no data_dir was given; or
If data_dir is a file and not a directory; or
- If data_dir is a non-empty directory and:
PG_VERSION
file is not available in the directorypg_wal
/pg_xlog
is not available in the directoryPG_VERSION
content does not match the major version reported bypostgres --version
-
patroni.validator.
validate_host_port
(host_port: str, listen: bool = False, multiple_hosts: bool = False) → bool¶ Check if host(s) and port are valid and available for usage.
- Parameters
host_port –
the host(s) and port to be validated. It can be in either of these formats:
host:ip
, if multiple_hosts isFalse
; orhost_1,host_2,...,host_n:port
, if multiple_hosts isTrue
.
listen – if the address is expected to be available for binding.
False
means it expects to connect to that address, andTrue
that it expects to bind to that address.multiple_hosts – if host_port can contain multiple hosts.
- Returns
True
if the host(s) and port are valid.- Raises
ConfigParseError
:If the host_port is not in the expected format; or
If
*
was specified along with more hosts in host_port; orIf we are expecting to bind to an address that is already in use; or
If we are not able to connect to an address that we are expecting to do so; or
If
gaierror
is thrown by socket module when attempting to connect to the given address(es).
-
patroni.validator.
validate_host_port_list
(value: List[str]) → bool¶ Validate a list of host(s) and port items.
Call
validate_host_port()
with each item in value.- Parameters
value – list of host(s) and port items to be validated.
- Returns
True
if all items are valid.
-
patroni.validator.
validate_host_port_listen
(host_port: str) → bool¶ Check if host and port are valid and available for binding.
Call
validate_host_port()
with listen set toTrue
.- Parameters
host_port – the host and port to be validated. Must be in the format
host:ip
.- Returns
True
if the host and port are valid and available for binding.
-
patroni.validator.
validate_host_port_listen_multiple_hosts
(host_port: str) → bool¶ Check if host(s) and port are valid and available for binding.
Call
validate_host_port()
with both listen and multiple_hosts set toTrue
.- Parameters
host_port –
the host(s) and port to be validated. It can be in either of these formats
host:ip
; orhost_1,host_2,...,host_n:port
- Returns
True
if the host(s) and port are valid and available for binding.