openGuass客户端工具

1、客户端连接

客户端进程申请连接数据库，Gaussdb监听连接，通过连接认证后，fork出后台进程backend process worker代替客户端进程操作数据库。

建立会话的过程
第一步：客户端发起请求
第二步：该阶段由主服务Gaussdb进程负责服务器是否接受客户端的host通信认证服务器对客户端进行身份鉴别。
第三步：阶段二通过之后，主服务进程为该客户端单独fork一个客户端工作进程worker
第四步：客户端与worker进程建立通信连接，由worker进程负责后续所有的客户端请求操作，直至客户端退出后，该worker进程消失。

客户端与数据库通过线程池连接

openguass服务响应流程

openguass数据库连接方法

连接数据库的客户端工具包括： 命令行工具gsql、图形工具Data Studio和应用程序接口（如ODBC和JDBC）。

1、gsql是openGauss提供在命令行下运行的数据库连接工具，可以通过此工具连接服务器并对其进行操作和维护，除了具备操作数据

库的基本功能，gsql还提供了若干高级特性，便于用户使用。例如，可以交互式地输入、编辑、执行SQL语句。

2、 Data Studio是一个集成开发环境（IDE），帮助数据库开发人员便捷地构建应用程序，以图形化界面形式提供数据库关键特性。

3、用户可以使用标准的数据库应用程序接口（如ODBC和JDBC），开发基于openGauss的应用程序。

2、gsql工具基本功能

数据库在部署成功后，需要通过一些工具来便捷地连接数据库，对数据库进行各种操作和调试。gsql是openGauss提供的在命令行下运行的数据库连接工具，用户可以通过该工具连接服务器并对其进行操作和维护，除了具备操作数据库的基本功能，gsql还提供了若干高级特性，便于用户使用。

2.1 gsql工具基本参数分类

获取数据库连接信息

gsql -d postgres -p 26000 -U user1 -W 'huawei@1234' -h 192.168.0.11 -r

客户端工具通过数据库主节点连接数据库。

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

1、服务器的IP地址：数据库主节点实例的服务器IP地址分别为192.168.0.11。

gs_om -t status --detail

node node_ip instance state

-----------------------------------------------------------------------------------

1 node1 192.168.0.11 6001 /opt/huawei/install/data/dn01 P Primary Normal

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

的端口号。

cat /opt/huawei/install/data/dn01/postgresql.conf | grep port

port = 26000 # (change requires restart)

gsql工具：连接参数

gsql工具：其它参数

2.2gsql工具特性

命令自动补齐:

根据openGauss语法规则，gsql支持使用Tab键进行命令的自动补齐，当编译时指定了选项--with-readline，且客户端连接时指定

“-r”参数，此功能被打开。例如，crea后键入Tab，gsql会将其补齐为create。

说明

● 支持数据库SQL关键字如select、create、table等。● 支持表名、视图名等自定义标识符的补齐。

● 元命令选项'S'、'+'不支持自动补齐。● 对表进行补齐时，只有前缀是"pg_"才会补齐系统表。

● 不支持建表时字段类型的补齐。● select后不支持任何补齐。● 不支持常量与宏的自动补齐。

● select * from a,b... 不支持第二个开始表的自动补齐, insert into t1 (col1,col2, ...) 不支持第二个列的自动补齐。

● 不支持create tablespace语句with以及with后参数的自动补齐。

● 创建索引不支持local、global的自动补齐，修改索引不支持rebuild自动补齐。

● set语句仅支持自动补全user和superuser级别的参数。● 不支持if exists的自动补齐。

● 不支持表名.列名的自动补齐，如alter sequence <name> owned bytableName.colName，owned by。

● 不支持自定义操作符自动补齐。使用复制粘贴这种方式输入命令，如果粘贴的命令里面有TAB键有可能会使输入命令的格式错乱，

无法正常执行。

客户端操作历史记录、超时

1、“-r”参数：

gsql支持客户端操作历史记录，当客户端连接时指定“-r”参数，此功能被打开。可以通过\set设置记录历史的条数，

例如，\set HISTSIZE50，将记录历史的条数设置为50，\set HISTSIZE 0，不记录历史。

说明

● 客户端操作历史记录条数默认设置为32条，最多支持记录500条。当客户端

交互式输入包含中文字符时，只支持UTF-8 的编码环境。

● 出于安全考虑，将包含PASSWORD、IDENTIFIED敏感词的记录识别为敏感

信息，不会记录到历史信息中，即不能通过上下翻回显。

2、session_timeout参数

缺省情况下，客户端连接数据库后处于空闲状态时会根据参数session_timeout的默认值自动断开连接。

默认10min。如果要关闭超时设置，设置参数session_timeout为0即可

