金仓数据库KingbaseES ksql工具用户指南及参考--3. Ksql入门

3.1. 配置Ksql

3.1.1. Ksql环境变量

3.1.2. 配置文件

3.1.3. 注解

3.2. 启动Ksql

3.2.1. 登录用户名和密码

3.2.2. 连接到数据库

3.2.3. 有关启动Ksql

3.2.4. Ksql程序语法

3.1. 配置Ksql

3.1.1. Ksql环境变量

COLUMNS

如果\pset columns为零，这个环境变量控制用于wrapped格式的宽度以及用来确定是否输出需要用到分页器或者切换到扩展自动模式中的垂直格式的宽度。

KINGBASE_DATABASE

KINGBASE_HOST

KINGBASE_PORT

KINGBASE_USER

默认连接参数。

SYS_COLOR

指定是否在诊断消息中使用颜色。可能的值是always, auto, never.

KSQL_EDITOR

EDITOR

VISUAL

\e、\ef以及\ev命令所使用的编辑器。会按照列出的顺序检查这些变量，第一个被设置的将被使用。如果都没有被设置，默认是使用Linux系统上的vi或者Windows系统上的notepad.exe。

KSQL_EDITOR_LINENUMBER_ARG
当\e、\ef或者\ev带有一个行号参数时，这个变量指定用于传递起始行号给用户编辑器的命令行参数。对于Emacs或者vi之类的编辑器，这个变量是一个加号。如果需要在选项名称和行号之间有空格，可以在该变量的值中包括一个结尾的空格。例如：
KSQL_EDITOR_LINENUMBER_ARG='+'
KSQL_EDITOR_LINENUMBER_ARG='--line '
在 Unix系统上默认是+（对应于默认编辑器vi，且对很多其他常见编辑器可用）。在Windows 系统上没有默认值。
KSQL_HISTORY

命令历史文件的替代位置。波浪线（~）扩展会被执行。

KSQL_PAGER

PAGER

如果一个查询的结果在屏幕上放不下，它们会通过这个命令分页显示。典型的值是more或less。通过把KSQL_PAGER或PAGER设置为空字符串可以禁用分页器的使用，调整\pset命令与分页器相关的选项也能达到同样的效果。会按照列出的顺序检查这些变量，第一个被设置的将被使用。如果都没有被设置，则大部分平台上默认使用more，但在Cygwin上使用less。

KSQLRC

用户的.ksqlrc文件的替代位置。波浪线（~）扩展会被执行。

SHELL

被\!命令执行的命令。

TMPDIR

存储临时文件的目录。默认是/tmp。

和大部分其他KingbaseES工具一样，这个工具也使用libkci所支持的环境变量。

3.1.2. 配置文件

ksqlrc and ~/.ksqlrc

如果没有-X选项，在连接到数据库后但在接收正常的命令之前，Ksql会尝试依次从系统级的启动文件（ksqlrc）和用户的个人启动文件（~/.ksqlrc）中读取并且执行命令。这些文件可以被用来设置客户端或者服务器，通常是一些\set和SET命令。

系统级的启动文件是ksqlrc，它应该在安装好的KingbaseES的“系统配置”目录中，最可靠的定位方法是运行sys_config --sysconfdir。默认情况下，这个目录将是../etc/（相对于包含KingbaseES可执行文件的目录）。可以通过KCISYSCONFDIR环境变量显式地设置这个目录的名称。

用户个人的启动文件是.ksqlrc，它应该在调用用户的主目录中。在Windows 上，由于没有用户主目录的概念，个人的启动文件是%APPDATA%\kingbase\ksqlrc.conf。用户启动文件的位置可以通过KSQLRC环境变量设置。

系统级和用户个人的启动文件都可以弄成是针对特定Ksql版本的，方法是在文件名后面加上一个横线以及KingbaseES的主、次版本号，例如~/.ksqlrc-9.2或者~/.ksqlrc-9.2.5。版本最为匹配的文件会优先于不那么匹配的文件读入。

.ksql_history

命令行历史被存储在文件~/.ksql_history中，或者是Windows 的文件%APPDATA%\kingbase\ksql_history中。

历史文件的位置可以通过HISTFILEKsql变量或者KSQL_HISTORY环境变量明确的设置。

3.1.3. 注解

