企业官网建设流程全解析

KingbaseES 客户端连接机制与 ksql 命令行交互基础

本文继续使用 Windows 本地环境，以ksql连接电科金仓 KingbaseES 数据库。目标不是只连上一次，而是掌握连接、查看状态、执行 SQL、保存结果和脚本化执行这一套基础动作。

引言

上一篇文章完成了 KingbaseES Windows 单机环境的基线检查，确认了服务、端口、工具目录和本地连接条件都可用。有了这个基础，本文就可以进一步进入客户端层面，重点研究ksql如何连接 KingbaseES，以及连接成功后应该如何进行基础交互。

本文不是只演示一条连接命令，而是围绕ksql的使用链路展开：先拆解连接参数，再确认会话状态，然后学习常用元命令，最后把 SQL 写成脚本执行。这样做的目的，是让读者从“能连上数据库”进一步过渡到“能稳定、可重复地使用命令行管理数据库”。

这一篇开始正式使用ksql。

ksql是 KingbaseES 自带的命令行连接工具。它适合做三类事情：

1. 日常验证：确认数据库是否能连、当前用户是谁、当前连到哪个库。
2. SQL 实操：执行建库、建表、查询、授权、事务等操作。
3. 运维脚本：把 SQL 写成脚本文件，通过命令行重复执行。

本文会围绕本地环境进行演示：

工具目录：D:\Tools\Kingbase\ES\Server\bin 连接命令：ksql -U system -d test -h localhost -p 54321 登录用户：system 目标数据库：test 主机地址：localhost 端口号：54321

ksql 在数据库访问链路中的位置

ksql不是数据库本身，而是 KingbaseES 提供的命令行客户端。它的作用是把用户输入的 SQL、元命令和连接参数组织起来，通过数据库通信协议发送给服务端，再把服务端返回的结果显示在终端中。

一次完整的ksql连接可以拆成三层：

数据库会话是后续所有操作的上下文。你执行的SELECT、CREATE TABLE、\dt、\conninfo都发生在这个会话中。理解这一点很重要，因为很多问题不是 SQL 本身错了，而是会话上下文不对：连错数据库、使用了错误用户、搜索路径不一致，都会导致结果和预期不同。

因此本文不只是演示“如何连上”，还会强调连接后的自检动作：确认当前库、当前用户、服务端口和客户端状态。这个习惯在本地学习时看似繁琐，但在多环境、多数据库、多账号的企业场景里非常关键。

一、连接命令先拆开看

完整连接命令如下：

这条命令推荐作为本系列的标准连接写法。它没有依赖默认数据库、默认端口或当前操作系统用户名，而是把连接信息全部显式表达出来

ksql -U system -d test -h localhost -p 54321

第一次使用时，不要机械复制，最好先理解每个参数。

如果把数据库连接想成一次“进入房间”的过程，可以这样类比：

localhost -> 这栋楼在本机 54321 -> 从哪个门进去 test -> 进入哪一个房间 system -> 用哪个身份进去 password -> 身份对应的钥匙

官方快速上手手册中提到，ksql支持本地连接和远程连接。本文使用的localhost就是本地连接，适合学习和单机验证。

二、进入 ksql 所在目录

打开 Windows 命令提示符：

Win + R -> 输入 cmd -> 回车

进入 KingbaseES 工具目录：

ksql.exe位于 KingbaseES 安装目录的Server\bin下。进入这个目录后再执行命令，可以避免环境变量未配置导致的命令识别问题。对于新手读者来说，这种写法比要求先配置 PATH 更稳。

cd /d D:\Tools\Kingbase\ES\Server\bin

确认当前目录：

cd

预期看到：

D:\Tools\Kingbase\ES\Server\bin

确认ksql.exe存在：

dir ksql.exe

如果能看到文件列表，就可以执行连接命令。

三、连接本地 test 数据库

执行：

ksql -U system -d test -h localhost -p 54321

随后会提示输入密码。这里输入的是system用户的数据库密码。为了安全，密码不会明文显示，这是正常现象。

连接成功后，会进入类似界面：

看到test=#，说明已经进入test数据库的交互界面。

如果提示符是：

test=>

也不一定是错误。一般可以先理解为当前连接用户权限不同。本文使用system用户时，通常会看到#。

四、先执行 4 条确认 SQL

连接成功后，不要马上建表。建议先做一次“身份确认”。

身份确认的意义在于降低误操作风险。数据库命令行没有图形界面那样明显的环境提示，一旦连错库或用错用户，后续 SQL 可能会在错误环境中执行。下面 4 条查询分别确认数据库、用户、端口和时间，构成一个最小会话检查清单。

