GaussDB-cm_ctl工具介绍

GaussDB-cm_ctl工具介绍

功能介绍

cm_ctl是GaussDB提供的用来控制数据库实例服务的工具。该工具主要供OM调用，及数据库实例服务自恢复时使用。

cm_ctl的主要功能有：
  • 启动数据库实例服务、AZ的所有实例、单个主机上的所有实例或单独启动某个实例进程。
  • 停止数据库实例服务、AZ的所有实例、单个主机上的所有实例或单独停止某个DN实例进程。
  • 重启逻辑数据库实例服务。
  • 查询数据库实例状态或者单个主机的状态。
  • 切换主备实例或重置实例状态。
  • 重建备机。
  • 查看数据库实例配置文件。
  • 设置日志级别、一主多备数据库实例部署下cm_server的仲裁模式、AZ之间的切换模式。
  • 获取日志级别，一主多备数据库实例部署下cm_server的仲裁模式、AZ之间的切换模式。
  • 检测实例进程状态。
与cm_ctl工具相关的文件：
  • cluster_manual_start

    该文件是数据库实例启停标志文件。文件位于$GAUSSHOME/bin下。其中，GAUSSHOME为环境变量。启动数据库实例时，cm_ctl会删除该文件；停止数据库实例时，cm_ctl会生成该文件，并向文件写入停止模式。

  • instance_manual_start_X（X是实例编号）

    该文件是单个实例启停标志文件。文件位于$GAUSSHOME/bin下。其中，GAUSSHOME为环境变量。启动实例时，cm_ctl会删除该文件；停止实例时，cm_ctl会生成该文件，并向文件写入停止模式。

cm_ctl的相关约束：
  • 灾备数据库实例下使用build及switchover命令无法生效。
  • 一主一备一logger实例finishredo命令无法生效。
  • cm_ctl日志文件无法写入时，会将日志信息在终端屏幕输出。

命令说明

命令格式中常用的几个符号含义如下：

  • 尖括号 < >：必选参数，实际使用时应将其替换为所需要的参数。
  • 大括号 { }：必选参数，使用时只能选择括号内的参数。
  • 方括号 [ ]：可选参数，在命令中根据需要加以取舍。
  • 竖线 |：用于分隔多个互斥参数，含义为“或”，使用时只能选择一个。

cm_ctl命令的格式如下：

  • cm_ctl <模式参数> [option参数] [公共参数]
cm_ctl参数可分为如下几类：
表1 模式参数

参数

参数说明

start

一主多备、小型化数据库部署模式下启动数据库实例服务、单个主机上的所有实例或单独启动某个DN实例进程，或者直接启动整个AZ。

switchover

一主多备数据库部署模式下切换数据库主备实例、实现AZ之间的相互切换。

finishredo

所有备机停止回放，每个分片中选择一个强制升主。

注意：

该参数属于高风险操作，请谨慎执行。

build

重建备实例。

check

检测实例进程运行状态，用户无需关注，不建议使用。

stop

一主多备、小型化数据库部署模式下停止数据库实例服务、单个主机上的所有实例或单独停止某个DN实例进程。或者直接停止整个AZ。

query

一主多备、小型化数据库部署模式下查询数据库实例状态或者单个主机的状态。

view

查看数据库实例配置文件。

set

设置日志级别，一主多备数据库部署模式下cm_server的仲裁模式、AZ之间的切换模式。

set --param

设置cm参数，具体参数可以参见 CM配置参数介绍。

get

获取日志级别，一主多备数据库部署模式下cm_server的仲裁模式、AZ之间的切换模式。

hotpatch

对cm_server执行热补丁操作。

setrunmode

DCF部署方式下，设置DCF投票数，主要用于DCF强启。

changerole

DCF模式下，将角色为primary的修改为passive或者follower。

changemember

DCF模式下，改变指定DCF节点属性，包括节点角色、节点所在的逻辑组、节点的选举优先级等。

reload

在线加载数据库实例静态配置文件，用户无需关注，不建议使用。

reload --param

