一、前言

1.1 编写文档目的

本文档描述了KingbaseES ksql工具的使用指南以及常见问题。

1.2 适用范围

本文档面向所有使用金仓数据库的用户，主要是数据库管理员和应用程序开发人员。

1.3 相关文档

暂无

1.4 术语

二、Ksql入门

2.1 Ksql概述

  Ksql 是 KingbaseES 数据库的一个组件，在安装 KingbaseES 数据库时，默认会安装Ksql。Ksql 是 KingbaseES 基于终端的前端，提供交互式查询，通过文件输入或者命令行输入，得到查询结果。此外，Ksql还提供一些元命令和多种类似shell 的特性来为编写脚本和自动化多种任务提供便利。命令行方式的客户端对开发人员可能不太友好，但是对于运维人员来说非常的方便，是必须掌握的技能。

2.2 启动、停止Ksql

  要开始使用Ksql，就必须首先了解如何启动和停止 Ksql。当启动Ksql时，需要一个用户名和密码才能登录到KingbaseES数据库。数据库管理员负责创建具有必要权限的数据库账户，并提供能够访问的用户名和密码。使用连接命令对不同的用户进行连接，用户名和密码必须对该数据库有效。连接命令格式如下：

./ksql -U 账号名称 -W 密码 -p 端口 -d 数据库名称
1

其中，命令的常用参数以及作用如下表所示。

  在Linux或者Windows终端输入Ksql命令连接目标数据库，当目标数据库连接成功后，Ksql会提供一个提示符，该提示符是Ksql当前连接到的数据库名称后面跟上字符串=#。例如：

# 登录数据库
[root@localhost ~]cd /opt/Kingbase/ES/V8/Server/bin
# 登录kingbase -U 用户名 -W 密码 -P 端口 -d 数据库名
[root@localhost bin]# ./ksql -U system -p 54321 -d test
ksql (V8.0)
输入 "help" 来获取帮助信息.

test=# 
1
2
3
4
5
6
7
8

在使用ksql时，用户名与密码最好使用英文的双引号引用起来，否则一些特殊的符号，如分号（;）、|等特殊字符将会引发一些不必要的错误。

  在提示符下，用户可以键入SQL命令。正常情况下，当碰到一个表示命令终结的分号时，输入的行会被发送给服务器。一行的结束并不表示命令的完结。因此，为了清晰，可以把命令散布在多个行上。如果命令被发送并且执行而不产生错误，该命令的结果将会显示在屏幕上。例如：

test=# select * from sys_user;  
usename | usesysid | usecreatedb | usesuper | userepl | usebypassrls |  passwd  | valuntil | useconfig 
--------+----------+-------------+----------+---------+--------------+----------+----------+-----------
system  |       10 | t           | t        | t       | t            | ******** |          | 
sao     |        9 | f           | f        | f       | f            | ******** |          | 
sso     |        8 | f           | f        | f       | f            | ******** |          | 
1
2
3
4
5
6

  如果需要退出Ksql命令行，输入 quit 即可，Ksql正常完成，它会向 shell 返回 0。如果它自身发生一个致命错误（例如内存用完、找不到文件），它会返回 1。如果到服务器的连接出问题并且事务不是交互式的，它会返回 2。如果在脚本中发生错误，它会返回 3

2.3 输入和执行命令

  在Ksql命令行中，使用空格来分隔命令中的单词，分号(;)表示该命令的结束，然后按 ENTER 键，Ksql 处理该命令，将其发送到服务器并返回结果。如果在输入分号之前错误的按了 ENTER 键，Ksql 将提示输入命令的下一行的行号。键入分号再次运行命令。例如：

test=# select * from sys_user; 
usename | usesysid | usecreatedb | usesuper | userepl | usebypassrls |  passwd  | valuntil | useconfig 
--------+----------+-------------+----------+---------+--------------+----------+----------+-----------
system  |       10 | t           | t        | t       | t            | ******** |          | 
sao     |        9 | f           | f        | f       | f            | ******** |          | 
sso     |        8 | f           | f        | f       | f            | ******** |          | 
(3 行记录)
1
2
3
4
5
6
7

  假设不小心漏输where 条件，导致执行了一个结果集较大的查询任务，查询结果已经显示了一部分，但并不需要查看其余部分内容，这时可以使用 Ctrl + C 命令，Ksql 将停止显示。

三、Ksql 常用操作

3.1 查看当前用户和所有用户

[kingbase@node1 ~]$ ksql -h 192.168.3.111 -U SYSTEM -p 54321 -W test
ksql (V8.0)
输入 "help" 来获取帮助信息.

test=# \du
                             角色列表
 角色名称 |                    属性                    | 成员属于 
----------+--------------------------------------------+----------
 a        | 无法登录                                   | {}
 sao      | 没有继承                                   | {}
 sso      | 没有继承                                   | {}
 system   | 超级用户, 建立角色, 建立 DB, 复制, 绕过RLS | {}
 
test=# select * from sys_user;
usename | usesysid | usecreatedb | usesuper | userepl | usebypassrls |  passwd  | valuntil | useconfig 
--------+----------+-------------+----------+---------+--------------+----------+----------+-----------
system  |       10 | t           | t        | t       | t            | ******** |          | 
sao     |        9 | f           | f        | f       | f            | ******** |          | 
sso     |        8 | f           | f        | f       | f            | ******** |          | 
(3 行记录)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

3.2 显示所有数据库信息

[kingbase@node1 ~]$ ksql -h 192.168.3.111 -U SYSTEM -p 54321 -W test
ksql (V8.0)
输入 "help" 来获取帮助信息.

test=# \l
                                 数据库列表
   名称    | 拥有者 | 字元编码 | 校对规则 |    Ctype    |     存取权限      
-----------+--------+----------+----------+-------------+-------------------
 security  | system | UTF8     | ci_x_icu | zh_CN.UTF-8 | 
 template0 | system | UTF8     | ci_x_icu | zh_CN.UTF-8 | =c/system        +
           |        |          |          |             | system=CTc/system
 template1 | system | UTF8     | ci_x_icu | zh_CN.UTF-8 | =c/system        +
           |        |          |          |             | system=CTc/system
 test      | system | UTF8     | ci_x_icu | zh_CN.UTF-8 | 
(4 行记录)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15