gs_ctl

init[db]

Initializes a DN.

start

Starts a DN.

restart

Restarts a DN.

build

Rebuilds the instance on the node where the instance needs to be rebuilt.

stop

Stops a DN.

reload

Reloads the configuration files (postgresql.conf and pg_hba.conf).

status

Displays the DN running status.

failover

Promotes the standby DN to the primary DN when the primary DN is faulty.

After the switchover is successful, run the gs_om -t refreshconf command to record the information about the primary and standby servers. Ensure that the gs_om -t refreshconf command is executed successfully. Otherwise, the database status will be affected when the database is restarted.

switchover

When the primary/standby DN relationship is normal, and the standby DN is switched to the primary DN for maintenance purposes, data will not be lost during the switchover.

query

Queries the status between the primary and standby DNs.

notify

Specifies the primary/standby DNs after startup.

kill

Sends semaphore to a specified process.

querybuild

Checks the rebuild process of a DN.

finishredo

Forcibly stops redo.

copy

Copies Xlogs in the dual-center DR mode based on shared storage.

member

The management of member nodes.

changerole

Change the role of a node.

setrunmode

Set the running mode.

-D, --pgdata=DATADIR

Specifies the data directory.

The value of DATADIR must be valid.

-s, --silent

Prints partial prompt information only for the reload, restart, and stop commands.

Prints information such as "gstl stopped, xxx". Information such as " waiting for server to shut down, server stopped" is not printed.

-

-t, --timeout=SECS

This parameter controls the following functions:

Maximum seconds for waiting the completion of database startup or shutdown.

Value range: integer (s)

Default value:

Maximum seconds for waiting the completion of database startup or shutdown: 60s.

-V , --version

Prints the gs_ctl version information and exits.

-

-w

Waits for the transaction to complete and then executes the database startup or shutdown operation.

Default value: If this parameter is not specified, the operation is executed until the transaction is complete.

-W

Does not wait for the transaction to complete and executes the database startup or shutdown operation forcibly.

-

-M

-M must be followed by the SERVERMODE parameter, which specifies the start mode of a database upon startup.

The value of SERVERMODE can be one of the following three:

• primary: The local host starts as the primary node.
• standby: The local host starts as the standby node.
• pending: The local host waits for switching to the primary or standby node.

-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.

Value range: unsigned integer

-q

The process does not automatically start after the build is complete. It needs to be started by the invoker.

-

-d

Prints more debugging information.

-

-P PASSWORD

Used together with the -U parameter and specifies the password of the user that connects to the local database.

-

-U USERNAME

Specifies the user that connects to the database. This parameter can be used only with the parameter notify, query, or querybuild.

For domain users, use the DOMAIN\username format.

Value range: users exist in openGauss.

Default value: If this parameter is not specified, the current OS user is used.

-Z NODE-TYPE

Can be "single_node"

-

-?, -h, --help

Displays help information about gs_ctl command parameters.

-

-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 the gaussdb command options to be transferred and executed by openGauss.

The options should usually be surrounded by single or double quotation marks to ensure that they are passed through as a whole.

Parameters supported by gaussdb

-p PATH-TO-POSTGRES

Specifies the location of the gaussdb executable.

By default, the gaussdb executable is taken from the same directory as gs_ctl. In most cases, it is not necessary to use this option.

-m, --mode=MODE

Specifies the stop mode.

Values of mode:

• fast: All active transactions are rolled back and all clients are disconnected forcibly, and then the server is stopped.
• immediate: The server is shut down forcibly and fault recovery occurs on the next startup.

Default value: fast

-f

All active transactions are rolled back and all clients are disconnected forcibly, and then the server is switched and no checkpoint is performed.

N/A

-m SWITCHOVER-MODE

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

Values of mode:

• smart: The cluster is switched over after all the clients are disconnected. If the server is in hot standby, recovery and replication flows will be terminated once all clients have been disconnected.

  Note: In the cluster environment, the cluster management connection and customer service connection make it difficult to execute the smart mode. Therefore, this mode is discarded in this version.

• fast: All active transactions are rolled back and all clients are disconnected forcibly, and then the server is switched.

Default value: fast

-b, --mode=MODE

Specifies the rebuild mode of a DN standby server.

Values of mode:

• full: fully resynchronizes the data directory of the primary DN using an image.
• incremental: incrementally restores the standby DN based on the differences between the data of primary and standby DNs found in Xlogs.
  WARNING:

  • Incremental rebuild is used for active-active clusters with inconsistent primary/standby logs.
  • If damaged data files and lost data directories of a standby DN cannot be restored by incremental rebuild, full rebuild can be used to restore the standby DN.