1. 查看当前数据库

SELECTcurrent_database();

预期结果：

current_database ------------------ test

2. 查看当前用户

SELECTcurrent_user;

预期结果：

current_user -------------- system

3. 查看当前端口

SELECTinet_server_port();

预期结果：

inet_server_port ------------------ 54321

4. 查看当前时间

SELECTnow();

这条 SQL 主要验证数据库执行 SQL 的能力。如果能返回时间，说明当前会话可以正常执行查询。

也可以把 4 条合成一条：

SELECTcurrent_database()ASdb_name,current_userASlogin_user,inet_server_port()ASserver_port,now()ASdb_time;

五、掌握 ksql 的几个常用元命令

在ksql中，除了普通 SQL，还有一类以反斜杠开头的命令，常被称为元命令。它们不是业务 SQL，而是ksql客户端提供的辅助能力。

1. 查看帮助

\?

帮助信息较多时，可以按空格翻页，按q退出帮助页面。

2. 查看当前连接信息

\conninfo

这条命令很实用。连接多个库、多个环境时，先执行一次\conninfo，可以避免把测试库和生产库搞混。

3. 查看数据库列表

\l

这会列出当前实例中的数据库。

如果你想确认test是否存在，可以使用：

\l test

4. 查看当前库中的表

\dt

刚开始学习时，test数据库里可能没有业务表，输出为空是正常的。

5. 查看 SQL 执行耗时

\timing

开启后，再执行 SQL，ksql会显示耗时。后续讲 SQL 调优时，这个命令会经常用到。

再次执行可以关闭：

\timing

6. 清屏

Windows 中可以执行：

\!cls

Linux 中可以执行：

\!clear

\!的意思是让ksql调用操作系统命令。

六、创建一个连接验证表

为了让本文不只停留在“能连上”，我们创建一个很小的验证表，记录每次连接测试。

这个表本身没有复杂业务含义，它的价值在于验证当前用户是否具备创建模式、创建表、插入数据和查询数据的能力。换句话说，它把“连接成功”进一步扩展为“连接后可以完成基本读写”。

CREATESCHEMAIFNOTEXISTSkb_course;

切换当前会话的搜索路径：

SETsearch_pathTOkb_course,public;

创建连接检查表：

CREATETABLEIFNOTEXISTSconnect_check(idSERIALPRIMARYKEY,check_itemVARCHAR(50)NOTNULL,check_resultVARCHAR(100)NOTNULL,client_hostVARCHAR(100),server_portINT,checked_atTIMESTAMPDEFAULTCURRENT_TIMESTAMP);

插入一条记录：

INSERTINTOconnect_check(check_item,check_result,client_host,server_port)VALUES('ksql_local_login','success','localhost',inet_server_port());

查询验证：

SELECTid,check_item,check_result,client_host,server_port,checked_atFROMconnect_checkORDERBYidDESC;

预期结果类似：

这一步说明三件事：

1. 当前用户有创建模式和表的权限。
2. 当前会话能够写入数据。
3. SQL 查询能正确返回结果。

七、把查询结果输出到文件

在写技术文章时，经常需要保留命令输出。ksql可以用\o把查询结果输出到文件。

在ksql中执行：

\o D:/Tools/Kingbase/connect_check_report.txt

然后执行：

SELECTcurrent_database()ASdb_name,current_userASlogin_user,inet_server_port()ASserver_port,COUNT(*)AScheck_countFROMconnect_check;

关闭输出重定向：

\o

此时可以到 Windows 中查看文件：

type D:\Tools\Kingbase\connect_check_report.txt

如果路径不存在，可以换成桌面或其他已有目录，例如：

\o C:/Users/你的用户名/Desktop/connect_check_report.txt

注意在ksql中写 Windows 路径时，建议使用正斜杠/，这样可以减少反斜杠转义带来的麻烦。

八、把 SQL 写成脚本重复执行

命令行工具的价值不只是手工输入 SQL，更重要的是可以脚本化。

脚本化的意义在于可重复。手工输入适合学习和演示，但巡检、初始化、批量验证更适合写入.sql文件后统一执行。这样不仅减少输入错误，也方便把执行过程留痕。

在D:\Tools\Kingbase\ES\Server\bin目录外创建一个脚本文件，例如：

D:\Tools\Kingbase\sql\01_connect_check.sql

文件内容如下：

