# gsql使用指导 #### 工具介绍 gsql是GaussDB提供在命令行下运行的数据库连接工具，可以通过此工具连接服务器并对其进行操作和维护，除了具备操作数据库的基本功能，gsql还提供了若干高级功能，便于用户使用。 **基本功能：** - 连接数据库：默认只支持从服务器本机连接，如果需要连接到远端的数据库，必须在服务端进行配置。详细操作请参见《开发指南》中"数据库使用入门 \> 连接数据库 \> 使用gsql连接"章节。 ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png) gsql创建连接时，会有5分钟超时时间。如果在这个时间内，数据库未正确地接受连接并对身份进行认证，gsql将超时退出。针对此问题，可以参考[FAQ](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/gaussdb-08-0620.html)。 - 执行SQL语句：支持交互式地键入并执行SQL语句，也可以执行一个文件中指定的SQL语句。 - 执行元命令：元命令可以帮助管理员查看数据库对象的信息、查询缓存区信息、格式化SQL输出结果，以及连接到新的数据库等。元命令的详细说明请参见[元命令参考](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/gaussdb-08-0619.html)。 **高级功能：** gsql的高级功能如[表1]所示。 表1gsql高级功能 | 特性名称 | 描述 | |:---|:---| | 变量 | gsql提供类似于Linux的shell命令的变量特性，可以使用gsql的元命令\\set设置一个变量，格式如下： ``` \set varname value ``` 删除由\\set命令设置的变量请使用如下方式： ``` \unset varname ``` 说明： - 变量只是简单的名称/值对，这里的值可以是任意长度。 - 变量名称必须由字母（包括非拉丁字母）、数字和下划线组成，且对大小写敏感。 - 如果使用\\set varname的格式（不带第二个参数），则只是设置这个变量而没有给变量赋值。 - 可以使用不带参数的\\set来显示所有变量的值。 变量的示例和详细说明请参见[变量]。 | | SQL代换 | 利用gsql的变量特性，可以将常用的SQL语句设置为变量，以简化操作。 SQL代换的示例和详细说明请参见[SQL代换]。 | | 自定义提示符 | gsql使用的提示符支持用户自定义。可以通过修改gsql预留的三个变量PROMPT1、PROMPT2、PROMPT3来改变提示符。 这三个变量的值可以用户自定义，也可以使用gsql预定义的值。详细说明请参见[提示符]。 | | 客户端操作历史记录 | gsql支持客户端操作历史记录，当客户端连接时指定"-r"参数，此功能被打开。可以通过\\set设置记录历史的条数，例如，\\set HISTSIZE 50，将记录历史的条数设置为50，\\set HISTSIZE 0，不记录历史。 说明： - 客户端操作历史记录条数默认设置为32条，最多支持记录500条。当客户端交互式输入包含中文字符时，只支持UTF-8的编码环境。 - 出于安全考虑，将包含PASSWORD、IDENTIFIED、GS_ENCRYPT_AES128、GS_DECRYPT_AES128、GS_ENCRYPT、GS_DECRYPT、GS_ENCRYPT_BYTEA、GS_DECRYPT_BYTEA、PG_CREATE_PHYSICAL_REPLICATION_SLOT_EXTERN、SECRET_ACCESS_KEY、SECRETKEY、CREATE_CREDENTIAL、ACCESSKEY、SECRET_KEY、DESENCRYPT、DESDECRYPT、DES3ENCRYPT、DES3DECRYPT等字符串（不区分大小写）的SQL语句记录识别为包含敏感信息的语句，不会记录到历史信息中，即不能通过上下翻回显。 | - 变量 可以使用gsql元命令\\set设置一个变量。例如，把变量foo的值设置为bar： ``` gaussdb=# \set foo bar ``` 要引用变量的值，在变量前面加冒号。例如，查看变量的值： ``` gaussdb=# \echo :foo bar ``` 这种变量的引用方法适用于规则的SQL语句和除\\copy、\\ef、\\help、\\sf、\\!以外的元命令。 gsql预定义了一些特殊变量，同时也规划了变量的取值。为了保证和后续版本最大限度兼容，请避免以其他目的使用这些变量。所有特殊变量见[表2]。 ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png) - 所有特殊变量都由大写字母、数字和下划线组成。 - 要查看特殊变量的默认值，请使用元命令\\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代换方式替换一个变量的值可在变量前加冒号。例如： ``` 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) ``` ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png) 变量的值是逐字复制的，甚至可以包含不对称的引号或反斜杠命令。所以必须保证输入的内容有意义。 - 提示符 通过[表3]的三个变量可以设置gsql的提示符，这些变量由字符和特殊的转义字符所组成。 表3提示符变量 | 变量 | 描述 | 示例 | |:---|:---|:---| | PROMPT1 | gsql请求一个新命令时使用的正常提示符。 PROMPT1的默认值为：%o%R%#。 | 使用变量PROMPT1切换提示符： - 提示符变为local： ``` gaussdb=# \set PROMPT1 %M local:/data/huawei/wisequery/perfadm_mppdb ``` - 提示符变为name： ``` gaussdb=# \set PROMPT1 name name ``` - 提示符变为=： ``` gaussdb=# \set PROMPT1 %R = ``` | | PROMPT2 | 在一个命令期待更多输入时（例如，查询没有用一个分号结束或者引号不完整）显示的提示符。 | 使用变量PROMPT2显示提示符： ``` 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提示符： ``` 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 | \\e和\\ef命令使用环境变量指定的编辑器。变量是按照列出的先后顺序检查的。在Unix系统上默认的编辑工具是vi。 | | VISUAL | \\e和\\ef命令使用环境变量指定的编辑器。变量是按照列出的先后顺序检查的。在Unix系统上默认的编辑工具是vi。 | | PSQL_EDITOR_LINENUMBER_ARG | 当\\e和\\ef带上一行数字参数使用时，这个变量指定的命令行参数用于向编辑器传递起始行数。对于Emacs或vi编辑器，该参数值为一个加号。如果选项和行号之间需要空白，在变量的值后加一个空格。例如： ``` PSQL_EDITOR_LINENUMBER_ARG = '+' PSQL_EDITOR_LINENUMBER_ARG='--line ' ``` Unix系统默认的是+。 | | PSQLRC | 用户的.gsqlrc文件的存放位置。 | | SHELL | 使用\\!命令和shell执行的命令效果相同。 | | TMPDIR | 存储临时文件的目录。缺省是/tmp。 | ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png) gsql不支持按照nls_date_format格式显示datea类型，当前只支持显示YYYY-MM-DD HH24-MI-SS AD格式。 #### 前提条件 - 连接数据库时使用的用户需要具备访问数据库的权限。 - gsql需要与数据库版本配套。 - 当gsql客户端编码设置为UTF8时，若GaussDB返回的数据编码格式不是UTF8，则数据将无法正确显示在gsql客户端中。 ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png) - gsql工具可通过发布包中的gsql_env.sh脚本设置环境变量使用，例如：source gsql_env.sh。 - 如果之前设置过环境变量，执行gsql_env.sh后会以脚本中环境变量优先。 #### 命令格式 ``` gsql [OPTION]... [DBNAME [USERNAME]] ``` #### 参数说明 详细的gsql参数请参见[表6]、[表7]、[表8]、[表9]和[表10]。 表6常用参数 | 参数 | 参数说明 | 取值范围 | |:---|:---|:---| | -c, --command=COMMAND | 声明gsql要执行一条字符串命令然后退出。 | - | | -d, --dbname=DBNAME | 指定连接的数据库名称。若未指定数据库名称，则使用初始化时默认生成的数据库名称。 另外，gsql允许使用扩展的DBNAME，即"postgres\[ql\]://\[user\[:password\]@\]\[netloc\]\[:port\]\[,...\]\[/dbname\]\[?param1=value1\&...\]"或"\[key=value\] \[...\]"形式的连接串作为DBNAME，gsql将从连接串中解析连接信息，并优先使用这些信息。 说明： gsql使用扩展的DBNAME创建连接时，不支持指定replication参数。 | 字符串。 | | -f, --file=FILENAME | 使用文件作为命令源而不是交互式输入。gsql将在处理完文件后结束。如果FILENAME是-（连字符），则从标准输入读取。 说明： 当服务端编码为GB18030/GB18030_2022时，若gsql -f 结合管道符('\>') 执行（如：gsql -f xxx.sql \> xxx.log），导入文件编码格式需与服务端编码格式保持一致，建议在文件中手动设置client_encoding为服务端编码格式。 | 绝对路径或相对路径，且满足操作系统路径命名规则。 | | -l, --list | 列出所有可用的数据库，然后退出。 | - | | -v, --set=, --variable=NAME=VALUE | 设置gsql变量NAME为VALUE。 变量的示例和详细说明请参见[变量]。 | - | | -X, --no-gsqlrc | 不读取启动文件（系统范围的gsqlrc或者用户的\~/.gsqlrc都不读取）。 说明： 启动文件默认为\~/.gsqlrc，或通过PSQLRC环境变量指定。 | - | | -1 ("one"), --single-transaction | 当gsql使用-f选项执行脚本时，会在脚本的开头和结尾分别加上START TRANSACTION/COMMIT用以把整个脚本当作一个事务执行。这将保证该脚本完全执行成功，或者脚本无效。 说明： 如果脚本中已经使用了START TRANSACTION、COMMIT、ROLLBACK，则该选项无效。 | - | | -y, --slash-command | 将当前语句终结并发送到内核执行或者重新执行已经执行过的语句（不包括gsql元命令）。 说明： - 该功能仅支持ORA兼容模式数据库，而且不支持-c, --command参数的使用场景。 - ORA兼容模式数据库下默认普通语句分隔符为";"，PL/SQL为"/"，使用该参数时不支持更换分隔符。 | - | | -?, --help | 显示关于gsql命令行参数的帮助信息然后退出。 | - | | -V, --version | 打印gsql版本信息然后退出。 | - | 表7输入和输出参数 | 参数 | 参数说明 | 取值范围 | |:---|:---|:---| | -a, --echo-all | 在读取行时向标准输出打印所有内容。 说明： 使用此参数可能会暴露部分SQL语句中的敏感信息，如创建用户语句中的password信息等，请谨慎使用。 | - | | -B, --base64 | 表示-c参数传入的是Base64编码后的内容。 说明： 此参数必须与-c参数同时使用。 | - | | -e, --echo-queries | 把所有发送给服务器的查询同时回显到标准输出。 说明： 使用此参数可能会暴露部分SQL语句中的敏感信息，如创建用户语句中的password信息等，请谨慎使用。 | - | | -E, --echo-hidden | 回显由\\d和其他反斜杠命令生成的实际查询。 | - | | -k, --with-key=KEY | 使用gsql对导入的加密文件进行解密。 说明： - 对于本身就是shell命令中的关键字符如单引号（'）或双引号（"），Linux shell会检测输入的单引号（'）或双引号（"）是否匹配。如果不匹配，shell认为用户没有输入完毕，会一直等待用户输入，从而不会进入到gsql程序。 - 不支持解密导入存储过程和函数。 | - | | -L, --log-file=FILENAME | 除了正常的输出源之外，把所有查询输出记录到文件FILENAME中。 说明： - 使用此参数可能会暴露部分SQL语句中的敏感信息，如创建用户语句中的password信息等，请谨慎使用。 - 此参数只保留查询结果到相应文件中，主要目标是为了查询结果能够更好更准确地被其他调用者（例如自动化运维脚本）解析，而不是保留gsql运行过程中的相关日志信息。 | 绝对路径或相对路径，且满足操作系统路径命名规则。 | | -m, --maintenance | 允许在两阶段事务恢复期间连接集群。 说明： 该选项是一个开发选项，禁止用户使用，只限专业技术人员使用，功能是：使用该选项时，gsql可以连接到备机，用于校验主备机数据的一致性。 | - | | -n, --no-libedit | 关闭命令行编辑。 | - | | -o, --output=FILENAME | 将所有查询输出重定向到文件FILENAME。 | 绝对路径或相对路径，且满足操作系统路径命名规则。 | | -q, --quiet | 安静模式，执行时不会打印出额外信息。 | 缺省时gsql将打印许多其他输出信息。 | | -s, --single-step | 单步模式运行。意味着每个查询在发往服务器之前都要提示用户，用这个选项也可以取消执行。此选项主要用于调试脚本。 说明： 使用此参数可能会暴露部分SQL语句中的敏感信息，如创建用户语句中的password信息等，请谨慎使用。 | - | | -S, --single-line | 单行运行模式，这时每个命令都将由换行符结束。 | - | | -C，-C1, --enable-client-encryption=1 | 可通过该选项打开密态数据库开关，此开关为密态等值查询基本能力开关。 | - | | -C3，--enable-client-encryption=3 | 可通过该选项打开内存解密逃生通道开关，支持密态等值查询基本能力以及内存解密逃生通道能力。 | - | 表8输出格式参数 | 参数 | 参数说明 | 取值范围 | |:---|:---|:---| | -A, --no-align | 切换为非对齐输出模式。缺省为对齐输出模式。 | - | | -F, --field-separator=STRING | 设置域分隔符（默认为"\|"）。 | - | | -H, --html | 指定HTML格式输出。 | - | | -P, --pset=VAR\[=ARG\] | 在命令行上以\\pset的风格设置打印选项。 说明： 这里必须用等号而不是空格分隔名称和值。例如，把输出格式设置为LaTeX，可以键入-P format=latex。 | - | | -R, --record-separator=STRING | 设置记录分隔符。 | - | | -r | 开启在客户端操作中可以进行编辑的模式。缺省为关闭。 | - | | -t, --tuples-only | 只打印行。 | - | | -T, --table-attr=TEXT | 允许声明放在HTML table标签里的选项。 使用时请搭配参数"-H,--html"，指定为HTML格式输出。 | - | | -x, --expanded | 启用扩展格式显示。 | - | | -z, --field-separator-zero | 设置非对齐输出模式的域分隔符为空。 使用时请搭配参数"-A, --no-align"，指定为非对齐输出模式。 | - | | -0, --record-separator-zero | 设置非对齐输出模式的记录分隔符为空。 使用时请搭配参数"-A, --no-align"，指定为非对齐输出模式。 | - | | -2, --pipeline | 使用管道传输密码，禁止在终端使用，必须和-c或者-f参数一起使用。 | - | 表9连接参数 | 参数 | 参数说明 | 取值范围 | |:---|:---|:---| | -h, --host=HOSTNAME | 指定正在运行服务器的主机名、Unix域套接字的路径或者域名。接受以","分隔的字符串来指定多个主机地址，支持指定多个主机地址，支持指定IPv6主机地址。 当指定多个主机地址时，默认情况下会跳过故障的节点，自动选择第一个可用的主节点进行连接。可通过设置PGTARGETSESSIONATTRS环境变量的值来选择连接到不同类型的节点，PGTARGETSESSIONATTRS变量取值如下： - read-write：可读写的节点。 - read-only：只读节点。 - primary或者不设定：主节点。 - standby：备节点。 - prefer-standby：首选备节点，没有备节点则转为any。 - any：不进行角色检查。 说明： 主CN节点和主DN节点都是主节点，一般情况下DN节点都是只读节点，可以通过设置PGTARGETSESSIONATTRS为read-write来选择连接到CN节点。 | 如果省略主机名，gsql将通过Unix域套接字与本地主机的服务器相连，或者在没有Unix域套接字的机器上，通过TCP/IP与localhost连接。 | | -p, --port=PORT | 指定数据库服务器的端口号。可以配置一个或多个，当配置一个时，所有的主机地址都使用同一个端口连接；当配置多个时，顺序与主机地址顺序相同，个数必须与主机地址数相等，当不相等时会报错。 可以通过port参数修改默认端口号。 | 默认端口可通过编译参数来指定，不指定时默认为5432。 | | -U, --username=USERNAME | 指定连接数据库的用户。 说明： - 通过该参数指定用户连接数据库时，需要同时提供用户密码用以身份验证。可以通过交互方式输入密码，或者通过-W参数指定密码。 - 用户名中包含有字符$，需要在字符$前增加转义字符才可成功连接数据库。 | 字符串，默认使用与当前操作系统用户同名的用户。 | | -W, --password=PASSWORD | 当使用-U参数连接本地数据库或者连接远端数据库时，可通过该选项指定密码。 说明： - 登录CN所在服务器后连接本地CN实例时，默认使用trust连接，会忽略此参数。 - 用户密码中包含特殊字符"\\"和"\`"时，需要增加转义字符才可成功连接数据库。 - 如果用户未输入该参数，但是数据库连接需要用户密码，这时将出现交互式输入，请用户输入当前连接的密码。该密码最长长度为999字节，受限于GUC参数password_max_length的最大值。 | 字符串。 | 表10Unix Domain Socket运维通道的运维命令 | 参数 | 参数说明 | 取值范围 | |:---|:---|:---| | -O, --emergency-command=EMERGENCYCOMMAND | Unix Domain Socket运维通道的运维命令。 在极端情况下，gsql工具无法与GaussDB建立连接时，可以使用该命令进行应急运维。此命令通过Unix Domain Socket运维通道与GaussDB通信，实现一键运维功能。 -O选项的参数格式具体如下： ``` "{port} {command} [{param} [...]]" ``` {port}：数据库监听端口。 {command}：具体运维命令。 {param}：该运维命令的参数，可能有0个或多个。 说明： - 使用此选项时，gsql工具必须与GaussDB进程位于同一台服务器上。 - 如果运维命令的参数包含空格，请在参数两边加上引号。 | - "{port} mem_log"：记载全局的内存概况与全局级内存上下文、线程级内存上下文、session级内存上下文的top20内存上下文占用详情。该功能仅在GUC参数use_workload_manager开启时有效，范围同内存过载记录mem_log特性。无参数。示例： ``` -O "19995 mem_log" ``` - "{port} kill_wait_event {wait_event}"：查杀指定等待事件会话。参数{wait_event}表示具体的锁、轻量级锁以及I/O的信息等。示例： ``` -O "19995 kill_wait_event relation" ``` - "{port} kill_business_sql"：查杀非rdsAdmin用户的全部业务SQL语句。无参数。示例： ``` -O "19995 kill_business_sql" ``` - "{port} kill_slow_sql {username}"：批量查杀非默认数据库下，指定用户的状态为非idle的执行超过1分钟的SQL语句。参数{username}表示用户名。示例： ``` -O "19995 kill_slow_sql omm" ``` - "{port} kill_slow_sql {username} {database}"：批量查杀指定用户在指定数据库中的执行超过1分钟的SQL语句。参数{username}表示用户名，{database}表示数据库名。示例： ``` -O "19995 kill_slow_sql omm db1" ``` - "{port} kill_executing_sql {username}"：查杀非默认数据库下，指定用户的状态为active的正在执行的SQL语句。参数{username}表示用户名。示例： ``` -O "19995 kill_executing_sql omm" ``` - "{port} kill_mem_topn {top n}"：查杀内存占用top n的SQL语句。参数{top n}表示指定的top n。示例： ``` -O "19995 kill_mem_topn 10" ``` - "{port} kill_cpu_topn {top n}"：查杀CPU TIME占用top n的SQL语句。参数{top n}表示指定的top n。示例： ``` -O "19995 kill_cpu_topn 10" ``` | #### 示例 **示例一** 连接数据库并执行命令。 1. 使用gsql连接到GaussDB服务器。 gsql工具使用-d参数指定目标数据库名、-U参数指定数据库用户名、-h参数指定主机名、-p参数指定端口号信息。详细的gsql参数请参见[参数说明]。 ``` --使用jack用户连接到远程主机postgres数据库的8000端口。（根据实际需要替换各参数值） gsql -h 10.180.123.163 -d postgres -U jack -p 8000 ``` ![](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png) - 若未指定数据库名称，则使用初始化时默认生成的数据库名称。 - 若未指定数据库用户名，则默认使用当前操作系统用户作为数据库用户名。 - 当某个值没有前面的参数（-d、-U等）时，若连接的命令中没有指定数据库名（-d），则该参数会被解释为数据库名；如果已经指定数据库名（-d）而没有指定数据库用户名（-U），该参数则会被解释为数据库用户名。 例如，以下命令中，参数postgres和omm不属于任何选项，会被分别解释为数据库名和用户名。 ``` gsql postgres omm -p 8000 ``` 等效于以下命令。 ``` gsql -d postgres -U omm -p 8000 ``` 2. 执行gsql元命令和SQL语句。 ``` --创建数据库human_staff。 gaussdb=# CREATE DATABASE human_staff; CREATE DATABASE --列出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元命令请参见[元命令参考](https://support.huaweicloud.com/distributed-ref-v10-gaussdb/gaussdb-08-0619.html)。 **示例二** 获取帮助信息。 ``` 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 Emergency O&M command: -O, --emergency-command=EMERGENCYCOMMAND emergency O&M command 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. ``` **示例三** 执行Unix Domain Socket运维通道的运维命令。以下为如何通过Unix Domain Socket运维通道查看内存使用情况的简单示例： 1. 登录GaussDB节点所在服务器，执行以下gsql命令，确认是否生成内存概况以及内存上下文等使用记录。 ``` gsql -O "{port} mem_log" ``` 其中，{port}为数据库节点名称。当显示true时，则表示已生成具体的详情信息；如果执行失败，则显示失败原因。 ``` -- 示例中19995为数据库监听端口。 gsql -O "19995 mem_log" true ``` 2. 查看$GAUSSLOG/mem_log/{nodename}目录下生成的mem_log文件内容，其中{nodename}为数据库节点名称。 ``` -- 示例中datanode为数据库节点名称。 ls -l $GAUSSLOG/mem_log/datanode total 8 -rw-------. 1 omm omm 7543 May 28 15:15 mem_log-2025-05-28_151518.log ``` 3. 执行以下命令查看文件内容。 ``` cat $GAUSSLOG/mem_log/datanode/mem_log-time.log ``` 其中，mem_log-time.log为[2]中$GAUSSLOG/mem_log/datanode路径下生成的文件（文件名后缀为.log）。