加载可以动态生效的cm参数，部分参数不支持reload，只能重启cm才能生效。

list --param

列出cm_agent或cm_server所有的参数。

encrypt

对输入的密码进行加密操作，密码支持8~15位，且必须包含三种字符（数字，字母，符号）。

ddb

执行对DCC组件的配置数据存取命令。CM依赖DCC组件对配置数据分布式存取，实现数据库实例配置管理高可用能力。

switch

执行ddb模式的切换。

注意：
  • ETCD模式切换到DCC模式之前需要参见 安全设计 手动生成证书，切换完成后，需要通过cm_ctl打开enable_ssl开关（修改enable_ssl参数）。
  • 如果有会涉及到ETCD的操作，例如节点替换，扩容，备份恢复等。在操作之前， 必须先确保切回到ETCD模式再执行相关操作。

res

在节点上进行资源配置的新增、修改、查询、删除。

show

展示数据库实例浮动ip。

res

执行自定义资源相关命令。

notify

执行通知cm消息的命令。

pull

从cms主获取最新的急诊室元数据文件

push

把本地急诊室元数据文件上传给cms主
表2 公共参数

参数

参数说明

-D <DATA_DIR>

指定实例数据目录。

-n <NODE_ID>

指定节点。

-t <SECS>

指定超时时间。超时后，会退出并报错。

-l <FILE_NAME>

结果输出到指定文件。

-z <AZ_NAME>

指定AZ名称。

-V, --version

打印cm_ctl版本信息，然后退出。

-?, -h,--help

显示关于cm_ctl命令行参数的帮助信息，然后退出。
表3 query参数

参数

参数说明

-v

显示详细数据库实例状态。

说明：

数据库实例有如下几种状态：

  • Normal：表示数据库实例可用，且数据有冗余备份。所有进程都在运行，主备关系正常。
  • Degraded：表示数据库实例可用，但数据没有冗余备份。
  • Unavailable：表示数据库实例不可用。

-C

按主备关系成对显示数据库实例状态。

说明：

-C参数需要和-v参数一起使用才能按主备关系成对显示数据库实例详细状态信息，使用-C时，必须指定-v参数。

-r

显示备机redo状态。

说明：

使用-r时，必须指定-v参数。

-s

显示导致各个节点主备实例数量不均衡的实例。

说明：

-s参数需要和-v以及-C参数一起使用才能按主备关系成对显示导致各个节点主备实例数量不均衡的实例，使用-s参数时，必须指定-C、-v参数。

-S

显示数据库实例启动时的状态检查结果。

说明：
-S参数需要和-v以及-C参数一起使用才能按显示数据库实例的状态检查结果。有以下三种状态：
  • Normal：表示数据库实例可用，且数据有冗余备份。所有进程都在运行，主备关系正常。
  • Degraded：表示数据库实例可用，但数据没有冗余备份。
  • Unavailable：表示数据库实例不可用。

-F

显示各个节点Fenced UDF状态。

说明：

-F参数需要和-v以及-C参数一起使用才能显示各个节点Fenced UDF状态，使用-F参数时，必须指定-C、-v参数。

-i

显示物理节点ip。

说明：

-i参数需要和-v以及-C参数一起使用。

-d

显示实例数据目录。

说明：

-d参数需要和-v以及-C参数一起使用。

-z ALL

显示数据库实例所有实例AZ名称。

说明：

-z参数需要和-v以及-C参数一起使用，并且-z后面需要跟参数ALL。

-x

显示数据库实例所有异常实例。

说明：

-x参数需要和-v以及-C参数一起使用。

-p

显示数据库实例所有DN端口。

说明：

-p参数需要和-v以及-C参数一起使用。

--minorityAz

只查询指定AZ的cms和etcd。

说明：

此参数会忽略非指定AZ的cms、etcd节点，可以在少数派场景提高查询速度。

-g

显示备份和恢复群集信息。
表4 stop参数

参数

参数说明

-m <SHUTDOWN_MODE>

