HomeMogDBMogDB StackUqbar
Ecological Tools
Doc Tools
中文
v5.0

Documentation:v5.0

Supported Versions:
Current(v5.0)

Other Versions:
v3.1/
v3.0/
v2.1/
v2.0/
v1.1

cm_ctl

cm_ctl is a tool provided by MogDB to control database instance services. This tool is called by O&M personnel for automatic database instance service restoration. cm_ctl provides the following functions:

  • Starts database instance services, all the instances in an AZ, all instances on a single host, or a single instance process.
  • Stops database instance services, all instances in an AZ, all instances on a single host, or instance processes on a single node.
  • Restarts the logical database instance service.
  • Queries the database instance status or the status of a single host.
  • Switches over the primary and standby instances or resets the instance status.
  • Rebuilds the standby node.
  • Views the database instance configuration file.
  • Sets the log level, the arbitration mode of cm_server when one primary and multiple standby database instances are deployed, and the switchover mode between AZs.
  • Obtains the log level, the arbitration mode of cm_server when one primary and multiple standby database instances are deployed, and the switchover mode between AZs.
  • Checks the status of an instance process.

Files related to the cm_ctl tool:

  • cluster_manual_start

    This is a flag file for starting and stopping a database instance. The file is stored in $GAUSSHOME/bin, where GAUSSHOME is an environment variable. When the database instance is started, the cm_ctl tool deletes the file. When the database instance is stopped, the cm_ctl tool generates the file and writes the stop mode to the file.

  • instance_manual_start_X (X indicates the instance ID.)

    This is a flag file of starting and stopping a single instance. The file is stored in $GAUSSHOME/bin, where GAUSSHOME is an environment variable. When starting the instance, cm_ctl deletes the file. When stopping the instance, cm_ctl generates the file and writes the stop mode to the file.

cm_ctl constraints:

  • In cluster mode, the cm_ctl tool instead of the gs_ctl tool is used to switch the database role.

Command Description

cm_ctl uses the following options:

Usage:

cm_ctl start [-z AVAILABILITY_ZONE [--cm_arbitration_mode=ARBITRATION_MODE]] | [-n NODEID [-D DATADIR]] [-t SECS]
cm_ctl switchover [-z AVAILABILITY_ZONE] | [-n NODEID -D DATADIR [-f]] | [-a] | [-A] [-t SECS]
cm_ctl finishredo
cm_ctl build [-c] [-n NODEID] [-D DATADIR [-t SECS] [-f] [-b full] [-j NUM]]
cm_ctl check -B BINNAME -T DATAPATH
cm_ctl stop [[-z AVAILABILITY_ZONE] | [-n NODEID [-D DATADIR]]] [-t SECS] [-m SHUTDOWN-MODE]
cm_ctl query [-z ALL] [-l FILENAME] [-v [-C [-s] [-S] [-d] [-i] [-F] [-x] [-p]] | [-r]] [-t SECS] [--minorityAz=AZ_NAME]
cm_ctl view [-v | -N | -n NODEID] [-l FILENAME]
cm_ctl set [--log_level=LOG_LEVEL] [--cm_arbitration_mode=ARBITRATION_MODE] [--cm_switchover_az_mode=SWITCHOVER_AZ_MODE] [--cmsPromoteMode=CMS_PROMOTE_MODE -I INSTANCEID]
cm_ctl set --param --agent | --server [-n [NODEID]] -k [PARAMETER]="[value]"
cm_ctl get [--log_level] [--cm_arbitration_mode] [--cm_switchover_az_mode]
cm_ctl setrunmode -n NODEID -D DATADIR  [[--xmode=normal] | [--xmode=minority --votenum=NUM]]
cm_ctl changerole [--role=PASSIVE | --role=FOLLOWER] -n NODEID -D DATADIR [-t SECS]
cm_ctl changemember [--role=PASSIVE | --role=FOLLOWER] [--group=xx] [--priority=xx] -n NODEID -D DATADIR [-t SECS]
cm_ctl reload --param [--agent | --server]
cm_ctl list --param --agent | --server
cm_ctl encrypt [-M MODE] -D DATADIR
cm_ctl ddb DCC_CMD
cm_ctl switch [--ddb_type=[DDB]] [--commit] [--rollback]

