gaussdb

Background

gaussdb is a major process of openGauss and also an executable command. A database process can be started using gaussdb.

Syntax

gaussdb [OPTION]...

Description

To access the database, the client application connects (over a local network or the Internet) to a running gaussdb process. Then the process starts an independent thread to handle the connection.

NOTICE: When starting the database using gaussdb, you also need to open another window to connect to the database or use the symbol (&) to enable the application to run in the background.

A gaussdb process manages all data in a database. A system can operate multiple gaussdb processes using different data directories and port numbers. When gaussdb is started, the location of the data directory must be specified by -D. Typically, -D points directly to the database directory created by gs_initdb.

By default, gaussdb starts in the foreground and prints log information to the standard error. In practice, most gaussdb processes start automatically on the background when the system is started.

The gaussdb tool can also be called in single-user mode. The primary use for this mode is during the initialization of gs_initdb. Sometimes, it is used for debugging or disaster recovery. However, running a single-user server is not truly suitable for debugging the server, because no realistic inter-process communication and locking happens. When the gaussdb command is called in single-user mode from the shell, you can enter queries, and the results will be printed to the screen, but in a form that is more favorable for developers rather than common users. In single-user mode, the session user ID is set to 1 and given the administrator permission. The user does not need to be existent. Therefore, servers in single-user mode can be used to manually recover damaged system catalogs.

Options

gaussdb supports command parameters listed in Table 1.

Table 1 Parameter description

Parameter	Description	Value Range
-B NBUFFERS	Sets the number of shared buffers to be used by the server processes.	-
-b BINARY UPGRADES	Binary upgrade flag.	-
-c NAME=VALUE	Names a running parameter. -c can appear multiple times to set multiple parameters.	-
-C NAME	Prints the value of a specified parameter during running and then exits. It can be used on a running server, and returns values from postgresql.conf.	The value can be the value of any parameter in the postgresql.conf file.
-d 1-5	Sets the debug level. The value ranges from 1 to 5. The higher this value is set, the more debugging output is written to the server logs.	Value range: 1–5 NOTE: If the value is less than or equal to 0, only notice-level information is recorded.
-D DATADIR	Specifies the file system location of the data directory or configuration files.	User-defined value
-e	Sets the default date style to "European", that is, DMY ordering of input date fields. This also causes the day to be printed before the month in certain date output formats.	-
-F	Disables fsync calls for performance improvement, at the risk of data corruption in the event of a system crash. Specifying this option is equivalent to disabling the fsync parameter.	-
-h HOSTNAME	Specifies the host name or IP address on which gaussdb listens on TCP/IP connections from client applications.	Existing host name or IP address at the front-end
-i	Allows remote clients to communicate with the server through TCP/IP (Internet domain socket) connections.	-
-k DIRECTORY	Specifies the directory of the Unix domain socket on which gaussdb listens on connections from client applications.	The default value is /tmp. You can change the value during compilation.
-l	Allows remote clients to connect to the server via secure socket layer (SSL).	-
-N MAX-CONNECT	Sets the maximum number of client connections that this server will accept. The default value of this parameter is automatically chosen by gs_initdb. Specifying this option is equivalent to setting the max_connections configuration parameter.	Value range: positive integer
-M SERVERMODE	Specifies the startup mode.	SERVERMODE can be set to 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 server is in pending mode to be promoted to a primary server or demoted to a standby server. cascade_standby: The local server starts as a cascaded standby server. hadr_main_standby: The local node starts as the first standby node in the streaming DR scenario.
-o OPTIONS	Sends OPTIONS to all server processes. The syntax is kept, but it does not support any function.	-
-p PORT	Specifies the TCP/IP port or local Unix domain socket filename extension on which gaussdb is to listen for connections from client applications. The default port number is 8000.	A positive integer within the port range supported by the OS
-s	Prints time information and other statistics at the end of each command.	-
-S WORK-MEM	Specifies the amount of memory to be used by internal sorts and hashes before resorting to temporary disk files.	Unit: KB
--single_node	Starts a single DN database.	-
-V, --version	Prints the gaussdb version information and exits.	-
--NAME=VALUE	Names a running parameter.	-
--describe-config	Describes configuration parameters and then exits.	-
--securitymode	Runs in security mode. NOTICE: In security mode, COPY TO/FROM filename cannot be executed, permissions cannot be granted to the public role, and tablespaces cannot be created or modified. Users can create, modify, delete, and use foreign tables only when they have the USEFT attribute.	-
-?, --help	Displays help information about gaussdb command parameters and exits.	-

Parameters described in Table 2 are used for debugging purposes, and in some cases for assisting in restoring severely damaged databases. Do not use these parameters for debugging if databases are providing services for applications.

Table 2 Developer options

