Patroni

patronictl is a Python 3-based CLI (command line interface) installed with the Patroni package, which provides functions for monitoring clusters and accessing DCS using the REST API provided by Patroni clusters.

Used to manage PostgreSQL clusters, check their status, and verify configuration settings.

Check Installation

patronictl is provided by default with the Python 3 package patroni. You can check whether patronictl is installed on the node and its version as follows.

$ which patronictl 
/usr/local/bin/patronictl

$ patronictl version
patronictl version 3.3.0


Configure Local Configuration File

This is a configuration value that is read from a yml file located in the path that is input as a parameter when the Patroni process runs.

You can send a SIGHUP signal to the Patroni process or send a POST /reload request to the REST API server to reload the configuration file. The path to the default template environment configuration file is /etc/patroni/patroni.yml. Create a yml file in that path and modify the contents of the file to suit the environment you want to configure

  • You can define meta information for the Patroni cluster, etcd connection information, logging configuration, REST API server configuration, and PostgreSQL parameter information.

  • The PostgreSQL parameter set is defined in the Local Configuration and Global Dynamic. If there are duplicate keys, the value in the Local Configuration takes precedence.

  • Configuration below. Define the bootstrap.dcs item to set the initial configuration set for Global Dynamic Configuration below.

Cluster meta information

  • scope: the Patroni cluster you want to configure. PostgreSQL parameters Applied to cluster_name.

  • namespace: Prefix of the key to use within the Configuration Store.

  • name: The name of this instance (node). Must be unique within the cluster; if not set, the hostname is used.

Logging

  • log.type: Specifies the log format. Two options are supported: plain and json. Using the json

    type requires an additional installation of the Python package patroni[jsonlogger].

  • log.format: Specify the format of the log messages. Use the LogRecord module of the Python

    logging package. ◦If the log type is plain, it should be given as a string like the example above. ◦If the log type is json, it can be given as an array of items to be logged. ◦See https://docs.py thon.org /3.6/library /logg ing .html#logrecord-attributesarrow-up-right ◦log.dir: The path to the directory where Patroni logs will be written, and the default retention for log files. The size is 425 MB. ◦For items not mentioned, see the documentation at the links below; https://patroni.readthedocs.io/en/latest/ENVIRONMENT.html#logarrow-up-right

Rest API

  • restapi.listen: The IPv4 address and port number to which the Patroni REST API server will be bound.

  • restapi.connect_address: The externally identifiable Rest API server address of this node to use for communication between Patroni members. This value is also parsed and used as the Host address when making API calls to lookup cluster members.

DCS (etcd)

Example for etcd v3

  • etcd3.protocol: Supports http or https as the protocol to use when accessing the etcd3 cluster. http is used as the default value, and if it is https, you need to set etcd3.cacert , etcd3.cert , etcd3.key additionally.

  • etcd3.host: etcd3 endpoint URL

  • etcd3.hosts: Array of etcd3 cluster endpoint URLs

Bootstrapping

If a PostgreSQL database is not initialized on the node when Patroni starts, use the information in this section to initialize a database instance. If there is an already configured PostgreSQL database on the node, the contents of this section or any changes you add will not be reflected in Patroni.

The contents of the sub-item bootstrap.dcs initialize the Patroni cluster and are the values that will be stored in the DCS as Global Dynamic Configuration.

  • bootstrap.dcs: When When initializing with Patroni cluster preferences, this is the Global Dynamic Configuration set stored in /<namespace>/<scope>/config in DCS.

  • bootstrap.initdb: If you set initdb (default) as the database initialization method, this is an array of parameters to pass to initdb when it is run.

PostgreSQL

Defines system parameters, default users, host-based authentication rules, database parameters, and other settings for the PostgreSQL database.

