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.