vb_ctl

功能描述

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

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

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

工具运行产生的日志位于 $GAUSSLOG/bin/gs_ctl 目录下，每个日志最大 16 MB，最多保留 50 个。如果没有配置环境变量 $GAUSSLOG，则不会产生日志文件。

语法格式

初始化数据库。
```
vb_ctl init[db] [-D DATADIR] [-s] [-o "--nodename=NODENAME --OPTIONS=VALUES"]
```
运行vb_initdb --help命令去查看支持的OPTIONS。详细请参考vb_initdb。

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

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]
```
数据库包括以下三种运行状态：
- server is running (PID: xxx)：VexDB服务已启动。
- no server running：VexDB服务已关闭。
- single-user server is running (PID: xxx)：VexDB数据库支持通过single单用户模式登录。
主机故障时，备机停止回放，强制升主。
```
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]

给指定的进程发送信号量。允许用于kill的信号名称包括：ABRT、HUP、INT、QUIT、TERM、USR1、USR2。
```
vb_ctl kill  SIGNALNAME PID
```
查看数据库的重建进度。
```
vb_ctl querybuild   [-D DATADIR]
```
基于共享存储的双中心容灾模式，进行xlog日志拷贝。
```
vb_ctl copy   [-D DATADIR] [-Q COPYMODE]
```
获取VexDB的调用栈。
```
vb_ctl stack [-D DATADIR] [-I lwtid]
```
统计数据库系统的历史使用情况。
VexDB为了方便用户查阅数据库历史使用情况，提供了vb_ctl statistic功能，可以通过参数控制查询的时间段，最终输出一个HTML文件，HTML文件以图形化方式展示出数据库历史使用情况。
```
vb_ctl statistic [-D DATADIR] [-p OUTPUT_PATH] {[-d DAYS] | [-m MONTHS]| [-r STARTDATE,STOPDATE]}
```
使用该功能需要开启GUC参数enable_wdr_snapshot，否则生成的HTML文件内容为空。

集群规模在线调整。

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

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

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

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

参数说明

vb_ctl参数可分为如下几类：

公共参数，详细请参见表1. 公共参数。
start和restart模式的参数，详细请参见表2. start，stop或restart相关参数。
xlog copy参数，详细请参见表4. xlog copy参数。
DCF参数，详细请参见表5. DCF参数。
stack参数，详细请参见表6. stack参数。
switchover参数，详细请参见表7. switchover参数。
资源池化build参数，详细请参见表8. 资源池化build参数。
query参数，详细请参见表9. query参数。
系统使用情况statistic参数，详细请参见表10. 系统使用情况statistic参数。

表1 公共参数