Table 1 Commands of options

Command Description
start Starts the database instance service, all instances on a single host, instance processes on a single node, or the entire AZ when one primary database and multiple standby databases are deployed.
switchover Switches over the primary and standby database instances when one primary database and multiple standby databases are deployed. In DCF mode, the -n NODEID and -D DATADIR parameters are not supported.
finishredo Stops the playback on all standby nodes, and forcibly promotes one of the shards to primary.Note:Setting this parameter is a high-risk operation. Exercise caution when performing this operation.
build Rebuilds a standby instance.
check Checks the running status of an instance process. You are not advised to use this one.
stop Stops the database instance service, all instances on a single host, or the instance processes on a single node when one primary database and multiple standby databases are deployed.
query Queries the database instance status or the status of a single host when one primary database and multiple standby databases are deployed.
view Views the database instance configuration file.
set Sets the log level, the arbitration mode of cm_server when one primary database and multiple standby databases are deployed, the switchover mode between AZs, and the promotion mode to primary of cm_server.
set --param Sets CM parameters. By default, parameters on all nodes are set. You can also use the -n option to set parameters on a node. For details about the parameters, see CM Parameters.
get Obtains the log level, the arbitration mode of cm_server when one primary database and multiple standby databases are deployed, and the switchover mode between AZs.
setrunmode Sets the number of DCF votes in DCF deployment mode. This is used for forcible DCF startup.
changerole Changes the primary role to passive or follower in the DCF mode.
changemember Changes the attributes of a DCF node in DCF mode, including the role, logical group, and election priority of the node.
reload Loads the static configuration file of a database instance online. You are not advised to use this one.
reload --param Loads CM parameters that can take effect dynamically. Some parameters cannot be reloaded and can take effect only after the CM is restarted.
list Lists all parameters of cm_agent or cm_server.
encrypt Encrypts an entered password. The password can contain 8 to 15 characters and must contain at least three types of the following characters: digits, letters, and symbols.
ddb Runs the DCC command in DCC mode.
switch Switches to the DDB mode.Note:Currently, MogDB can be switched only to the DCC mode.

Table 2 Common options

Option Description
-D DATADIR Specifies the instance data directory. This is used only to perform operations on database nodes, such as start, stop, switchover, build, setrunmode, changerole, changemember and encrypt.
-l FILENAME Outputs the result to a specified file. This is used only for query, such as query and view.
-n NODEID Specifies a node.
-z AVAILABILITY_ZONE Specifies the AZ name.
-t SECS Specifies the timeout period.
-V, --version Prints the cm_ctl version and exits.
-?, -h,--help Displays help information about cm_ctl command-line options and exits.

img NOTE:

  • The common options listed here may not be applicable to all commands. For details about how to use the common options, see the preceding description. You can also run the cm_ctl –help command to query the common options.

Table 3 Options of switchover

Option Description
-a Restores nodes to their initial status.
Note:
Switchover is performed for maintenance. Before a switchover, ensure that the cluster is running properly, all services are stopped, and the pgxc_get_senders_catchup_time() view shows no ongoing catchup between the primary and standby nodes.
-A Switches all node instances from primary to standby.
-f Specifies a type of switchover.
Note:
- Switchover is performed for maintenance. Before a switchover, ensure that the cluster is running properly, all services are stopped, and the pgxc_get_senders_catchup_time() view shows no ongoing catchup between the primary and standby nodes.
- Usage: cm_ctl switchover -n NODEID -D DATADIR -f.

Table 4 Options of build

Option Description
-f Forcibly rebuilds a standby node.
-b full Performs a full build. If this parameter is not specified, automatic build is performed for the deployment mode of one primary database instance and multiple standby database instances. auto build: calls the incremental build first and calls the full build after the incremental build fails.
-c Rebuilds cm_server (by copying the DCC data directory on the primary node to the specified node. This method is applicable only to the scenario where there are one primary node and one standby node.)

Table 5 Options of check

