vb_ctl

功能描述

vb_ctl是Vastbase提供的数据库服务控制工具，可以用来启停数据库服务和查询数据库状态。

vb_ctl工具由数据库安装用户执行，具有以下功能：

启动、停止、重启Vastbase节点。
在不停止数据库的情况下，重新加载配置文件（postgresql.conf，pg_hba.conf）。
主备切换、主备状态查询、重建和重建状态查询。

语法格式

初始化数据库。

vb_ctl init[db] [-D DATADIR] [-s] [-o "OPTIONS"]

启动/停止/重启数据库。

vb_ctl start   [-w] [-t SECS] [-D DATADIR] [-s] [-l FILENAME] [-o "OPTIONS"] [-M SERVERMODE]

vb_ctl stop    [-W] [-t SECS] [-D DATADIR] [-s] [-m SHUTDOWN-MODE]

vb_ctl restart [-w] [-t SECS] [-D DATADIR] [-s] [-m SHUTDOWN-MODE] [-o "OPTIONS"]

在主机上重建备实例或级联备实例。

vb_ctl build   [-D DATADIR] [-b MODE] [-r SECS] [-C CONNECTOR] [-q] [-M SERVERMODE]

重载配置文件（postgresql.conf, pg_hba.conf）。
```
vb_ctl reload  [-D DATADIR] [-s]
```
显示数据库运行状态。
```
vb_ctl status  [-D DATADIR]
```
主机故障时，备机停止回放，强制升主。
```
vb_ctl finishredo [-D DATADIR] [-s]
```

在主机异常时，将备机切换为主机。

vb_ctl failover [-W] [-t SECS] [-D DATADIR] [-U USERNAME] [-P PASSWORD] [-T TERM]

在主备机正常时，出于维护的需要，将备机切换为主机，可保证切换过程中数据不丢失。
- 必须在要切换为主机的备机上执行switchover命令才会生效。在主机上执行switchover命令，仅作查询使用。
- switchover命令下发后，命令如果超时返回，后台进程的执行状态可能处于不可确定状态。
```
vb_ctl switchover  [-W] [-D DATADIR] [-m SWITCHOVER-MODE] [-U USERNAME] [-P PASSWORD] [-f]
```

查询主备机之间的状态信息。

vb_ctl query   [-D DATADIR] [-U USERNAME] [-P PASSWORD] [-L lsn]

启动后再指定主备机。

vb_ctl notify  -M SERVERMODE [-D DATADIR] [-U USERNAME] [-P PASSWORD]

给指定的进程发送信号量。
```
vb_ctl kill  SIGNALNAME PID
```
查看数据库的重建进度。
```
vb_ctl querybuild   [-D DATADIR]
```

集群规模在线调整。

vb_ctl member [-O OPERATION] [-u DCF-NODE-ID] [-i DCF-NODE-IP] [-e DCF-NODE-PORT] [-D PRIMARY-DATADIR]

集群支持少数派强起功能。

vb_ctl setrunmode   [-x XMODE] [-v VOTE-NUM] [-D PRIMARY-DATADIR]

DCF模式下，将角色为primary的修改为passive或者follower。
```
vb_ctl changerole [-R DCF-ROLE] [-D DATADIR] [-t SEC]
```

参数说明

vb_ctl参数可分为如下几类：

公共参数，详细请参见表1 公共参数。
start和restart模式的参数，详细请参见表2 start，stop或restart相关参数。
switchover参数，详细请参见表3 switchover参数。
build参数，详细请参见表4 build参数。
query参数，详细请参见表5 query参数。
member参数，详细请参见表6 member参数。
changerole参数，详细请参见表7 changerole参数。
setrunmode参数，详细请参见表8 setrunmode参数。

表1 公共参数

