gs_ctl

Background

gs_ctl, provided by openGauss, is used to control the database service. It can be used to start and stop the database service and to query the database status. gs_ctl is used by the openGauss management module.

gs_ctl is executed by OS user omm.

Start, stop, and restart the openGauss node.
Reload the configuration files (postgresql.conf and pg_hba.conf) without stopping the database.
Perform primary/standby switchover, query primary/standby status, rebuild the database instance, and query the rebuilding status.

Description

The gs_ctl tool can use the following types of parameters:

Parameters for option. For details, see Table 1.
Common parameters. For details, see Table 2.
Parameters for start and restart. For details, see Table 3.
Parameters for stop and restart. For details, see Table 4.
Parameters for switchover. For details, see Table 5.
Parameters for build. For details, see Table 6.

restore parameter. For details, see Table 7.

Table 1 option parameters

Parameter	Description
start	Starts the database.
restart	Restarts the database.
build	Rebuilds the standby instance on the host.
stop	Stops the database.
reload	Reloads the configuration files (postgresql.conf and pg_hba.conf).
status	Displays the running status of the database services
promote	Exits the faulty restoration when the running standby server is instructed in the specified data directory, and starts to perform the read and write operations.
failover	When the primary server is abnormal, switches the standby server to a primary server. After the failover is successful, you need to run the gs_om -t refreshconf command to record information about the current primary and standby servers.
switchover	When the primary/standby server relationship is normal, switches the standby server is to primary for maintenance purposes. Data will not be lost during the switchover. You must run the switchover command on the standy node to be switched to the primary node. After the switchover is successful, you need to run the gs_om -t refreshconf command to record information about the current primary and standby servers. After the switchover command is executed, if a timeout message is returned, the execution status of the background process may be uncertain.
query	Queries the status between the primary and standby server.
notify	Specifies the primary/standby relationship after startup.
kill	Sends semaphore to a specified process.
querybuild	Checks the rebuilding process of the database
restore	Restores an incremental backup set. The restoration can be performed only when the gaussdb process is stopped.

Table 2 Common parameters

Parameter	Description	Value Range
-D, --pgdata=DATADIR	Specifies the data directory.	The value of DATADIR must be a valid data directory.
-s, --silent	Prints errors without references.	-
-t, --timeout=SECS	This parameter controls the following functions: Maximum seconds for waiting the completion of database startup or shutdown.	Value range: an integer (second). Default Maximum seconds for waiting the completion of database startup or shutdown: 60s.
-V , --version	Prints the gs_ctl version and exits.	-	-
-M	-M must be followed by the SERVERMODE parameter, which specifies the startup mode of a database upon startup. NOTE: The -M parameter is not supported when the current host is in the single-node mode or one-primary-and-zero standby mode.	Value range of SERVERMODE: primary: The server starts in primary mode. standby: The server starts in standby mode. pending: The server is in pending mode to be promoted to a primary server or a standby server.
-T	-T is followed by a term. The term is used as the host term when the command for switching the standby server to primary is executed. During the rebuilding, hosts greater than the term will be connected for rebuilding.	Value range of term: an unsigned integer.
-d	Displays more debugging information.	None
-P PASSWORD	Specifies the password of the user connecting to the local database. It is used in conjunction with the -U parameter. NOTE: When -U is not specified, and the authentication mode is trust, the setting of the -P parameter is invalid.	-
-U USERNAME	Specifies the user that connects to the database. This parameter can be used only in conjunction with the parameter notify, query, failover, switchover or querybuild. For domain users, use the DOMAIN\username format.	Value range: users existing in openGauss. Default value: If this parameter is not specified, the current OS user is used.
-?, --help	Displays the help information related to the gs_ctl command line parameters.	-

Table 3 Common parameters for start and restart

Parameter	Description	Value Range
-c, --core-file	Allows the gaussdb process to produce core files.	-
-l, --log=FILENAME	Appends the server log output to the FILENAME file.	The value of FILENAME is a file that the user who starts the database service has the permission to operate. For example, the value is a file in the data directory.
-o OPTIONS	Specifies options to be passed from openGauss directly to the gaussdb command. The options should usually be surrounded by single or double quotation marks to ensure that they are transferred as a whole.	Parameters supported in gaussdb.
-p PATH-TO-POSTGRES	Specifies the location of the executable file of the gaussdb.	By default, the gaussdb executable file is taken from the same directory as gs_ctl.