Option Description
-B BINNAME Specifies the name of a process, which can be cm_agent, gaussdb, or cm_server.
-T DATAPATH Specifies the instance data directory.

Table 6 Options of stop

Option Description
-m SHUTDOWN-MODE Specifies the stop mode. The values are as follows:
- smart (s): All database instances exit after user services end.
- fast (f): The specified database instance exits without waiting for the user service to end.
- immediate (i): The specified database instance is forced to exit without waiting for the user service to end.

Table 7 Options of query

Option Description
-s Displays instances that result in unbalanced primary and standby instance quantity on each host.
Note:
The -s option must be used together with -v and -C so that instances that result in unbalanced primary and standby instance quantity on each host can be displayed in pairs. When -s is used, -C and -v must be specified.
-C Displays the database instance status in pairs based on the primary and standby relationship.
Note:
The -C option must be used together with -v to display detailed database instance status information in pairs based on the primary and standby relationship. When -C is used, -v must be specified.
-v Displays the detailed database instance status.
Note:
A database instance can be in any of the following states:
- Normal: indicates that the database instance is available and data is backed up. All the processes are running and the primary-standby relationship is normal.
- Degraded: The database instance is available, but data is not backed up.
- Degraded: The database instance is unavailable.
-d Displays the instance data directory.
Note:
The -d option must be used together with -v and -C.
-i Displays the IP address of the physical node.
Note:
The -i option must be used together with -v and -C.
-F Displays the Fenced UDF status of each node.
Note:
The -F option must be used together with -v and -C to display the fenced UDF status of each node. When -F is used, -C and -v must be specified.
-z ALL Displays the name of the AZ where the database instance is located.
Note:
The -z option must be used together with -v and -C, and must be followed by ALL.
-r Displays the redo status of the standby node.
Note:
When -r is used, the -v must be specified.
-g Displays information about cluster backup and restoration.
-x Displays all abnormal database instances.
Note:
The -x option must be used together with -v and -C.
-S Displays the status check result when the database instance is started.
Note:
The -S option must be used together with -v and -C to display the database instance status check result. The values are as follows:
- Normal: The database instance is available and data is backed up. All the processes are running and the primary-standby relationship is normal.
- Degraded: The database instance is available, but data is not backed up.
- Degraded: The database instance is unavailable.
--minorityAz Queries the CMS in a specified AZ.
Description:
This ignores the CMS nodes in non-specified AZs and can improve the query speed in few scenarios.
-p Displays the ports of all database instance nodes.
Note:
The -p option must be used together with -v and -C.

Table 8 Options of set

Option Description
--log_level=LOG_LEVEL Sets the log level of the primary cm_server. Six log levels are included: DEBUG5, DEBUG1, WARNING, LOG, ERROR, and FATAL, in an ascending order in terms of log print level. The higher the log level, the less the output log information.
--cm_arbitration_mode=ARBITRATION_MODE Sets the arbitration mode of cm_server when one primary node and multiple standby nodes are deployed. There are two modes: MAJORITY and MINORITY. MAJORITY indicates the majority mode, and MINORITY indicates the minority mode. MogDB does not support the MINORITY mode. This parameter can be set to MINORITY but it does not take effect.
--cm_switchover_az_mode=SWITCHOVER_AZ_MODE Specifies whether to enable automatic switchover between AZs when one primary node and multiple standby nodes are deployed. There are two modes: NON_AUTO and AUTO. NON_AUTO indicates the non-automatic switchover mode, and AUTO indicates the automatic switchover mode. In AUTO mode, the primary cm_server automatically controls the node instance switchover between AZ1 and AZ2.
--cmsPromoteMode=CMS_PROMOTE_MODE -I INSTANCEID Sets the promotion mode to primary of cm_server. There are two modes: AUTO and PRIMARY_F. AUTO indicates that the promotion mode to primary is automatically selected. PRIMARY_F indicates that the node specified by -I is forcibly promoted to primary, regardless of whether there is a primary node. Therefore, multiple primary cm_server may exist.

Table 9 Options of set cm

