gsql
gsql是openGauss提供在命令行下运行的数据库连接工具,可以通过此工具连接服务器并对其进行操作和维护,除了具备操作数据库的基本功能,gsql还提供了若干高级特性,便于用户使用。
gsql概述
基本功能
连接数据库:详细操作请参见《快速入门》中“访问openGauss > 使用gsql访问openGauss”章节。
说明:
gsql创建连接时,数据库默认设置会有5分钟超时时间。如果在这个时间内,数据库未正确地接受连接并对身份进行认证,gsql将超时退出。 针对此问题,可以参考常见问题处理。
执行SQL语句:支持交互式地键入并执行SQL语句,也可以执行一个文件中指定的SQL语句。
执行元命令:元命令可以帮助管理员查看数据库对象的信息、查询缓存区信息、格式化SQL输出结果、以及连接到新的数据库等。元命令的详细说明请参见元命令参考。
高级特性
gsql的高级特性如表1所示。
表 1 gsql高级特性
gsql提供类似于Linux的shell命令的变量特性,可以使用gsql的原命令\set设置一个变量,格式如下: \set varname value \unset varname 变量的示例和详细说明请参见变量。 | |
利用gsql的变量特性,可以将常用的SQL语句设置为变量,以简化操作。 SQL代换的示例和详细说明请参见SQL代换。 | |
gsql使用的提示符支持用户自定义。可以通过修改gsql预留的三个变量PROMPT1、PROMPT2、PROMPT3来改变提示符。 这三个变量的值可以用户自定义,也可以使用gsql预定义的值。详细请参见提示符。 | |
根据openGauss语法规则,gsql支持使用Tab键进行命令的自动补齐,当编译时指定了选项--with-readline,且客户端连接时指定“-r”参数,此功能被打开。例如,crea后键入Tab,gsql会将其补齐为create。 说明:
| |
gsql支持客户端操作历史记录,当客户端连接时指定“-r”参数,此功能被打开。可以通过\set设置记录历史的条数,例如,\set HISTSIZE 50,将记录历史的条数设置为50,\set HISTSIZE 0,不记录历史。 |
可以使用gsql元命令\set设置一个变量。例如把变量foo的值设置为bar:
openGauss=# \set foo bar
要引用变量的值,在变量前面加冒号。例如查看变量的值:
openGauss=# \echo :foo bar
这种变量的引用方法适用于正规的SQL语句和元命令。
gsql预定义了一些特殊变量,同时也规划了变量的取值。为了保证和后续版本最大限度地兼容,请避免以其他目的使用这些变量。所有特殊变量见表2。
说明:
- 所有特殊变量都由大写字母、数字和下划线组成。
- 要查看特殊变量的默认值,请使用元命令 \echo :varname(例如\echo :DBNAME)。
像元命令的参数一样,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 提示符变量
提示符变量的值是按实际字符显示的,但是,当设置提示符的命令中出现“%”时,变量的值根据“%”后的字符,替换为已定义的内容,已定义的提示符请参见表4。
表 4 已定义的替换
环境变量
表 5 与gsql相关的环境变量
如果\set columns为0,则由此参数控制wrapped格式的宽度。这个宽度用于决定在自动扩展的模式下,是否要把宽输出模式变成竖线的格式。
如果查询结果无法在一页显示,它们就会被重定向到这个命令。可以用\pset命令关闭分页器。典型的是用命令more或less来实现逐页查看。缺省值是平台相关的。
使用指导
前提条件
连接数据库时使用的用户需要具备访问数据库的权限。
背景信息
使用gsql命令可以连接远程数据库服务。连接远程数据库服务时,需要在服务器上设置允许远程连接,详细操作请参见使用gsql访问openGauss。
操作步骤
使用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参数请参见命令参考。
执行SQL语句。
以创建数据库human_staff为例。
CREATE DATABASE human_staff;
通常,输入的命令行在遇到分号的时候结束。如果输入的命令行没有错误,结果就会输出到屏幕上。
执行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
任务示例
使用如下命令连接数据库。
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=#
查看gsql的帮助信息。具体执行命令请参见表6 使用gsql联机帮助。
表 6 使用gsql联机帮助
命令参考
详细的gsql参数请参见表7 常用参数、表8 输入和输出参数、表9 输出格式参数和表10 连接参数。
表 7 常用参数
指定想要连接的数据库名称。另外,gsql允许使用扩展的DBNAME,即'postgres[ql]://[user[:password]@][netloc][:port][,...][/dbname][?param1=value1&...]'或'[key=value] [...]'形式的连接串作为DBNAME,gsql将从连接串中解析连接信息,并优先使用这些信息。 | ||
使用文件作为命令源而不是交互式输入。gsql将在处理完文件后结束。如果FILENAME是-(连字符),则从标准输入读取。 | ||
变量的示例和详细说明请参见变量。 | ||
当gsql使用-1选项执行脚本时,会在脚本的开头和结尾分别加上START TRANSACTION/COMMIT用以把整个脚本当作一个事务执行。这将保证该脚本完全执行成功,或者脚本无效。 | ||
--with-decryption | 指定解密算法,软件只支持AES128,第三方接口库支持AES128_CBC、AES128_CTR、AES128_GCM、AES256_CBC、AES256_CTR、AES256_GCM、SM4_CBC、SM4_CTR、AES128_CBC_HMAC_SHA256、AES128_CTR_HMAC_SHA256、AES128_GCM_HMAC_SHA256、AES256_CBC_HMAC_SHA256、AES256_CTR_HMAC_SHA256、AES256_GCM_HMAC_SHA256、SM4_CBC_HMAC_SM3、SM4_CTR_HMAC_SM3。如果不带HMAC,表示只做加密。带HMAC表示需要带HMAC运算做完整性校验。 | - |
--with-module-params | 指定第三方接口库参数
| - |
--with-salt | 指定IV,16字节。 | - |
表 8 输入和输出参数
表 9 输出格式参数
表 10 连接参数
如果省略主机名,gsql将通过Unix域套接字与本地主机的服务器相联,或者在没有Unix域套接字的机器上,通过TCP/IP与localhost连接。 | ||
元命令参考
介绍使用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 显示信息元命令
列出当前search_path中模式下所有的表、视图和序列。当search_path中不同模式存在同名对象时,只显示search_path中位置靠前模式下的同名对象。 | 列出当前search_path中模式下所有的表、视图和序列。 openGauss=# \d | ||
openGauss=# \dtable+ a | |||
openGauss=# \d+ f* | |||
列出所有名称以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的权限 xxxx表示赋予的权限,yyyy表示授予这个权限的角色。权限的参数说明请参见表 权限的参数说明。 | openGauss=# \dp | ||
列出所有修改过的配置参数。这些设置可以是针对角色的、针对数据库的或者同时针对两者的。PATTERN1和PATTERN2表示要列出的角色PATTERN和数据库PATTERN。 | openGauss=# \drds * postgres | ||
openGauss=# \dT | |||
openGauss=# \du | |||
这一组命令,字母E、i、s、t和v分别代表着外部表、索引、序列、表和视图。可以以任意顺序指定其中一个或者它们的组合来列出这些对象。例如:\dit列出所有的索引和表。在命令名称后面追加+,则每一个对象的物理尺寸以及相关的描述也会被列出。 | 如果指定了PATTERN,只列出名称匹配该PATTERN的对象。默认情况下只会显示用户创建的对象。通过PATTERN或者S修饰符可以把系统对象包括在内。 | openGauss=# \div | |
openGauss=# \dx | |||
列出服务器上所有数据库的名称、所有者、字符集编码以及使用权限。 openGauss=# \l | |||
假设存在函数function_a和函数名带圆括号的函数func()name,列出函数的定义。 openGauss=# \sf function_a openGauss=# \sf "func()name"(argtype1, argtype2) | |||
openGauss=# \z |
表 15 权限的参数说明
| |
| |
表 16 格式化元命令
| |
设置影响查询结果表输出的选项。NAME的取值见表 可调节的打印选项。 | |
表 17 可调节的打印选项
表 18 连接元命令
连接到一个新的数据库(当前数据库为postgres)。当数据库名称长度超过63个字节时,默认前63个字节有效,连接到前63个字节对应的数据库,但是gsql的命令提示符中显示的数据库对象名仍为截断前的名称。 | ||
表 19 操作系统元命令
| ||
表 20 变量元命令
设置内部变量NAME为VALUE或者如果给出了多于一个值,设置为所有这些值的连接结果。如果没有给出第二个参数,只设变量不设值。 有一些常用变量被gsql特殊对待,它们是一些选项设置,通常所有特殊对待的变量都是由大写字母组成(可能还有数字和下划线)。 表21是一个所有特殊对待的变量列表。 | |
表 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.
此问题是由于用户不具备访问该数据库的权限,可以使用如下方法解决。
使用管理员用户dbadmin连接数据库。
gsql -d postgres -U dbadmin -p 15400
赋予该用户访问数据库的权限。
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 查看会话连接数
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及其子调用,它是操作系统用来初始化进程做共享动态库加载的。如果进程已经初始化,但是共享动态库还未加载完成,严格意义上来说,进程并未完全启动。