参数	说明	取值范围
-b, --mode=MODE	指定重建备机的模式。	mode 的取值如下： full：通过全量镜像的方式重新同步主机的数据目录。 incremental：通过解析 Xlog 日志获取主备机差异的数据进行增量修复备机。说明：增量重建适用于主备双主等因日志造成的不一致场景。增量重建不适用于一主一备并且没有开启最大高可用的场景，此种场景下需要使用全量重建或者开启最大高可用后再进行增量重建。备机数据文件损坏、数据目录丢失等故障通过增量重建的方式无法修复，此时可通过全量重建的方式重新修复备机。 auto（不指定）：先增量，根据失败后是否可以再增量选择继续增量或者全量，三次增量失败后进行全量。 standby_full：通过指定的备机 ip 和 port 全量重建故障备机。使用该参数时需要同时使用-C 参数指定镜像的 ip 和 port。 copy_sec dure_files：在流式容灾场景下，获取指定节点数据目录下 gs_secure_files 目录对应内容。 copy_upgrade_file：在 dorado 容灾场景下，获取指定节点下升级所需指定文件。 cross_cluster_full：在 dorado 容灾场景下，通过全量镜像的方式重新同步主机的数据目录。 cross_cluster_standby_full：在 dorado 容灾场景下，通过全量镜像的方式重新同步备机的数据目录。 cross_cluster_incremental：基于共享存储的同城双中心场景下的跨集群增量 build。 check：检测是否需要 build，如果需要，返回 build 的类型。默认值：auto 说明重建级联备机需要加上-M cascade_standby 参数。
-D, --pgdata=DATADIR	指定数据目录的位置。若指定目录中包含配置文件 postgresql.conf，且配置文件内 data_directory 值与-D指定目录不同，将优先按 data_directory 目录执行。如果省略了-D选项，将使用环境变量 PGDATA。	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 参数可使 vb_ctl 命令在执行数据库启动、停止或重启操作时等待操作完全完成才返回结果。此处提到的等待操作指的是启停数据库本身需要的操作。以下是在不同操作场景下 -w参数的具体情况：启动：vb_ctl 会等待数据库实例完成所有启动步骤，包括读取配置文件、初始化内存结构、打开数据文件等，并进入正常服务状态再返回。关闭：vb_ctl 会等待数据库实例完成所有关闭步骤，如结束活动会话、将内存数据刷新至磁盘及释放系统资源，直到数据库进程彻底退出再返回。重启：vb_ctl 会等待数据库实例先停止，再重新启动并进入正常服务状态。整个过程涵盖了停止数据库的操作和启动数据库的操作，-w 会保证这两个阶段的操作都完成后才结束等待返回结果。	默认值：省略此参数时，默认会等待操作完成。
-W	-W 参数与 -w 参数相反，它表示不等待操作完成。	-
-M	-M 后面需要跟 SERVERMODE 参数，表示在启动时指定数据库的启动模式。说明：当前主机处于一主零备，或单机环境时，不支持-M 参数。	SERVERMODE 的取值范围： primary：本端以主机模式启动。 standby：本端以备机模式启动。 cascade_standby：本端以级联备机模式启动。 pending：本端处于等待状态，等待提升为主机或者备机。
-T	-T 后面跟 term，升主命令时会用此 term 作为主机 term，build 时会连接大于等于此 term 的主机进行 build	term 的取值范围，无符号整型。
-q	重建结束后，是否自动重启。指定该参数，则不会重启未指定场合，自动重启，重启默认最大等待时间是60秒。如果在此时间内数据库未能启动成功，就会报不再等待，命令退出。	无参数
-d	打印更多调试信息。	无参数
-L	查询 lsn 并展示最大长度。	-
-P PASSWORD	与-U 参数配合使用，指定连接本地数据库的用户密码。说明：当省略-U 参数，且认证方法为 trust 时，-P 参数无效。	-
-U USERNAME	指定连接数据库的用户。此参数只能与 notify、query、failover、switchover 和 querybuild 参数配合使用。对于域用户，使用 DOMAIN\username 格式。	取值范围：VexDB 中存在的用户。默认值：省略此参数则使用与当前操作系统用户同名的用户。
-Z NODE-TYPE	节点类型	-
-?, -h, --help	显示关于 vb_ctl 命令行参数的帮助信息。	-

表2 start，stop或restart相关参数

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

表3 init参数

参数	说明	取值范围
--nodename=NODENAME	初始化的节点名称。	字符串，节点的命名需要遵守如下规范：节点名称必须为小写字母（a-z）、下划线（_）、特殊符号#、数字（0-9）。节点名称必须以小写字母（a-z）或下划线（_）开头。节点名称不能为空，且最大的长度为64个字符。

表4 xlog copy参数

参数	说明	取值范围
-Q, --mode=MODE	指定xlog日志拷贝方向。	copy_from_local：从本地往共享存储上拷贝。 copy_from_share：从共享存储往本地存储上拷贝。 force_copy_from_local：强制从本地往共享存储上拷贝。

表5 DCF参数

参数	说明	取值范围
-O, --operation=OPERATION	VexDB 数据库实例，DCF 模式下，增删节点的操作。	add：向数据库实例的 DCF 节点配置中增加一个节点 remove：从数据库实例 DCF 节点配置中删除一个节点。 change：从数据库实例 DCF 节点配置中更改一个节点。
-u, --nodeid=DCF-NODE-ID	新增节点的 DCF NODE ID。	无符号整型。
-i, --ip=DCF-NODE-IP	新增节点与数据库实例 DCF 模块通信的 IP。	字符串。
-e, --port=DCF-NODE-PORT	新增节点与数据库实例 DCF 模块通信的 port。	整型。
-R, --role=DCF-NODE-ROLE	VexDB 数据库实例，DCF 模式下节点角色（需要在角色为 primary 的节点上使用）。	passive：passive 角色（passive 节点不参与选举，只做日志的同步以及回放，该类型节点在高负载的情况下，日志同步会做流控）。 follower：follower 角色（响应 Leader 的日志同步请求）。
-v, --votenum=VOTE-NUM	投票个数。	无符号整型。
-x, --xmode=XMODE	运行模式（在少数派的 DN 节点上使用）。	minority：少于一半节点的响应时可以成为 Leader（少数派强起）。 normal：获得超过一半节点的响应时可以成为 Leader。
-G	DCF 模式下，group 的值。	0~2147483647
--priority	DCF 模式下，节点选举的优先级。	0~2147483647

表6 stack参数

参数	说明	取值范围
-I lwtid	指用于指定需要获取调用栈的线程的lwtid。	正整数

