gs_ctl

背景信息

gs_ctl是openGauss提供的数据库服务控制工具，可以用来启停数据库服务和查询数据库状态。主要供openGauss管理模块调用。

gs_ctl工具由操作系统用户omm执行。

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

参数说明

gs_ctl参数可分为如下几类：

  • option参数，详细请参见表1。
  • 公共参数，详细请参见表2。
  • start和restart模式的参数，详细请参见表3。
  • stop和restart模式的参数，详细请参见表4。
  • switchover模式的参数，详细请参见表5。
  • build参数，详细请参见表6。

  • restore参数，详细请参见表7。

    表 1 option参数

    参数

    参数说明

    init[db]

    初始化数据库。

    start

    启动数据库。

    restart

    重启数据库。

    build

    在主机上重建备实例。

    stop

    停止数据库。

    reload

    重载配置文件（postgresql.conf, pg_hba.conf）。

    status

    显示数据库运行状态。

    promote

    在指定的数据目录运行的备用服务器被命令退出故障恢复，并开始进行读写操作。

    failover

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

    切换成功后，需要执行gs_om -t refreshconf 命令记录当前主备机信息。

    switchover

    在主备机正常时，出于维护的需要，将备机切换为主机，可保证切换过程中数据不丢失。

    切换成功后，需要执行gs_om -t refreshconf 命令记录当前主备机信息。

    switchover命令下发后，命令如果超时返回，后台进程的执行状态可能处于不可确定状态；如果备机在standby wait状态，可以通过重复下发switchover命令消除，使集群恢复到正常状态。

    query

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

    notify

    启动后再指定主备机。

    kill

    给指定的进程发送信号量。

    querybuild

    查看数据库的重建进度。

    restore

    恢复增量备份集，需要在gaussdb进程停止的情况下执行。

表 2 公共参数

参数

参数说明

取值范围

-D, –pgdata=DATADIR

指定数据目录的位置。

DATADIR的取值必须为有效的数据目录。

-s, –silent

仅打印错误，没有参考消息。

-

-t, –timeout=SECS

这个参数同时控制如下两个功能：

  • 等待数据库启动或者关闭完成的最大秒数。

取值范围：整型（秒）。

默认值：

  • 等待数据库启动或者停止完成：60秒。

-V , –version

打印gs_ctl的版本信息然后退出。

-

-w

用户执行启动或者关闭数据库的操作后，会等待事务操作的完成后再执行。

默认值：省略此参数时，默认会等待事务操作完成。

-W

用户执行启动或者关闭数据库的操作后，会强制完成启动或者关闭，不等待事务操作完成。

-

-M

-M后面需要跟SERVERMODE参数，表示在启动时指定数据库的启动模式。

说明：

当前主机处于一主零备，或单机环境时，不支持-M参数。

SERVERMODE的取值范围：

  • primary：本端以主机模式启动。
  • standby：本端以备机模式启动。
  • pending：本端处于等待状态，等待提升为主机或者备机。

-T

-T 后面跟term，升主命令时会用此term作为主机term，build时会连接大于等于此term的主机进行build

term的取值范围，无符号整型。

-d

打印更多调试信息

无参数

-P PASSWORD

与-U参数配合使用，指定连接本地数据库的用户密码。

说明：

当省略-U参数，且认证方法为trust时，-P参数无效。

-

-U USERNAME

指定连接数据库的用户。此参数只能与notify、query和querybuild参数配合使用。

对于域用户，使用DOMAIN\username格式。

取值范围：openGauss中存在的用户。

默认值：省略此参数则使用与当前操作系统用户同名的用户。

-?, –help

显示关于gs_ctl命令行参数的帮助信息。

-

表 3 start或restart共有参数

参数

参数说明

取值范围

-c, –core-file

允许gaussdb进程产生内核文件。

-

-l, –log=FILENAME

把服务器日志输出附加在FILENAME文件上。

FILENAME的取值为启动数据库服务的用户有权限的文件。

例如，data目录下的某文件。

-o OPTIONS

声明要直接传递给由openGauss执行的gaussdb的命令行选项。

参数通常都用单或者双引号包围以保证它们作为一个整体传递。

gaussdb支持的参数。

-p PATH-TO-POSTGRES

声明gaussdb可执行文件的位置。

缺省位于gs_ctl自身所在目录，一般不需要此选项。

表 4 stop和restart共有参数

参数

参数说明

取值范围

-m, –mode=MODE

声明关闭模式。

mode的取值：

  • smart：单机模式下主机立即断开，同fast。
  • fast：不等待客户端中断连接，所有活跃事务都被回滚并且客户端都被强制断开，然后服务器将被关闭。
  • immediate：强行关闭，在下次重新启动的时候将导致故障恢复。

默认值：fast

表 5 switchover参数

参数

参数说明

取值范围

-m SWITCHOVER-MODE

声明双机主备实例正常时切换的切换模式。

mode的取值：

  • fast：不等待客户端中断连接，所有活跃事务都被回滚并且客户端都被强制断开，然后服务器将被切换。
  • smart：本版本暂不支持该模式
  • immediate：本版本暂不支持该模式

默认值：fast

表 6 build参数

参数

参数说明

取值范围

-b MODE

指定重建备机的模式。

mode的取值：

● full：通过全量镜像的方式重新同步 主机的数据目录。

● incremental：通过解析Xlog日志获 取主备机差异的数据进行增量修复备机。

警告 ● 增量重建适用于主备双主等因日志 造成的不一致场景。

● 增量重建不适用于一主一备并且没有开启最大高可用的场景，此种场景下需要使用全量重建或者开启最大高可用后再进行增量重建。

● 备机数据文件损坏、数据目录丢失 等故障通过增量重建的方式无法修复，此时可通过全量重建的方式重 新修复备机。

● auto(不指定)：先增量，根据失败 后是否可以再增量选择继续增量或 者全量，三次增量失败后进行全 量。

默认值：auto

-r, –recvtimeout=INTERVAL

指定重建过程中备机日志接收等待主机响应的超时时间。

取值范围：整型（秒）。

默认值：120秒

提示：超时时间需根据业务繁忙程度设置，业务繁忙等待主机的响应时间需加长，建议超时时间=checkpoint的执行时间+1min。

-q

重建结束后，是否自动重启。

指定参数场合，不自动重启。

未指定场合，自动重启。

无参数

表 7 restore参数

参数

参数说明

取值范围

–remove-backup

指定是否删除增量备份集。

无参数

表 8 query参数

参数

参数说明

取值范围

-L

查询lsn并展示最大长度。

无参数