获取psql的SQL命令帮助

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 ]}[...] ];

实验：

gsql工具的使用

测试环境准备

$ gsql -d postgres -p 26000 -U omm -W 'gauss@123' -r

create table t1( id int,name varchar(20));

insert into t1 values(1,'Tom');

insert into t1 values(2,'Jerry');

select * from t1;

[omm@db1 ~]$ cat >>test.sql<<EOF

insert into t1 values(3,'user1');

EOF

[omm@db1 ~]$ gsql -d postgres -p 26000 -U omm -W 'gauss@123' -f test.sql

[omm@db1 ~]$ gsql -d postgres -p 26000 -U omm -W 'gauss@123' -c "select * from t1;"

[omm@db1 ~]$ gsql -d postgres -p 26000 -U omm -W 'gauss@123' -l

[omm@db1 ~]$ echo > test.sql && cat >>test.sql<<EOF

insert into t1 values(4,'John');

select * from t1 ;

insert into t1 values(5,'Scott');

EOF

[omm@db1 ~]$ gsql -d postgres -p 26000 -U omm -W 'gauss@123' -1 -f test.sql

[omm@db1 ~]$ gsql -d postgres -p 26000 -U omm -W 'gauss@123' -c "select * from t1;"

[omm@db1 ~]$ gsql -d postgres -p 26000 -U omm -W 'gauss@123' -f test.sql

[omm@db1 ~]$ gsql -d postgres -p 26000 -U omm -W 'gauss@123' -c "select * from t1;"

实验：gsql工具的使用

查询输出至指定文件

[omm@db1 db1]$ gsql -d postgres -p 26000 -U omm -W 'gauss@123' -r -L /home/omm/test1.log

select * from t1;

create user user1 identified by 'gauss@123';

postgres=# \! cat /home/omm/test1.log

输出格式化

gsql -d postgres -p 26000 -U omm -W 'gauss@123' -r -A

select * from t1;

gsql -d postgres -p 26000 -U omm -W 'gauss@123' -r -A -t

select * from t1;

gsql -d postgres -p 26000 -U omm -W 'gauss@123' -r -A -t -F ,

select * from t1;

2.3 psql元命令定义及其分类

psql元命令定义及其分类

1、定义：元命令就是在gsql里输入的任何以不带引号的反斜杠开头的命令。

2、分类：

元命令分为： 一般的元命令、

表 查询缓存区元命令、

表 输入/输出元命令、

表 显示信息元命令、

表 格式化元命令、

表 连接元命令、

表 操作系统元命令、

表变量元命令

表 大对象元命令

psql元命令的帮助

gsql里的元命令就是那些输入的任何以不带引号的反斜杠开头的命令。执行gsql元命令：元命令可以帮助管理员查看数

据库对象的信息、查询缓存区信息、格式化SQL输出结果，以及连接到新的数据库等。

postgres=# \?

General

\copyright show openGauss 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

\parallel [on [num]|off] toggle status of execute (currently off)

\q quit gsql

Query Buffer

\e [FILE] [LINE] edit the query buffer (or file) with external editor

\ef [FUNCNAME [LINE]] edit function definition with external editor

\p show the contents of the query buffer

\r reset (clear) the query buffer

\w FILE write query buffer to file

Input/Output

\copy ... perform SQL COPY with data stream to the client host

\echo [STRING] write string to standard output

\i FILE execute commands from file

psql常用的元命令

实验：psql元命令

实验环境准备：

postgres=# create database testdb10 with encoding='UTF-8';

postgres=# create tablespace tbs1 relative location 'tablespace/tbs1';

postgres=# create user user1 with sysadmin identified by 'opengauss@123456';

postgres=# create schema sch_user1 authorization user1;

postgres=# create table sch_user1.tt(id int primary key,name varchar(20) check (name=upper(name)));

postgres=# create table sch_user1.lt(id int,content CLOB);

postgres=# create view sch_user1.v1 as select * from sch_user1.tt where id < 2;

postgres=# create materialized view sch_user1.mv1 as select * from sch_user1.tt where id < 2;

postgres=# create sequence seq1 start 1 maxvalue 99999;

postgres=# CREATE FUNCTION func_add_sql(integer, integer) RETURNS integer

AS 'select $1 + $2;'

LANGUAGE SQL

IMMUTABLE

RETURNS NULL ON NULL INPUT;

postgres=# insert into sch_user1.tt values(1,'西红柿');

postgres=# insert into sch_user1.tt values(2,'黄瓜');

实验：psql元命令

实验环境准备：

\l
\d
\du
\dn
\di
\dv

3、客户端认证策略

如果主机需要远程连接数据库，必须在数据库系统的配置文件pg_hba.conf中增加此主机的信息，并且进行客户端接入认证。 配置

