has_ctl

功能描述

has_ctl是Vastbase提供的在高可用场景下控制数据库实例服务的工具。该工具主要供OM调用，及数据库实例服务自恢复时使用。

has_ctl的主要功能有：

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

与has_ctl工具相关的文件：

cluster_manual_start

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

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

has_ctl的相关约束：

在集群模式下，使用has_ctl集群工具来切换数据库角色，而不是vb_ctl数据库工具。

语法格式

start：一主多备数据库部署模式下启动数据库实例服务、单个主机上的所有实例或单独启动某个节点实例进程，或者直接启动整个AZ。
```
has_ctl start [-z AVAILABILITY_ZONE [--cm_arbitration_mode=ARBITRATION_MODE]] | [-n NODEID [-D DATADIR]] [-t SECS]
```

switchover：一主多备数据库部署模式下切换数据库主备实例。

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

finishredo：所有备机停止回放，每个分片中选择一个强制升主。
```
has_ctl finishredo
```
该参数属于高风险操作，请谨慎执行。

build：重建备实例。

has_ctl build [-c] [-n NODEID] [-D DATADIR [-t SECS] [-f] [-b full] [-j NUM]]

check：检测实例进程运行状态，用户无需关注，不建议使用。
```
has_ctl check -B BINNAME -T DATAPATH
```
stop：一主多备数据库部署模式下停止数据库实例服务、单个主机上的所有实例或单独停止某个节点实例进程。
```
has_ctl stop [[-z AVAILABILITY_ZONE] | [-n NODEID [-D DATADIR]]] [-t SECS] [-m SHUTDOWN-MODE]
```

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

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

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

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

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

has_ctl set [--log_level=LOG_LEVEL] [--cm_arbitration_mode=ARBITRATION_MODE] [--cm_switchover_az_mode=SWITCHOVER_AZ_MODE] [--cmsPromoteMode=CMS_PROMOTE_MODE -I INSTANCEID]

set --paramver：设置cm参数，默认set所有节点上的参数，也可以通过-n参数指定set某个节点，具体参数可以参考has配置参数介绍。
```
has_ctl set --param --agent | --server [-n [NODEID]] -k [PARAMETER]="[value]"
```
get：获取日志级别，一主多备数据库部署模式下cm_server的仲裁模式、AZ之间的切换模式。
```
has_ctl get [--log_level] [--cm_arbitration_mode] [--cm_switchover_az_mode]
```

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

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

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

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

changemember：DCF模式下，改变指定DCF节点属性，包括节点角色、节点所在的逻辑组、节点的选举优先级等。
```
has_ctl changemember [--role=PASSIVE | --role=FOLLOWER] [--group=xx] [--priority=xx] -n NODEID -D DATADIR [-t SECS]
```
reload：在线加载数据库实例静态配置文件，用户无需关注，不建议使用。
reload --param：加载可以动态生效的cm参数，部分参数不支持reload，只能重启cm才能生效。
```
has_ctl  reload --param [--agent | --server]
```
list：列出cm_agent或cm_server所有的参数。
```
has_ctl  list --param --agent | --server
```
encrypt：对输入的密码进行加密操作，密码支持8~15位，且必须包含三种字符（数字，字母，符号）。
```
has_ctl   encrypt [-M MODE] -D DATADIR
```
ddb：DCC或者share disk模式下，执行对DCC组件或者share disk的配置数据存取命令。CM依赖DCC组件或者share disk对配置数据分布式存取，实现集群配置管理高可用能力。
```
has_ctl ddb DCC_CMD
```
switch：执行ddb模式的切换。
```
has_ctl ddb DCC_CMD
```

参数说明

has_ctl参数可分为如下几类：

公共参数，详细请参见表1 公共参数。
start模式的参数，详细请参见表2 start模式参数。
switchover参数，详细请参见表3 switchover参数。
build模式的参数，详细请参见表4 build参数。
check模式的参数，详细请参见表5 check参数。
stop模式的参数，详细请参见表6 stop参数。
query模式的参数，详细请参见表7 query参数。
view模式的参数，详细请参见表8 view参数。
set模式的参数，详细请参见表9 set参数。
get模式的参数，详细请参见表10 get参数。
setrunmode模式的参数，详细请参见表11 setrunmode参数。
changerole模式的参数，详细请参见表12 changerole参数。
changemember模式的参数，详细请参见表13 changemember参数。
reload模式的参数，详细请参见表14 reload参数。
list模式的参数，详细请参见表15 list参数。
encrypt模式的参数，详细请参见表16 encrypt参数。
ddb模式的参数，详细请参见表17 ddb参数。
switch模式的参数，详细请参见表18 switch参数。
res模式的参数，详细请参见表19 res参数。

