gsql使用指导

工具介绍

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

基本功能：

• 连接数据库：默认只支持从服务器本机连接，如果需要连接到远端的数据库，必须在服务端进行配置。详细操作请参见《开发指南》中“数据库使用入门 > 连接数据库 > 使用gsql连接”章节中的“远程连接数据库”。
  

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

• 执行SQL语句：支持交互式地键入并执行SQL语句，也可以执行一个文件中指定的SQL语句。
• 执行元命令：元命令可以帮助管理员查看数据库对象的信息、查询缓存区信息、格式化SQL输出结果，以及连接到新的数据库等。元命令的详细说明请参见元命令参考。

高级功能：

gsql的高级功能如表1所示。

\set varname value

\unset varname

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

  1	gaussdb=# \set foo bar

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

  1 2	gaussdb=# \echo :foo bar

  这种变量的引用方法适用于规则的SQL语句和除\copy、\ef、\help、\sf、\!以外的元命令。

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

  

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

  表2 特殊变量设置

  变量	设置方法	变量说明
  DBNAME	\set DBNAME dbname	当前连接的数据库的名称。每次连接数据库时都会被重新设置。
  ECHO	\set ECHO all | queries	如果设置为all，只显示查询信息。等效于使用gsql连接数据库时指定-a参数。 如果设置为queries，显示命令行和查询信息。等效于使用gsql连接数据库时指定-e参数。
  ECHO_HIDDEN	\set ECHO_HIDDEN on | off | noexec	当使用元命令查询数据库信息（例如\dg）时，此变量的取值决定了查询的行为： 设置为on，先显示元命令实际调用的查询语句，然后显示查询结果。等效于使用gsql连接数据库时指定-E参数。 设置为off，则只显示查询结果。 设置为noexec，则只显示查询信息，不执行查询操作。
  ENCODING	\set ENCODING encoding	当前客户端的字符集编码。
  FETCH_COUNT	\set FETCH_COUNT variable	如果该变量的值为大于0的整数，假设为n，则执行SELECT语句时，每次从结果集中取n行到缓存并显示到屏幕。 如果不设置此变量，或设置的值小于等于0，则执行SELECT语句时，一次性把结果都取到缓存。 说明： 设置合理的变量值，将减少内存使用量。一般来说，设为100到1000之间的值比较合理。
  HISTCONTROL	\set HISTCONTROL ignorespace | ignoredups | ignoreboth | none	ignorespace：以空格开始的行将不会写入历史列表。 ignoredups：与以前历史记录里匹配的行不会写入历史记录。 ignoreboth、none或者其他值：所有以交互模式读入的行都被保存到历史列表。 说明： none表示不设置HISTCONTROL。
  HISTFILE	\set HISTFILE filename	此文件用于存储历史名列表。缺省值是~/.bash_history。
  HISTSIZE	\set HISTSIZE size	保存在历史命令里命令的个数。缺省值是500。
  HOST	\set HOST hostname	已连接的数据库主机名称。
  IGNOREEOF	\set IGNOREEOF variable	若设置此变量为数值，假设为10，则在gsql中输入的前9次EOF字符（通常是Ctrl+C）都会被忽略，在第10次按Ctrl+C才能退出gsql程序。 若设置此变量为非数值，则缺省为10。 若删除此变量，则向交互的gsql会话发送一个EOF终止应用。
  LASTOID	\set LASTOID oid	最后影响的oid值，即为从一条INSERT或lo_import命令返回的值。此变量只保证在下一条SQL语句的结果显示之前有效。
  ON_ERROR_ROLLBACK	\set ON_ERROR_ROLLBACK on | interactive | off	on：当一个事务块里的语句发生错误时，自动回滚到上一个命令之前的状态，并继续执行后续命令。该模式是通过在一个事务块的每个命令前隐含地创建一个SAVEPOINT来工作的，在发生错误时，自动回滚到之前创建的SAVEPOINT，从而撤销失败命令的影响。 interactive：仅在交互式会话中启用自动回滚功能。 off（缺省值）：事务块里的语句发生错误时，终止整个事务。
  ON_ERROR_STOP	\set ON_ERROR_STOP on | off	on：命令执行错误时会立即停止，在交互模式下，gsql会立即返回已执行命令的结果。 off（缺省值）：命令执行错误时将会跳过错误继续执行。
  PORT	\set PORT port	当前连接数据库的端口号。
  USER	\set USER username	当前用于连接的数据库用户。
  VERBOSITY	\set VERBOSITY terse | default | verbose	该选项用于控制错误报告的冗余行。 terse：仅返回严重且主要的错误文本以及文本位置（一般适合于单行错误信息）。 default：返回严重且主要的错误文本及其位置，还包括详细的错误细节、错误提示（可能会跨越多行）。 verbose：返回所有的错误信息。

