主要内容为使用gsql数据库开发调试工具连接openGauss数据库。

gsql客户端工具

gsql是openGauss提供在命令行下运行的数据库连接工具，可以通过此工具连接服务器并对其进行操作和维护，除了具备操作数据库的基本功能，gsql还提供了若干高级特性，便于用户使用。

gsql连接数据库

gsql是openGauss自带的客户端工具。使用gsql连接数据库，可以交互式地输入、编辑、执行SQL语句。

确认连接信息

客户端工具通过数据库主节点连接数据库。因此连接前，需获取数据库主节点所在服务器的IP地址及数据库主节点的端口号信息。

步骤 1 切换到omm用户，以操作系统用户omm登录数据库主节点。

[root@db1 script]# su - omm 

步骤 2 使用“gs_om -t status --detail”命令查询openGauss各实例情况。

[omm@db1 ~]$ gs_om -t status --detail

情况显示如下：

[ DBnode State ] 
 
node        node_ip      instance                    state 
------------------------------------------------------------------------------------- 
1  db1 192.168.0.58    6001 /gaussdb/data/db1 P Primary Normal

如上部署了数据库主节点实例的服务器IP地址为192.168.0.58。数据库主节点数据路径为“/gaussdb/data/db1”。

步骤 3 确认数据库主节点的端口号。

在步骤2查到的数据库主节点数据路径下的postgresql.conf文件中查看端口号信息。示例如下：

port = 26000				# (change requires restart)
#ssl_renegotiation_limit = 0		# amount of data between renegotiations, no longer supported
#tcp_recv_timeout = 0			# SO_RCVTIMEO, specify the receiving timeouts until reporting an error(change requires restart)
#comm_sctp_port = 1024			# Assigned by installation (change requires restart)
#comm_control_port = 10001		# Assigned by installation (change requires restart)
					# supported by the operating system:
						# The heartbeat thread will not start if not set localheartbeatport and remoteheartbeatport.
						# e.g. 'localhost=xx.xx.xxx.2 localport=12211 localheartbeatport=12214 remotehost=xx.xx.xxx.3 remoteport=12212 remoteheartbeatport=12215, localhost=xx.xx.xxx.2 localport=12213 remotehost=xx.xx.xxx.3 remoteport=12214'
					#   %r = remote host and port
alarm_report_interval = 10

26000为数据库主节点的端口号。
请在实际操作中记录数据库主节点实例的服务器IP地址，数据路径和端口号，并在之后操作中按照实际情况进行替换。

本地连接数据库

步骤 1 切换到omm用户，以操作系统用户omm登录数据库主节点。

[root@db1 script]# su - omm

步骤 2启动数据库服务

[root@db1 script]# gs_om -t start

显示如下，启动成功。

Starting cluster.
=========================================
=========================================
Successfully started.

步骤 3连接数据库。

执行如下命令连接数据库。

[omm@db1 ~]$ gsql -d postgres -p 26000 -r 

其中postgres为需要连接的数据库名称，26000为数据库主节点的端口号。请根据实际情况替换。
连接成功后，系统显示类似如下信息：