指定停止模式，停止模式有以下几种：

  • smart（s）：等待用户业务结束后，停止所有数据库实例。
  • fast（f）：不等待用户业务结束，指定数据库实例退出。
  • immediate（i）：不等待用户业务结束，指定数据库实例强制退出。

-I

指定需要停止的资源实例号，可以通过cm_ctl query -Cv查看资源实例和实例号的映射关系。

--server

DCC模式下，停止独立启动的cm_server。
表5 build参数

参数

参数说明

-f

强制重建备机。

-b full

指定进行全量build。不指定情况下，对于一主多备数据库实例部署模式进行auto build。auto build指：先调用增量build，失败之后调用全量build。

-c

重建 cm_server（将主节点的dcc数据目录复制到指定节点，只适用于一主一备模式）。
表6 check参数

参数

参数说明

-B <BIN_NAME>

指定进程名，其进程名包括“cm_agent”,“gaussdb”和“cm_server”。

-T <DATA_PATH>

指定实例数据目录。
表7 set参数

参数

参数说明

--log_level=<LOG_LEVEL>

设置主cm_server日志级别。共分为DEBUG5、DEBUG1、WARNING、LOG、ERROR和FATAL六个级别，日志打印信息级别越来越高。设置日志级别越高，输出日志信息就越少。

--cm_arbitration_mode=<ARBITRATION_MODE>

一主多备功能，设置cm_server的仲裁模式。共有MAJORITY、MINORITY两种模式，MAJORITY为多数派模式，MINORITY为少数派模式。少数派模式适用于一主多备数据库部署并且只有AZ3存活时，此时cm_server可以进行正常的仲裁业务；多数派模式适用于一主多备数据库部署并且各个组件（cm_server，etcd，dn）存活数量大于一半的场景。数据库实例正常情况下默认为多数派模式。

--cm_switchover_az_mode=

<SWITCHOVER_AZ_MODE>

一主多备功能，设置AZ之间的自动切换开关。共有NON_AUTO、AUTO两种模式，NON_AUTO为非自动切换模式，AUTO为自动切换模式。AUTO模式由主cm_server自动控制AZ1和AZ2之间的DN实例切换。

--cmsPromoteMode=<CMS_PROMOTE_MODE>

设置cms的升主方式，共有AUTO、PRIMARY_F两种模式，AUTO为默认自选主方式，PRIMARY_F会强制使-I指定的节点升主，无论当前是否有主，因此，有可能会导致cms存在多主情况。
表8 set cm参数

参数

参数说明

--param

表明需要设置cm参数，不带此参数则不能执行设置cm参数。

--agent | --server

此参数为必带参数，表明当前需要设置cm_server还是cm_agent的参数。

-n

指定需要修改哪一个节点的参数，如果不指定，即不加-n参数，则默认会修改所有节点的参数。

-k "<parameter>=<value>"

指定设置的参数和参数的值，只能设置已经存在的参数，不支持增加或删减参数。
表9 get参数

参数

参数说明

--log_level=<LOG_LEVEL>

获取主cm_server日志级别。共分为DEBUG5、DEBUG1、WARNING、LOG、ERROR和FATAL六个级别，日志打印信息级别越来越高。设置日志级别越高，输出日志信息就越少。

--cm_arbitration_mode=<ARBITRATION_MODE>

一主多备功能，获取cm_server的仲裁模式。共有MAJORITY、MINORITY两种模式，MAJORITY为多数派模式，MINORITY为少数派模式。少数派模式适用于一主多备数据库部署并且只有AZ3存活时，此时cm_server可以进行正常的仲裁业务；多数派模式适用于一主多备数据库部署并且各个组件（cm_server、etcd和dn）存活数量大于一半的场景。数据库实例正常情况下默认为多数派模式。

--cm_switchover_az_mode

=<SWITCHOVER_AZ_MODE>

一主多备功能，获取AZ之间的自动切换开关。共有NON_AUTO、AUTO两种模式，NON_AUTO为非自动切换模式，AUTO为自动切换模式。AUTO模式由主cm_server自动控制AZ1和AZ2之间的DN实例切换。
表10 switchover参数

