gsql使用指导

gsql概述

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

基本功能

• 连接数据库：详细操作请参见《开发者指南》中“数据库使用 > 连接数据库 > 使用gsql连接 > 远程连接数据库”章节。

说明： 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预定义了一些特殊变量，同时也规划了变量的取值。为了保证和后续版本最大限度地兼容，请避免以其他目的使用这些变量。

  说明：

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

表 2 特殊变量设置

• 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 提示符变量

%/%R%#
复制

复制

postgres=> \set PROMPT1 %M
[local:/tmp/gaussdba_mppdb]
复制

postgres=> \set PROMPT1 name
name
复制

postgres=> \set PROMPT1 %R
=
复制

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

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 已定义的替换

环境变量

表 5 与gsql相关的环境变量

PSQL_EDITOR_LINENUMBER_ARG = '+'
PSQL_EDITOR_LINENUMBER_ARG='–line '
复制

使用指导

前提条件

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

操作步骤

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元命令请参见元命令参考。