KingbaseES数据库：本地连接全攻略！从环境检查到问题排查，新手也能轻松上手

本文是专为 KingbaseES 数据库新手打造的本地连接指南，涵盖从环境准备到问题解决的完整流程。先通过启动金仓数据库管控工具、创建并验证实例，确认数据库启动状态与服务端口（默认 54321，非默认可通过配置文件查询）；再详解 ksql 命令行连接步骤，包括进入工具路径、执行连接命令及验证成功标识，同时说明断开连接的两种命令与事务处理注意事项；还介绍了查看帮助、连接信息、清屏及基础 SQL 执行等交互操作，最后针对 "连接被拒绝""密码失败""数据库不存在" 3 类高频报错，给出原因与解决办法，助新手快速掌握本地连接核心技能。

咱用 KingbaseES 数据库玩命令行的时候，"连上本地数据库"这步要是搞不定，后面啥操作都白搭------就像开车没插钥匙，再牛的车也动不了！别慌，就算你是刚摸数据库的"小白"，跟着这篇攻略走，从连接到唠嗑（基础交互），再到搞定那些让人头大的连接问题，保准你学得明明白白，比刷短视频还轻松！

一、前置环境检查：先确保数据库"醒着且能接客"

输连接命令前，咱得先确认俩事儿：本地 KingbaseES 数据库得是启动状态 ，还有得知道它的"门牌号"（服务端口） ------默认端口直接用就行，要是你之前瞎改了，就得费点劲找回来。

1.1 启动「金仓数据库管控工具」

启动这工具跟开饮料似的，有两种开盖方式，你选顺手的来：

桌面快捷方式：要是装数据库时选了创建快捷方式，直接找桌面上"金仓数据库管控工具"那图标，双击一下，跟点开微信似的简单。
开始菜单 ：点 开始→所有程序→KingbaseES V9→金仓数据库管控工具 也能启动。

打开后，左边导航栏选【单节点列表】（要是你装的是集群环境，就选"读写分离集群列表"，别选错了哈），右边会显示已有的实例------刚装完的时候这儿是空的，跟刚搬的空房子一样，正常！

1.2 点击「创建新实例」，进入配置向导

接下来得点「创建新实例」才能进配置向导，这步就像给空房子装家具。记住，必须在【单节点列表】这界面里，找到那个红通通的【创建新实例】按钮点进去，不然没法设置实例的那些参数，白忙活一场。

1.2.1 配置实例核心参数

点完会弹出"创建数据库实例"的窗口，按步骤填信息就行，跟填快递单似的简单。

要是你想调调内存、连接数这些"高级配置"，就把【高级配置】勾上；要是觉得默认的够用，直接点【下一步】，别瞎折腾。

1.3 执行实例创建，注册为系统服务

到了"执行"页面，有俩关键选项必须勾上，跟出门记得带钥匙一样重要，千万别漏：

✅ 创建后立即执行：勾上这个，系统会自动弄好日志、表空间这些数据文件，不用你手动捣鼓；
✅ 创建之后可登记为系统服务 ：比如登记成"KingbaseES_V9_kes_dev"这样的Windows服务，后续不仅开机能自动启动，管理起来也方便，跟给家里装了智能开关似的。

勾好之后点【执行】，然后等着进度条跑完就行，别着急催。这个过程会显示"初始数据库实例→设置参数→运行实例→注册服务"这几步，得每一步都显示"成功"，才算真搞定。要是中间失败了，看下面的执行日志就行，常见问题无非是端口被别的程序占了、数据目录没权限，或者内存不够用，跟手机提示"存储空间不足"一个道理。

1.4 验证实例是否正常运行

回到【单节点列表】，刷新一下，就能看到刚创建的新实例了。正常情况下，它的运行状态会显示"运行中"，还带着绿色的"健康码"；要是显示红色，就点【查看】-【日志】，跟医生看病查病历似的，准能找到问题。

这里必须唠叨一句：实例和软件不是一回事，别搞混了！

KingbaseES软件：就像"数据库引擎"，是给数据库提供"动力"的运行环境；
数据库实例才是真正的"工作间"，里面存着数据、用户、表，还有各种设置。这就好比"MySQL安装包"和"test数据库服务"的区别------得先有实例，才能存数据、干活，总不能在空安装包上写文档吧？

1.5 确认本地 KingbaseES 数据库已启动

数据库要是没启动，你再怎么试连接都白搭，跟对着关机的手机打电话一样。所以第一步必须查启动状态，不同系统查法不一样，咱分开说：

