stolonctl

Get cluster status

$ stolonctl --cluster-name [cluster_name] --store-backend [store_backend] --store-endpoints [store_endpoints] status

$ stolonctl --cluster-name [cluster_name] --store-backend [store_backend] --store-endpoints [store_endpoints] clusterdata

$ stolonctl --cluster-name [cluster_name] --store-backend [store_backend] --store-endpoints [store_endpoints] spec

$ stolonctl --cluster-name [cluster_name] --store-backend [store_backend] --store-endpoints [store_endpoints] update --patch '[cluster_spec]'

stolonctl [global-options] <command> [command-options]

Common global options include:
--cluster-name <name>: Specifies the name of the Stolon cluster.
--store-backend <backend>: Defines the backend for the consensus store (e.g., etcdv3, consul, zoov3, kubernetes).
--store-endpoints <endpoints>: A comma-separated list of store endpoints.
--store-prefix <prefix>: The prefix to use in the store for Stolon's data.

status
    Displays the current status and topology of the Stolon cluster, including master, replicas, and their health.

init
    Initializes a new Stolon cluster by writing its initial specification to the consensus store.

clusterdata
    Manages the cluster data in the consensus store. Subcommands include get, set, and remove.

update
    Updates the cluster specification for a running Stolon cluster. This can include changing parameters like PostgreSQL version, standby settings, or resource limits.

forcefailover
    Forces a failover to a specified PostgreSQL instance (keeper). This command is used for manual intervention or testing.

version
    Shows the stolonctl client version and build information.

completion
    Generates shell completion scripts for various shells like bash, zsh, fish, and powershell.

stolonctl is the command-line interface client for Stolon, a cloud-native PostgreSQL high availability and disaster recovery manager. It allows administrators to interact with and manage Stolon-controlled PostgreSQL clusters. Through stolonctl, users can inspect the cluster's current status, initialize new clusters, update cluster configurations, force failovers, and directly manipulate the cluster's state within the configured consensus store (e.g., etcd, Consul, ZooKeeper, or Kubernetes ConfigMap). It provides a unified way to observe the health and topology of the PostgreSQL instances managed by Stolon's sentinels and keepers, facilitating operational tasks for resilient PostgreSQL deployments. Its design emphasizes automation and integration with container orchestration platforms.

stolonctl relies on the Stolon cluster being properly configured and accessible to the specified consensus store. Direct manipulation of cluster data via clusterdata set should be done with extreme caution, as incorrect changes can disrupt the cluster's operation. It's primarily an operational tool for Stolon and not a general PostgreSQL client like psql.

stolonctl interacts with a Stolon cluster which typically consists of three main components: sentinels (monitor and elect masters), keepers (manage PostgreSQL instances), and a consensus store (holds cluster state). stolonctl communicates directly with the consensus store to read and write cluster information or with the Stolon API (if exposed) to trigger actions.

Many stolonctl commands are designed to be idempotent, meaning they can be run multiple times without causing unintended side effects, which is beneficial for automation and scripting purposes in cloud environments.

Stolon was initiated by Sorint.Lab to provide a robust, cloud-native high availability solution for PostgreSQL. stolonctl was developed as an integral part of the Stolon project from its early stages, serving as the primary command-line interface for administrators to interact with the Stolon cluster and its underlying consensus store. It has evolved alongside the Stolon project, adapting to new features and improvements in Stolon's architecture and capabilities.

psql(1), pg_basebackup(1), repmgr, patroni, etcdctl