表7 switchover参数

参数	说明	取值范围
-f	指定进行-f 类型 switchover。不等待客户端中断连接，所有活跃事务都被回滚并且客户端都被强制断开，然后服务器将被切换，且不做 checkpoint。使用方式： vb_ctl switchover -n NODEID -D DATADIR -f 。	无参数
-m SWITCHOVER-MODE	声明双机主备实例正常时切换的切换模式。	mode 的取值如下： fast：不等待客户端中断连接，所有活跃事务都被回滚并且客户端都被强制断开，然后服务器将被切换。 smart：等待所有客户端断开连接以及任何在线备份结束，正在进行中的事务不中断。默认值：fast

表8 资源池化build参数

参数	说明	取值范围
-r, --recvtimeout=INTERVAL	指定重建过程中备机日志接收等待主机响应的超时时间。	取值范围：整型（秒）。默认值：120秒提示：超时时间需根据业务繁忙程度设置，业务繁忙等待主机的响应时间需加长，建议超时时间=checkpoint 的执行时间+1min。
-C, connector	指定连接串。	-
--enable-dss	开启资源池化开关。	无参数
--vgname	卷组名。可选，未指定时由系统自动识别。	数据类型：字符串。例如：一个卷组“+data”或者两个卷组中间用“,”连接“+data,+log”。
--socketpath=socketpath	dss 实例进程使用的 socket 文件路径。可选，未指定时由系统自动识别。	实际的文件路径。
-b MODE	指定重建备机的模式。	mode 的取值： cross_cluster_full：资源池化执行 build，必须结合 dorado 容灾场景，该参数表示在 dorado 容灾场景下通过全量镜像的方式重新同步主机的数据目录。 check：判断是否需要 build。提示：资源池化 build 只适用于主备集群间的跨集群 build，不能用于资源池化单集群内的主备实例 build。

表9 query参数

参数	说明	取值范围
-D DATADIR	指定数据目录的位置，查询数据库状态，显示当前数据库的数据目录以及运行状态等信息。	DATADIR 的取值必须为有效的数据目录
-U USERNAME	查询受密码保护的数据库集群，可以使用-U 选项来指定用户名。	取值范围：VexDB 中存在的用户。默认值：省略此参数则使用与当前操作系统用户同名的用户。
-P PASSWORD	查询受密码保护的数据库集群，可以使用-P 选项来指定密码，一般与-U 配合使用	-
-L	查询 lsn 并展示最大长度。	-

表10 系统使用情况statistic参数

参数	说明	取值范围
-D DATADIR	指定要查询的数据库实例的路径。	含义同$PGDATA。
-p OUTPUT_PATH	输出的 HTML 文件路径。	文件路径（绝对路径）。
-d DAYS	输出之前 N 天（包含查询当日）的统计情况，结果按照天为单位进行汇总。	[1,180]
-m MONTHS	输出之前 N 月（包含查询当月）的统计情况，结果按照月为单位进行汇总。	[1,36]
-r STARTDATE,STOPDATE	查询置顶日期范围的统计情况，结果按照天为单位进行汇总。	STARTDATE 和 STOPDATE 为 date 类型，时间差不能超过180天。

说明
时间范围参数[-d DAYS]、[-m MONTHS]、[-r STARTDATE,STOPDATE]三者是互斥的，不能同时指定两个或两个以上参数。

使用示例

启动/停止数据库

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

显示数据库状态

vb_ctl status

返回结果如下：

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

重新加载配置文件

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

vb_ctl reload

实例主备切换

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

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

vb_ctl query

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

vb_ctl switchover

返回结果为：

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

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

vb_ctl failover

返回结果如下：

[2022-08-02 10:37:53.887][28312][][vb_ctl]: vb_ctl failover ,datadir is /home/vexdb/data/vexdb
[2022-08-02 10:37:53.887][28312][][vb_ctl]: failover term (1)
[2022-08-02 10:37:53.893][28312][][vb_ctl]:  waiting for server to failover...
[2022-08-02 10:37:53.894][28312][][vb_ctl]:  done
[2022-08-02 10:37:53.894][28312][][vb_ctl]:  failover completed (/home/vexdb/data/vexdb)

统计数据库使用情况

1、打开GUC参数enable_wdr_snapshot。

ALTER SYSTEM SET enable_wdr_snapshot TO on;

2、使用vb_ctl工具获取数据库使用情况统计信息。

vb_ctl statistic -D $PGDATA -p /tmp/mystatistic.html -d 30

上述命令执行成功后，会在/tmp路径下生成HTML文件mystatistic.html，用浏览器打开后显示如下内容：

vb_ctl

需要帮助？