gaussdb 数据库连接工具【gsql 使用、获取帮助、选项参考】【02】

1. 使用

• 使用gsql 连接到GaussDB服务器。

示例1，使用gaussdba用户连接到本机postgres数据库的5432端口。

gsql -d postgres -U gaussdba -p 5432

示例2，使用gaussdba用户连接到远程主机postgres数据库的5432端口。

gsql -h 192.168.3.4 -d postgres -U gaussdba -p 5432

示例3，不指定任何参数。假设执行gsql的操作系统用户为gaussdba，默认端口号为5432。

gsql 等效于 gsql -d postgres -U gaussdba -p 5432

2. 获取帮助

• 连接数据库时，可以使用如下命令获取帮助信息

gsql --help

显示如下帮助信息：

......
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: "postgres")
  -f, --file=FILENAME      execute commands from file, then exit
......

• 连接到数据库后，可以使用如下命令获取帮助信息

显示如下帮助信息：

You are using gsql, the command-line interface to gaussdb.
Type:  \copyright for distribution terms
       \h for help with SQL commands
       \? for help with gsql commands
       \g or terminate with semicolon to execute query
       \q to quit

例如，查看GaussDB支持的所有SQL命令：

POSTGRES-# \h
Available help:
  ABORT                            DECLARE  
  ALTER COLLATION                  DISCARD
... ...

例如，查看CREATE DATABASE命令的参数可使用下面的命令：

POSTGRES-# \help CREATE DATABASE
Command:     CREATE DATABASE
Description: create a new database
Syntax:
CREATE DATABASE name
    [ [ WITH ] [ OWNER [=] user_name ]
           [ TEMPLATE [=] template ]
           [ ENCODING [=] encoding ]
           [ LC_COLLATE [=] lc_collate ]
           [ LC_CTYPE [=] lc_ctype ]
           [ TABLESPACE [=] tablespace ]
           [ TABLESPACE [=] tablespace_name ]
           [ CONNECTION LIMIT [=] connlimit ] ]

例如，查看gsql支持的元命令操作：

POSTGRES-# \?
General
  \copyright             show PostgreSQL usage and distribution terms
  \g [FILE] or ;         execute query (and send results to file or |pipe)
  \h [NAME]              help on syntax of SQL commands, * for all commands
  \q                     quit gsql
... ...

3. gsql选项参考

• 常用选项

参数	参数说明	取值范围
-c, --command=COMMAND	声明gsql要执行一条字符串命令然后退出。	-
-d, --dbname=DBNAME	指定想要连接的数据库名称。	字符串。
-f, --file=FILENAME	使用FILENAME作为命令的语句源而不是交互式读入查询。gsql将在处理完文件后结束。如果FILENAME是-（连字符），则从标准输入读取。 说明： 数据库会将文件划分多个容量为2040字节的缓冲区，每次同时执行一个缓冲区中的多条语句，如果这些语句中存在创建新函数或者存储过程，则此缓冲区中后面的语句调用新创建的函数或存储过程时会报错。	绝对路径或相对路径，且满足操作系统路径命名规则。
-l, --list	列出所有可用的数据库，然后退出。	-
-v, --set=, --variable=NAME=VALUE	设置gsql变量NAME为VALUE。	-
-X, --no-gsqlrc	不读取启动文件（系统范围的gsqlrc或者用户的~/.gsqlrc都不读取）。	-
-1 ("one"), --single-transaction	当gsql使用-f选项执行脚本时，在脚本的开头和结尾分别加上START TRANSACTION/COMMIT用以把整个脚本当作一个事务执行。这将保证该脚本完全执行成功，或者脚本无效。 说明： 如果脚本中已经使用了START TRANSACTION，COMMIT，ROLLBACK，则该选项无效。	-
-?, --help	显示关于gsql命令行参数的帮助信息然后退出。	-
-V, --version	打印gsql版本信息然后退出。	-

• 输入和输出参数

参数	参数说明	取值范围
-a, --echo-all	在读取行时向标准输出打印所有内容。	-
-e, --echo-queries	把所有发送给服务器的查询同时回显到标准输出。	-
-E, --echo-hidden	回显由\d和其他反斜杠命令生成的实际查询。	-
-k, --with-key=KEY	使用gsql进行导入时用于解密加密文件。 注意： 对于本身就是 shell 命令中的关键字符如单引号（'）或双引号（"），Linux shell 会检测输入的单引号（'）或双引号（"）是否匹配。如果不匹配，shell 认为用户没有输入完毕，会一直等待用户输入，从而不会进入到 gsql 程序。	-
-L, --log-file=FILENAME	除了正常的输出源之外，把所有查询输出记录到文件FILENAME。	绝对路径或相对路径，且满足操作系统路径命名规则。
-o, --output=FILENAME	将所有查询输出重定向到文件FILENAME。	绝对路径或相对路径，且满足操作系统路径命名规则。
-q, --quiet	安静模式。	缺省时gsql将打印许多其他输出信息。
-s, --single-step	单步模式运行。意味着每个查询在发往服务器之前都要提示用户，用这个选项也可以取消执行。此选项主要用于调试脚本。	-
-S, --single-line	单行运行模式，这时每个命令都将由换行符结束，像分号那样。	-

• 输出格式参数

参数	参数说明	取值范围
-A, --no-align	切换为非对齐输出模式。	缺省为对齐输出模式。
-F, --field-separator=STRING	设置域分隔符（默认为 “|”）。	-
-H, --html	打开HTML格式输出。	-
-P, --pset=VAR[=ARG]	在命令行上以 \pset 的风格设置打印选项。 说明： 这里必须用等号而不是空格分隔名称和值。例如，把输出格式设置为 LaTeX ，可以键入 -P format=latex	-
-R, --record-separator=STRING	设置记录分隔符。	-
-t, --tuples-only	只打印行。	-
-T , --table-attr=TEXT	允许声明放在HTML table标签里的选项。	-
-x,--expanded	打开扩展表格式模式。	-
-z, --field-separator-zero	设置域分隔符为'\000'。	-
-0, --record-separator-zero	设置记录分隔符为'\000'。	-

• 连接参数

参数	参数说明	取值范围
-h, --host=HOSTNAME	指定正在运行服务器的主机名或者Unix域套接字的路径。	如果省略主机名，gsql将通过Unix域套接字与本地主机的服务器相联，或者在没有Unix域套接字的机器上，通过TCP/IP与localhost连接。
-p, --port=PORT	指定数据库服务器的端口号。 可以通过port参数修改默认端口号。	默认为5432。
-U, --username=USERNAME	指定连接数据库的用户。 说明： 通过该参数指定用户连接数据库时，需要同时提供用户密码用以身份验证。您可以通过交换方式输入密码，或者通过-W参数指定密码。	字符串。默认使用与当前操作系统用户同名的用户。
-w, --no-password	不提示用户输入密码。 说明： 如果使用该参数，则只能从环境变量GAUSSPASSWORD获取用户密码，而不会提示用户输入。	-
-W, --password=PASSWORD	当使用-U参数连接本地数据库或者连接远端数据库时，可通过该选项指定密码。如果省略此参数： 优先使用环境变量GAUSSPASSWORD的值做为-U参数指定用户的密码。 如果环境变量GAUSSPASSWORD的值为空，则会提示用户输入密码。	符合密码复杂度要求。