\echo'Start KingbaseES ksql connection check...'SELECTcurrent_database()ASdb_name,current_userASlogin_user,inet_server_port()ASserver_port,now()ASdb_time;CREATESCHEMAIFNOTEXISTSkb_course;SETsearch_pathTOkb_course,public;CREATETABLEIFNOTEXISTSconnect_check(idSERIALPRIMARYKEY,check_itemVARCHAR(50)NOTNULL,check_resultVARCHAR(100)NOTNULL,client_hostVARCHAR(100),server_portINT,checked_atTIMESTAMPDEFAULTCURRENT_TIMESTAMP);INSERTINTOconnect_check(check_item,check_result,client_host,server_port)VALUES('ksql_script_login','success','localhost',inet_server_port());SELECTid,check_item,check_result,client_host,server_port,checked_atFROMkb_course.connect_checkORDERBYidDESCLIMIT5;\echo'Connection check finished.'

然后回到命令提示符执行：

cd /d D:\Tools\Kingbase\ES\Server\bin ksql -U system -d test -h localhost -p 54321 -f D:\Tools\Kingbase\sql\01_connect_check.sql

这条命令的关键是-f：

以后做巡检、初始化、批量验证时，就可以把 SQL 固化成脚本，而不是每次手工敲。

九、退出 ksql

交互模式中退出：

\q

也可以使用：

QUIT

更推荐记住\q，简短直接。

退出前请养成一个习惯：如果执行过修改数据的操作，要确认是否需要提交或回滚。

COMMIT;

或：

ROLLBACK;

本文中大多数语句在默认自动提交模式下会立即生效；后续讲事务时，会专门说明自动提交、显式事务和回滚之间的关系。

十、可选：从 Linux 服务器连接 Windows 上的 KingbaseES

如果你有 CentOS 或 Ubuntu 服务器，也可以把它作为客户端去连接 Windows 上的 KingbaseES。但这一步不是本文必需内容，适合在本地连接稳定后再尝试。

假设 Windows 主机 IP 是：

192.168.1.100

Linux 上如果已经安装了 KingbaseES 客户端或有ksql工具，可以尝试：

ksql-h192.168.1.100-p54321-Usystem-dtest

如果连不上，排查顺序是：

1. Windows 防火墙是否放行54321。
2. KingbaseES 是否监听外部地址，而不只是localhost。
3. 数据库访问控制配置是否允许该 Linux 服务器地址连接。
4. 两台机器网络是否互通。

网络连通性可以先测：

ping192.168.1.100

端口连通性可以用：

nc-vz192.168.1.10054321

或：

telnet192.168.1.10054321

远程连接涉及监听地址、防火墙和访问控制，后续可以单独写一篇“跨平台连接与远程访问排查”。

十一、常见问题排查

问题 1：ksql命令找不到

原因通常是没有进入工具目录。

处理：（下面D:\Tools\Kingbase\ES\Server\bin换成你的实际目录）

cd /d D:\Tools\Kingbase\ES\Server\bin dir ksql.exe

确认存在后再执行连接命令。

问题 2：连接时一直要求输入密码

可能是密码输入错误，也可能是用户写错。

建议先确认命令：

ksql -U system -d test -h localhost -p 54321

然后输入system用户对应的密码。生产或正式环境中，不建议把密码直接写在命令行里。

问题 3：relation "connect_check" does not exist

可能是没有设置搜索路径，或者表不在当前模式下。

处理方式一：设置搜索路径。

SETsearch_pathTOkb_course,public;SELECT*FROMconnect_check;

处理方式二：使用完整对象名。

SELECT*FROMkb_course.connect_check;

问题 4：执行脚本时报路径错误

Windows 路径建议检查三点：

带双引号的写法：

ksql -U system -d test -h localhost -p 54321 -f "D:\Tools\Kingbase\sql\01_connect_check.sql"

十二、本文小结

本文承接第一篇的环境检查，完成了从“数据库服务可用”到“客户端会话可控”的过渡。通过这一篇，读者不仅知道连接命令怎么写，也能理解-U、-d、-h、-p分别代表什么，知道进入ksql后应先确认当前数据库、当前用户和连接端口。

本文完成了第一次ksql实战：

进入 Server\bin 连接 test 数据库 确认当前库、用户、端口和时间 学习常用 ksql 元命令 创建 kb_course.connect_check 验证表 把查询结果输出到文件 通过 -f 执行 SQL 脚本

到这里，ksql已经不只是“能打开”的工具，而是可以承担基础验证和脚本化操作的入口。

下一篇将从客户端交互进入数据库对象管理：创建一个本系列专用业务数据库kb_shop。后续客户、商品、订单、库存、查询、事务和备份恢复都会围绕这个业务库展开，因此第三篇会重点讲数据库生命周期和业务边界设计。