Using gsql to Connect to a Database

gsql provided by GaussDB is a database connection tool running in the CLI. 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 "Client Tools > gsql" in Tool Reference.

Precautions

By default, when a client has been idle for the period specified by session_timeout after connecting to a database, the client automatically disconnects from the database. To disable the timeout setting, set 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. The openEuler environment is used as an example.
1. Log in to the client.
2. Run the following command to create the /tmp/tools directory:
```
mkdir /tmp/tools
```
3. Obtain GaussDB-Kernel_VxxxRxxxCxx-XXXXX-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 actual situation.
  - The tool package name may vary in different OSs. Select the tool package suitable for your OS.
4. Run the following commands to decompress the package:
```
cd /tmp/tools
tar -zxvf GaussDB-Kernel_VxxxRxxxCxx-XXXXX-64bit-gsql.tar.gz
```
5. Log in to the server where the primary database node is located, and copy the bin directory in the database installation directory to /tmp/tools on the client host.
```
scp -r /opt/huawei/install/app/bin root@10.10.0.30:/tmp/tools
```
  In the preceding command, /opt/huawei/install/app indicates the {gaussdbAppPath} path configured in the clusterconfig.xml file, and 10.10.0.30 indicates the IP address of the client host.
6. Log in to the host where the client is installed and set environment variables.
  Run the following command to 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
```
7. Run the following command to 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. When connecting to a database for the first time, you can connect to this database.
```
gsql -d postgres -h 10.10.0.11 -U jack -p 8000
Password for user jack:
```
postgres is the name of the database, 10.10.0.11 is the IP address of the server where the primary node of the database resides, jack is the user for connecting to the database, and 8000 is the port number of the primary database node.

In a centralized database instance, when you need to connect to the primary node and the IP addresses of three nodes in the database instance are 10.10.0.11, 10.10.0.12, and 10.10.0.13, you can use the gsql -d postgres -h 10.10.0.11,10.10.0.12,10.10.0.13 -U jack -p 8000 command. gsql connects to the three IP addresses in sequence. If the current IP address is not the IP address of the primary node, gsql disconnects from the current IP address and attempts to connect to the next IP address, until the primary node is found.
- If a machine connected to GaussDB is not in the same network segment as GaussDB, the IP address specified by -h should be the value of coo.cooListenIp2 (application access IP address) set in Manager.
- By default, the initial user of the database is not allowed to remotely connect to the database. If Kerberos authentication is enabled in an instance, the initial user is allowed to remotely connect to the database in the instance.