Ksql和具有相同主版本或者更老的主版本服务器最为匹配。如果服务器的版本比Ksql本身要高，则反斜线命令尤其容易失败。不过，\d家族的反斜线命令应该可以和V7版本之后的服务器一起使用，但服务器的版本不必比ksql本身新。运行 SQL 命令并且显示查询结果的一般功能应该也能和具有更新主版本的服务器一起使用，但是并非在所有的情况下都能保证如此。

如果你想用ksql连接到多个具有不同主版本的服务器，推荐使用最新版本的Ksql。或者，你可以为每一个主版本保留一份Ksql拷贝，并且针对相应的服务器使用匹配的版本。但实际上，这种额外的麻烦是不必要的。

在KingbaseES V8.2 之前，-c选项表示-X（--no-ksqlrc），但现在不是这样了。

在KingbaseES V7 之前，Ksql允许一个单字母反斜线命令的第一个参数直接写在该命令后面，中间不需要空格。现在则要求一些空格。

3.1.3.1. 给 Windows 用户的注解

Ksql是一个“控制台应用”。由于 Windows 的控制台窗口使用的是一种和系统中其他应用不同的编码，在Ksql中使用 8 位字符时要特别注意。如果Ksql检测到一个有问题的控制台代码页，它将会在启动时警告你。要更改控制台代码页，有两件事是必要的：

输入cmd.exe /c chcp 1252可以设置代码页（1252是适用于德语的一个代码页，请在这里替换成你的值）。如果正在使用Cygwin，可以把这个命令放在/etc/profile中。

把控制台字体设置为Lucida Console，因为栅格字体无法与ANSI 代码页一起使用。

3.2. 启动Ksql

3.2.1. 登录用户名和密码

当您启动Ksql时,需要一个用户名和密码才能登录到KingbaseES数据库模式。您的用户名和密码是KingbaseES数据库授权的用户。

数据库管理员负责创建具有必要权限的数据库账户，并提供能够访问的用户名和密码。

您可以使用连接命令对不同的用户进行连接，用户名和密码必须对该数据库有效。例如，连接到 user1用户：

$ ksql -Uuser1 -d test -p54320
ksql (V8.0)
Type "help" for help.

3.2.1.1. 更改密码

在命令行界面中，您可以使用 \password [ username ]命令修改密码。

3.2.2. 连接到数据库

必须连接到KingbaseES数据库才能查询或修改该数据库中的数据。您可以连接到默认数据库或通过网络连接到其他数据库。连接命令格式如下：

ksql [option...] [dbname [username]]

$ ksql -h 10.11.0.14 -Uuser1 -d test -p54320
Password for user user1:
ksql (V8.0)
Type "help" for help.

3.2.3. 有关启动Ksql

3.2.3.1. 启动Ksql命令行

要开始使用Ksql,您必须首先了解如何启动和停止Ksql。

请确保在您的计算机上已经安装了Ksql；
登录到操作系统(如果需要)；
输入连接到数据库的命令，然后按 Enter 键。例如：

ksql -h 10.11.0.14 -Uuser1 -d test -p54320

根据提示输入密码后再按 ENTER 键。为了保护您的密码安全不会显示在屏幕上。

$ ksql -h 10.11.0.14 -Uuser1 -d test -p54320
Password for user user1:
ksql (V8.0)
Type "help" for help.

Ksql显示连接的KingbaseES数据版本以及如何获取帮助的命令。接下来，Ksql将显示Ksql命令提示符：test=#

Ksql命令提示符指示Ksql已经准备好接受您的命令。

关于获取命令行帮助

若要访问Ksql命令的命令行帮助，在SQL命令提示符上输入 help 命令。例如：

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

3.2.3.2. 退出Ksql命令行

如果您因为用户名或密码无效或由于其他原因导致无法登录到Ksql,那么Ksql将返回相应的错误信息。

当您完成与Ksql相关的操作并返回到操作系统时,在Ksql提示符下输入 \q 命令或 Ctrl+Z。

3.2.4. Ksql程序语法

您可以使用操作系统提示符处的Ksql命令启动Ksql命令行：

ksql [option...] [dbname [username]]

例如：

ksql -p54320 -d test

启动Ksql并连接到默认数据库：
- 打开 UNIX或Windows终端，输入Ksql命令。例如：
```
$ ksql -p54320 -Uuser1
```
  命令参数中不指定连接的数据库。
- Ksql 启动并连接到默认数据库。
```
ksql (V8.0)
Type "help" for help.
user1=#
```
  现在，您可以开始在SQL#提示符下开始输入和执行SQL、PL/SQL和Ksql语句和命令。

