【金仓数据库】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 数据库已启动

数据库未启动时，任何连接操作都会失败，所以第一步必须检查启动状态：

• Linux 系统：通过进程查看数据库是否运行
  打开终端，执行以下命令，若能看到包含 “kingbase” 的进程，说明数据库已启动：

  ps aux | grep kingbase
  

  若没有相关进程，需启动数据库（具体启动命令可参考数据库安装目录下的启动脚本，如 /opt/Kingbase/ES/V9/Server/bin/kingbasectl start）。

• 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 打开命令提示符，执行以下命令：

   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”。

1. 进入ksql所在路径（安装目录下的Server\bin）：

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

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 密码区分大小写）；
3. 若忘记密码，需联系数据库管理员重置（普通用户无法自行重置密码）。

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

报错完整信息：

database "kingbase_test" does not exist

原因：

命令中指定的数据库名不存在（比如把 kingbase 写成 kingbase_test）。

解决步骤：

1. 确认数据库名拼写正确（可询问管理员当前存在的数据库名）；
2. 若需连接的数据库未创建，需先创建数据库（后续文章会讲解 “创建数据库” 操作）。

总结

本文详细阐述了“ksql 连接本地数据库”的整个流程，包含环境核查，建立连接，断开连接，基本交互以及问题查找等内容，掌握了这些操作之后，你就拿到了进入 KingbaseES 命令行操作的“钥匙”，后续我们还会讲解利用 ksql 创建数据库，管理表等核心操作，从而逐步掌握 KingbaseES 的所有命令行功能。