Linux 系统 ：想知道数据库跑没跑，打开终端输个命令就行。敲下面这行，要是能看到带"kingbase"的进程，说明它醒着；要是啥都没有，就得手动启动（具体命令看数据库安装目录里的启动脚本，比如 /opt/Kingbase/ES/V9/Server/bin/kingbasectl start）：
bash 复制代码
```
ps aux | grep kingbase
```
Windows 系统：得从"服务"里看状态，步骤超简单：
1. 按 Win + R，输 services.msc 打开"服务"窗口，跟打开电脑控制面板似的；
2. 在服务列表里找你刚创建的实例，没改名字的话默认叫"kes_instance"，别找错了；
3. 右键点服务→【启动】（要是已经启动了就跳过，别重复操作）；
  - 要是启动失败，后面"常见问题"里有办法，别慌；
4. 确认服务状态是"正在运行"，启动类型设成"自动"------这样重启电脑后不用手动启动，省事儿！

1.6 获取数据库服务端口（关键！默认/非默认都得会）

KingbaseES 数据库默认"门牌号"是 54321，要是你没改端口，这步直接跳过；要是改了，或者忘了自己改没改，就得按下面的方法找：

1.6.1 Linux 系统查询端口

先找到数据库的"数据文件路径"（装的时候自己选的，默认可能是 /opt/kingbase/data 或 /test/kb_install/data，别瞎猜）；
输下面这行命令，从 kingbase.conf 配置文件里扒端口信息，把"你的数据文件路径"换成真路径就行：
bash 复制代码
```
cat /你的数据文件路径/kingbase.conf | grep ^\s*port
```
举个例子（假设数据路径是 /opt/kingbase/data）：
bash 复制代码
```
cat /opt/kingbase/data/kingbase.conf | grep ^\s*port
```
输完会显示类似 port = 54321 的结果，等号后面的数字就是"门牌号"。

1.6.2 Windows 系统查询端口

先找到数据文件路径（我这儿有个参考路径，你得找自己的，别照抄）；
按 Win + R，输 cmd 打开命令提示符，然后敲下面这行命令（把"D:\Tools\Kingbase\ES\kes_instance"换成你的数据路径）：
cmd 复制代码
```
findstr /R "^\s*port" D:\Tools\Kingbase\ES\kes_instance\kingbase.conf
```
输完会显示 port = 54321，这就是当前的服务端口，记下来别丢了！

二、ksql 连接本地数据库

ksql 是 KingbaseES 自带的"连接器"，本地连接不用跨网络，比远程连接简单多了，就两种情况："用默认端口连"和"指定端口连"。

前提：先打开命令行终端

Linux 系统 ：直接按 Ctrl + Alt + T 打开终端，快得很；
Windows 系统 ：按 Win + R 输 cmd 开"命令提示符"，或者开"PowerShell"也行。

先进入 ksql 所在的文件夹（就在安装目录的 Server\bin 里），比如我这路径是 D 盘的，就输：
cmd 复制代码
```
cd /d D:\Tools\Kingbase\ES\Server\bin
```
输连接命令（默认管理员用户是 system，密码 manager，数据库 test，端口 54321，别瞎改，改了就错了）：
cmd 复制代码
```
ksql -U system -d test -h localhost -p 54321
```
然后输密码（默认是 manager，要是你装的时候改了密码，就输改后的，别记错了），按回车；
要是看到下面这提示，说明你连成功了，能开始操作了：

bash 复制代码

 授权类型: 开发版.
输入 "help" 来获取帮助信息.
test=#

三、ksql 断开数据库连接：简单两步，别忘保存

想退出 ksql 命令行？不用复杂操作，输个命令就行，但有个坑得注意------"没提交的事务"！要是你有操作没保存，断开前得想清楚要不要提交，不然数据丢了哭都来不及。

3.1 断开命令：两种写法都能用

在 test=# 后面，输下面随便一个命令，按 Enter 就断开了：

快捷命令（推荐用这个，省事儿）：\q（就是小写 q 前面加个反斜杠，别输错了）；
完整命令：QUIT（大小写随便，输 quit 也管用，不用纠结）。

输完之后，就回到系统终端了------Linux 会显示 user@localhost:~$，Windows 显示 C:\Users\用户名>，这就说明断干净了。

3.2 重要提醒：断开前先检查事务！

断开之前，一定得看看有没有没处理完的事务！要是你在连接的时候，做了 INSERT（插入数据）、UPDATE（改数据）、DELETE（删数据）这些操作，还没输 COMMIT（提交），一断开连接，这些操作就全"白干"了，数据根本存不下来。