3.2.4.1. option选项

-a --echo-all

把所有非空输入行按照它们被读入的形式打印到标准输出（不适用于交互式行读取）。这等效于把变量ECHO设置为 all。

-A --no-align

切换到非对齐输出模式（默认输出模式是对齐的）。这等效于 \pset format unaligned。

-b --echo-errors

把失败的 SQL 命令打印到标准错误输出。这等效于把变量ECHO设置为errors。

-c command --command=command
指定Ksql执行一个给定的命令字符串command。这个选项可以重复多次并且以任何顺序与-f选项组合在一起。当-c或者-f被指定时，Ksql不会从标准输入读取命令，直到它处理完序列中所有的-c和-f选项之后终止。

command必须是一个服务器完全可解析的命令字符串（即不包含Ksql相关的特性）或者单个反斜线命令。因此不能在一个-c选项中混合SQL和Ksql元命令。要那样做，可以使用多个-c选项或者把字符串用管道输送到Ksql中，例如：
ksql -c '\x' -c 'SELECT * FROM foo;'
或者
echo '\x \\ SELECT * FROM foo;' | Ksql
（\\是分隔符元命令）。

每一个被传递给-c的SQL命令字符串会被当做一个单独的请求发送给服务器。因此，即便该字符串包括多个SQL命令，服务器也会把它当做一个事务来执行，除非在该字符串中有显式的BEGIN/COMMIT命令把它划分成多个事务。此外，Ksql只会打印出该字符串中最后一个SQL命令的结果。这和从文件中读取同一字符串或者把同一字符串传给Ksql的标准输出时的行为不同，因为那两种情况下Ksql会独立地发送每一个SQL命令。

由于这种行为，把多于一个SQL命令放在-c字符串中通常会得到意料之外的结果。最好使用多个-c命令或者把多个命令输送给Ksql的标准输入，按照上文所说的使用echo或者通过一个 shell，例如：
ksql <<EOF
\x
SELECT * FROM foo;
EOF
--csv

切换到CSV(逗号分隔值)输出模式。这相当于\pset format csv。

-d dbname --dbname=dbname

指定要连接的数据库的名称。这等效于指定dbname为命令行上的第一个非选项参数。

如果这个参数包含一个=符号或者以一个合法的URI前缀（kingbase://或者kingbase://）开始，它会被当作一个conninfo字符串。

-e --echo-queries

把发送到服务器的所有 SQL命令复制到标准输出。这等效于把变量ECHO设置为queries。

-E --echo-hidden

回显\d以及其他反斜线命令生成的实际查询。可以用它来学习Ksql的内部操作。这等效于把变量ECHO_HIDDEN设置为on。

-f filename --file=filename

从文件filename而不是标准输入中读取命令。这个选项可以被重复多次，也可以以任意顺序与-c选项组合。当-c或者-f被指定时，Ksql不会从标准输入读取命令，直到它处理完序列中所有的-c和-f选项之后终止。除此以外，这个选项很大程度上等价于元命令\i。

如果filename是-（连字符），那么会读取标准输入直到遇见一个EOF指示或者\q元命令。这种方式可以用把自多个文件的输入组合成一种交互式输入。不过注意在这种情况下不会使用Readline（很像指定了-n的情况）。

使用这个选项与ksql < filename有细微的不同。通常，两种形式都可以做到我们所期望的，但是使用-f启用了一些好的特性，例如带有行号的错误消息。使用这个选项可以降低启动开销。在另一方面，使用shell输入重定向的变体（理论上）保证会得到与手工输入时相同的输出。

-F separator --field-separator=separator

使用separator作为非对齐输出的域分隔符。这等效于\pset fieldsep或者\f。

-h hostname --host=hostname

指定运行服务器的机器的主机名。如果这个值由一个斜线开始，它会被用作Unix 域套接字的目录。

-H --html

切换到HTML模式输出。这等效于\pset format html或者\H命令。

-l --list

列出所有可用的数据库，然后退出。其他非连接选项会被忽略。这与元命令\list类似。

在使用这个选项时，Ksql将连接到数据库kingbase，除非在命令行上提及一个不同的数据（选项-d或非选项参数，可能是通过一个服务项，但不能通过一个环境变量）。

-L filename --log-file=filename

除了把所有查询输出写到普通输出目标之外，还写到文件filename中。

-n --no-readline