文件（默认名称为pg_hba.conf）存放在数据库的数据目录里。

hba（host-based authentication）表示是基于主机的认证。

三种认证方式

1、基于主机的认证：

服务器端根据客户端的IP地址、用户名及要访问的数据库 来查看配置文件从而判断用户是否通过认证。

2、口令认证：包括远程连接的加密口令认证和本地连接的非加密口令认证。

3、SSL加密：使用OpenSSL（开源安全通信库）提供服务器端和客户端安全连接的环境。

pg_hba.conf书写规则：

1、“pg_hba.conf”文件的格式是一行写一条信息，表示一个认证规则，空白和注释（以#开头）被忽略。

2、每个认证规则是由若干空格和/，空格和制表符分隔的字段组成。如果字段用引号包围，则它可以包含空白。一条记录不能跨行存

在。

pg_hba.conf四种格式：

local DATABASE USER METHOD [OPTIONS]

host DATABASE USER ADDRESS METHOD [OPTIONS]

hostssl DATABASE USER ADDRESS METHOD [OPTIONS]

hostnossl DATABASE USER ADDRESS METHOD [OPTIONS]

说明:

配置文件参考官方文档：07 开发者指南-5.1 客户端接入认证-5.1.2 配置文件参考

条目间的优先级 ：

1、因为认证时系统是为每个连接请求顺序检查“pg_hba.conf”里的记录的，所以这些记录的顺序是非常关键的。

在配置“pg_hba.conf”文件时，请依据通讯需求按照格式内容从上至下配置记录，优先级高的需求需要配置在前面。

2、openGauss和扩容配置的IP优先级最高，用户手动配置的IP请放在这二者之后，如果已经进行的客户配置和扩容节点的IP在同一网段，请在

扩容前删除，扩容成功后再进行配置。

对于认证规则的配置建议如下：

● 靠前的记录有比较严格的连接参数和比较弱的认证方法。

● 靠后的记录有比较宽松的连接参数和比较强的认证方法。

支持如下几种认证方式：

● trust

● reject

● md5

不推荐使用，默认不支持，可通过password_encryption_type参数配置原因MD5加密算法安全性低，存在安全风险。

建议：使用更安全的加密算法。

● sha256

● cert

● gss（仅用于openGauss内部节点间认证）

系统默认：

配置文件中： #password_encryption_type = 2 #Password storage type,

0 is md5 for PG,

1 is sha256 + md5,

2 is sha256 only

认证方法的选择

对应openGauss外部客户端连接，trust为不安全的认证方式，请将认证方式设置为sha256。

DataStudio不支持trust的认证方式，请将认证方式设置为sha256。

pg_hba.conf条目说明：

TYPE DATABASE USER ADDRESS METHOD

"local" is for Unix domain socket connections only

#表示只允许以安装时-U参数指定的用户从服务器本机进行连接。

local all all trust

IPv4 local connections:

#表示允许jack用户从10.10.0.50主机上连接到任意数据库，使用sha256算法对密码进行加密。

host all jack 10.10.0.50/32 sha256

#表示允许任何用户从10.10.0.0/24网段的主机上连接到任意数据库，使用sha256算法对密码进行加密，并且经过SSL加密传输。

hostssl all all 10.10.0.0/24 sha256

#表示允许任何用户从10.10.0.0/24网段的主机上连接到任意数据库，使用Kerberos认证方式，当前版本暂不支持客户端kerberos认证。

host all all 10.10.0.0/24 gss include_realm=1 krb_realm=HADOOP.COM

3.1 客户端认证策略设置

1、用户权限对远程用户登录的影响：

一个用户要想成功连接到特定的数据库，不仅需要通过pg_hba.conf中的规则检查，还必须要有该数据库上的CONNECT权限。

如果希望控制某些用户只能连接到指定数据库，赋予/撤 销CONNECT权限通常比在pg_hba.conf中设置规则更为简单。

2、使用gs_guc设置客户端认证策略

gs_guc set -N all -I all -h "host all jack 10.10.0.30/32 sha256"

Total instances: 2. Failed instances: 0.

Success to perform gs_guc!

3、修改pg_hba.conf设置客户端认证策略

3.2确认连接信息

gsql -d postgres -p 26000 -U user1 -W 'huawei@1234' -h 192.168.0.11 -r

客户端工具通过数据库主节点连接数据库。

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

1、服务器的IP地址：数据库主节点实例的服务器IP地址分别为192.168.0.11。

gs_om -t status --detail

node node_ip instance state

-----------------------------------------------------------------------------------

1 node1 192.168.0.11 6001 /opt/huawei/install/data/dn01 P Primary Normal

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

的端口号

cat /opt/huawei/install/data/dn01/postgresql.conf | grep port

