shardmanctl
Prev Up3.3. Shardman Command ReferenceHome Next

shardmanctl

shardmanctl — Shardman auxiliary command-line client

Synopsis

shardmanctl [common_options] forall --sql query [ --twophase ]

shardmanctl [common_options] getconnstr [--direct-masters]

shardmanctl [common_options] rebalance

shardmanctl [common_options] rebalance_cleanup

shardmanctl [common_options] update [[ -f | --file stolon_spec_file] | spec_text [ -p | --patch ] [ -w | --wait ]]

Here common_options are:

[--cluster-name cluster_name] [--log-level error | warn | info | debug ] [--retries retries_number] [--session-timeout seconds] [--store-endpoints store_endpoints] [--store-ca-file store_ca_file] [--store-cert-file store_cert_file] [--store-key client_private_key] [--store-timeout duration] [--version] [ -h | --help ]

Description

shardmanctl is an auxiliary utility for managing a Shardman cluster.

The forall command is used to execute an SQL statement on all replication groups in a Shardman cluster.

The getconnstr command is used to get the libpq connection string for connecting to a cluster as administrator.

The rebalance command is used to evenly rebalance sharded tables in a cluster. This can be useful, for example, if you did not perform rebalance when adding nodes to the cluster.

The rebalance_cleanup command is used to perform cleanup after failure of a rebalance command. On each node, it cleans up subscriptions and publications left from the rebalance command and drops tables that store data of partially-transferred partitions of sharded tables.

The update command is used to update the stolon configuration. The new configuration is applied to all replication groups and is saved in clusterdata, so that new replication groups are initialized with this configuration. Note that update can cause a DBMS restart.

Note

All the described shardmanctl commands take a global metadata lock.

Command-line Reference

This section describes shardmanctl commands. For Shardman common options used by the commands, see the section called “Common Options”.

forall

Syntax: 

shardmanctl [common_options] forall --sql query [--twophase]

Executes an SQL statement on all replication groups in a Shardman cluster

--sql query

Specifies the statement to be executed

--twophase

Use the two-phase-commit protocol to execute the statement

getconnstr

Syntax: 

shardmanctl [common_options] getconnstr [--direct-masters]

Gets the libpq connection string for connecting to a cluster as administrator.

--direct-masters

Return the connection string that refers to master servers directly. If the ClusterSpec.UseProxy configuration parameter is true, by default, the connection string returned refers to proxies.

rebalance

Syntax: 

shardmanctl [common_options] rebalance

Rebalances sharded tables.

rebalance_cleanup

Syntax: 

shardmanctl [common_options] rebalance_cleanup

Performs cleanup after failure of a rebalance command.

update

Syntax: 

shardmanctl [common_options] update [[-f|--file stolon_spec_file]|spec_text [-p|--patch][-w|--wait]]

Updates the stolon configuration.

-f stolon_spec_file
--specfile=stolon_spec_file

Specifies the file with the stolon configuration. The value of “-” means the standard input. By default, the configuration is passed in spec_text.

-w
--wait

Specifies that shardmanctl should wait for configuration changes to take effect. If new configuration can not be loaded by all replication groups, shardmanctl will wait forever.

-p
--patch

Merge the new configuration into the existing one. By default, the new configuration replaces the existing one.

Common Options

shardmanctl common options are optional parameters that are not specific to the utility. They specify etcd connection settings, cluster name and a few more settings. By default shardmanctl tries to connect to the etcd store 127.0.0.1:2379 and use the cluster0 cluster name. The default log level is info.

-h, --help

Show brief usage information

--cluster-name cluster_name

Specifies the name for a cluster to operate on. The default is cluster0.

--log-level level

Specifies the log verbosity. Possible values of level are (from minimum to maximum): error, warn, info and debug. The default is info.

--retries number

Specifies how many times shardman-ladle retries a failing etcd request. If an etcd request fails, most likely, due to a connectivity issue, shardman-ladle retries it the specified number of times before reporting an error. The default is 5.

--session-timeout seconds

Specifies the session timeout for shardman-ladle locks. If there is no connectivity between shardman-ladle and the etcd store for the specified number of seconds, the lock is released. The default is 30.

--store-endpoints string

Specifies the etcd address in the format: http[s]://address[:port](,http[s]://address[:port])*. The default is http://127.0.0.1:2379.

--store-ca-file string

Verify the certificate of the HTTPS-enabled etcd store server using this CA bundle

--store-cert-file string

Specifies the certificate file for client identification by the etcd store

--store-key string

Specifies the private key file for client identification by the etcd store

--store-timeout duration

Specifies the timeout for a etcd request. The default is 5 seconds.

--version

Show shardman-utils version information

Environment

SDM_CLUSTER_NAME

An alternative to setting the --cluster-name option

SDM_FILE

An alternative to setting the --file option for update

SDM_LOG_LEVEL

An alternative to setting the --log-level option

SDM_RETRIES

An alternative to setting the --retries option

SDM_STORE_ENDPOINTS

An alternative to setting the --store-endpoints option

SDM_STORE_CA_FILE

An alternative to setting the --store-ca-file option

SDM_STORE_CERT_FILE

An alternative to setting the --store-cert-file option

SDM_STORE_KEY

An alternative to setting the --store-key option

SDM_STORE_TIMEOUT

An alternative to setting the --store-timeout option

SDM_SESSION_TIMEOUT

An alternative to setting the --session-timeout option

Examples

Getting the Cluster Connection String

To get the connection string for a Shardman cluster that has the cluster0 name, uses an etcd cluster consisting of n1,n2 and n3 nodes listening on port 2379, run: 

 $ shardmanctl --store-endpoints http://n1:2379,http://n2:2379,http://n3:2379 getconnstr
 
 dbname=postgres host=n1,n4,n2,n1,n1,n2,n4,n3 password=yourpasswordhere port=5432,5433,5432,5433,5432,5433,5432,5433 user=postgres

Executing a Query on All Replication Groups

To execute the “select version()” query on all replication groups, run: 

 $ shardmanctl --store-endpoints http://n1:2379,http://n2:2379,http://n3:2379 forall --sql 'select version()'
 
 Node 1 says:
 [PostgreSQL 13.1 on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 9.3.0-17ubuntu1~20.04) 9.3.0, 64-bit]
 Node 4 says:
 [PostgreSQL 13.1 on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 9.3.0-17ubuntu1~20.04) 9.3.0, 64-bit]
 Node 3 says:
 [PostgreSQL 13.1 on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 9.3.0-17ubuntu1~20.04) 9.3.0, 64-bit]
 Node 2 says:
 [PostgreSQL 13.1 on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 9.3.0-17ubuntu1~20.04) 9.3.0, 64-bit]

Performing Rebalance

To rebalance sharded tables in the cluster0 cluster, run: 

 $ shardmanctl --store-endpoints http://n1:2379,http://n2:2379,http://n3:2379 rebalance

Updating PostgreSQL Configuration Settings

To set the max_connections parameter to 200 in the cluster, create the spec file (for instance, ~/stolon.json) with the following contents: 

 {
   "pgParameters": {
     "max_connections": "200"
   }
 }

Then run: 

 $ shardmanctl --store-endpoints http://n1:2379,http://n2:2379,http://n3:2379 update -p -f ~/stolon.json

Since changing max_connections requires a restart, DBMS instances are restarted by this command.

See Also

shardman-ladle, sdmspec.json
Prev Up Next
shardman-ladle Home sdmspec.json