• auto (not specified): selects incremental first and then Full after incremental fails for three times.
• standby_full: uses the standby server to rebuild the standby server or uses the first standby server in a DR scenario to rebuild the faulty standby server in the DR database instance.
• copy_secure_files: In the streaming DR scenario, obtains the content in the gs_secure_files directory in the data directory of a specified node.
• copy_upgrade_file: obtains specified files required for the upgrade on a specified node in the Dorado DR scenario.
• cross_cluster_full: performs cross-cluster full build based on shared storage in the intra-city dual-center scenario.
• cross_cluster_incremental: performs cross-cluster incremental build based on shared storage in the same-city dual-center scenario.

Default value: auto

-r, --recvtimeout=INTERVAL

Specifies the timeout duration that a standby DN waits for receiving logs synchronized from the primary DN.

Value range: integer (s)

Default value: 120s

-q

After the rebuild is finished, whether to restart automatically.

In specified parameter scenarios, it does not restart automatically.

In unspecified scenarios, it restarts automatically. The default maximum waiting time for restart is 60 seconds. If the database fails to start successfully within this period, an error message will be displayed indicating that the system will no longer wait, and the command will exit. Subsequently, the status of the database startup can be confirmed using the `gs_om -t status --detail` command or other commands that check the database status.

-

-C CONNECTOR

Specifies the connection string used for connecting to the source DN to rebuild a DN on the current node. Only the connection from the standby server to the standby server is supported.

The connection string contains the IP address and port number of the DN to be rebuilt on the current node and those of the source DN. Its format is as follows:

'localhost=Local DN IP localport=Local DN Port+1 remotehost=DN IP remoteport=DN Port+1'

-L

Queries the LSN and displays the maximum length.

None

--operation

Adds or deletes nodes in DCF mode in an openGauss database instance.

• add: adds a node to the DCF node configuration of the database instance.
• remove: deletes a node from the DCF node configuration of the database instance.

-u, --nodeid

Specifies a new DCF node ID.

Unsigned integer

-i, --ip

Specifies an IP address used by the new node to communicate with the DCF module of the database instance.

Character string

-e, --port

Specifies a port number used by the new node to communicate with the DCF module of the database instance.

Integer

[-D, --pgdata=]DATADIR

Specifies the data directory.

Set DATADIR as required.

-G

Sets the group number in a DCF.

Integer

--priority

Sets the priority in a DCF.

Integer

-R, --role

Specifies the node role in DCF mode in an openGauss database instance. This role must be used on the node whose role is primary.

• passive: passive role
• follower: follower role

-u, --nodeid

Specifies a new DCF node ID.

Unsigned integer

[-D, --pgdata=]DATADIR

Specifies the data directory.

Set DATADIR as required.

-v, --votenum

Specifies the number of votes.

Unsigned integer

-x, --xmode

Specifies the running mode (used on minority DNs).

• minority: minority forcible startup
• normal: resuming

[-D, --pgdata=]DATADIR

Specifies the data directory.

Set DATADIR as required.

-I

The lwtid used to specify the thread for which the call stack is to be obtained.

Positive integers.

-Q

Specify the direction of xlog copy.

• copy_from_local：Copy from local to shared storage.
• copy_from_share：Copy from shared storage to local storage.
• force_copy_from_local：Force copy from local to shared storage.

-b MODE

Specify the mode of rebuilding the standby machine.

mode values:

-q

Whether to restart automatically after the rebuild is finished.

In specified parameter scenarios, it does not restart automatically.

In unspecified scenarios, it restarts automatically. The default maximum waiting time for restart is 60 seconds. If the database fails to start successfully within this period, an error message will be displayed indicating that the system will no longer wait, and the command will exit. Subsequently, the status of the database startup can be confirmed using the `gs_om -t status --detail` command or other commands that check the database status.

-

--enable-dss

Turn on the resource pooling switch.

-

-g

Enable resource pooling and specify nodes for building.

Value range: integer, [0-63], starting from 0.

Default value: 0.

Note: The `-g` input parameter refers to the resource pooling node ID, which is the `ss_instance_id`.

--instance-id=instance_id

The ID number of the instance when DSS and DMS are enabled.

Positive integer.

--vgname

Volume group name.

Data type: string.

For example: a volume group "+ data" or two volume groups separated by ","connection"+data,+log".

--socketpath

The socket file path used by the DSS instance process.

The socket file path for the dss instance process.