openGauss维护管理之客户端连接工具gsql

Posted 2023-03-15

一、概述

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

1、基本功能

**连接数据库：
  gsql创建连接时，数据库默认设置会有5分钟超时时间。如果在这个时间内，数据库未正确地接受连接并对身份进行认证，gsql将超时退出。
**执行SQL语句：**支持交互式地键入并执行SQL语句，也可以执行一个文件中指定的SQL语句。
**执行元命令：**元命令可以帮助管理员查看数据库对象的信息、查询缓存区信息、格式化SQL输出结果、以及连接到新的数据库等。

2、高级特性

1、变量
gsql提供类似于Linux的shell命令的变量特性，可以使用gsql的原命令\\set设置一个变量，格式如下：
\\set varname value
要删除一个变量请使用如下方式：
\\unset varname
说明：
变量只是简单的名称/值对，这里的值可以是任意长度。
变量名称必须由字母（包括非拉丁字母）、数字和下划线组成，且对大小写敏感。
如果使用\\set varname的格式（不带第二个参数），则只是设置这个变量而没有给变量赋值。
可以使用不带参数的\\set来显示所有变量的值。
变量的示例和详细说明请参见变量。

2、SQL代换
利用gsql的变量特性，可以将常用的SQL语句设置为变量，以简化操作。
像元命令的参数一样，gsql变量的一个关键特性是可以把gsql变量替换成正规的SQL语句。此外，gsql还提供为变量更换新的别名或其他标识符等功能
。使用SQL代换方式替换一个变量的值可在变量前加冒号。例如：
openGauss=# \\set foo HR.areaS
openGauss=# select * from :foo;
 area_id |       area_name        
---------+------------------------
       4 | Middle East and Africa
       3 | Asia
       1 | Europe
       2 | Americas
(4 rows)
执行以上命令，将会查询HR.areaS表。
须知： 变量的值是逐字复制的，甚至可以包含不对称的引号或反斜杠命令。所以必须保证输入的内容有意义。

3、自定义提示符
gsql使用的提示符支持用户自定义。可以通过修改gsql预留的三个变量PROMPT1、PROMPT2、PROMPT3来改变提示符。
这三个变量的值可以用户自定义，也可以使用gsql预定义的值。详细请参见提示符。

4、命令自动补齐
根据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 by tableName.colName，owned by。
不支持自定义操作符自动补齐。使用复制粘贴这种方式输入命令，如果粘贴的命令里面有TAB键有可能会使输入命令的格式错乱，无法正常执行。
"\\t\\n@$><=;|&() "这些特殊字符在sql语句中具有固定含义。如果自定义表名中包含这些特殊字符，那么输入的sql语句从这些字符开始不支持自
  动补齐。

5、客户端操作历史记录
gsql支持客户端操作历史记录，当客户端连接时指定“-r”参数，此功能被打开。可以通过\\set设置记录历史的条数，例如，\\set HISTSIZE 50，将
记录历史的条数设置为50，\\set HISTSIZE 0，不记录历史。
说明：
客户端操作历史记录条数默认设置为32条，最多支持记录500条。当客户端交互式输入包含中文字符时，只支持UTF-8 的编码环境。
出于安全考虑，将包含PASSWORD、IDENTIFIED敏感词的记录识别为敏感信息，不会记录到历史信息中，即不能通过上下翻回显。

二、使用指导

数据库连接

1、使用gsql连接到openGauss服务器。
gsql工具使用-d参数指定目标数据库名、-U参数指定数据库用户名、-h参数指定主机名、-p参数指定端口号信息。
说明：
若未指定数据库名称，则使用初始化时默认生成的数据库名称；
若未指定数据库用户名，则默认使用当前操作系统用户作为数据库用户名；
当某个值没有前面的参数（-d、-U等）时，若连接的命令中没有指定数据库名（-d）则该参数会被解释成数据库名；
如果已经指定数据库名（-d）而没有指定数据库用户名（-U）时，该参数则会被解释成数据库用户名。
示例1，使用omm用户连接到本机postgres数据库的15400端口。
gsql -d postgres -p 15400
示例2，使用jack用户连接到远程主机postgres数据库的15400端口。
gsql -h 10.180.123.163 -d postgres -U jack -p 15400
示例3，参数postgres和omm不属于任何选项时，分别被解释成了数据库名和用户名。
gsql postgres omm -p 15400
等效于
gsql -d postgres -U omm -p 15400