参数

参数说明

-A

将所有DN实例统一从主切换到备。

-a

重置节点状态为初始配置状态。

说明：

switchover为维护操作：确保数据库实例状态正常，所有业务结束，并使用pgxc_get_senders_catchup_time()视图查询无主备追赶后，再进行switchover操作。

-f

指定进行-f类型switchover。

说明：
  • switchover为维护操作：确保数据库实例状态正常，所有业务结束，并使用pgxc_get_senders_catchup_time()视图查询无主备追赶后，再进行switchover操作。
  • 使用方式：cm_ctl switchover -n <NODE_ID> -D <DATA_DIR> -f。
表11 view参数

参数

参数说明

-v

显示数据库实例所有节点的静态配置详细信息。

说明：

相对于cm_ctl view命令，-v 显示内容增加了cmserver、dn组件的编号显示，如下：cmseverInstanceID，datanodeInstanceID。

-N

只显示本节点的静态配置信息，即执行cm_ctl view命令的节点的信息，N表示Native。
表12 hotpatch参数

参数

参数说明

取值范围

-E <HOTPATCH_COMMAND>

指定需要执行的热补丁操作。
  • load： 加载热补丁
  • unload：卸载热补丁
  • active：激活热补丁
  • deactive：去激活热补丁
  • info：显示热补丁信息
  • list：显示热补丁列表

-P <HOTPATCH_NAME>

指定需要执行操作的热补丁名称，需要完整的路径名。

字符串
表13 reload 参数

参数

参数说明

--param

表明需要加载cm参数，不带此参数则不能执行加载cm参数。

--agent | --server

表明当前需要动态加载cm_server还是cm_agent的参数。
表14 list参数

参数

参数说明

--param

此参数为必带参数，表明需要列出cm参数信息

--agent | --server

此参数为必带参数，表明当前需要查看cm_server还是cm_agent的参数。
表15 switch参数

参数

参数说明

--ddb_type=<DDB_TYPE>

选择需要切换到哪一个模式（etcd或dcc）。

--commit

执行切换会使数据库实例无法选主，需要执行commit恢复数据库实例。

--rollback

回滚操作，执行切换失败需要执行回滚操作。
表16 encrypt参数

参数

参数说明

-M

指定加密类型，支持server、client。默认类型为server。

-D

指定生成的加密密码文件路径。
表17 ddb参数

参数

参数说明

--put <key> <value>

往dcc中插入键值对，如果键值对已存在则会修改键key所对应的值value。

--get <key>

查询dcc中key对应的value。

--delete <key>

删除dcc中指定的键值对。

--prefix

get或者delete后添加prefix参数，可以实现模糊匹配查询和删除。

--cluster_info

获取数据库实例信息。

--leader_info

获取主节点信息。

--help，-h

显示dcc命令帮助信息。

--version，-v

显示dcc版本信息。

--member_list

查询dcc节点信息。

--member_add -n <NODE_ID> -i IP -p <PORT> -r <ROLE>

向dcc集群中增加节点。

--member_remove -n <NODE_ID>

从dcc集群中删除节点。

--change_role -n <NODE_ID> -r <ROLE>

改变节点的角色。

--build_info

查询dcc构建信息。

--fixleader -fixval {0 | 1}

修改dcc定主状态。
表18 setrunmode参数

参数

参数说明

取值范围

--xmode

指定DCF的运行模式。
  • normal：正常模式。
  • minority：少数派模式，需要--votenum指定投票数。

--votenum

指定DCF少数派运行方式的投票数。

正整数，不高于DCF总副本数。
表19 changerole参数

参数

参数说明

取值范围

--role

集中式DN数据库实例，DCF模式下节点角色。
  • passive：passive角色。
  • follower：follow角色。
表20 changemember参数

参数

参数说明

取值范围

--role

集中式DN数据库实例，DCF模式下节点角色。
  • passive：passive角色。
  • follower：follow角色。

--group

DCF模式下，修改group的值。

