How to use the command 'stolonctl' (with examples)
Stolonctl is a command-line interface for Stolon, a cloud-native PostgreSQL manager for PostgreSQL high availability. It allows users to interact with Stolon and perform various operations on the Postgres clusters managed by Stolon. In this article, we will explore some common use cases of the ‘stolonctl’ command along with examples.
Use case 1: Get cluster status
Code:
stolonctl --cluster-name cluster_name --store-backend store_backend --store-endpoints store_endpoints status
Motivation:
Getting the cluster status is important to check the health and availability of the PostgreSQL cluster. It provides valuable information such as the current leader, standby nodes, and their respective states. Monitoring the cluster status helps in troubleshooting and ensuring high availability of the database.
Explanation:
--cluster-name
specifies the name of the Stolon cluster.--store-backend
defines the backend store type used by Stolon to store its metadata (like cluster data and specifications).--store-endpoints
specifies the endpoints of the store backend.
Example output:
Cluster status:
State: healthy
Current: leader=<node-1-ip:port>
Generations: <node-1-ip:port>=<generation>,<node-2-ip:port>=<generation>,...
Watches: <node-1-ip:port>=0
The output provides information about the current state of the cluster, including the current leader and the generations of each node.
Use case 2: Get cluster data
Code:
stolonctl --cluster-name cluster_name --store-backend store_backend --store-endpoints store_endpoints clusterdata
Motivation:
Retrieving the cluster data gives a comprehensive overview of the PostgreSQL cluster managed by Stolon. It includes information such as the cluster name, version, and important metadata about the primary and standby nodes. This information is useful for monitoring and management purposes.
Explanation:
The arguments --cluster-name
, --store-backend
, and --store-endpoints
have the same meanings as in the previous use case.
Example output:
Cluster data:
cluster-name: cluster_name
cluster-kind: postgresql
version: 13
...
nodes:
- pg-replica-0 : standby
- pg-replica-1 : standby
- pg-replica-2 : primary
The output displays detailed information about the cluster, including its name, kind, version, and the status of each node.
Use case 3: Get cluster specification
Code:
stolonctl --cluster-name cluster_name --store-backend store_backend --store-endpoints store_endpoints spec
Motivation:
Obtaining the cluster specification helps in understanding the configuration and parameters used by Stolon for managing the PostgreSQL cluster. It includes details such as the PostgreSQL version, replication mode, and various tuning parameters. This information is crucial for troubleshooting and making changes to the cluster configuration.
Explanation:
The arguments --cluster-name
, --store-backend
, and --store-endpoints
have the same meanings as in the previous use cases.
Example output:
Cluster specification:
postgresql:
version: 13
replication-mode: async
synchronous-mode: off
...
The output provides the cluster specification, including the replication mode, synchronous mode, and other relevant configuration parameters for the PostgreSQL cluster.
Use case 4: Update cluster specification with a patch in JSON format
Code:
stolonctl --cluster-name cluster_name --store-backend store_backend --store-endpoints store_endpoints update --patch 'cluster_spec'
Motivation:
Updating the cluster specification allows users to modify the configuration and behavior of the PostgreSQL cluster managed by Stolon. By providing a patch in JSON format, users can change specific settings such as replication modes, tuning parameters, or even PostgreSQL versions.
Explanation:
The arguments --cluster-name
, --store-backend
, and --store-endpoints
have the same meanings as in the previous use cases. The --patch
argument specifies the JSON patch that describes the modifications to be made.
Example output:
Cluster specification updated successfully.
The output confirms that the cluster specification was successfully updated.
Conclusion:
In this article, we explored various use cases of the ‘stolonctl’ command, which is a CLI for managing PostgreSQL high availability clusters using Stolon. We covered the commands for getting cluster status, cluster data, cluster specification, and updating the cluster specification. These use cases are essential for monitoring, managing, and making changes to PostgreSQL clusters managed by Stolon.