gsql ((openGauss 1.0.0 build 290d125f) compiled at 2020-05-08 02:59:43 commit 2143 last mr 131 
Non-SSL connection (SSL connection is recommended when requiring high-security) 
Type "help" for help. 
 
postgres=# 

omm用户是管理员用户，因此系统显示“DBNAME=#”。若使用普通用户身份登录和连接数据库，系统显示“DBNAME=>”。
“Non-SSL connection”表示未使用SSL方式连接数据库。如果需要高安全性时，请用SSL进行安全的TCP/IP连接。

步骤 4 退出数据库。

postgres=# \q   

gsql获取帮助

前提条件

以下操作在openGauss的数据库主节点所在主机上执行（本地连接数据库），切换到omm用户。

su - omm

连接数据库时，可以使用如下命令获取帮助信息

gsql --help

显示如下帮助信息：

...... 
Usage: 
  gsql [OPTION]... [DBNAME [USERNAME]] 
 
General options: 
  -c, --command=COMMAND    run only single command (SQL or internal) and exit 
  -d, --dbname=DBNAME      database name to connect to (default: "postgres") 
  -f, --file=FILENAME      execute commands from file, then exit 
......

连接到数据库后，可以使用如下命令获取帮助信息

步骤 1 使用如下命令连接数据库。

gsql -d postgres -p 26000 -r 

步骤 2 输入help指令。

postgres=#help

显示如下帮助信息：

You are using gsql, the command-line interface to gaussdb. 
Type:  \copyright for distribution terms 
       \h for help with SQL commands 
       \? for help with gsql commands 
       \g or terminate with semicolon to execute query 
       \q to quit

步骤 3 查看版权信息。

postgres=#\copyright

显示如下版权信息：

openGauss Database Management System
Copyright (c) Huawei Technologies Co., Ltd. 2020. All rights reserved.

步骤 4 查看openGauss支持的所有SQL语句。

postgres=#\h

显示如下信息：

Available help: 
  ABORT                             
  ALTER AGGREGATE 
  ALTER APP WORKLOAD GROUP                   
... ...

步骤 5 查看CREATE DATABASE命令的参数可使用下面的命令。

postgres=#\help CREATE DATABASE

显示如下帮助信息：

Command:     CREATE DATABASE 
Description: create a new database 
Syntax: 
CREATE DATABASE database_name 
     [ [ WITH ] {[ OWNER [=] user_name ]| 
           [ TEMPLATE [=] template ]| 
           [ ENCODING [=] encoding ]| 
           [ LC_COLLATE [=] lc_collate ]| 
           [ LC_CTYPE [=] lc_ctype ]| 
           [ DBCOMPATIBILITY [=] compatibility_type ]| 
           [ TABLESPACE [=] tablespace_name ]| 
           [ CONNECTION LIMIT [=] connlimit ]}[...] ];

步骤 6 查看gsql支持的命令。

postgres=# \? 

显示如下信息：

General 
  \copyright             show PostgreSQL usage and distribution terms 
  \g [FILE] or ;         execute query (and send results to file or |pipe) 
  \h(\help) [NAME]              help on syntax of SQL commands, * for all commands 
  \q                     quit gsql 
... ...

步骤 7 退出数据库

postgres=# \q

gsql命令使用

前提条件

以下操作在openGauss的数据库主节点所在主机上执行（本地连接数据库），切换到omm用户。

su - omm

执行一条字符串命令

gsql命令直接执行一条显示版权信息的字符串命令

gsql -d postgres -p 26000 -c "\copyright"

显示如下，显示后退出gsql环境：

openGauss Database Management System
Copyright (c) Huawei Technologies Co., Ltd. 2020. All rights reserved
$

使用文件作为命令源而不是交互式输入

步骤 1 创建文件夹存放相关文档。

mkdir /home/omm/openGauss

步骤 2 创建文件，例如文件名为“mysql.sql”，并写入可执行sql语句“select * from pg_user;”。

vi /home/omm/openGauss/mysql.sql

文件打开输入i，进入INSERT模式，输入” select * from pg_user;”。

select * from pg_user;

然后点击Esc，输入“：wq”保存文档并退出。

步骤 3 执行如下命令使用文件作为命令源。

gsql -d postgres -p 26000 -f  /home/omm/openGauss/mysql.sql    

结果如下，并且gsql将在处理完文件后结束：

usename | usesysid | usecreatedb | usesuper | usecatupd | userepl |  passwd  | valbegin | valuntil |   respool    | parent | spacel
imit | useconfig | nodegroup | tempspacelimit | spillspacelimit 
---------+----------+-------------+----------+-----------+---------+----------+----------+----------+--------------+--------+-------
-----+-----------+-----------+----------------+-----------------
 omm     |       10 | t           | t        | t         | t       | ******** |          |          | default_pool |      0 |       
     |           |           |                | 
 jack     |    16385 | f           | f        | f         | f       | ******** |          |          | default_pool |      0 |       
     |           |           |                | 
(2 rows)

total time: 3  ms

步骤 4 如果FILENAME是-（连字符），则从标准输入读取。

gsql -d postgres -p 26000 -f -
postgres=# select * from pg_user;
usename | usesysid | usecreatedb | usesuper | usecatupd | userepl |  passwd  | valbegin | valuntil |   respool    | parent | spacel
imit | useconfig | nodegroup | tempspacelimit | spillspacelimit 
---------+----------+-------------+----------+-----------+---------+----------+----------+----------+--------------+--------+-------
-----+-----------+-----------+----------------+-----------------
 omm     |       10 | t           | t        | t         | t       | ******** |          |          | default_pool |      0 |       
     |           |           |                | 
 joe     |    16385 | f           | f        | f         | f       | ******** |          |          | default_pool |      0 |       
     |           |           |                | 
(2 rows)

步骤 5 退出数据库连接。

postgres=# \q               
total time: 174163  ms

列出所有可用的数据库（\l的l表示list）

gsql -d postgres -p 26000 -l    

结果如下，并且gsql将在显示后结束：

        List of databases
  Name    | Owner | Encoding  | Collate | Ctype | Access privileges 
-----------+-------+-----------+---------+-------+-------------------
 db_tpcc   | joe     | SQL_ASCII | C       | C     | 
 postgres  | omm   | SQL_ASCII | C       | C     | 
 template0 | omm   | SQL_ASCII | C       | C     | =c/omm           +
           |         |           |         |       | omm=CTc/omm
 template1 | omm   | SQL_ASCII | C       | C     | =c/omm           +
           |         |           |         |       | omm=CTc/omm
(4 rows)
$

设置gsql变量NAME为VALUE

步骤 1 设置foo的值为bar。

gsql -d postgres -p 26000 -v foo=bar 

步骤 2 在数据库能够显示foo的值。

postgres=# \echo :foo
bar

步骤 3退出数据库连接。

postgres=> \q

打印gsql版本信息。

gsql -V

结果如下，并且gsql将在显示后结束：

gsql (openGauss 1.0.0 build 0bd0ce80) compiled at 2020-06-30 18:19:23 commit 0 last mr  

使用文件作为输出源。

步骤 1创建文件，例如文件名为“output.txt”。

touch  /home/omm/openGauss/output.txt

步骤 2执行如下命令，除了正常的输出源之外，把所有查询输出记录到文件中。

gsql -d postgres -p 26000 -L /home/omm/openGauss/output.txt

进入gsql环境，输入以下语句：

postgres=# create table mytable (firstcol int);
CREATE TABLE
postgres=# insert into mytable values(100);
INSERT 0 1
postgres=# select * from mytable ;
 firstcol 
----------
      100
(1 row)
postgres=# \q

步骤 3 查看“output.txt”文档中的内容如下：

cat /home/omm/openGauss/output.txt

显示如下：

********* QUERY **********
create table mytable (firstcol int);
**************************

CREATE TABLE
********* QUERY **********
insert into mytable values(100);
**************************

INSERT 0 1
********* QUERY **********
select * from mytable;
**************************

 firstcol
----------
      100
(1 row)

将所有查询输出重定向到文件FILENAME

步骤 1 创建文件，例如文件名为“outputOnly.txt”。

touch /home/omm/openGauss/outputOnly.txt

步骤 2 执行如下命令

gsql -d postgres -p 26000 -o /home/omm/openGauss/outputOnly.txt 

步骤 3 进入gsql环境，输入以下语句：

postgres=# drop table mytable;
postgres=# create table mytable (firstcol int);
postgres=# insert into mytable values(100);
postgres=# select * from mytable;
postgres=# \q 

所有操作都没有回显。

步骤 4 查看“outputOnly.txt”文档中的内容如下：

cat /home/omm/openGauss/outputOnly.txt

显示如下：

DROP TABLE
CREATE TABLE
INSERT 0 1
 firstcol
----------
      100
(1 row)
"/opt/software/openGauss/output.txt" 8L, 76C     

安静模式

安静模式：执行时不会打印出额外信息

gsql -d postgres -p 26000 -q

进入gsql环境，输入以下语句：

postgres=# create table t_test (firstcol int);
postgres=# insert into t_test values(200);
postgres=# select * from t_test;
 firstcol 
----------
      200
(1 row)

postgres=# \q

连接上数据库，创建数据库和插入数据等都没有回显信息。

单行运行模式

单行运行模式：这时每个命令都将由换行符结束，像分号那样

gsql -d postgres -p 26000 -S

进入gsql环境，输入以下语句：

postgres^# select * from t_test;
 firstcol 
----------
      200
(1 row)

postgres^# select * from t_test
 firstcol 
----------
      200
(1 row)

postgres=# \q

语句最后结尾有;号和没有;号，效果都一样。

编辑模式

步骤 1 如下命令连接数据库，开启在客户端操作中可以进行编辑的模式。

gsql -d postgres -p 26000 -r

步骤 2 进入gsql环境，输入以下语句：

步骤 3 写完后不要按回车，光标在最后闪烁。

步骤 4 按“向左”键讲光标移动到“*”，将此符号修改为“firstcol”。

编辑模式“上下左右键”，“删除键”和“退格键”都可以使用，并且按下“*向上”、“向下”键可以切换输入过的命令。

步骤 5 退出数据库连接

postgres=# \q

远程使用用户名和密码连接数据库

远程使用jack用户连接ip地址为192.168.0.58端口号为26000的数据库。
登录客户端主机(192.168.0.58)，使用以下命令远程登录数据库。

gsql -d postgres -h 192.168.0.58 -U jack -p 26000 -W Bigdata@123;

-d参数指定目标数据库名、-U参数指定数据库用户名、-h参数指定主机名、-p参数指定端口号信息,-W参数指定数据库用户密码。
进入gsql环境，显示如下：

gsql ((openGauss 1.0 build ec0e781b) compiled at 2020-04-27 17:25:57 commit 2144 last mr 131 )
SSL connection (cipher: DHE-RSA-AES256-GCM-SHA384, bits: 256)
Type "help" for help.

postgres=> 

gsql元命令使用

前提条件

以下操作在openGauss的数据库主节点所在主机上执行（本地连接数据库），使用gsql连接到openGauss数据库。

步骤 1切换到omm用户，以操作系统用户omm登录数据库主节点。

su - omm

步骤 2gsql连接数据库。

gsql -d postgres -p 26000 -r 

打印当前查询缓冲区到标准输出

步骤 1创建“outputSQL.txt”文件。

touch /home/omm/openGauss/outputSQL.txt

步骤 2连接数据库。

gsql -d postgres -p 26000 -r

步骤 3输入以下语句。

postgres=# select * from pg_roles;
 rolname | rolsuper | rolinherit | rolcreaterole | rolcreatedb | rolcatupdate | rolcanlogin | rolreplication | rolauditadmin | rolsy
stemadmin | rolconnlimit | rolpassword | rolvalidbegin | rolvaliduntil |  rolrespool  | rolparentid | roltabspace | rolconfig |  oid
  | roluseft | rolkind | nodegroup | roltempspace | rolspillspace 
---------+----------+------------+---------------+-------------+--------------+-------------+----------------+---------------+------
----------+--------------+-------------+---------------+---------------+--------------+-------------+-------------+-----------+-----
--+----------+---------+-----------+--------------+---------------
 omm     | t        | t          | t             | t           | t            | t           | t              | t             | t    
          |           -1 | ********    |               |               | default_pool |           0 |             |           |    1
0 | t        | n       |           |              | 
 joe     | f        | t          | f             | f           | f            | t           | f              | f             | f    
          |           -1 | ********    |               |               | default_pool |           0 |             |           | 1725
5 | f        | n       |           |              | 
(3 rows)

postgres=# \w /home/omm/openGauss/outputSQL.txt
postgres=# \q

步骤 4打开文件“outputSQL.txt”文件，查看其中内容。

cat /home/omm/openGauss/outputSQL.txt

显示如下：

select * from pg_roles;

导入数据

步骤 1连接数据库。

gsql -d postgres -p 26000 -r

步骤 2创建目标表a。

postgres=# CREATE TABLE a(a int);

步骤 3导入数据，从stdin拷贝数据到目标表a。

postgres=# \copy a from stdin;

出现>>符号提示时，输入数据，输入.时结束。

Enter data to be copied followed by a newline. 
End with a backslash and a period on a line by itself. 
>> 1 
>> 2 
>> \.

步骤 4查询导入目标表a的数据。

postgres=# SELECT * FROM a; 
 a  
--- 
 1 
 2 

退出数据库：

postgres=# \q

步骤 5从本地文件拷贝数据到目标表a，创建文件/home/omm/openGauss/2.csv。

vi /home/omm/openGauss/2.csv

步骤 6输入i，切换到INSERT模式，插入数据如下:

3
4
5

• 如果有多个数据，分隔符为‘，’。
• 在导入过程中，若数据源文件比外表定义的列数多，则忽略行尾多出来的列

步骤 7按下Esc键，输入“:wq”后回车，保存并退出。

步骤 8连接数据库。

gsql -d postgres -p 26000 -r

步骤 9如下命令拷贝数据到目标表。

postgres=# \copy a FROM '/home/omm//openGauss/2.csv' WITH (delimiter',',IGNORE_EXTRA_DATA 'on');

步骤 10查询导入目标表a的数据。

postgres=# SELECT * FROM a; 
 a  
--- 
1 
2 
3
4
5
(5 rows)

查询表空间

postgres=# \db  

显示如下：

postgres=> 
      List of tablespaces
    Name    | Owner | Location 
------------+-------+----------
 pg_default   | omm   | 
 pg_global    | omm   | 
(2 rows)

查询表的属性。

步骤 1 创建表customer_t1。

postgres=# DROP TABLE IF EXISTS customer_t1;
postgres=# CREATE TABLE customer_t1 
( 
    c_customer_sk             integer, 
    c_customer_id             char(5), 
    c_first_name              char(6), 
    c_last_name               char(8) 
);

步骤 2 查询表的属性。

postgres=# \d+;

显示如下：

Schema |    Name     | Type  | Owner |    Size    | Storage              | Description 
--------+-------------+-------+-------+------------+----------------------------------+-------------
 public | customer_t1 | table | omm   | 0 bytes    | {orientation=row,compression=no} | 
 public | mytable     | table | omm   | 8192 bytes | {orientation=row,compression=no} | 
 public | t_test      | table | omm   | 8192 bytes | {orientation=row,compression=no} | 
 public | ta          | table | omm   | 0 bytes    | {orientation=row,compression=no} | 
(4 rows)

步骤 3查询表customer_t1的属性。

postgres=# \d+ customer_t1;

显示如下：

                           Table "public.customer_t1"
    Column     |     Type     | Modifiers | Storage  | Stats target | Description 
---------------+--------------+-----------+----------+--------------+-------------
 c_customer_sk | integer      |           | plain    |              | 
 c_customer_id | character(5) |           | extended |              | 
 c_first_name  | character(6) |           | extended |              | 
 c_last_name   | character(8) |           | extended |              | 
Has OIDs: no
Options: orientation=row, compression=no

查询索引信息

步骤 1 在表customer_t1上创建索引。

create index customer_t1_index1 on customer_t1(c_customer_id);

步骤 2查询索引信息。

postgres=# \di+；

postgres=# \di+；
显示如下：

                               List of relations
 Schema |        Name     | Type  | Owner |    Table    |    Size    | Storage | Description 
--------+--------------------+-------+-------+-------------+------------+---------+-------------
 public | customer_t1_index1 | index | omm   | customer_t1 | 8192 bytes |         |

步骤 3查询customer_t1_index1索引的信息。

postgres=# \di+ customer_t1_index1

显示如下：

                                  List of relations
 Schema |        Name     | Type  | Owner |    Table    |    Size    | Storage | Description 
--------+--------------------+-------+-------+-------------+------------+---------+-------------
 public | customer_t1_index1 | index | omm   | customer_t1 | 8192 bytes |         |

切换数据库

步骤 1创建数据库。

DROP DATABASE IF EXISTS db_tpcc02;
CREATE DATABASE db_tpcc02;

步骤 2切换数据库。

postgres=# \c db_tpcc02;

显示如下：

Non-SSL connection (SSL connection is recommended when requiring high-security)
You are now connected to database "db_tpcc" as user "omm".
db_tpcc=# 

步骤 3退出数据库：

postgres=# \q