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

咱用 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）：

  ps aux | grep kingbase
  

• Windows 系统：得从“服务”里看状态，步骤超简单：

  1. 按 Win + R，输 services.msc 打开“服务”窗口，跟打开电脑控制面板似的；
  2. 在服务列表里找你刚创建的实例，没改名字的话默认叫“kes_instance”，别找错了；
  3. 右键点服务→【启动】（要是已经启动了就跳过，别重复操作）；
     • 要是启动失败，后面“常见问题”里有办法，别慌；
  4. 确认服务状态是“正在运行”，启动类型设成“自动”——这样重启电脑后不用手动启动，省事儿！

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

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

1.6.1 Linux 系统查询端口

1. 先找到数据库的“数据文件路径”（装的时候自己选的，默认可能是 /opt/kingbase/data 或 /test/kb_install/data，别瞎猜）；
2. 输下面这行命令，从 kingbase.conf 配置文件里扒端口信息，把“你的数据文件路径”换成真路径就行：

   cat /你的数据文件路径/kingbase.conf | grep ^s*port
   

   举个例子（假设数据路径是 /opt/kingbase/data）：

   cat /opt/kingbase/data/kingbase.conf | grep ^s*port
   

   输完会显示类似 port = 54321 的结果，等号后面的数字就是“门牌号”。

1.6.2 Windows 系统查询端口

1. 先找到数据文件路径（我这儿有个参考路径，你得找自己的，别照抄）；
2. 按 Win + R，输 cmd 打开命令提示符，然后敲下面这行命令（把“D:ToolsKingbaseESkes_instance”换成你的数据路径）：

   findstr /R "^s*port" D:ToolsKingbaseESkes_instancekingbase.conf
   

   输完会显示 port = 54321，这就是当前的服务端口，记下来别丢了！

二、ksql 连接本地数据库

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

前提：先打开命令行终端

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

1. 先进入 ksql 所在的文件夹（就在安装目录的 Serverbin 里），比如我这路径是 D 盘的，就输：

   cd /d D:ToolsKingbaseESServerbin
   

2. 输连接命令（默认管理员用户是 system，密码 manager，数据库 test，端口 54321，别瞎改，改了就错了）：

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

3. 然后输密码（默认是 manager，要是你装的时候改了密码，就输改后的，别记错了），按回车；
4. 要是看到下面这提示，说明你连成功了，能开始操作了：

 授权类型: 开发版.
输入 "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”（通用）这两类就行，别贪多。

举个例子：

?

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

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

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

 conninfo

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

4.3 清屏：让界面清爽点

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

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

举个例子（Linux 清屏）：

! clear

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

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

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

dt

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

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

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

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

报错完整信息长这样：

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?

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

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

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

报错完整信息：

password authentication failed for user "system"

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

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

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

报错完整信息：

database "kingbase_test" does not exist

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

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

总结

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