Parameter	Description	Value Range
-f s\|i\|n\|m\|h	Forbids the use of particular scan and join methods.	Value range: s: stops a sequence. i: scans indexes. n: closes a nested loop. m: merges join. h: hashes join.
-n	Debugs problems that cause a server process breakdown. Usually, it will instruct all other server processes to terminate and then reinitialize the shared memory and semaphores. This option specifies that gaussdb will not reinitialize shared memory.	-
-O	Allows users to modify system catalogs.	-
-P	Ignores system indexes when reading system catalogs, but still updates the indexes when modifying the tables.	-
-t pa\|pl\|ex	Prints timing statistics for each query relating to each of the major system modules.	-
-T	Debugs problems that cause a server process breakdown. This option specifies that gaussdb will stop all other server processes by sending the signal SIGSTOP, but will not cause them to exit. This permits system programmers to manually collect core dumps from all server processes.	-
-W NUM	Specifies the number of seconds to wait before a new server process is started.	Unit: s
--localxid	Uses the local transaction ID instead of the global transaction ID. NOTICE: This option is used only for gs_initdb. Using this option may cause database inconsistency.	Existing local transaction ID

Options listed in Table 3 apply only to the single-user mode.

Table 3 Options for the single-user mode

Parameter	Description	Value Range
--single	Selects the single-user mode. This must be the first option of the command.	-
DBNAME	Specifies the name of the database to be accessed.	String. The default value is the username.
-d 0-5	Re-specifies the debug level.	0-5
-E	Echoes all commands.	-
-j	Disables use of newline as a statement delimiter.	-
-r FILENAME	Saves all server standard output and standard errors to filename.	-

Table 4 Options for the automatic startup mode

Parameter	Description	Value Range
--boot	Enables the automatic startup mode. This must be the first option of the command.	-
-r FILENAME	Saves all server standard output and standard errors to filename.	-
-x NUM	Specifies a new server thread type. The automatic startup mode can be used during database initialization. This parameter starts various threads to execute different logics. Generally, this parameter is not used because the automatic startup mode is seldom used.	-

Table 5 Options for the upgrade mode

Parameter	Description	Value Range
-u NUM	Specifies the database kernel version before the upgrade.	-

Except the preceding parameters, all other parameters in postgres.conf can be transferred to GaussDB in --guc_name=guc_value mode when GaussDB is started. Example: --enable_fast_query_shipping=off

Environment Variables

PGLINETENCODING: indicates the default character encoding used by clients. The clients can override this variable individually. This value can also be set in the configuration file.
PGDATESTYLE: indicates the default value of the DateStyle run-time parameter. The use of this environment variable is deprecated.
TZ: indicates the time zone of the server.

Error Processing

A failure message mentioning semget or shmget probably indicates that you need to reconfigure your kernel to provide adequate shared memory and semaphore. You can decrease shared_buffers to reduce the shared memory consumption of openGauss, or decrease max_connections to reduce the semaphore consumption of openGauss.

A failure message suggesting that another server is already running should be checked carefully, for example by using the following command depending on your system:

ps ax | grep gaussdb

ps -ef | grep gaussdb

If you are certain that no conflicting server is running, you can remove the lock file mentioned in the message and try again.

A port binding failure message indicates that the port is already in use by a non-openGauss process. This message may also be reported if you terminate gaussdb and immediately restart it using the same port. In this case, you must simply wait a few seconds until the operating system closes the port before trying again. Finally, you may get this error if you specify a port number that your operating system considers it to be reserved. For example, the Unix considers ports whose IDs are under 1024 to be “trusted” and permits only Unix administrators to access the Unix.

NOTICE:
Using SIGKILL to kill the main process prevents gaussdb from releasing system resources (such as shared memory and semaphores) that is holds, which affects new processes.
To properly terminate the server process, signals SIGTERM, SIGINT, and SIGQUIT can be used. SIGTERM will wait for all clients to terminate before exit. SIGINT will forcibly disconnect all clients, and SIGQUIT will exit immediately without proper shutdown, resulting in a recovery run during restart.
The SIGHUP signal will reload the server configuration files. It is also possible to send SIGHUP to an individual server process, but that is usually not sensible.
To cancel a running query, send the SIGINT signal to the process running that command.

Usage

Run the following command to start a server in single-user mode:

gaussdb --single -D /usr/local/pgsql/data other-options my_database

Use -D to provide the correct path of the database directory for the server. Besides, specify the name of the existing particular database.

NOTICE:
In most cases, the single-user mode server treats newline as the command entry terminator. To continue a command across multiple lines, you must type a backslash just before each newline except the last one.
If you use the -j option, then newline does not terminate command entry. In this case, the server will read the standard input until the end-of-file (EOF) marker, then process the input as a single command string. Backslashs and newlines are treated as common characters in this case.
To quit the session, type EOF (by pressing Ctrl+D). If you have used -j, two consecutive EOFs are needed to exit the session.
The single-user mode server does not provide complex line-editing functions (no command history, for example). The single-user mode also does not do any background processing, like automatic checkpoints.

Examples

Run the following command to start gaussdb in the background using the default value:
```
nohup gaussdb >logfile 2>&1 </dev/null  &
```
Start gaussdb on a specified port (for example, 1234). The -D parameter indicates the data directory after gs_initdb initialization.
```
gaussdb -p 1234 -D /usr/local/pgsql/data
```
To connect to this server using gsql, specify this port with the -p option:
```
gsql -d postgres -p 1234
```