参数	参数说明	取值范围
-D, --pgdata=DATADIR	指定数据目录的位置。若指定目录中包含配置文件postgresql.conf，且配置文件内data_directory值与-D指定目录不同，将优先按data_directory目录执行。	DATADIR的取值必须为有效的数据目录。
-s, --silent	对reload、restart、stop命令仅打印部分提示信息，对其他命令不生效。打印信息如：server promoting、 server shutting down。不打印信息如：waiting for server to shut down、server stopped等提示信息。	-
-t, --timeout=SECS	等待数据库启动、关闭或者主备切换完成的最大秒数。如果等待超时，命令会结束退出，并通知不再等待。	取值范围：整型（秒）。默认值：等待数据库启动、停止或者主备切换完成：60秒。
-V , --version	打印vb_ctl的版本信息然后退出。	-
-w	用户执行启动或者关闭数据库的操作后，会等待事务操作的完成后再执行。	默认值：省略此参数时，默认会等待事务操作完成。
-W	用户执行启动或者关闭数据库的操作后，会强制完成启动或者关闭，不等待事务操作完成。	-
-M	-M后面需要跟SERVERMODE参数，表示在启动时指定数据库的启动模式。说明：当前主机处于一主零备，或单机环境时，不支持-M参数。	SERVERMODE的取值范围： primary：本端以主机模式启动。 standby：本端以备机模式启动。 cascade_standby：本端以级联备机模式启动。 pending：本端处于等待状态，等待提升为主机或者备机。
-T	-T 后面跟term，升主命令时会用此term作为主机term，build时会连接大于等于此term的主机进行build	term的取值范围，无符号整型。
-d	打印更多调试信息。	无参数。
-P PASSWORD	与-U参数配合使用，指定连接本地数据库的用户密码。说明：当省略-U参数，且认证方法为trust时，-P参数无效。	-
-U USERNAME	指定连接数据库的用户。此参数只能与notify、query、failover、switchover和querybuild参数配合使用。对于域用户，使用DOMAIN\username格式。	取值范围：Vastbase中存在的用户。默认值：省略此参数则使用与当前操作系统用户同名的用户。
-?, -h, --help	显示关于vb_ctl命令行参数的帮助信息。	-

表2 start，stop或restart相关参数

参数	参数说明	取值范围
-c, --core-file	允许Vastbase进程产生内核文件。	-
-l, --log=FILENAME	把服务器日志输出附加在FILENAME文件上。	FILENAME的取值为启动数据库服务的用户有权限的文件。例如，data目录下的某文件。
-o "OPTIONS"	声明要直接传递给由Vastbase执行的Vastbase的命令行选项。参数通常都用单或者双引号包围以保证它们作为一个整体传递。	Vastbase支持的参数。
-p PATH-TO-POSTGRES	声明Vastbase可执行文件的位置。	默认值：vb_ctl自身所在目录。
-m, --mode=MODE	声明关闭模式。	mode的取值如下： fast：不等待客户端中断连接，所有活跃事务都被回滚并且客户端都被强制断开，然后服务器将被关闭。 immediate：强行关闭，在下次重新启动的时候将导致故障恢复。默认值：fast

表3 switchover参数

参数	参数说明	取值范围
-f	不等待客户端中断连接，所有活跃事务都被回滚并且客户端都被强制断开，然后服务器将被切换，且不做checkpoint。	无参数
-m SWITCHOVER-MODE	声明双机主备实例正常时切换的切换模式。	mode的取值如下： fast：不等待客户端中断连接，所有活跃事务都被回滚并且客户端都被强制断开，然后服务器将被切换。 smart：本版本暂不支持该模式。默认值：fast

表4 build参数

参数	参数说明	取值范围
-b MODE	指定重建备机的模式。	mode的取值如下： full：通过全量镜像的方式重新同步主机的数据目录。 incremental：通过解析Xlog日志获取主备机差异的数据进行增量修复备机。说明： - 增量重建适用于主备双主等因日志造成的不一致场景。 -增量重建不适用于一主一备并且没有开启最大高可用的场景，此种场景下需要使用全量重建或者开启最大高可用后再进行增量重建。 -备机数据文件损坏、数据目录丢失等故障通过增量重建的方式无法修复，此时可通过全量重建的方式重新修复备机。 auto（不指定）：先增量，根据失败后是否可以再增量选择继续增量或者全量，三次增量失败后进行全量。 standby_full：通过指定的备机ip和port全量重建故障备机。使用该参数时需要同时使用-C参数指定镜像的ip和port。 copy_secure_files：在流式容灾场景下，获取指定节点数据目录下gs_secure_files目录对应内容。 copy_upgrade_file：在dorado容灾场景下，获取指定节点下升级所需指定文件。默认值：auto cross_cluster_full：基于共享存储的同城双中心场景下的跨集群全量build。 cross_cluster_incremental：基于共享存储的同城双中心场景下的跨集群增量build。 check：检测是否需要build，如果需要，返回build的类型。默认值：auto 说明：重建级联备机需要加上-M cascade_standby参数。 cross_cluster_full：在dorado容灾场景下，通过全量镜像的方式重新同步主机的数据目录。
-r, --recvtimeout=INTERVAL	指定重建过程中备机日志接收等待主机响应的超时时间。	取值范围：整型（秒）。默认值：120秒提示：超时时间需根据业务繁忙程度设置，业务繁忙等待主机的响应时间需加长，建议超时时间=checkpoint的执行时间+1min。
-q	重建结束后，是否自动重启。指定该参数，则不会重启未指定场合，自动重启，重启默认最大等待时间是60秒。如果在此时间内数据库未能启动成功，就会报不再等待，命令退出。	无参数。