表1 公共参数

此处列出的公共参数并不一定适用于所有命令，而是多个命令支持，为避免冗余信息，所以统一在此说明，详细的使用方法见以上使用方法，也可以使用has_ctl --help进行查询。

参数	参数说明
-D DATADIR	指定实例数据目录。仅用于对数据库节点进行操作的命令，如start、stop、switchover、build、setrunmode、changerole、changemember、encrypt。
-l FILENAME	查询结果输出到指定文件。仅用于查询类的命令，如query、view。
-n NODEID	指定节点。
-z AVAILABILITY_ZONE	指定AZ名称。
-t SECS	指定超时时间。超时后，会退出并报错。
-V, --version	打印has_ctl版本信息，然后退出。
-?, -h,--help	显示关于has_ctl命令行参数的帮助信息，然后退出。

表2 start模式参数

参数参数说明

--cm_arbitration_mode=ARBITRATION_MODE 一主多备功能，获取cm_server的仲裁模式。共有MAJORITY、MINORITY两种模式，MAJORITY为多数派模式，MINORITY为少数派模式。少数派模式适用于一主多备数据库部署并且只有AZ3存活时，此时cm_server可以进行正常的仲裁业务，非此模式下将仲裁模式设置成少数派成功后，cm会自动将仲裁模式改为多数派，以保证集群正常运转；多数派模式适用于一主多备数据库部署并且各个组件（cm_server，节点）存活数量大于一半的场景。数据库实例正常情况下默认为多数派模式。

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

参数	参数说明
--cm_arbitration_mode=ARBITRATION_MODE	一主多备功能，获取cm_server的仲裁模式。共有MAJORITY、MINORITY两种模式，MAJORITY为多数派模式，MINORITY为少数派模式。少数派模式适用于一主多备数据库部署并且只有AZ3存活时，此时cm_server可以进行正常的仲裁业务，非此模式下将仲裁模式设置成少数派成功后，cm会自动将仲裁模式改为多数派，以保证集群正常运转；多数派模式适用于一主多备数据库部署并且各个组件（cm_server，节点）存活数量大于一半的场景。数据库实例正常情况下默认为多数派模式。
-l	指定需要启动的资源实例号，可以通过`has_ctl query -Cv`查看资源实例和实例号的映射关系。

表3 switchover参数

参数	参数说明
-a	将集群的主机重置到初始配置的节点。
-A	将主机切换到一个合适的备机节点上。
-f	指定进行-f类型switchover。使用方式：`has_ctl switchover -n NODEID -D DATADIR -f`。
-z	将主机切换到-z参数指定的AZ。注意：switchover为维护操作：确保数据库实例状态正常，所有业务结束，并使用pgxc_get_senders_catchup_time()视图查询无主备追赶后，再进行switchover操作。

表4 build参数

参数	参数说明
-f	强制重建备机。
-b full	指定进行全量build。不指定情况下，对于一主多备数据库实例部署模式进行auto build。auto build指：先调用增量build，失败之后调用全量build。
-c	重建 cm_server（将主节点的DCC数据目录拷贝到指定节点，只适用于一主一备模式）。

表5 check参数

参数	参数说明
-B BINNAME	指定进程名，其进程名包括“cm_agent”,“gaussdb”和“cm_server”。
-T DATAPATH	指定实例数据目录。

表6 stop参数

参数	参数说明
-m SHUTDOWN-MODE	指定停止模式，停止模式有以下几种： smart（s）：等待用户业务结束后，停止所有数据库实例。 fast（f）：不等待用户业务结束，指定数据库实例退出。 immediate（i）：不等待用户业务结束，指定数据库实例强制退出。
-I	指定需要停止的资源实例号，可以通过`has_ctl query -Cv`查看资源实例和实例号的映射关系。

表7 query参数

