【金仓数据库】ksql 指南（一）连接本地 KingbaseES 数据库与基础交互

引言

在使用 KingbaseES 数据库进行命令行操作时，"成功连接本地数据库" 是一切操作的前提。本文将手把手教你完成本地数据库的连接、基础交互，以及解决常见连接问题，即使是数据库新手也能轻松上手。 @[toc]

一、前置环境检查：确保数据库 "能被连接"

在执行连接命令前，我们需要先确认两件事：本地 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" 的进程，说明数据库已启动：
bash 复制代码
```
ps aux | grep kingbase
```
若没有相关进程，需启动数据库（具体启动命令可参考数据库安装目录下的启动脚本，如 /opt/Kingbase/ES/V9/Server/bin/kingbasectl start）。
Windows 系统：通过服务查看数据库状态
1. 按下 Win + R，输入 services.msc 打开 "服务" 窗口；
2. 在服务列表中找到刚刚创建的实例，名称就是你刚刚创建的实例名称，如果没改的话默认就是"kes_instance"

右键服务→【启动】（如果已启动则跳过）；
- 若启动失败，参考"常见问题"部分排查；
确认服务状态为"正在运行"，启动类型为"自动"（避免重启后需手动启动）。

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

进入ksql所在路径（安装目录下的Server\bin）：
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 密码区分大小写）；
若忘记密码，需联系数据库管理员重置（普通用户无法自行重置密码）。

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

报错完整信息：

plaintext 复制代码

database "kingbase_test" does not exist

原因：

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

解决步骤：

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

总结

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

【金仓数据库】ksql 指南（一） 连接本地 KingbaseES 数据库与基础交互

引言

一、前置环境检查：确保数据库 "能被连接"

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

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

1.2.1 配置实例核心参数

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

1.4 验证实例是否正常运行

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

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

1.6.1 Linux 系统查询端口

1.6.2 Windows 系统查询端口

二、ksql 连接本地数据库

三、ksql 断开数据库连接：简单两步

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

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

四、ksql 基础交互命令包含 4 个新手必备的操作

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

4.2 查看当前连接信息：确认连接状态

4.3 清屏：让界面更整洁

4.4 执行 SQL 语句：基础查询示例

五、常见连接问题排查：遇到报错不用慌

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

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

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

总结

【金仓数据库】ksql 指南（一）连接本地 KingbaseES 数据库与基础交互