Help Center/ GaussDB/ Developer Guide(Centralized_V2.0-8.x)/ Database Quick Start/ Connecting to a Database/ Using gsql to Connect to a Database
Updated on 2025-05-29 GMT+08:00
View PDF
Share

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 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

  1. Contact an administrator to configure the remote connection.
  2. 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. Create tools in the /tmp directory. (The /tmp/tools directory is only an example. You can also create other directories.) 
      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 proper tool package based on the OS you use.
    4. Decompress the package. 
      cd /tmp/tools
tar -zxvf GaussDB-Kernel_Database version number_OS version number_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.

      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. Make the environment variables take effect. 
      source ~/.bashrc

  3. Connect to a database.

    After a database is installed, the postgres database 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. gsql allows you to use domain names instead of IP addresses.

    In a centralized database instance environment, if the IP addresses of the three instance nodes are 10.10.0.11, 10.10.0.12, and 10.10.0.13, respectively, you run the following command to connect to the primary node:

    gsql -d postgres -h 10.10.0.11,10.10.0.12,10.10.0.13 -U jack -p 8000

    gsql connects to the three IP addresses in sequence. If the current IP address is not the primary node, gsql disconnects from the IP address and attempts to connect to the next IP address until the primary node is found. 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
    • 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 a cluster, the initial user is allowed to remotely connect to the database in the cluster.

Parent topic: Connecting to a Database