The key in the Global Dynamic Configuration is the same as the one specified by postgresql. If the same key is defined twice in this file and in the Global Dynamic Configuration, the value defined in this file (i.e., the Local Configuration File) takes precedence.

  • postgresql.listen: Enter the address for the PostgreSQL server to be run by Patroni on this node to listen to in the form of <IP address>:<Port number> .

  • postgresql.connect_address: Enter the connection URL of PostgreSQL to be referenced by other nodes or client applications. This is the value returned when retrieving cluster information and DSN.

  • postgresql.proxy_address: If you have a proxy server to access the PostgreSQL server, you can enter the URL of that proxy server for service discovery as needed, and this value is stored with the cluster information in DCS.

  • postgresql.data_dir: The data path to the PostgreSQL server. The user running the Patroni process must have access to this path. If this path is empty, the Patroni process will run with the initdb behavior.

  • postgresql.bin_dir: Specifies the path where the PostgreSQL executable binaries pg_ctl, initdb, postgres, etc. are located.

  • postgresql.config_dir: Path to the directory to hold the PostgreSQL configuration file

    postgresql.conf. The default value is the same as the data_dir value.

  • postgresql.pg_hba: Enter items to write to the pg_hba.conf file (PostgreSQL's default host-based authentication settings) that Patroni will create. This entry is ignored if the PostgreSQL parameter hba_file is set to a custom value.

  • postgresql.parameters: PostgreSQL database parameters. They are entered in key-value format a n d are used when generating the postgresql.conf file.


Usage

patronictl does not store any configuration settings and must be given a DCS connection URL or Patroni connection URL to get information about the cluster on each run.

Use the Configuration .yml file that you used to configure the cluster as an argument as shown below.

You can also register with a Linux alias as shown below.

Check Cluster Information

Displays the configuration nodes in the cluster, as well as the connection and status information for each node.

Topology Output

DSN Output

Outputs the DSN (Data Source Name) of the cluster node. If no separate option is specified, outputs the connection information for the leader node.

You can also print access information for members with specific roles, or you can print access information for specific members by name.

Restart

Restart the PostgreSQL process on one of the member nodes of the cluster. The cluster name (set in the meta information) must be given as an argument, with the name of the member node as an optional extra. If no member name is specified, all nodes are restarted once.

Provides an interactive prompt to enter a restart date and time (with the option to restart immediately and the ability to schedule a restart by specifying a timestamp), and the ability to filter by checking the version of the PostgreSQL server to restart.

Reloading

This function reloads the configuration without restarting the PostgreSQL server on one of the member nodes of the cluster. The cluster name must be given as an argument, with the name of the member node as an option.

Confirm whether you want to schedule a cluster member reload through an interactive prompt.

PostgreSQL variables (GUC) with Context values of internal and postmaster cannot be changed by the Reloading feature. The internal variable is determined when compiling the server program or when initializing the database with the initdb command and cannot be changed without reinstalling the database, and the postmaster variable can only be changed by restarting the PostgreSQL process.

View History

View the history of Failover and Switchover that occurred in the cluster.

Query

You can run a database query against a PostgreSQL node with a specific role to see the results.

Failover

If there is no Leader node due to a failure in the cluster, you can manually run a failover.

You can also perform a manual failover with the patronictl failover command in a healthy cluster. However, if you want to change the Leader instance in a healthy cluster, we recommend using the patronictl switchover command.

Switchover

This action converts the PostgreSQL/Patroni Leader node to a Replica and promotes one of the other Replica nodes to Leader.

Pause / Resume

Stops the automatic failover feature of the Patroni cluster and puts the cluster into Maintenance Mode.

Exit maintenance mode with the Resume command and re-enable the automatic failover feature of the cluster.

Check Configuration

You can view the DCS to see the configuration currently applied to your Patroni cluster.

Modify Configuration

You can modify the Dynamic Configuration values of your Patroni cluster stored in DCS.

You can run a text editor or vi specified by the local user's EDITOR environment variable as a subprocess to modify and save the configuration in TTY format.

Last updated