gaussdb

Background

gaussdb is a major process of MogDB 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 & 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 data directory must be specified using the -data-dir option. Typically, -D points directly to the database directory created by gs_initdb.

By default, gaussdb starts in the foreground and prints log messages to the standard error stream. In practical applications, gaussdb should be automatically started as a background process at boot time in most cases.

The gaussdb command 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 useful for developers rather than common users. In single user mode, the session user ID is set to 1 and given the administrator rights. 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-line parameters listed in Table 1.

Table 1 Parameter description

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

Table 2 Developer options

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

Table 3 Options for the single-user mode

Table 4 Automatic startup mode options

Table 5 Upgrade mode options

In addition to the preceding parameters, all parameters in postgres.conf can be transferred to gaussdb using -guc_name=guc_value when gaussdb is started. For example: -enable_fast_query_shipping=off

Environment Variables

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

Error Handling

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

If a failure message suggesting that another server is running is reported, check the system using the following command based on your system:

ps ax | grep gaussdb

or

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 failure message indicating inability to bind to a port might indicate that the port is already in use by a non-MogDB 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:

• If possible, do not use SIGKILL to stop the main process. because the operation prevents gaussdb from releasing system resources (such as shared memory and semaphores) that it holds before terminating. This might cause problems for starting a fresh process.
• 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.
• The main server process uses SIGTERM to tell its subordinate server processes to quit properly and SIGQUIT to terminate without a cleanup. These signals should not be used by users. It is also unwise to send SIGKILL to a server process: The main process will interpret this as a crash and will force all the subordinate processes to quit as part of its standard crash-recovery pocedure.

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 command line 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. Backslashes and newlines are treated as common characters in this case.
• To quit the session, type EOF (Control+D). If you have used -j, two consecutive EOFs are needed to exit.
• 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.

Example

1. Run the following command to start gaussdb in the background using default values:

   nohup gaussdb >logfile 2>&1 </dev/null  &

2. Run the following command to start gaussdb with a specified port, for example, 1234:

   gaussdb --single_node -p -D data_dir

   To connect to this server using gsql, specify this port with the -p option:

   gsql -d postgres -p 1234