• SQL代换
  像元命令的参数一样，gsql变量的一个关键特性是可以把gsql变量替换成正规的SQL语句。此外，gsql还提供为变量更换新的别名或其他标识符等功能。使用SQL代换方式替换一个变量的值可在变量前加冒号。例如：

  1 2 3 4 5 6 7 8 9 10

  gaussdb=# \set foo 'HR.areaS' -- 执行以下命令，将会查询HR.areaS表。 gaussdb=# SELECT * FROM :foo; area_id | area_name ---------+------------------------ 4 | Middle East and Africa 3 | Asia 1 | Europe 2 | Americas (4 rows)

  

  变量的值是逐字复制的，甚至可以包含不对称的引号或反斜杠命令。所以必须保证输入的内容有意义。

• 提示符

  通过表3的三个变量可以设置gsql的提示符，这些变量由字符和特殊的转义字符所组成。

  表3 提示符变量

  变量	描述	示例
  PROMPT1	gsql请求一个新命令时使用的正常提示符。 PROMPT1的默认值为：%o%R%#。	使用变量PROMPT1切换提示符： 提示符变为[local]： 1 2 gaussdb=# \set PROMPT1 %M local:/data/huawei/wisequery/perfadm_mppdb 提示符变为name： 1 2 gaussdb=# \set PROMPT1 name name 提示符变为=： 1 2 gaussdb=# \set PROMPT1 %R =
  PROMPT2	在一个命令期待更多输入时（例如，查询没有用一个分号结束或者引号不完整）显示的提示符。	使用变量PROMPT2显示提示符： 1 2 3 4 5 6 7 8 9 10 gaussdb=# \set PROMPT2 TEST gaussdb=# 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提示符： 1 2 3 4 5 6 7 gaussdb=# \set PROMPT3 '>>>>' gaussdb=# 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]。
  %o	数据库名称。如果是postgres库，显示gaussdb；其他库则显示数据库名。
  %>	主机正在侦听的端口号。
  %n	数据库会话的用户名。
  %/	当前数据库名称。
  %~	类似%/，如果数据库是缺省数据库时输出的是波浪线“~”。
  %#	如果会话用户是数据库系统管理员，使用“#”，否则用“>”。
  %R	对于PROMPT1通常是“=”，如果是单行模式则是“^”，如果会话与数据库断开（如果\connect失败可能发生）则是“!”。 对于PROMPT2该序列被“ -”、“ *”、单引号、双引号或“$”（取决于gsql是否等待更多的输入：查询没有终止、正在一个 /* ... */ 注释里、正在引号或者美元符扩展里）代替。
  %x	事务状态： 如果不在事务块里，则是一个空字符串。 如果在事务块里，则是“*”。 如果在一个失败的事务块里则是“!”。 如果无法判断事务状态时为“?”（比如没有连接）。
  %digits	指定字节值的字符将被替换到该位置。
  %:name	gsql变量“name”的值。
  %command	command的输出，类似于使用“^”替换。
  %[ . . . %]	提示可以包含终端控制字符，这些字符可以改变颜色、背景、提示文本的风格、终端窗口的标题。例如， gaussdb=# \set PROMPT1 '%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%#' 这个句式的结果是在VT100兼容的可显示彩色的终端上的一个宽体（1;）黑底黄字（33;40）。

  环境变量：

  与gsql相关的环境变量参见表5。

  表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工具可通过发布包中的gsql_env.sh脚本设置环境变量使用，例如：source gsql_env.sh。
• 如果之前设置过环境变量，执行gsql_env.sh后会以脚本中环境变量优先。

命令格式

gsql [OPTION]... [DBNAME [USERNAME]]

参数说明

详细的gsql参数请参见表6、表7、表8和表9。

示例

示例一

连接数据库并执行命令。

