gsql

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

gsql概述

基本功能

• **连接数据库：**详细操作请参见《快速入门》中“访问openGauss > 使用gsql访问openGauss”章节。

  说明：

  gsql创建连接时，数据库默认设置会有5分钟超时时间。如果在这个时间内，数据库未正确地接受连接并对身份进行认证，gsql将超时退出。 针对此问题，可以参考常见问题处理。

• **执行SQL语句：**支持交互式地键入并执行SQL语句，也可以执行一个文件中指定的SQL语句。

• **执行元命令：**元命令可以帮助管理员查看数据库对象的信息、查询缓存区信息、格式化SQL输出结果、以及连接到新的数据库等。元命令的详细说明请参见元命令参考。

高级特性

gsql的高级特性如表1所示。

表 1 gsql高级特性

\set varname value

\unset varname

• 变量

  可以使用gsql元命令\set设置一个变量。例如把变量foo的值设置为bar：

  openGauss=# \set foo bar

  要引用变量的值，在变量前面加冒号。例如查看变量的值：

  openGauss=# \echo :foo
  bar

  这种变量的引用方法适用于正规的SQL语句和元命令。

  gsql预定义了一些特殊变量，同时也规划了变量的取值。为了保证和后续版本最大限度地兼容，请避免以其他目的使用这些变量。所有特殊变量见表2。

  说明：

  • 所有特殊变量都由大写字母、数字和下划线组成。
  • 要查看特殊变量的默认值，请使用元命令**\echo :**varname（例如\echo :DBNAME）。

表 2 特殊变量设置

\set DBNAME dbname

\set ECHO all | queries

\set ECHO_HIDDEN  on | off | noexec

\set ENCODING   encoding

\set FETCH_COUNT variable

\set HOST hostname

\set IGNOREEOF variable

\set LASTOID oid

\set  ON_ERROR_ROLLBACK  on | interactive | off

\set ON_ERROR_STOP on | off

\set PORT port

\set USER username

\set VERBOSITY   terse | default | verbose