连接参数
-h, --host=HOSTNAME
指定正在运行服务器的主机名或者Unix域套接字的路径。
如果省略主机名，gsql将通过Unix域套接字与本地主机的服务器相联，或者在没有Unix域套接字的机器上，通过TCP/IP与localhost连接。

-p, --port=PORT
指定数据库服务器的端口号。
可以通过port参数修改默认端口号。
默认为5432。

-U, --username=USERNAME
指定连接数据库的用户。
说明：
通过该参数指定用户连接数据库时，需要同时提供用户密码用以身份验证。您可以通过交换方式输入密码，或者通过-W参数指定密码。
用户名中包含有字符，需要在字符
前增加转义字符才可成功连接数据库。
字符串。默认使用与当前操作系统用户同名的用户。

-W, --password=PASSWORD
当使用-U参数连接远端数据库时，可通过该选项指定密码。
说明：
数据库主节点所在服务器后连接本地数据库主节点实例时，默认使用trust连接，会忽略此参数。
用户密码中包含特殊字符“\\”和“`”时，需要增加转义字符才可成功连接数据库。
如果用户未输入该参数，但是数据库连接需要用户密码，这时将出现交互式输入，请用户输入当前连接的密码。该密码最长长度为999字节，受限于GUC
参数password_max_length的最大值。
符合密码复杂度要求。

SQL语句

2、执行SQL语句。
以创建数据库human_staff为例。
CREATE DATABASE human_staff;
通常，输入的命令行在遇到分号的时候结束。如果输入的命令行没有错误，结果就会输出到屏幕上。

3、执行gsql元命令。
以列出openGauss中所有的数据库和描述信息为例。
openGauss=#  \\l
                                List of databases
      Name      |  Owner   | Encoding  | Collate | Ctype |   Access privileges   
----------------+----------+-----------+---------+-------+-----------------------
 human_resource | omm | 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
 human_staff    | omm | SQL_ASCII | C       | C     | 
(5 rows)

示例
首先要创建一个表空间EXAMPLE：
openGauss=# CREATE TABLESPACE EXAMPLE RELATIVE LOCATION tablespace1/tablespace_1;
CREATE TABLESPACE

表空间创建成功后，创建schema HR：
openGauss=# CREATE schema HR;
CREATE SCHEMA

以把一个查询分成多行输入为例。注意提示符的变化：
openGauss=# CREATE TABLE HR.areaS(
openGauss(# area_ID   NUMBER,
openGauss(# area_NAME VARCHAR2(25)
openGauss(# )tablespace EXAMPLE;
CREATE TABLE

查看表的定义：
openGauss=# \\d HR.areaS
               Table "hr.areas"
  Column   |         Type          | Modifiers
-----------+-----------------------+-----------
 area_id   | numeric               |
 area_name | character varying(25) |
Tablespace: "example"

向HR.areaS表插入数据：
openGauss=# INSERT INTO HR.areaS (area_ID, area_NAME) VALUES (1, Europe);

查看表：
omm@[local] openGauss=#SELECT * FROM HR.areaS;
 area_id |       area_name        
---------+------------------------
       1 | Europe
       4 | Middle East and Africa
       2 | Americas
       3 | Asia
(4 rows)

可以用\\pset命令以不同的方法显示表：
omm@[local] openGauss=#\\pset border 2
Border style is 2.
omm@[local] openGauss=#SELECT * FROM HR.areaS;
+---------+------------------------+
| area_id |       area_name        |
+---------+------------------------+
|       1 | Europe                 |
|       2 | Americas               |
|       3 | Asia                   |
|       4 | Middle East and Africa |
+---------+------------------------+
(4 rows)
omm@[local] openGauss=#\\pset border 0
Border style is 0.
omm@[local] openGauss=#SELECT * FROM HR.areaS;
area_id       area_name        
------- ----------------------
      1 Europe
      2 Americas
      3 Asia
      4 Middle East and Africa
(4 rows)

查看会话数连接

查看指定用户的会话连接数上限
执行如下命令查看连接到指定用户USER1的会话连接数上限。其中-1表示没有对用户user1设置连接数的限制。
SELECT ROLNAME,ROLCONNLIMIT FROM PG_ROLES WHERE ROLNAME=user1;

查看指定数据库的会话连接数上限。
SELECT DATNAME,DATCONNLIMIT FROM PG_DATABASE WHERE DATNAME=postgres;

查看指定数据库已使用的会话连接数。
SELECT COUNT(*) FROM PG_STAT_ACTIVITY WHERE DATNAME=postgres;