参数	参数说明
-s	显示导致各个节点主备实例数量不均衡的实例。说明：-s参数需要和-v以及-C参数一起使用才能按主备关系成对显示导致各个节点主备实例数量不均衡的实例，使用-s参数时，必须指定-C、-v参数。
-C	按主备关系成对显示数据库实例状态。说明：-C参数需要和-v参数一起使用才能按主备关系成对显示数据库实例详细状态信息，使用-C时，必须指定-v参数。
-v	显示详细数据库实例状态。数据库实例有如下几种状态： Normal：表示数据库实例可用，且数据有冗余备份。所有进程都在运行，主备关系正常。 Degraded：表示数据库实例可用，但数据没有冗余备份。 Unavailable：表示数据库实例不可用。
-d	显示实例数据目录。说明：-d参数需要和-v以及-C参数一起使用。
-i	显示物理节点ip。说明：-i参数需要和-v以及-C参数一起使用。
-F	显示各个节点Fenced UDF状态。说明：-F参数需要和-v以及-C参数一起使用才能显示各个节点Fenced UDF状态，使用-F参数时，必须指定-C、-v参数。
-z ALL	显示数据库实例所在AZ名称。说明：-z参数需要和-v以及-C参数一起使用，并且-z后面需要跟参数ALL。
-r	显示备机redo状态。说明：使用-r时，必须指定-v参数。
-g	显示备份和恢复群集信息。
-x	显示所有异常的数据库实例。说明：-x参数需要和-v以及-C参数一起使用。
-S	显示数据库实例启动时的状态检查结果。说明：-S参数需要和-v以及-C参数一起使用才能按显示数据库实例的状态检查结果。有以下三种状态： Normal：表示数据库实例可用，且数据有冗余备份。所有进程都在运行，主备关系正常。 Degraded：表示数据库实例可用，但数据没有冗余备份。 Unavailable：表示数据库实例不可用。
--minorityAz	只查询指定AZ的cms。说明：此参数会忽略非指定AZ的cms节点，可以在少数派场景提高查询速度。
-p	显示数据库实例所有节点端口。说明：-p参数需要和-v以及-C参数一起使用。

表8 view参数

参数	参数说明
-v	显示数据库实例所有节点的静态配置详细信息。
-N	只显示本节点的静态配置信息，即执行`has_ctl view`命令的节点的信息，N表示Native。

表9 set参数

参数	参数说明
--log_level=LOG_LEVEL	设置主cm_server日志级别。共分为DEBUG5、DEBUG1、WARNING、LOG、ERROR和FATAL六个级别，日志打印信息级别越来越高。设置日志级别越高，输出日志信息就越少。
--cm_arbitration_mode=ARBITRATION_MODE	一主多备功能，设置cm_server的仲裁模式。共有MAJORITY、MINORITY两种模式，MAJORITY为多数派模式，MINORITY为少数派模式。Vastbase不支持少数派，此参数可以设置成MINORITY，但不会生效。
--cm_switchover_az_mode=SWITCHOVER_AZ_MODE	一主多备功能，设置AZ之间的自动切换开关。共有NON_AUTO、AUTO两种模式，NON_AUTO为非自动切换模式，AUTO为自动切换模式。AUTO模式由主cm_server自动控制AZ1和AZ2之间的节点实例切换。
--cmsPromoteMode=CMS_PROMOTE_MODE -I INSTANCEID	设置cm_server的升主方式，共有AUTO、PRIMARY_F两种模式，AUTO为默认自选主方式，PRIMARY_F会强制使-I指定的节点升主，无论当前是否有主，因此，有可能会导致cms存在多主情况。
--param	表明需要设置cm参数，不带此参数则不能执行设置cm参数。
--agent \| --server	此参数为必带参数，表明当前需要设置cm_server还是cm_agent的参数。
-k parameter="value"	指定设置的参数和参数的值，只能设置已经存在的参数，不支持增加或删减参数。

表10 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会自动将仲裁模式改为多数派，以保证集群正常运转；多数派模式适用于一主多备数据库部署并且各个组件（cm_server，节点）存活数量大于一半的场景。数据库实例正常情况下默认为多数派模式。
--cm_switchover_az_mode=SWITCHOVER_AZ_MODE	一主多备功能，获取AZ之间的自动切换开关。共有NON_AUTO、AUTO两种模式，NON_AUTO为非自动切换模式，AUTO为自动切换模式。AUTO模式由主cm_server自动控制AZ1和AZ2之间的节点实例切换。