• 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的提示符，这些变量是由字符和特殊的转义字符所组成。

  表 3 提示符变量

  变量	描述	示例
  PROMPT1	gsql请求一个新命令时使用的正常提示符。 PROMPT1的默认值为： %/%R%#	使用变量PROMPT1切换提示符： 提示符变为[local]： postgres=> \set PROMPT1 %M [local:/tmp/gaussdba_mppdb] 提示符变为name： postgres=> \set PROMPT1 name name 提示符变为=： postgres=> \set PROMPT1 %R =
  PROMPT2	在一个命令输入期待更多输入时（例如，查询没有用一个分号结束或者引号不完整）显示的提示符。	使用变量PROMPT2显示提示符： openGauss=# \set PROMPT2 TEST openGauss=# select * from HR.areaS TEST; area_id | area_name ————-+—————————— 1 | Europe 2 | Americas 4 | Middle East and Africa 3 | Asia (4 rows))
  PROMPT3	当执行COPY命令，并期望在终端输入数据时（例如，COPY FROM STDIN），显示提示符。	使用变量PROMPT3显示COPY提示符： openGauss=# \set PROMPT3 ‘>>>>’ openGauss=# copy HR.areaS from STDIN; Enter data to be copied followed by a newline. End with a backslash and a period on a line by itself. >>>>1 aa >>>>2 bb >>>>.

  提示符变量的值是按实际字符显示的，但是，当设置提示符的命令中出现“%”时，变量的值根据“%”后的字符，替换为已定义的内容，已定义的提示符请参见表4。

  表 4 已定义的替换

  符号	符号说明
  %M	主机的全名（包含域名），若连接是通过Unix域套接字进行的，则全名为[local]，若Unix域套接字不是编译的缺省位置，就是[local:/dir/name]。
  %m	主机名删去第一个点后面的部分。若通过Unix域套接字连接，则为[local]。
  %>	主机正在侦听的端口号。
  %n	数据库会话的用户名。
  %/	当前数据库名称。
  %~	类似 %/，如果数据库是缺省数据库时输出的是波浪线~。
  %#	如果会话用户是数据库系统管理员，使用#，否则用>。
  %R	对于PROMPT1通常是“=”，如果是单行模式则是“^”，如果会话与数据库断开（如果\connect失败可能发生）则是“!”。 对于PROMPT2该序列被“ -”、单引号、双引号或“$”（取决于gsql是否等待更多的输入：查询没有终止、正在一个 / … / 注释里、正在引号或者美元符扩展里）代替。
  %x	事务状态： 如果不在事务块里，则是一个空字符串。 如果在事务块里，则是“*”。 如果在一个失败的事务块里则是“!”。 如果无法判断事务状态时为“?”（比如没有连接）。
  %digits	指定字节值的字符将被替换到该位置。
  %:name	gsql变量“name”的值。
  %command	command的输出，类似于使用“^”替换。
  %[ . . . %]	提示可以包含终端控制字符，这些字符可以改变颜色、背景、提示文本的风格、终端窗口的标题。例如， potgres=> \set PROMPT1 ‘%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%#’ 这个句式的结果是在VT100兼容的可显示彩色的终端上的一个宽体（1;）黑底黄字（33;40）。

  环境变量

  表 5 与gsql相关的环境变量

  名称	描述
  COLUMNS	如果\set columns为0，则由此参数控制wrapped格式的宽度。这个宽度用于决定在自动扩展的模式下，是否要把宽输出模式变成竖线的格式。
  PAGER	如果查询结果无法在一页显示，它们就会被重定向到这个命令。可以用\pset命令关闭分页器。典型的是用命令more或less来实现逐页查看。缺省值是平台相关的。 说明： less的文本显示，受系统环境变量LC_CTYPE影响。
  PSQL_EDITOR	\e和\ef命令使用环境变量指定的编辑器。变量是按照列出的先后顺序检查的。在Unix系统上默认的编辑工具是vi。
  EDITOR
  VISUAL
  PSQL_EDITOR_LINENUMBER_ARG	当\e和\ef带上一行数字参数使用时，这个变量指定的命令行参数用于向编辑器传递起始行数。像Emacs或vi这样的编辑器，这只是个加号。如果选项和行号之间需要空白，在变量的值后加一个空格。例如： PSQL_EDITOR_LINENUMBER_ARG = ‘+’ PSQL_EDITOR_LINENUMBER_ARG=’—line ‘ Unix系统默认的是+。
  PSQLRC	用户的.gsqlrc文件的交互位置。
  SHELL	使用!命令跟shell执行的命令是一样的效果。
  TMPDIR	存储临时文件的目录。缺省是/tmp。

使用指导

前提条件

连接数据库时使用的用户需要具备访问数据库的权限。

背景信息

使用gsql命令可以连接远程数据库服务。连接远程数据库服务时，需要在服务器上设置允许远程连接，详细操作请参见《开发者指南》中“数据库使用 > 连接数据库 > 使用gsql连接 > 远程连接数据库”章节。

操作步骤

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

   详细的gsql参数请参见命令参考。

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)

   更多gsql元命令请参见元命令参考。

示例

首先要创建一个表空间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');
INSERT 0 1
openGauss=# INSERT INTO HR.areaS (area_ID, area_NAME) VALUES (2, 'Americas');
INSERT 0 1
openGauss=# INSERT INTO HR.areaS (area_ID, area_NAME) VALUES (3, 'Asia');
INSERT 0 1
openGauss=# INSERT INTO HR.areaS (area_ID, area_NAME) VALUES (4, 'Middle East and Africa');
INSERT 0 1

切换提示符：

openGauss=# \set PROMPT1 '%n@%m %~%R%#'
omm@[local] openGauss=#

查看表：

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

使用元命令：

omm@[local] openGauss=#\a \t \x
Output format is unaligned.
Showing only tuples.
Expanded display is on.
omm@[local] openGauss=#SELECT * FROM HR.areaS;
area_id|2
area_name|Americas
area_id|1
area_name|Europe
area_id|4
area_name|Middle East and Africa
area_id|3
area_name|Asia
omm@[local] openGauss=#