Option Description
--param Specifies the CM parameters to be set. If this option is not specified, the CM parameters cannot be set.
--agent | --server Specifies whether to set the cm_server or cm_agent parameters. This option is mandatory.
-k parameter="value" Specifies the parameters and parameter values to be set. Only existing parameters can be set. Parameters cannot be added or deleted.

Table 10 Options of get

Option Description
--log_level=LOG_LEVEL Obtains the log level of the primary cm_server. Six log levels are included: DEBUG5, DEBUG1, WARNING, LOG, ERROR, and FATAL, in an ascending order in terms of log print level. The higher the log level, the less the output log information.
--cm_arbitration_mode=ARBITRATION_MODE Obtains the arbitration mode of cm_server when one primary node and multiple standby nodes are deployed. There are two modes: MAJORITY and MINORITY. MAJORITY indicates the majority mode, and MINORITY indicates the minority mode. The MINORITY mode is applicable to the scenario where one primary database and multiple standby databases are deployed and only AZ3 is alive. In this case, cm_server can perform arbitration properly. In other modes, after the arbitration mode is set to MINORITY, the CM automatically changes the arbitration mode to MAJORITY to ensure the normal running of the cluster. The MAJORITY mode is applicable to the scenario where one primary database and multiple standby databases are deployed and the number of alive components (cm_server and nodes) is greater than half of the total. In normal cases, the database instance is in MAJORITY mode by default.
Note:
MogDB does not support the MINORITY mode.
--cm_switchover_az_mode=SWITCHOVER_AZ_MODE Obtains the automatic switchover between AZs when one primary node and multiple standby nodes are deployed. There are two modes: NON_AUTO and AUTO. NON_AUTO indicates the non-automatic switchover mode, and AUTO indicates the automatic switchover mode. In AUTO mode, the primary cm_server automatically controls the node instance switchover between AZ1 and AZ2.

Table 11 Options of view

Option Description
-v Displays the static configuration details of all nodes in the database instance.
Description:
Compared with the cm_ctl view command, cm-server and node component IDs (for example, cmseverInstanceID and datanodeInstanceID) are added to the output of -v.
-N Displays only the static configuration of the local node, that is, information about the node where the cm_ctl view command is executed. N indicates native.

Table 12 Options of setrunmode

Option Description Value Range
--xmode Specifies the DCF running mode. - normal: normal mode.
- minority: minority mode. The --votenum option is required to specify the number of votes.
--votenum Specifies the number of votes for a DCF minority run. The value is a positive integer and cannot be greater than the total number of DCF copies.

Table 13 Options of changerole

Option Description Value Range
--role Changes the primary role to passive or follower in the DCF mode. - passive: passive role
- follower: follower role

Table 14 Options of changemember

Option Description Value Range
--role Changes the primary role to passive or follower in the DCF mode. - passive: passive role
- follower: follower role
--group Changes the value of group in DCF mode. 0~2147483647
--priority Changes the value of priority in DCF mode. 0~2147483647

Table 15 Options of start

Option Description
--cm_arbitration_mode=ARBITRATION_MODE Obtains the arbitration mode of cm_server when one primary node and multiple standby nodes are deployed. There are two modes: MAJORITY and MINORITY. MAJORITY indicates the majority mode, and MINORITY indicates the minority mode. The MINORITY mode is applicable to the scenario where one primary database and multiple standby databases are deployed and only AZ3 is alive. In this case, cm_server can perform arbitration properly. In other modes, after the arbitration mode is set to MINORITY, the CM automatically changes the arbitration mode to MAJORITY to ensure the normal running of the cluster. The MAJORITY mode is applicable to the scenario where one primary database and multiple standby databases are deployed and the number of alive components (cm_server and nodes) is greater than half of the total. In normal cases, the database instance is in MAJORITY mode by default.
Note:
MogDB does not support the MINORITY mode.

Table 16 Options of reload

Option Description
--param Specifies the CM parameters to be loaded. If this parameter is not specified, the CM parameters cannot be loaded.
--agent | --server Specifies whether to dynamically load cm_server or cm_agent parameters.

Table 17 Options of list

Option Description
--param Specifies the CM parameters to be listed. This is mandatory.
--agent | --server Specifies the cm_server or cm_agent parameters to be listed. This is mandatory.