不使用Readline做行编辑并且不使用命令历史。这对于在剪切和粘贴时关闭Tab很有用。

-o filename --output=filename

把所有查询输出放到文件filename中。这等效于命令\o。

-p port --port=port

指定服务器用于监听连接的 TCP 端口或者本地 Unix域套接字文件扩展。默认是KINGBASE_PORT环境变量的值，如果没有设置，则默认为编译时指定的端口号（通常是54321）。

-P assignment --pset=assignment

以\pset的形式指定打印选项。注意，这里你必须用一个等号而不是空格来分隔名称和值。例如，要设置输出格式为LaTeX，应该写成-P format=latex。

-q --quiet

指定Ksql应该安静地工作。默认情况下，它会打印出欢迎消息以及多种输出。如果使用了这个选项，以上那些就都不会输出。在使用-c选项时，配合这个选项很有用。这等效于设置变量QUIET为on。

-R separator --record-separator=separator

把separator用作非对齐输出的记录分隔符。这等效于\pset recordsep命令。

-s --single-step

运行在单步模式中。这意味着在每个命令被发送给服务器之前都会提示用户一个可以取消执行的选项。使用这个选项可以调试脚本。

-S --single-line

运行在单行模式中，其中新行会终止一个 SQL命令，就像分号的作用一样。

注意

这种模式被提供给那些坚持使用它的用户，但是并不一定要使用它。特别地，如果在一行中混合了SQL和元命令，那对于没有经的用户来说，它们的执行顺序可能不总是那么清晰。

-t --tuples-only

关闭打印列名和结果行计数页脚等。这等效于\t或者\pset tuples_only命令。

-T table_options --table-attr=table_options

指定要替换HTML``table``标签的选项。详见\pset tableattr。

-U username --username=username

作为用户username而不是默认用户连接到数据库（当然，你必须具有这样做的权限）。

-v assignment --set=assignment --variable=assignment

执行一次变量赋值，和\set元命令相似。注意你必须在命令行上用等号分隔名字和值（如果有）。要重置一个变量，去掉等号就行。要把一个变量置为空值，使用等号但是去掉值。这些赋值在命令行处理期间被完成，因此反映连接状态的变量将在稍后被覆盖。

-V --version

打印Ksql版本并且退出。

-w --no-password

从不发出一个口令提示。如果服务器要求口令认证并且没有其他方式提供口令（例如一个.pgpass文件），那儿连接尝试将失败。这个选项对于批处理任务和脚本有用，因为在其中没有一个用户来输入口令。

注意这个选项将对整个会话保持设置，并且因此它会影响元命令\connect的使用，就像初始的连接尝试那样。

-W --password

强制Ksql在连接到一个数据库之前提示要求一个口令。

这个选项不是必不可少的，因为如果服务器要求口令认证，Ksql将自动提示要求一个口令。但是，Ksql将浪费一次连接尝试来发现服务器想要一个口令。在某些情况下值得用-W来避免额外的连接尝试。

注意这个选项将对整个会话保持设置，并且因此它会影响元命令\connect的使用，就像初始的连接尝试那样。

-x --expanded

打开扩展表格式模式。这等效于\x或者\pset expanded命令。

-X --no-ksqlrc

不读取启动文件（要么是系统范围的ksqlrc文件，要么是用户的~/.ksqlrc文件）。

-z --field-separator-zero

设置非对齐输出的域分隔符为零字节。这等效于\pset fieldsep_zero。

-0 --record-separator-zero

设置非对齐输出的记录分隔符为零字节。例如，这对与xargs -0配合有关。这等效于\pset recordsep_zero。

-1 --single-transaction

这个选项只能被用于与一个或者多个-c以及/或者-f选项组合。它会让Ksql在第一个上述选项之前发出一条BEGIN命令并且在最后一个上述选项之后发出一条COMMIT命令，这样就把所有的命令都包裹在一个事务中。这个选项可以保证要么所有的命令都成功地完成，要么不应用任何更改。

如果命令本身包含BEGIN、COMMIT或者ROLLBACK，这个选项将不会得到想要的效果。此外，如果单个命令不能在一个事务块中执行，指定这个选项将导致整个事务失败。

-? --help[=topic]

显示有关Ksql的帮助并且退出。可选的topic参数（默认为options）选择要解释哪一部分的Ksql：commands描述Ksql的反斜线命令；options描述可以被传递给Ksql的命令行选项；而variables则显示有关Ksql配置变量的帮助。