Using gsql to Connect to a Database

gsql is a database connection tool running in the CLI provided by GaussDB. gsql provides basic and advanced functions of databases to facilitate user operations. This section describes how to use gsql to connect to a database. For details about how to use gsql, see "Database Connection Tools > gsql for Connecting to a Database" in Tool Reference.

Precautions

By default, when a client has been idle for the period specified by GUC parameter session_timeout after connecting to a database, the client automatically disconnects from the database. To disable the timeout setting, set GUC parameter session_timeout to 0.

Prerequisites

You have contacted the administrator for connection information.

Remotely Connecting to a Database

Contact an administrator to configure the remote connection.
On the host, upload the client tool package and configure environment variables for the gsql client.
1. Log in to the client.
2. Create the /tmp/tools directory. (The /tmp/tools directory is only an example. You can also create another directory.)
```
mkdir /tmp/tools
```
3. Obtain the tool package GaussDB-Kernel_Database version number_OS version number_64bit_gsql.tar.gz from the software installation package and upload it to the /tmp/tools directory.
  - The software package is located where you put it before installation. Set it based on the actual situation.
  - The tool package name may vary in different OSs. Select the tool package suitable for your OS.
4. Decompress the package.
```
cd /tmp/tools
tar -zxvf GaussDB-Kernel_Database version number_OS version number_64bit_gsql.tar.gz
```
5. Set environment variables.
  Open the ~/.bashrc file.
```
vi ~/.bashrc
```
  Enter the following content and run :wq! to save and exit:
```
export PATH=/tmp/tools/bin:$PATH
export LD_LIBRARY_PATH=/tmp/tools/lib:$LD_LIBRARY_PATH
```
6. Make the environment variables take effect.
```
source ~/.bashrc
```
Connect to a database.

After the database is installed, a database named postgres is generated by default.
```
gsql -d postgres -h 10.10.0.11 -U jack -p 8000
Password for user jack:
```
postgres is the name of the database to be connected, 10.10.0.11 is the IP address of the server where the CN resides, jack is the username for logging in to the database, 8000 is the port number of the CN. The IP address and port number of the connected server can be replaced with those of the server where the DN resides. gsql allows you to use domain names instead of IP addresses.

In a multi-CN database environment, if you want to skip a faulty CN, you can use gsql to connect to a normal CN.

For example, if there are three CNs in a database instance, and the IP addresses and port numbers of the three CNs are 10.10.0.11:8000, 10.10.0.12:8002, and 10.10.0.13:8004, respectively, you run the following command:
```
gsql -d postgres -h 10.10.0.11,10.10.0.12,10.10.0.13 -U jack -p 8000,8002,8004
```
gsql connects to the three IP addresses and port numbers in sequence. If any CN is not normal, gsql attempts to connect to the next IP address and port number until it successfully connects to a normal CN. You can set the value of the PGTARGETSESSIONATTRS environment variable to connect to different types of nodes. For more information, see the description of the host parameter in section "Database Connection Tools > gsql for Connecting to a Database" in Tool Reference.

The following command demonstrates how to use an IPv6 address to connect to a database:
```
gsql -d postgres -h 2407:c182:14f0:594:er63:49c5:493q:594c -U jack -p 8000
```
- In the preceding example, user jack is a common user created by the database initial user.
- By default, the initial user of the database is not allowed to remotely connect to the database. If Kerberos authentication is enabled in a cluster, the initial user is allowed to remotely connect to the database in the cluster.