1. 使用gsql连接到GaussDB服务器。

   gsql工具使用-d参数指定目标数据库名、-U参数指定数据库用户名、-h参数指定主机名、-p参数指定端口号信息。详细的gsql参数请参见参数说明。

   --使用jack用户连接到远程主机postgres数据库的8000端口。（根据实际需要替换各参数值）
   gsql -h 10.180.123.163 -d postgres -U jack -p 8000

   

   • 若未指定数据库名称，则使用初始化时默认生成的数据库名称。
   • 若未指定数据库用户名，则默认使用当前操作系统用户作为数据库用户名。
   • 当某个值没有前面的参数（-d、-U等）时，若连接的命令中没有指定数据库名（-d），则该参数会被解释为数据库名；如果已经指定数据库名（-d）而没有指定数据库用户名（-U），该参数则会被解释为数据库用户名。

     例如，以下命令中，参数postgres和omm不属于任何选项，会被分别解释为数据库名和用户名。

     gsql postgres omm -p 8000

     等效于以下命令。

     gsql -d postgres -U omm -p 8000

2. 执行SQL语句。

   1 2 3

   --创建数据库human_staff。 gaussdb=# CREATE DATABASE human_staff; CREATE DATABASE

3. 执行gsql元命令和SQL语句。

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

   --列出GaussDB中所有的数据库和描述信息。 gaussdb=# \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 | gaussdb | omm | SQL_ASCII | C | C | (6 rows) --删除数据库human_staff。 gaussdb=# DROP DATABASE human_staff; DROP DATABASE

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

示例二

获取帮助信息。

gsql --help
gsql is the GaussDB Kernel interactive terminal.

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
  -l, --list               list available databases, then exit
  -v, --set=, --variable=NAME=VALUE
                           set gsql variable NAME to VALUE
  -V, --version            output version information, then exit
  -X, --no-gsqlrc          do not read startup file (~/.gsqlrc)
  -1 ("one"), --single-transaction
                           execute command file as a single transaction
  -?, --help               show this help, then exit

Input and output options:
  -a, --echo-all           echo all input from script
  -e, --echo-queries       echo commands sent to server
  -E, --echo-hidden        display queries that internal commands generate
  -k, --with-key=KEY       the key for decrypting the encrypted file
  -L, --log-file=FILENAME  send session log to file
  -m, --maintenance        can connect to cluster during 2-pc transaction recovery
  -n, --no-libedit        disable enhanced command line editing (libedit)
  -o, --output=FILENAME    send query results to file (or |pipe)
  -q, --quiet              run quietly (no messages, only query output)
  -C, -C1, --enable-client-encryption=1
                           enable client encryption feature
  -C2, --enable-client-encryption=2
                           enable client sorting based client encryption feature
  -C3, --enable-client-encryption=3
                           enable Trusted Domain operation based on client encryption feature
  -s, --single-step        single-step mode (confirm each query)
  -S, --single-line        single-line mode (end of line terminates SQL command)
  -y, --slash-command      enable slash command to re-execute query in buffer

Output format options:
  -A, --no-align           unaligned table output mode
  -F, --field-separator=STRING
                           set field separator (default: "|")
  -H, --html               HTML table output mode
  -P, --pset=VAR[=ARG]     set printing option VAR to ARG (see \pset command)
  -R, --record-separator=STRING
                           set record separator (default: newline)
  -r                       if this parameter is set,use libedit
  -t, --tuples-only        print rows only
  -T, --table-attr=TEXT    set HTML table tag attributes (e.g., width, border)
  -x, --expanded           turn on expanded table output
  -z, --field-separator-zero
                           set field separator to zero byte
  -0, --record-separator-zero
                           set record separator to zero byte
  -2, --pipeline           use pipeline to pass the password, forbidden to use in terminal
                           must use with -c or -f

Connection options:
  -h, --host=HOSTNAME      database server host or socket directory (default: "/data/huawei/wisequery/perfadm_mppdb")
                           allow multi host IP address with comma separator, Use the
                           PGTARGETSESSIONATTRS(default: "primary") variable to select the
                           IP address to be connected.
                           (PGTARGETSESSIONATTRS can be {read-write|read-only|primary|
                            standby|prefer-standby|any})
  -p, --port=PORT          database server port (default: "5432")
  -U, --username=USERNAME  database user name (default: "omm")
  -W, --password=PASSWORD  the password of specified database user

For more information, type "\?" (for internal commands) or "\help" (for SQL
commands) from within gsql, or consult the gsql section in the GaussDB Kernel
documentation.