表5 query参数

参数	参数说明	取值范围
-L	查询lsn并展示最大长度。	-

表6 member参数

参数	参数说明	取值范围
--operation	vastbase数据库实例，DCF模式下，增删节点的操作。	add：向数据库实例的DCF节点配置中增加一个节点 remove：从数据库实例DCF节点配置中删除一个节点。
-u, --nodeid	新增节点的DCF NODE ID。	无符号整型。
-i, --ip	新增节点与数据库实例DCF模块通信的IP。	字符串。
[-D, --pgdata=]DATADIR	指定数据目录的位置。若指定目录中包含配置文件postgresql.conf，且配置文件内data_directory值与-D指定目录不同，将优先按data_directory目录执行。	DATADIR的取值：用户自定义。

表7 changerole参数

参数	参数说明	取值范围
-R, --role	Vastbase数据库实例，DCF模式下节点角色（需要在角色为primary的节点上使用）。	passive：passive角色（passive节点不参与选举，只做日志的同步以及回放，该类型节点在高负载的情况下，日志同步会做流控）。 follower：follower角色（响应Leader的日志同步请求）。
-u, --nodeid	新增节点的DCF NODE ID。	无符号整型。
[-D, --pgdata=]DATADIR	指定数据目录的位置。若指定目录中包含配置文件postgresql.conf，且配置文件内data_directory值与-D指定目录不同，将优先按data_directory目录执行。	DATADIR的取值：用户自定义。

表8 setrunmode参数

参数	参数说明	取值范围
-v, --votenum	投票个数。	无符号整型。
-x, --xmode	运行模式（在少数派的DN节点上使用）。	minority：少于一半节点的响应时可以成为Leader（少数派强起）。 normal：获得超过一半节点的响应时可以成为Leader。
[-D, --pgdata=]DATADIR	指定数据目录的位置。若指定目录中包含配置文件postgresql.conf，且配置文件内data_directory值与-D指定目录不同，将优先按data_directory目录执行。	DATADIR的取值：用户自定义。

使用示例

启动/停止数据库

启动数据库。
```
vb_ctl start
```
使用端口5432端口启动数据库，而且不带fsync（强制刷盘）运行。
```
vb_ctl -o "-F -p 5432" start
```
关闭数据库（使用-m选项控制数据库以fast方式关闭）。
```
vb_ctl stop -m fast
```

显示数据库状态

vb_ctl status

vb_ctl状态输出如下：

[2023-04-10 16:09:13.131][29655][][vb_ctl]: vb_ctl status,datadir is /home/vb_210/data/vastbase
vb_ctl: server is running (PID: 29381)
/home/vb_210/local/vastbase/bin/vastbase "-F" "-p" "5432"

重新加载配置文件

在配置文件中改变参数后，需要使用如下命令使参数生效。

vb_ctl reload

实例主备切换

将数据库主实例切换为备实例。

1、操作系统用户vastbase登录数据库任意节点，执行如下命令，检查主备节点状态。

vb_ctl query

2、以操作系统用户vastbase登录需要升主的备节点，执行如下命令进行主备切换。

vb_ctl switchover

返回结果为：

vb_ctl switchover ,datadir is /home/vastbase/data/vastbase
switchover term (1)
waiting for server to switchover.......
switchover completed (/home/vastbase/data/vastbase)

3、当主节点故障时，登录备节点，将备节点提升为主节点。

vb_ctl failover