Table 4 Common parameters for stop and restart

Parameter	Description	Value Range
-m, --mode=MODE	Specifies the disabled mode.	Values of mode: smart: The host is immediately disconnected, which is the same as fast. fast: All active transactions are rolled back and all clients are disconnected forcibly, and then the server is disabled. immediate: The server is shut down forcibly and fault recovery occurs on the next startup. Default value: fast

Parameter

Description

Value Range

-m, --mode=MODE

Specifies the disabled mode.

Values of mode:

smart: The host is immediately disconnected, which is the same as fast.
fast: All active transactions are rolled back and all clients are disconnected forcibly, and then the server is disabled.
immediate: The server is shut down forcibly and fault recovery occurs on the next startup.

Default value: fast

Table 5 switchover parameters

Parameter	Description	Value Range
-m SWITCHOVER-MODE	Specifies the HA switchover mode when the primary/standby instances are normal.	Values of mode: fast: All active transactions are rolled back and all clients are disconnected forcibly, and then the server is switched. smart: This mode is not supported in this version. immediate: This mode is not supported in this version. Default value: fast

Parameter

Description

Value Range

-m SWITCHOVER-MODE

Specifies the HA switchover mode when the primary/standby instances are normal.

Values of mode:

fast: All active transactions are rolled back and all clients are disconnected forcibly, and then the server is switched.
smart: This mode is not supported in this version.
immediate: This mode is not supported in this version.

Default value: fast

Table 6 build parameters

Parameter	Description	Value Range
-b MODE	Specifies the mode of the standby server on the DN to be recreated.	Values of mode: full: Fully resynchronizes the data directory of the primary server using an image. incremental: Incrementally restores the standby server based on the differences between the data of primary and standby DNs found in Xlogs. Note that incremental rebuilding is used for scenarios of the primary-standby HA inconsistent logs. Incremental rebuilding does not apply to the scenario where one primary and one standby are deployed and the maximum HA is not enabled. In this scenario, you need to perform full rebuilding or enable the maximum HA before performing the incremental rebuilding. The server cannot be restored using the incremental rebuilding method if the standby server data file is damaged or the data directory is lost. Restore the standby server using the incremental rebuilding method. auto (not specified): Select incremental first and then full after incremental fails for three times. Default value: auto
-r, --recvtimeout=INTERVAL	Specifies the timeout duration that the log of the standby server receives the host response during the rebuilding process.	Value range: an integer (second). Default value: 120s
-q	Specifies whether to automatically restart after the rebuilding is complete. If this parameter is specified, the system does not automatically restart. If this parameter is not specified, the system automatically restarts.	None

Parameter

Description

Value Range

-b MODE

Specifies the mode of the standby server on the DN to be recreated.

Values of mode:

full: Fully resynchronizes the data directory of the primary server using an image.

incremental: Incrementally restores the standby server based on the differences between the data of primary and standby DNs found in Xlogs.

Note that incremental rebuilding is used for scenarios of the primary-standby HA inconsistent logs.

Incremental rebuilding does not apply to the scenario where one primary and one standby are deployed and the maximum HA is not enabled. In this scenario, you need to perform full rebuilding or enable the maximum HA before performing the incremental rebuilding.

The server cannot be restored using the incremental rebuilding method if the standby server data file is damaged or the data directory is lost. Restore the standby server using the incremental rebuilding method.

auto (not specified): Select incremental first and then full after incremental fails for three times.

Default value: auto

-r, --recvtimeout=INTERVAL

Specifies the timeout duration that the log of the standby server receives the host response during the rebuilding process.

Value range: an integer (second).

Default value: 120s

-q

Specifies whether to automatically restart after the rebuilding is complete.

If this parameter is specified, the system does not automatically restart.

If this parameter is not specified, the system automatically restarts.

None

Table 7 restore parameters

Parameter	Description	Value Range
--remove-backup	Specifies whether to delete an incremental backup set.	None

Table 8 query parameters

Parameter	Description	Value Range
-L	Queries the LSN and displays the maximum length.	None