0~2147483647

--priority

DCF模式下，修改priority的值。

0~2147483647
表21 start参数

参数

参数说明

-I

指定需要启动的资源实例号，可以通过cm_ctl query -Cv查看资源实例和实例号的映射关系。

--server

DCC模式下，单独启动cm_server。
表22 res参数

参数

参数说明

--add --res_name=<name> --res_attr=<res_info>

新增资源配置，name为新增资源的名称，res_info为新增资源的信息。

--del --res_name=<name>

删除资源配置，name为删除资源的名称。

--edit --res_name=<name> --res_attr=<res_info>

修改资源配置，name为被修改资源的名称，res_info为被修改的资源信息。

--edit --res_name=<name> --add_inst=<inst_info> [--inst_attr=<inst_addr>]

新增资源实例，name为新增实例的资源名称，inst_info为新增实例的信息，inst_addr为新增实例的属性。

--edit --res_name=<name> --edit_inst=<inst_info> [--inst_attr=<inst_attr>]

修改资源实例，name为新增实例的资源名称，inst_info为新增实例的信息，inst_attr为新增实例属性。

--edit --res_name=<name> --del_inst=<inst_info>

删除资源实例，name为删除实例的资源名称，inst_info为删除实例的信息。

--check

检查资源配置。不合理处会显示Warning，配置不可用才会报错。

--list

展示资源配置。

--list --res_name=<name>

展示资源配置，name为该资源名称。

--list --res_name=<name> --list_inst

展示资源实例配置，name为该资源名称。
表23 notify参数

参数

参数说明

--fault_occur

通知cm，发生了一个或多个故障。

--fault_recover

通知cm，一个节点的故障已经恢复。

--detail

发生故障的详细信息。故障以json串的形式表示，json串格式如下：

{
    "faultList": [{
	// 必要参数
	"alarmId": "",  // 故障ID
	"faultNodeId": "",  // 故障节点号
	"faultGrade": ""  // 故障级别
     }, { ...
    }]
}
 
表24 disablecm\enablecm参数

参数

参数说明

--all

所有实例（DN、CMS）的自动启停和集群仲裁。

--start

所有实例（DN、CMS）的自动启动。

--stop

所有实例（DN、CMS）的自动停止。

--arbitrate

集群仲裁能力。参数可选“DN_ARBITRATE”。不附加参数默认选择可选参数内的全部仲裁能力。
表25 pull参数

参数

参数说明

--cm_meta_config

从cms主，获取最新的急诊室元数据文件
表26 push参数

参数

参数说明

--cm_meta_config

把本地急诊室元数据文件上传给cms主

