文档中心MogDBMogDB StackUqbar
生态工具
文档工具
EN
v5.0

文档:v5.0

支持的版本:
最新(v5.0)/
v3.1

其他版本:
v3.0/
v2.1/
v2.0/
v1.1

gsql概述

基本功能

  • 连接数据库：详细操作请参见《管理指南》中“日常运维 > gsql客户端连接”章节。

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

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

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

高级特性

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

表 1 gsql高级特性

特性名称 描述
变量 gsql提供类似于Linux的shell命令的变量特性，可以使用gsql的原命令\set设置一个变量，格式如下：
\set varname value
要删除一个变量请使用如下方式：
\unset varname
说明：
- 变量只是简单的名称/值对，这里的值可以是任意长度。
- 变量名称必须由字母（包括非拉丁字母）、数字和下划线组成，且对大小写敏感。
- 如果使用\set varname的格式（不带第二个参数），则只是设置这个变量而没有给变量赋值。
- 可以使用不带参数的\set来显示所有变量的值。
SQL代换 利用gsql的变量特性，可以将常用的SQL语句设置为变量，以简化操作。
自定义提示符 gsql使用的提示符支持用户自定义。可以通过修改gsql预留的三个变量PROMPT1、PROMPT2、PROMPT3来改变提示符。
这三个变量的值可以用户自定义，也可以使用gsql预定义的值。
命令自动补齐 根据MogDB语法规则，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 owned by tableName.colName，owned by。
- 不支持自定义操作符自动补齐。使用复制粘贴这种方式输入命令，如果粘贴的命令里面有TAB键有可能会使输入命令的格式错乱，无法正常执行。
- "\t\n@$><=;|&{() "这些特殊字符在sql语句中具有固定含义。如果自定义表名中包含这些特殊字符，那么输入的sql语句从这些字符开始不支持自动补齐。
客户端操作历史记录 gsql支持客户端操作历史记录，当客户端连接时指定“-r”参数，此功能被打开。可以通过\set设置记录历史的条数，例如，\set HISTSIZE 50，将记录历史的条数设置为50，\set HISTSIZE 0，不记录历史。
说明：
- 客户端操作历史记录条数默认设置为32条，最多支持记录500条。当客户端交互式输入包含中文字符时，只支持UTF-8 的编码环境。
- 出于安全考虑，将包含PASSWORD、IDENTIFIED敏感词的记录识别为敏感信息，不会记录到历史信息中，即不能通过上下翻回显。

  • 变量

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

    MogDB=# \set foo bar

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

    MogDB=# \echo :foo
bar

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

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

    img 说明:

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

    表 2 特殊变量设置

    变量 设置方法 变量说明
    DBNAME \set DBNAME dbname 当前连接的数据库的名称。每次连接数据库时都会被重新设置。
    ECHO \set ECHO all | queries - 如果设置为all，只显示查询信息。设置为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之间的值比较合理。
    HOST \set HOST hostname 已连接的数据库主机名称。
    IGNOREEOF \set IGNOREEOF variable - 若设置此变量为数值，假设为10，则在gsql中输入的前9次EOF字符（通常是Ctrl+D组合键）都会被忽略，在第10次按Ctrl+D才能退出gsql程序。
    - 若设置此变量为非数值，则缺省为10。
    - 若删除此变量，则向交互的gsql会话发送一个EOF终止应用。
    LASTOID \set LASTOID oid 最后影响的oid值，即为从一条INSERT或lo_import命令返回的值。此变量只保证在下一条SQL语句的结果显示之前有效。
    ON_ERROR_ROLLBACK \set ON_ERROR_ROLLBACK on | interactive | off - 如果是on，当一个事务块里的语句产生错误的时候，这个错误将被忽略而事务继续。
    - 如果是interactive，这样的错误只是在交互的会话里忽略。
    - 如果是off（缺省），事务块里一个语句生成的错误将会回滚整个事务。on_error_rollback-on模式是通过在一个事务块的每个命令前隐含地发出一个SAVEPOINT的方式工作的，在发生错误的时候回滚到该事务块。
    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之一以控制错误报告的冗余行。
    - terse：仅返回严重且主要的错误文本以及文本位置（一般适合于单行错误信息）。
    - default：返回严重且主要的错误文本及其位置，还包括详细的错误细节、错误提示（可能会跨越多行）。
    - verbose：返回所有的错误信息。

  • SQL代换

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

    MogDB=# \set foo 'HR.areaS'
MogDB=# select * from :foo;
 area_id |       area_name
---------+------------------------
       4 | Middle East and Africa
       3 | Asia
       1 | Europe
       2 | Americas
(4 rows)

    执行以上命令，将会查询HR.areaS表。

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

  • 提示符

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

    表 3 提示符变量

    变量 描述 示例
    PROMPT1 gsql请求一个新命令时使用的正常提示符。
    PROMPT1的默认值为：
    %/%R%#    		 使用变量PROMPT1切换提示符：
    - 提示符变为[local]：
    mogdb=> \set PROMPT1 %M [local:/tmp/gaussdba_mppdb]
    - 提示符变为name：
    mogdb=> \set PROMPT1 name name
    - 提示符变为=：
    mogdb=> \set PROMPT1 %R =
    PROMPT2 在一个命令输入期待更多输入时（例如，查询没有用一个分号结束或者引号不完整）显示的提示符。 使用变量PROMPT2显示提示符：
    MogDB=# \set PROMPT2 TEST
    MogDB=# select * from HR.areaS TEST;
    `area_id
    PROMPT3 当执行COPY命令，并期望在终端输入数据时（例如，COPY FROM STDIN），显示提示符。 使用变量PROMPT3显示COPY提示符：
    MogDB=# \set PROMPT3 '>>>>'
    MogDB=# 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 已定义的替换

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

反馈
Copyright © 2011-2024 www.enmotech.com All rights reserved.