获取帮助

操作步骤

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

  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: "omm")
    -f, --file=FILENAME      execute commands from file, then exit
  ......

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

  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

任务示例

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

   gsql -d postgres -p 15400

   postgres为需要连接的数据库名称，15400为数据库主节点的端口号。

   连接成功后，系统显示类似如下信息：

   gsql ((openGauss x.x 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.
   openGauss=#

2. 查看gsql的帮助信息。具体执行命令请参见表6 使用gsql联机帮助。

   表 6 使用gsql联机帮助

   描述	示例
   查看版权信息	\copyright
   查看openGauss支持的SQL语句的帮助	查看openGauss支持的SQL语句的帮助 例如，查看openGauss支持的所有SQL语句： openGauss=# \h Available help: ABORT ALTER APP WORKLOAD GROUP … … 例如，查看CREATE DATABASE命令的参数可使用下面的命令： openGauss=# \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支持的命令： openGauss=# \? General \copyright show FusionInsight LibrA 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 … …

命令参考

详细的gsql参数请参见表7 常用参数、表8 输入和输出参数、表9 输出格式参数和表10 连接参数。

表 7 常用参数

表 8 输入和输出参数

表 9 输出格式参数

表 10 连接参数

元命令参考

介绍使用openGauss数据库命令行交互工具登录数据库后，gsql所提供的元命令。所谓元命令就是在gsql里输入的任何以不带引号的反斜杠开头的命令。

注意事项

• 一个gsql元命令的格式是反斜杠后面紧跟一个动词，然后是任意参数。参数命令动词和其他参数以任意个空白字符间隔。

• 要在参数里面包含空白，必须用单引号把它引起来。要在这样的参数里包含单引号，可以在前面加一个反斜杠。任何包含在单引号里的内容都会被进一步进行类似C语言的替换：\n（新行）、\t（制表符）、\b（退格）、\r（回车）、\f（换页）、\digits（八进制表示的字符）、\xdigits（十六进制表示的字符）。

• ““包围的内容被当做一个命令行传入shell。该命令的输出（删除了结尾的新行）被当做参数值。

• 如果不带引号的参数以冒号（:）开头，它会被当做一个gsql变量，并且该变量的值最终会成为真正的参数值。

• 有些命令以一个SQL标识的名称（比如一个表）为参数。这些参数遵循SQL语法关于双引号的规则：不带双引号的标识强制转换成小写，而双引号保护字母不进行大小写转换，并且允许在标识符中使用空白。在双引号中，成对的双引号在结果名称中分析成一个双引号。比如，FOO“BAR”BAZ解析成fooBARbaz；而“A weird”“name”解析成“A weird”name。

• 对参数的分析在遇到另一个不带引号的反斜杠时停止。这里会认为是一个新的元命令的开始。特殊的双反斜杠序列（\\）标识参数的结尾并将继续分析后面的SQL语句（如果存在）。这样SQL和gsql命令可以自由的在一行里面混合。但是在任何情况下，一条元命令的参数不能延续超过行尾。

元命令

元命令的详细说明请参见表11 一般的元命令、表12 查询缓存区元命令、表13 输入/输出元命令、表14 显示信息元命令、表16 格式化元命令、表18 连接元命令、表19 操作系统元命令、表20 变量元命令和表22 大对象元命令。

须知： 以下命令中所提到的FILE代表文件路径。此路径可以是绝对路径（如/home/gauss/file.txt），也可以是相对路径（file.txt，file.txt会默认在用户执行gsql命令所在的路径下创建）。

表 11 一般的元命令

表 12 查询缓存区元命令

表 13 输入/输出元命令

说明： 表14 显示信息元命令中的选项S表示显示系统对象，PATTERN表示显示对象附加的描述信息。用来指定要被显示的对象名称。

表 14 显示信息元命令

openGauss=# \d

openGauss=#  \dtable+ a

openGauss=# \d+ f

openGauss=# \da f

openGauss=# \db p

openGauss=# \dc 

openGauss=# \dC c

openGauss=# \dd

openGauss=# \ddp

openGauss=# \dD

openGauss=# \ded

openGauss=# \det

openGauss=# \des

openGauss=# \deu

openGauss=# \dew

openGauss=# \df

openGauss=# \dF+

openGauss=# \dFd

openGauss=# \dFp

openGauss=# \dFt

openGauss=# \dg j?e

openGauss=# \dl

openGauss=# \dL

openGauss=#  \dm

openGauss=#  \dn+ d

openGauss=# \do

openGauss=# \dO

rolename=xxxx/yyyy  —赋予一个角色的权限

=xxxx/yyyy  —赋予public的权限 

openGauss=# \dp

openGauss=# \drds  postgres

openGauss=# \dT

openGauss=# \du

openGauss=# \div

openGauss=# \dx

openGauss=#  \l

openGauss=# \sf function_a
openGauss=# \sf 
“func()name”(argtype1, argtype2)

openGauss=# \z

表 15 权限的参数说明

表 16 格式化元命令

表 17 可调节的打印选项

表 18 连接元命令

表 19 操作系统元命令

表 20 变量元命令

表 21 \set常用命令

表 22 大对象元命令

#### **PATTERN**

很多\d命令都可以用一个PATTERN参数来指定要被显示的对象名称。在最简单的情况下，PATTERN正好就是该对象的准确名称。在PATTERN中的字符通常会被变成小写形式（就像在SQL名称中那样），例如\dt FOO将会显示名为foo的表。就像在SQL名称中那样，把PATTERN放在双引号中可以阻止它被转换成小写形式。如果需要在一个PATTERN中包括一个真正的双引号字符，则需要把它写成两个相邻的双引号，这同样是符合SQL引用标识符的规则。例如，\dt “FOO”“BAR”将显示名为FOO”BAR（不是foo”bar）的表。和普通的SQL名称规则不同，不能只在PATTERN的一部分周围放上双引号，例如\dt FOO”FOO”BAR将会显示名为fooFOObar的表。

不使用PATTERN参数时，\d命令会显示当前schema搜索路径中可见的全部对象——这等价于用*作为PATTERN。所谓对象可见是指可以直接用名称引用该对象，而不需要用schema来进行限定。要查看数据库中所有的对象而不管它们的可见性，可以把*.*用作PATTERN。

如果放在一个PATTERN中，*将匹配任意字符序列（包括空序列），而?会匹配任意的单个字符（这种记号方法就像 Unix shell 的文件名PATTERN一样）。例如，\dt int*会显示名称以int开始的表。但是如果被放在双引号内，*和?就会失去这些特殊含义而变成普通的字符。

包含一个点号（.）的PATTERN被解释为一个schema名称模式后面跟上一个对象名称模式。例如，\dt foo*.*bar*会显示名称以foo开始的schema中所有名称包括bar的表。如果没有出现点号，那么模式将只匹配当前schema搜索路径中可见的对象。同样，双引号内的点号会失去其特殊含义并且变成普通的字符。

高级用户可以使用字符类等正则表达式记法，如[0-9]可以匹配任意数字。所有的正则表达式特殊字符都按照POSIX正则表达式所说的工作。以下字符除外：

• .会按照上面所说的作为一种分隔符。
• *会被翻译成正则表达式记号.*。
• ?会被翻译成.。
• $则按字面意思匹配。

根据需要，可以通过书写?、(R+|)、(R|)和_R_?来分别模拟PATTERN字符.、R*和_R_?。$不需要作为一个正则表达式字符，因为PATTERN必须匹配整个名称，而不是像正则表达式的常规用法那样解释（换句话说，$会被自动地追加到PATTERN上）。如果不希望该PATTERN的匹配位置被固定，可以在开头或者结尾写上*。注意在双引号内，所有的正则表达式特殊字符会失去其特殊含义并且按照其字面意思进行匹配。另外，在操作符名称PATTERN中（即\do的PATTERN参数），正则表达式特殊字符也按照字面意思进行匹配。

DELIMITER

更改SQL语句之间分隔符命令，分隔符默认值为“;”。

DELIMITER命令为为客户端设置一个分隔符。当用户设置分隔符后，gsql客户端识别到分隔符时，会立即将SQL语句发送到服务端执行，但是服务端仍然将“;”看做SQL语句分隔符，并相应的处理SQL语句。

注意事项：

• delimiter符号目前不是自由设定的，结束符范围有限制，目前接受大小写字母组合或特殊字符组合（~/!/@/#/^/&/`/?/+/-/*//（除号）/%/</>/=），其中常见的用法是”//“。
• 符号组合中尽量使用无歧义符号组合，特殊符号组合（注释符：”\*“、”–“等）目前不支持用于delimiter命名。
• delimiter长度范围：0~15。
• 设置的结束符的级别是会话级别的，当切换数据库时delimiter_name会设置为默认值‘;’。
• 用户如果想使用其他字符组合例如”adbc $$”，可以使用引号包含，例如delimiter “adbc $$”，但使用时也需要使用引号包含，例如：select 1”adbc $$”。
• delimiter分隔符只有sql_compatibility = ‘B’时支持。

常见问题处理

连接性能问题

• 开启了log_hostname，但是配置了错误的DNS导致的连接性能问题。

  在连接上数据库，通过“show log_hostname”语句，检查数据库中是否开启了log_hostname参数。

  如果开启了相关参数，那么数据库内核会通过DNS反查客户端所在机器的主机名。这时如果数据库主节点配置了不正确的/不可达的DNS服务器，那么会导致数据库建立连接过程较慢。此参数的更多信息，详见《数据库参考》中“GUC参数说明 > 错误报告和日志 > 记录日志的内容”章节中关于“log_hostname”的描述。

• 数据库内核执行初始化语句较慢导致的性能问题。

  此种情况定位较难，可以尝试使用Linux的跟踪命令：strace。

  strace gsql -U MyUserName -W MyPassWord -d postgres -h 127.0.0.1 -p 23508 -r -c '\q'

  此时便会在屏幕上打印出数据库的连接过程。比如较长时间停留在下面的操作上：

  sendto(3, "Q\0\0\0\25SELECT VERSION()\0", 22, MSG_NOSIGNAL, NULL, 0) = 22
  poll([{fd=3, events=POLLIN|POLLERR}], 1, -1) = 1 ([{fd=3, revents=POLLIN}])

  此时便可以确定是数据库执行“SELECT VERSION()”语句较慢。

  在连接上数据库后，便可以通过执行“explain performance select version()”语句来确定初始化语句执行较慢的原因。更多信息，详见《性能调优指南》中“SQL调优指南 > SQL执行计划介绍”章节。

  另外还有一种场景不太常见：由于数据库主节点所在机器的磁盘满或故障，此时所查询等受影响，无法进行用户认证，导致连接过程挂起，表现为假死。解决此问题清理数据库主节点的数据盘空间便可。

• TCP连接创建较慢问题。

  此问题可以参考上面的初始化语句较慢排查的做法，通过strace跟踪，如果长时间停留在：

  connect(3, {sa_family=AF_FILE, path="/home/test/tmp/gaussdb_llt1/.s.PGSQL.61052"}, 110) = 0

  或者

  connect(3, {sa_family=AF_INET, sin_port=htons(61052), sin_addr=inet_addr("127.0.0.1")}, 16) = -1 EINPROGRESS (Operation now in progress)

  那么说明客户端与数据库端建立物理连接过慢，此时应当检查网络是否存在不稳定、网络吞吐量太大的问题。

创建连接故障

• gsql: could not connect to server: No route to host

  此问题一般是指定了不可达的地址或者端口导致的。请检查-h参数与-p参数是否添加正确。

• gsql: FATAL: Invalid username/password,login denied.

  此问题一般是输入了错误的用户名和密码导致的，请联系数据库管理员，确认用户名和密码的正确性。

• gsql: FATAL: Forbid remote connection with trust method!

  数据库由于安全问题，禁止远程登录时使用trust模式。这时需要修改pg_hba.conf里的连接认证信息。具体的设置信息请参见：《数据库管理指南》中“管理数据库安全 > 客户端接入认证 > 配置文件参考”章节。

  说明：

  请不要修改pg_hba.conf中openGauss主机的相关设置，否则可能导致数据库功能故障。建议业务应用部署在openGauss之外，而非openGauss内部。

• 连接数据库，添加“-h 127.0.0.1”可以连接，去掉后无法连接问题。

  通过执行SQL语句“show unix_socket_directory”检查数据库主节点使用的Unix套接字目录，是否与shell中的环境变量$PGHOST一致。

  如果检查结果不一致，那么修改PGHOST环境变量到GUC参数unix_socket_directory指向的目录便可。

  关于unix_socket_directory的更多信息，详见《数据库参考》中“GUC参数说明 > 连接和认证 > 连接设置”章节中的说明。

• The “libpq.so” loaded mismatch the version of gsql, please check it.

  此问题是由于环境中使用的libpq.so的版本与gsql的版本不匹配导致的，请通过“ldd gsql”命令确认当前加载的libpq.so的版本，并通过修改LD_LIBRARY_PATH环境变量来加载正确的libpq.so。

• gsql: symbol lookup error: xxx/gsql: undefined symbol: libpqVersionString

  此问题是由于环境中使用的libpq.so的版本与gsql的版本不匹配导致的（也有可能是环境中存在PostgreSQL的libpq.so），请通过“ldd gsql”命令确认当前加载的libpq.so的版本，并通过修改LD_LIBRARY_PATH环境变量来加载正确的libpq.so。

• gsql: connect to server failed: Connection timed out

  Is the server running on host “xx.xxx.xxx.xxx” and accepting TCP/IP connections on port xxxx?

  此问题是由于网络连接故障造成。请检查客户端与数据库服务器间的网络连接。如果发现从客户端无法PING到数据库服务器端，则说明网络连接出现故障。请联系网络管理人员排查解决。

  ping -c 4 10.10.10.1
  PING 10.10.10.1 (10.10.10.1) 56(84) bytes of data.
  From 10.10.10.1: icmp_seq=2 Destination Host Unreachable
  From 10.10.10.1 icmp_seq=2 Destination Host Unreachable
  From 10.10.10.1 icmp_seq=3 Destination Host Unreachable
  From 10.10.10.1 icmp_seq=4 Destination Host Unreachable
  --- 10.10.10.1 ping statistics ---
  4 packets transmitted, 0 received, +4 errors, 100% packet loss, time 2999ms

• gsql: FATAL: permission denied for database “postgres”

  DETAIL: User does not have CONNECT privilege.

  此问题是由于用户不具备访问该数据库的权限，可以使用如下方法解决。

  1. 使用管理员用户dbadmin连接数据库。

     gsql -d postgres -U dbadmin -p 15400

  2. 赋予该用户访问数据库的权限。

     GRANT CONNECT ON DATABASE postgres TO user1;

     说明： 实际上，常见的许多错误操作也可能产生用户无法连接上数据库的现象。如用户连接的数据库不存在，用户名或密码输入错误等。这些错误操作在客户端工具也有相应的提示信息。

     gsql -d postgres -p 15400
     gsql: FATAL:  database "postgres" does not exist
     gsql -d postgres -U user1 -W gauss@789 -p 15400
     gsql: FATAL:  Invalid username/password,login denied.

• gsql: FATAL: sorry, too many clients already，active/non-active: 2/10/3.

  此问题是由于系统连接数量超过了最大连接数量。请联系数据库DBA进行会话连接数管理，释放无用会话。

  关于查看用户会话连接数的方法如表23 查看会话连接数。

  会话状态可以在视图PG_STAT_ACTIVITY中查看。无用会话可以使用函数pg_terminate_backend进行释放。

  select datid,pid,state from pg_stat_activity;

   datid |       pid       | state  
  -------+-----------------+--------
   13205 | 139834762094352 | active
   13205 | 139834759993104 | idle
  (2 rows)

  其中pid的值即为该会话的线程ID。根据线程ID结束会话。

  SELECT PG_TERMINATE_BACKEND(139834759993104);

  显示类似如下信息，表示结束会话成功。

  PG_TERMINATE_BACKEND
  ----------------------
   t
  (1 row)

  表 23 查看会话连接数

  描述	命令
  查看指定用户的会话连接数上限。	执行如下命令查看连接到指定用户USER1的会话连接数上限。其中-1表示没有对用户user1设置连接数的限制。 SELECT ROLNAME,ROLCONNLIMIT FROM PG_ROLES WHERE ROLNAME=’user1’; rolname | rolconnlimit ————-+——————— user1 | -1 (1 row)
  查看指定数据库的会话连接数上限。	执行如下命令查看连接到指定数据库postgres的会话连接数上限。其中-1表示没有对数据库postgres设置连接数的限制。 SELECT DATNAME,DATCONNLIMIT FROM PG_DATABASE WHERE DATNAME=’postgres’; datname | datconnlimit —————+——————— postgres | -1 (1 row)
  查看指定数据库已使用的会话连接数。	执行如下命令查看指定数据库postgres上已使用的会话连接数。其中，1表示数据库postgres上已使用的会话连接数。 SELECT COUNT(*) FROM PG_STAT_ACTIVITY WHERE DATNAME=’postgres’; count -———— 1 (1 row)

• gsql: wait xxx.xxx.xxx.xxx:xxxx timeout expired

  gsql在向数据库发起连接的时候，会有5分钟超时机制，如果在这个超时时间内，数据库未能正常的对客户端请求进行校验和身份认证，那么gsql会退出当前会话的连接过程，并报出如上错误。

  一般来说，此问题是由于连接时使用的-h参数及-p参数指定的连接主机及端口有误（即错误信息中的xxx部分），导致通信故障；极少数情况是网络故障导致。要排除此问题，请检查数据库的主机名及端口是否正确。

• gsql: could not receive data from server: Connection reset by peer.

  同时，检查数据库主节点日志中出现类似如下日志“ FATAL: cipher file “/data/dbnode/server.key.cipher” has group or world access”，一般是由于数据目录或部分关键文件的权限被误操作篡改导致。请参照其他正常实例下的相关文件权限，修改回来便可。

• gsql: FATAL: GSS authentication method is not allowed because XXXX user password is not disabled.

  目标数据库主节点的pg_hba.conf里配置了当前客户端IP使用“gss”方式来做认证，该认证算法不支持用作客户端的身份认证，请修改到”sha256”后再试。配置方法见《开发者指南》中“管理数据库安全 > 客户端接入认证 > 配置文件参考”章节 。

  说明：

  • 请不要修改pg_hba.conf中openGauss主机的相关设置，否则可能导致数据库功能故障。
  • 建议业务应用部署在openGauss之外，而非openGauss内部。

其他故障

• 出现因“总线错误”（Bus error）导致的core dump或异常退出

  一般情况下出现此种问题，是进程运行过程中加载的共享动态库（在Linux为.so文件）出现变化；或者进程二进制文件本身出现变化，导致操作系统加载机器的执行码或者加载依赖库的入口发生变化，操作系统出于保护目的将进程杀死，产生core dump文件。

  解决此问题，重试便可。同时请尽可能避免在升级等运维操作过程中，在openGauss内部运行业务程序，避免升级时因替换文件产生此问题。

  说明：

  此故障的core dump文件的可能堆栈是dl_main及其子调用，它是操作系统用来初始化进程做共享动态库加载的。如果进程已经初始化，但是共享动态库还未加载完成，严格意义上来说，进程并未完全启动。