表11 setrunmode参数

参数	参数说明	取值范围
--xmode	指定DCF的运行模式。	normal：正常模式。 minority：少数派模式，需要--votenum指定投票数。
--votenum	指定DCF少数派运行方式的投票数。	正整数，不高于DCF总副本数。

表12 changerole参数

参数	参数说明	取值范围
--role	DCF模式下，将角色为primary的修改为passive或者follower。	passive：passive角色。 follower：follow角色。

表13 changemember参数

参数	参数说明	取值范围
--role	DCF模式下，将角色为primary的修改为passive或者follower。	passive：passive角色。 follower：follow角色。
--group	DCF模式下，修改group的值。	0~2147483647
--priority	DCF模式下，修改priority的值。	0~2147483647

表14 reload参数

参数	参数说明
--param	表明需要加载cm参数，不带此参数则不能执行加载cm参数。
--agent \| --server	表明当前需要动态加载cm_server还是cm_agent的参数。

表15 list参数

参数	参数说明
--param	此参数为必带参数，表明需要列出cm参数信息。
--agent \| --server	此参数为必带参数，表明当前需要查看cm_server还是cm_agent的参数。

表16 encrypt参数

参数	参数说明
-M	指定加密类型，支持server、client。默认类型为server。
-D	定生成的加密密码文件路径。

表17 ddb参数

参数	参数说明
--put [key] [value]	往DCC或者share disk中插入键值对，如果键值对已存在则会修改键key所对应的值value。
--get [key]	查询DCC或者share disk中key对应的value。
--delete [key]	删除DCC或者share disk中指定的键值对。
--prefix	get或者delete后添加prefix参数，可以实现模糊匹配查询和删除。
--cluster_info	DCC部署模式下获取数据库实例信息，share disk部署模式下不支持该命令。
--leader_info	DCC部署模式下获取主节点信息，share disk部署模式下不支持该命令。
--help，-h	显示DDB命令帮助信息。
--version，-v	DCC部署模式下显示DCC版本信息，share disk部署模式下不支持该命令。

表18 switch参数

参数	参数说明
-M--ddb_type=[DDB]	选择需要切换DDB模式（Vastbase只支持DCC模式）。
--commit	执行切换会使数据库实例无法选主，需要执行commit恢复数据库实例。
--rollback	回滚操作，执行切换失败需要执行回滚操作。

表19 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]	新增资源实例，name为新增实例的资源名称，inst_info为新增实例的信息。
--edit --res_name=[name] --del_inst=[inst_info]	删除资源实例，name为删除实例的资源名称，inst_info为删除实例的信息。
--check	检查资源配置。不合理处会显示Warning，配置不可用才会报错。

命令参考

启动实例。

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

数据库主备切换。

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

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

重建备节点。

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

检测实例进程运行状态。
```
has_ctl check -B BINNAME -T DATAPATH
```

停止实例。

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

查询集群状态。

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

查看集群配置文件。

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

设置参数。

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

设置CM参数。

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

获取参数。

has_ctl get [--log_level] [--cm_arbitration_mode] [--cm_switchover_az_mode]

设置DCF投票数。

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

改变DCF角色信息。

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

改变DCF节点属性。

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

动态加载CM参数。

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

列出所有CM参数。

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

加密。
```
has_ctl  encrypt [-M MODE] -D DATADIR
```

执行DDB命令行。

has_ctl ddb DDB_CMD
has_ctl ddb --put [key] [value]  --设置
has_ctl ddb --delete [key]  --删除
has_ctl ddb --help  --查看DDB命令帮助信息

执行switch ddb命令。

has_ctl switch [--ddb_type=[DDB]] [--commit] [--rollback]

执行res命令。

has_ctl res --add --res_name=[name] --res_attr=[res_info] --新增资源
has_ctl res --del --res_name=[name]  --删除资源
has_ctl res --edit --res_name=[name] --res_attr=[res_info]  --修改资源
has_ctl res --edit --res_name=[name] --add_inst=[inst_info] --新增资源实例
has_ctl res --edit --res_name=[name] --del_inst=[inst_info] --删除资源实例
has_ctl res --check  --检查资源

使用示例

关于has_ctl工具的使用具体可参考集群使用章节。