port = 26000 # (change requires restart)

4、使用 gsql 本地连接

gsql是openGauss提供的在命令行下运行的数据库连接工具。此工具除了具备操作数据库的基本功能，还提供了若干高级特性，便

于用户使用。

连接方法：

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

步骤2 连接数据库。

数据库安装完成后，默认生成名称为postgres的数据库。第一次连接数据库时可以连接到此数据库。

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

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

gsql ((openGauss 2.0.0 build 78689da9) compiled at 2021-03-31 21:04:03 commit 0 last mr )

Non-SSL connection (SSL connection is recommended when requiring high-security)

Type "help" for help.

postgres=#

注意事项：

缺省情况下，客户端连接数据库后处于空闲状态时会根据参数session_timeout的默认值自动断开连接。如果要关闭超时设置，设置参数

session_timeout为0即可。

4.1 配置白名单

通过 gs_guc 配置白名单：

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

步骤2 配置客户端认证方式，允许客户端以“jack”用户连接到本机，此处远程连接禁止使用“omm”用户（即数据库初始化用户）。

例如，下面示例中配置允许IP地址为10.10.0.30的客户端访问本机。

gs_guc set -N all -I all -h "host all jack 10.10.0.30/32 sha256"

说明：

● -N all表示openGauss的所有主机。● -I all表示主机的所有实例。

● -h表示指定需要在“pg_hba.conf”增加的语句。● all表示允许客户端连接到任意的数据库。● jack表示连接数据库的用户。

● 10.10.0.30/32表示只允许IP地址为10.10.0.30的主机连接。此处的IP地址不能为openGauss内 的IP，在使用过程中，请根据用户的网络进

行配置修改。32表示子网掩码为1的位数，即255.255.255.255

● sha256表示连接时jack用户的密码使用sha256算法加密。

这条命令在数据库主节点实例对应的“pg_hba.conf”文件中添加了一条规则，用于对连接数据库主节点的客户端进行鉴定。

4.2 安装 gsql 客户端并连接数据库

1、安装 gsql 客户端：

在客户端机器上，上传客户端工具包并配置gsql的执行环境变量。

步骤1 以root用户登录客户端机器。

步骤2 创建“/tmp/tools”目录。

mkdir /tmp/tools

步骤3 获取软件安装包中的“openGauss-2.0.0-CentOS-64bit-Libpq.tar.gz”上传到“/tmp/tools”路径下。

步骤4 解压文件。cd /tmp/tools

tar -zxvf openGauss-2.0.0-CentOS-64bit-Libpq.tar.gz

步骤5 登录数据库主节点所在的服务器，拷贝数据库安装目录下的bin目录到客户端主机的

“/tmp/tools”路径下，随后继续登录客户端主机执行步骤6操作。

scp -r /opt/huawei/install/app/bin root@10.10.0.30:/tmp/tools

其中，/opt/huawei/install/app为clusterconfig.xml文件中配置的{gaussdbAppPath}路径，10.10.0.30为客户端主机ip。

步骤6 登录客户端所在主机，设置环境变量。

打开“~/.bashrc”文件。

vi ~/.bashrc

export PATH=/tmp/tools/bin:$PATH

export LD_LIBRARY_PATH=/tmp/tools/lib:$LD_LIBRARY_PATH

步骤7 使环境变量配置生效。

source ~/.bashrc

2、连接数据库。

数据库安装完成后，默认生成名称为postgres的数据库。第一次连接数据库时可以连接到此数据库。

gsql -d postgres -h 10.10.0.11 -U jack -p 26000 -W Test@123

jack为连接数据库的用户，26000为数据库主节点的端口号，Test@123为连接数据库用户jack的密码。

5、客户端连接数据库

下面示例中配置允许IP地址为10.10.0.30的客户端访问本机。

gs_guc set -N all -I all -h "host all jack 10.10.0.30/32 sha256"

gs_guc reload -D /opt/huawei/install/data/dn01/ -h "host all all 192.168.0.1/32 sha256"

这条命令在数据库主节点实例对应的“pg_hba.conf”文件中添加了一条规则，用于对连接数据库主节点的客户端进行鉴定。

说明：

● -N all表示openGauss的所有主机。

● -I all表示主机的所有实例。

● -h表示指定需要在“pg_hba.conf”增加的语句。

● all表示允许客户端连接到任意的数据库。

● jack表示连接数据库的用户。

● 10.10.0.30/32表示只允许IP地址为10.10.0.30的主机连接。此处的IP地址不能为openGauss内 的IP，在使用过程中，请根据用户的网络进行

配置修改。32表示子网掩码为1的位数，即255.255.255.255

● sha256表示连接时jack用户的密码使用sha256算法加密。

常见问题