【金仓数据库】ksql 指南（一） 连接本地 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 数据库已启动
数据库未启动时，任何连接操作都会失败，所以第一步必须检查启动状态：
- Windows 系统：通过服务查看数据库状态
在服务列表中找到刚刚创建的实例，名称就是你刚刚创建的实例名称，如果没改的话默认就是“kes_instance”
按下 Win + R，输入 services.msc 打开 “服务” 窗口；
Linux 系统：通过进程查看数据库是否运行
打开终端，执行以下命令，若能看到包含 “kingbase” 的进程，说明数据库已启动：
ps aux |grep kingbase 若没有相关进程，需启动数据库（具体启动命令可参考数据库安装目录下的启动脚本，如 /opt/Kingbase/ES/V9/Server/bin/kingbasectl start）。
- 右键服务→【启动】（如果已启动则跳过）；
- 若启动失败，参考“常见问题”部分排查；
- 确认服务状态为“正在运行”，启动类型为“自动”（避免重启后需手动启动）。
1.6 获取数据库服务端口（关键！默认 / 非默认都要会）
KingbaseES 数据库默认服务端口是 54321，如果安装时未修改端口，可直接跳过这一步；若修改过端口，或不确定端口号，需通过以下命令查询：
1.6.1 Linux 系统查询端口
- 首先找到数据库的 “数据文件路径”（安装时指定，默认可能是
/opt/kingbase/data或/test/kb_install/data）；
执行以下命令，从配置文件 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 系统查询端口
- 找到数据文件路径（上面是我的路径，你可参考）；
按下 Win + R，输入 cmd 打开命令提示符，执行以下命令：
findstr /R "^\s*port" D:\Tools\Kingbase\ES\kes_instance\kingbase.conf 示例（假设数据路径为 D:\Tools\Kingbase\ES\kes_instance）：结果会显示 port = 54321，即当前服务端口。
二、ksql 连接本地数据库
ksql是KingbaseES自带的命令行连接工具，本地连接时不用跨网络，所以操作比远程连接简单一些，主要存在“默认端口连接”和“指定端口连接”这两种情况。
前提：打开命令行终端
- Linux 系统：直接打开终端（快捷键
Ctrl + Alt + T）； - Windows 系统：打开 “命令提示符”（
Win + R输入cmd）或 “PowerShell”。
- 输入密码（默认
manager，如果安装时改了密码就输修改后的），按回车； - 若出现以下提示，说明连接成功：
执行连接命令（默认管理员用户system，密码manager，数据库test，端口54321）：
ksql -U system -d test -h localhost -p 54321 进入ksql所在路径（安装目录下的Server\bin）：
cd /d D:\Tools\Kingbase\ES\Server\bin 授权类型: 开发版. 输入 "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? 原因：
数据库未启动，或端口号错误。
解决步骤：
- 按 “一、前置环境检查” 中的方法，确认数据库已启动；
- 重新查询端口号，确认命令中的
-p参数与实际端口一致。
问题 2：报错 “用户密码验证失败”
报错完整信息：
password authentication failed for user "system" 原因：
输入的用户名不存在，或密码错误。
解决步骤：
- 确认用户名拼写正确（如
system不要写成sys或System）； - 重新输入密码（注意大小写，KingbaseES 密码区分大小写）；
- 若忘记密码，需联系数据库管理员重置（普通用户无法自行重置密码）。
问题 3：报错“数据库不存在”
报错完整信息：
database "kingbase_test" does not exist 原因：
命令中指定的数据库名不存在（比如把 kingbase 写成 kingbase_test）。
解决步骤：
- 确认数据库名拼写正确（可询问管理员当前存在的数据库名）；
- 若需连接的数据库未创建，需先创建数据库（后续文章会讲解 “创建数据库” 操作）。
总结
本文详细阐述了“ksql 连接本地数据库”的整个流程，包含环境核查，建立连接，断开连接，基本交互以及问题查找等内容，掌握了这些操作之后，你就拿到了进入 KingbaseES 命令行操作的“钥匙”，后续我们还会讲解利用 ksql 创建数据库，管理表等核心操作，从而逐步掌握 KingbaseES 的所有命令行功能。
