前 言

gsql命令参考官方文档

简介

本指导书适用于对数据库开发调试工具的使用，通过该指导书可以使用gsql数据库开发调试工具连接openGauss数据库。

内容描述

本实验指导书主要内容为使用gsql数据库开发调试工具连接openGauss数据库。

前置条件

• 由于本实验主要是在openEuler操作系统上进行gsql开发调试工具连接数据库，需要掌握Linux系统的基本操作和系统命令，详细请参见附录一。
• 连接数据库后可以使用gsql元命令管理和使用数据库，需要掌握openGauss数据库的基本操作，数据库基本操作参见附录二。
  实验环境说明
• 组网说明
  本实验环境为openGauss数据库管理系统，安装在华为云openEuler弹性服务器ECS上。

客户端工具

1.1 实验介绍

1.1.1 关于本实验

本实验主要描述openGauss数据库的客户端工具的使用和连接数据库的方法。

1.1.2 实验目的

• 掌握gsql客户端工具本地连接数据库的方法;
• 掌握gsql客户端工具远程连接数据库的方法;
• 掌握gsql客户端工具使用方法；
• 掌握图形化界面客户端工具Data Studio的安装及使用方法。

1.2 gsql客户端工具

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

1.2.1 gsql连接数据库

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

1.2.1.1 确认连接信息

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

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

[root@db1 script]# su - omm 

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

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

情况显示如下：

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

• 步骤 3确认数据库主节点的端口号。
  在步骤2查到的数据库主节点数据路径下的postgresql.conf文件中查看端口号信息。示例如下：
  要根据自己的主节点修改路径

[omm@db1 ~]$ cat /gaussdb/data/db1997/postgresql.conf | grep port

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

1.2.1.2 本地连接数据库

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

su - omm

• 步骤 2启动数据库服务

gs_om -t start

• 步骤 3连接数据库。
  执行如下命令连接数据库。

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

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

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

• 步骤 4退出数据库。

postgres=# \q 

1.2.2 gsql获取帮助

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

切换到omm用户。

su - omm

使用如下命令获取帮助信息

gsql --help

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

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

gsql -d postgres -p 26000 -r

• 步骤 2输入help指令。

postgres=# help

• 步骤 3查看版权信息。

postgres=# \copyright

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

postgres=# \h

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

postgres=# \help CREATE DATABASE

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

postgres=# \? 

• 步骤 7退出数据库

postgres=# \q

1.2.3 gsql命令使用

1.2.3.1 前提条件

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

su - omm

1.2.3.2 执行一条字符串命令

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

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

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

• 步骤 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;

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

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

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

gsql -d postgres -p 26000 -f -
postgres=# select * from pg_user;

• 步骤 5退出数据库连接。

postgres=# \q 

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

gsql -d postgres -p 26000 -l

1.2.3.5 设置gsql变量NAME为VALUE 关键字:-v

• 步骤 1设置foo的值为bar。

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

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

postgres=# \echo :foo
bar

• 步骤 3退出数据库连接。

postgres=> \q

1.2.3.6 打印gsql版本信息。

gsql -V

1.2.3.7 使用文件作为输出源 关键字:-L

• 步骤 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 ;

退出数据库

postgres=# \q

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

cat /home/omm/openGauss/output.txt

显示如下：

1.2.3.8 将所有查询输出重定向到文件FILENAME 关键字:-o

• 步骤 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

1.2.3.9 安静模式 关键字:-q

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

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

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

1.2.3.10 单行运行模式 关键字:-S

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

gsql -d postgres -p 26000 -S

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

postgres^# select * from t_test;
 firstcol 
----------
(1 row)
postgres^# select * from t_test
 firstcol 
----------
(1 row)
postgres=# \q

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

1.2.3.11 编辑模式 关键字:-r

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

gsql -d postgres -p 26000 -r

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

select * from t_test;

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

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

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

• 步骤 5退出数据库连接

postgres=# \q

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

远程使用jack用户连接ip地址为192.168.0.58端口号为26000的数据库

• 步骤 1登录客户端主机(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=>

1.2.4 gsql元命令使用

1.2.4.1 前提条件

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

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

su - omm

• 步骤 2gsql连接数据库。

gsql -d postgres -p 26000 -r

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

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

touch ./home/omm/openGauss/outputSQL.txt

下图经历了一段切换目录的过程

• 步骤 2连接数据库。

gsql -d postgres -p 26000 -r

• 步骤 3输入以下语句。

postgres=# select * from pg_roles;

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

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

cat /home/omm/openGauss/outputSQL.txt

显示如下：

1.2.4.3 导入数据

• 步骤 1连接数据库。

gsql -d postgres -p 26000 -r

• 步骤 2创建目标表a。

postgres=# CREATE TABLE a(a int);

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

postgres=# \copy a from stdin;

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

>> 1 
>> 2 
>> \.

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

postgres=# SELECT * FROM a; 

退出数据库：

postgres=# \q

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

vi /home/omm/openGauss/2.csv

• 步骤 6输入i，切换到INSERT模式，插入数据如下: 如果有多个数据，分隔符为，。
  在导入过程中，若数据源文件比外表定义的列数多，则忽略行尾多出来的列。
• 步骤 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; 

1.2.4.4 查询表空间

postgres=# \db

显示如下：

1.2.4.5 查询表的属性 关键字:\d+

• 步骤 1创建表customer_t1。

postgres=# DROP TABLE IF EXISTS customer_t1;
postgres=# CREATE TABLE customer_t1 

• 步骤 2查询表的属性。

postgres=# \d+;

显示如下：

• 步骤 3查询表customer_t1的属性。

postgres=# \d+ customer_t1;

1.2.4.6 查询索引信息 关键字:\di+

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

create index customer_t1_index1 on customer_t1(c_customer_id);

• 步骤 2查询索引信息。

postgres=# \di+；

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

postgres=# \di+ customer_t1_index1

1.2.4.7 切换数据库 关键字:\c db

• 步骤 1创建数据库。

DROP DATABASE IF EXISTS db_tpcc02;
CREATE DATABASE db_tpcc02;

• 步骤 2切换数据库。

postgres=# \c db_tpcc02;

显示如下：

• 步骤 3退出数据库：

postgres=# \q