gaussdb 数据库连接工具【gsql 变量、sql代换、提示符、相关环境变量】【01】

1. 基本功能

• 连接GaussDB：默认只支持从服务器本机连接，如果需要连接到远端的GaussDB，必须在服务端进行配置。

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

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

2. 高级特性

特性名称	描述
变量	gsql提供类似于Unix的shell命令的变量特性，可以使用gsql的元命令\set设置一个变量，格式如下： \set varname value 要删除一个变量请使用如下方式： \unset varname 说明： 变量只是简单的名称/值对，这里的值可以是任意长度。 变量名称必须由字母（包括非拉丁字母）、数字和下划线组成，且对大小写敏感。 如果使用\set varname的格式（不带第二个参数），则只是设置这个变量而没有给变量赋值。 可以使用不带参数的\set来显示所有变量的值。
SQL代换	利用gsql的变量特性，可以将常用的SQL命令设置为变量，以简化操作。
自定义提示符	gsql使用的提示符支持用户自定义。可以通过修改gsql预留的两个变量PROMPT1，PROMPT2来改变提示符。

• 变量

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

testdb=> \set foo bar

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

testdb=> \echo :foobar

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

注意特殊的预留变量尽量避免使用，查看特殊变量的默认值，请使用元命令 \echo :varname（例如 \echo :DBNAME）

变量	设置方法	变量说明
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 host	已连接的数据库服务器主机。
IGNOREEOF	\set IGNOREEOF variable	若设置此变量为数值，在应用终止前该数值的 EOF 字符将被忽略； 若设置此变量为非数值，则缺省为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还提供为变量更换新的别名或其他标示符等功能。执行以下命令，将会查询my_table表。

testdb=> \set foo 'my_table'
testdb=> SELECT * FROM :foo;

使用引号更安全

testdb=> \set foo  'my_table'
testdb=> SELECT * FROM :"foo";

能否加载多列待测试 ？？？执行操作系统命令有一定的安全漏洞

testdb=> \set content  `cat my_file.txt`
testdb=> INSERT INTO my_table VALUES (:'content');

冒号是SQL中合法的命令，例如设置了当前变量name，则字符 :name，:‘name’ 或者:"name"将会被替换成变量name的值，如果不设置变量name，带冒号的字符就不会被替换。

• 提示符

通过设置可以改变gsql的提示符

变量	描述	示例
PROMPT1	gsql请求一个新命令时使用的正常提示符。 PROMPT1的默认值为： %/%R%#	使用变量PROMPT1切换提示符： 提示符变为[local]： TESTDB=> \set PROMPT1 %M [local]提示符变为name： TESTDB=> \set PROMPT1 name name提示符变为=： TESTDB=> \set PROMPT1 %R =
PROMPT2	在一个命令输入期待更多输入时（例如，查询没有用一个分号结束或者引号不完整）显示的提示符。	使用变量PROMPT2显示提示符： POSTGRES=# \set PROMPT2 TEST POSTGRES=# select * from MY_TABLE TEST;   NAME   ---------   helllo!   helllo! (2 rows)

一些预定义变量说明

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

3. 与gsql相关的一些环境变量

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