Using gsql to Connect to a Database

Updated on 2025-02-27 GMT+08:00

View PDF

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 "Client Tools > gsql" 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 the 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. 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.
  NOTE:
  - 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. Run the following commands to decompress the package:
```
cd /tmp/tools
tar -zxvf GaussDB-Kernel_VxxxRxxxCxx-XXXXX-64bit-gsql.tar.gz
```
5. 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
```
6. 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.
```
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.
NOTE:
- In the preceding example, user jack is a common user created by the database initialization 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.