Table 18 Options of encrypt

Option Description
-M Specifies the encryption type. The value can be server or client. The default value is server.
-D Specifies the path of the encrypted password file.

Table 19 Options of switch

Option Description
--ddb_type=[DDB] Select the DDB mode to be switched to. (MogDB supports only the DCC mode.)
--commit After the switchover, the database instance cannot be promoted to primary. You need to run the commit command to restore the database instance.
--rollback Rolls back the switchover that fails.

Table 20 Options of ddb

Option Description
--put [key] [value] Inserts a key-value pair to DCC. If the key-value pair already exists, the value corresponding to the key is changed.
--get [key] Queries the value corresponding to the key in DCC.
--delete [key] Deletes a specified key-value pair from DCC.
--prefix You can add the prefix option after the get or delete operation to implement fuzzy query and deletion.
--cluster_info Obtains the database instance information.
--leader_info Obtains information about the primary node.
--help, -h Displays the DCC command help information.
--version, -v Displays the DCC version information.

Command Reference

  • Start an instance.

    cm_ctl start [-z AVAILABILITY_ZONE [--cm_arbitration_mode=ARBITRATION_MODE]] | [-n NODEID [-D DATADIR]] [-t SECS]

  • Perform a switchover between primary and standby databases.

    cm_ctl switchover [-z AVAILABILITY_ZONE] | [-n NODEID -D DATADIR [-f]] | [-a] | [-A] [-t SECS]

  • Stop the playback on all standby nodes, and forcibly promote one of the shards to primary.

    cm_ctl finishredo

  • Rebuild the standby node.

    cm_ctl build -n NODEID -D DATADIR [-t SECS] [-f] [-b full]

  • Check the running status of an instance process.

    cm_ctl check -B BINNAME -T DATAPATH

  • Stop an instance.

    cm_ctl stop [[-z AVAILABILITY_ZONE] | [-n NODEID [-D DATADIR [-R]]]] [-t SECS] [-m SHUTDOWN-MODE]

  • Query the cluster status.

    cm_ctl query [-z ALL] [-l FILENAME] [-v [-C [-s] [-S] [-d] [-i] [-F] [-x] [-p]] | [-r]] [-t SECS] [--minorityAz=AZ_NAME]

  • View the cluster configuration file.

    cm_ctl view [-v | -N | -n NODEID] [-l FILENAME]

  • Set parameters.

    cm_ctl set [--log_level=LOG_LEVEL] [--cm_arbitration_mode=ARBITRATION_MODE] [--cm_switchover_az_mode=SWITCHOVER_AZ_MODE]

  • Set CM parameters.

    cm_ctl set --param --agent | --server [-n NODEID] -k PARAMETER="'value'"

  • Obtain parameters.

    cm_ctl get [--log_level] [--cm_arbitration_mode] [--cm_switchover_az_mode]

  • Set the number of DCF votes.

    cm_ctl setrunmode -n NODEID -D DATADIR  [[--xmode=normal] | [--xmode=minority --votenum=NUM]]

  • Change the DCF role information.

    cm_ctl changerole [--role=PASSIVE | --role=FOLLOWER] -n NODEID -D DATADIR [-t SECS]

  • Change the attributes of the DCF node.

    cm_ctl changemember [--role=PASSIVE | --role=FOLLOWER] [--group=xx] [--priority=xx] -n NODEID -D DATADIR [-t SECS]

  • Dynamically load CM parameters.

    cm_ctl reload --param [--agent | --server]

  • List all CM parameters.

    cm_ctl list --param [--agent | --server]

  • Perform encryption.

    cm_ctl encrypt [-M MODE] -D DATADIR

  • Run the DCC command.

    cm_ctl ddb DCC_CMD
Set: cm\_ctl ddb --put [key] [value]
Delete: cm\_ctl ddb --delete [key]
View DCC command help information: cm\_ctl ddb --help

  • Run the switch ddb command.

    cm_ctl switch [--ddb_type=[DDB]] [--commit] [--rollback]
HOME

Issue
Copyright © 2011-2024 www.enmotech.com All rights reserved.