命令参考

  • 启动实例。 
    cm_ctl start [-z <AZ_NAME> [--cm_arbitration_mode=<ARBITRATION_MODE>]] | [-n <NODE_ID> [-D <DATA_DIR> | -I <RESOURCE_INSTANCE_ID>]] [-t <SECS>]
     
  • 数据库主备倒换。 
    cm_ctl switchover [-z <AZ_NAME>] | [-n <NODE_ID> -D <DATA_DIR> [-f]] | [-a] | [-A] [-t <SECS>]
     
  • 所有备机停止回放，每个分片中选择一个强制升主。 
    cm_ctl finishredo
     
  • 重建备DN。 
    cm_ctl build -n <NODE_ID> -D <DATA_DIR> [-t <SECS>] [-f] [-b full]
     
  • 检测实例进程运行状态。 
    cm_ctl check -B <BIN_NAME> -T <DATA_PATH>
     
  • 停止实例。 
    cm_ctl stop [[-z <AZ_NAME>] | [-n <NODE_ID> [-D <DATA_DIR> | -I <RESOURCE_INSTANCE_ID>]]] [-t <SECS>] [-m <SHUTDOWN_MODE>]
     
  • 查询数据库实例状态。 
    cm_ctl query [-z ALL] [-l <FILE_NAME>] [-v [-C [-s] [-S] [-d] [-i] [-F] [-x] [-p]] | [-r]] [-t <SECS>] [--minorityAz=<AZ_NAME>]
     
  • 查看数据库实例配置文件。 
    cm_ctl view [-v | -N | -n <NODE_ID> | -c] [-l <FILE_NAME>]
     
  • 设置参数。 
    cm_ctl set [--log_level=<LOG_LEVEL>] [--cm_arbitration_mode=<ARBITRATION_MODE>] [--cm_switchover_az_mode=<SWITCHOVER_AZ_MODE>]
     
  • 设置CM参数： 
    cm_ctl set --param {--agent | --server} [-n <NODE_ID>] -k "<PARAMETER>=<VALUE>"
     
  • 获取参数。 
    cm_ctl get [--log_level] [--cm_arbitration_mode] [--cm_switchover_az_mode]
     
  • 对cm_server执行热补丁操作。 
    cm_ctl hotpatch -E <PATCH_COMMAND> -P <PATCH_NAME>
     

  • 设置DCF投票数

    cm_ctl setrunmode -n <NODE_ID> -D <DATA_DIR>  {--xmode=normal | --xmode=minority --votenum=<NUM>}
     
  • 改变dcf角色信息 
    cm_ctl changerole --role={PASSIVE | FOLLOWER} -n <NODE_ID> -D <DATA_DIR> [-t <SECS>]
     
  • 改变dcf节点属性 
    cm_ctl changemember --role={PASSIVE | FOLLOWER} [--group=xx] [--priority=xx] -n <NODE_ID> -D <DATA_DIR> [-t <SECS>]
     
  • 动态加载静态配置文件 
    cm_ctl reload
     
  • 动态加载CM参数： 
    cm_ctl reload --param {--agent | --server}
     
  • 列出所有CM参数： 
    cm_ctl list --param {--agent | --server}
     
  • 加密： 
    cm_ctl encrypt [-M <MODE>] -D <DATA_DIR>
     
  • 执行ddb命令行 
    cm_ctl ddb "<DCC_CMD>"
设置：cm_ctl ddb "--put <key> <value>"
删除：cm_ctl ddb "--delete <key>"
查看dcc命令帮助信息：cm_ctl ddb "--help"
     
  • 切换ddb模式： 
    cm_ctl switch {--ddb_type=<DDB_TYPE> | --commit | --rollback}
     
  • 执行res命令：
    • 新增资源： 
      cm_ctl res --add --res_name=<name>  --res_attr=<res_info>
       
    • 删除资源： 
      cm_ctl res --del --res_name=<name>
       
    • 修改资源： 
      cm_ctl res --edit --res_name=<name>  --res_attr=<res_info> [--inst_attr=<res_attr>]
       
    • 新增资源实例： 
      cm_ctl res --edit --res_name=<name>  --add_inst=<inst_info> [--inst_attr=<res_attr>]
       
    • 修改资源实例： 
      cm_ctl res --edit --res_name=<name> --edit_inst=<inst_info> [--inst_attr=<res_attr>]
       
    • 删除资源实例： 
      cm_ctl res --edit --res_name=<name>  --del_inst=<inst_info>
       
    • 检查资源： 
      cm_ctl res --check
       
    • 展示所有资源基本配置： 
      cm_ctl res --list
       
    • 展示单个资源配置: 
      cm_ctl res --list --res_name=<name>
       
    • 展示单个资源实例配置： 
      cm_ctl res --list --res_name=<name> --list_inst
       
  • 执行show命令： 
    cm_ctl show
     
  • 执行notify命令：
    • 通知cm发生故障 
      cm_ctl notify --fault_occur --detail="<fault_info_json>"
       
    • 通知cm故障恢复 
      cm_ctl notify --fault_recover -n <node_id>
       
  • 开启和修改急救室功能命令：
    • 获取最新的元数据信息： 
      cm_ctl pull --cm_meta_config
       
    • 上传本地最新的元数据信息： 
      cm_ctl push --cm_meta_config
       
 
posted @ 2024-10-29 15:40  jerrywang1983  阅读(285)  评论(0)    收藏  举报