所以断开前必须确认：

想保存操作：先输 COMMIT;（末尾的分号别漏，不然没效果）；
不想保存了：就输 ROLLBACK;（回滚完再断开，别心疼）。

四、ksql 基础交互命令：4个新手必学操作

连成功之后，得会用这几个命令，不然在 ksql 里跟"哑巴"似的，这些命令是后续操作的基础，文档里写得很清楚，咱慢慢说。

4.1 查看帮助：忘了命令就查它

要是忘了命令咋输，别瞎蒙，输 \?（反斜杠后面跟个问号，别输错），然后按 Enter，就能看到 ksql 命令的详细说明------里面分了好多类，比如"连接管理""查询操作""对象查看"，新手重点看"Connection"（连接）和"General"（通用）这两类就行，别贪多。

举个例子：

plaintext 复制代码

\?

输完会出来一大堆命令，按 Space 键翻页，想退出帮助界面就按 q，跟看小说翻页一样。

4.2 查看当前连接信息：确认自己连对了没

想知道自己当前连的是哪个数据库、用的哪个用户、端口对不对，输下面这命令就行：

plaintext 复制代码

 \conninfo

输完会显示类似的结果，连得对不对，一眼就能看明白，别连错库还瞎操作。

4.3 清屏：让界面清爽点

要是终端里显示的内容太多，看得眼晕，就清个屏，不同系统命令不一样：

Linux 系统 ：输 \! clear（反斜杠加感叹号，再跟 clear，别少字符）；
Windows 系统 ：输 \! cls（反斜杠加感叹号，再跟 cls，记准了）。

举个例子（Linux 清屏）：

plaintext 复制代码

\! clear

输完之后，终端之前的内容就全没了，重新显示 test=#，看着清爽，后续操作也舒服。

4.4 执行 SQL 语句：简单查个表试试水

虽然这篇主要讲"连接"，但咱也简单演示下 SQL 语句咋执行（为后面的文章打个基础）：比如想看看当前数据库里有哪些表，输下面这命令（末尾的分号别忘，不然执行不了）：

plaintext 复制代码

\dt

（\dt 是 ksql 专用命令，意思是"display tables"，就是显示表列表，记不住就想"查表格"）。

五、常见连接问题排查：遇到报错别慌，按图索骥

连数据库的时候，难免会遇到报错，别一看见红字就慌。下面这 3 个是最常出现的问题，我把原因和解决办法都列出来了，新手照着排查，保准能搞定。

问题 1：报错"无法连接到服务器：连接被拒绝"

报错完整信息长这样：

plaintext 复制代码

could not connect to server: Connection refused
Is the server running on host "localhost" (127.0.0.1) and accepting
TCP/IP connections on port 54321?

原因： 要么数据库没启动，要么你输的端口号错了，就这俩情况。 解决步骤：

按"一、前置环境检查"里的方法，确认数据库是不是真的启动了；
重新查一下端口号，看看命令里 -p 后面的数字，跟实际端口对不对得上，别输错了。

问题 2：报错"用户密码验证失败"

报错完整信息：

plaintext 复制代码

password authentication failed for user "system"

原因： 要么你输的用户名不存在，要么密码输错了，别瞎试。 解决步骤：

先确认用户名拼没拼错（比如 system 别写成 sys 或者 System，大小写不对也不行）；
重新输密码（记住，KingbaseES 密码区分大小写，别 Caps Lock 没关）；
要是忘了密码，别自己瞎琢磨，找数据库管理员重置------普通用户没这权限，别白费功夫。

问题 3：报错"数据库不存在"

报错完整信息：

plaintext 复制代码

database "kingbase_test" does not exist

原因： 你命令里写的数据库名根本不存在，比如把 kingbase 写成 kingbase_test，瞎加后缀。 解决步骤：

确认数据库名拼没拼错（不知道有啥数据库就问管理员，别瞎猜）；
要是你想连的数据库还没创建，那得先创建数据库------后面的文章会讲咋创建，别急。

总结

这篇文章把"用 ksql 连本地 KingbaseES 数据库"的全流程都说透了，从查环境、建连接，到断连接、基础交互，再到解决报错，都讲得明明白白。学会这些操作，你就拿到了 KingbaseES 命令行的"入门钥匙"。后面咱还会讲用 ksql 创建数据库、管理表这些核心操作，一步步来，保准你慢慢吃透 KingbaseES 的所有命令行功能，不用急！