原文链接：【KWDB 创作者计划】KWDB数据库的基本操作与管理-CSDN博客

作者：江湖有缘

前言

KWDB 是一款高性能、分布式多模型数据库，专为处理大规模数据而设计。它不仅具备卓越的扩展性和稳定性，还提供了丰富的功能来满足各种应用场景的需求。无论是开发新手还是经验丰富的数据库管理员，KWDB 都能为你提供强大的支持和灵活的操作体验。本指南将带大家从零开始，轻松掌握 KWDB 数据库的基本操作与管理。

一、KWDB介绍

1.1 KWDB简介

KWDB 是一款面向 AIoT 场景的分布式、多模融合数据库产品。 支持在同一个实例中建立时序库和关系库，并统一处理多种类型的数据，具备对海量时序数据的高效读写与分析能力。 产品具备高可用、安全稳定、易运维等特性，广泛应用于工业物联网、数字能源、车联网、智慧矿山等多个行业领域，为用户提供一站式数据存储、管理与分析的基础平台。

1.2 主要特点与应用场景

• 主要特点：

高性能处理能力：支持海量时序数据高速读写，提供插值查询、数学函数等丰富的时序特色功能，提升应用效率。

低运管成本：统一存储与管理多模数据，一套系统满足跨业务、跨部门数据融合需求，降低企业IT与运维投入。

低存储成本：支持 5-30 倍数据压缩比，结合数据生命周期管理策略，灵活控制数据保留时间，显著节省存储资源。

高安全性：提供数据库审计与加密机制，保障数据在复杂业务场景下的安全稳定运行。

易用性强：提供标准 SQL 接口、高速写入、极速查询、集群部署等能力，与第三方工具无缝集成，开发运维更便捷。

• 主要应用场景

应用场景 场景描述

工业物联网 支持 SCADA/DCS 系统对接，统一存储设备实时数据与生产管理数据，助力智能化生产分析。

数字能源 融合传感器与业务数据，实现调峰调频分析与实时预警，推动能源系统智能化升级。

车联网 高速写入车端传感器数据，支撑车辆状态监控与上层业务分析，打造智能车联网解决方案。

智慧矿山 统一处理采选冶全流程中的关系与时序数据，打通多业务系统，提升矿山数字化水平。

二、本次实践规划

2.1 部署环境要求

KWDB数据库的硬件规格要求如下所示：

项目                                          要求

CPU 和内存        | 单节点建议配置不低于 4 核心 CPU 和 8 GB 内存。对于数据量大、复杂的工作负载、高并发以及对性能要求较高的场景，建议增加 CPU 核心数和内存容量，以确保系统的高效运行和稳定性。

磁盘                       | - 推荐使用 SSD 或 NVMe 存储设备，避免使用 NFS、CIFS、CEPH 等共享存储。

                                |- 磁盘需具备至少 500 IOPS（每秒输入输出操作次数）和 30 MB/s 的处理效率，以满足数据库的读写需求。

文件系统              | 建议使用 ext4 文件系统，以提供良好的兼容性和性能表现。

备注                       |在实际部署过程中，用户应根据具体的业务规模和性能需求灵活规划硬件资源，确保系统能够高效稳定地运行。

• KWDB 支持在以下已安装 Docker的操作系统中进行容器部署

操作系统 |版本| 架构

Anolis| 7.9                   |ARM_64、x86_64

Anolis |8.6                    |ARM_64、x86_64

CentOS| 7                     |x86_64

CentOS |8                     |x86_64

Debian |V11                 |ARM_64

KylinOS| V10 SP3 2403 |ARM_64、x86_64

KylinOS |V10 SP3 2303 |ARM_64、x86_64

openEuler| 22.03           |x86_64

Ubuntu |V18.04               |x86_64

Ubuntu| V20.04                |ARM_64、x86_64

Ubuntu |V22.04                |ARM_64、x86_64

Ubuntu |V24.04                |ARM_64、x86_64

UOS| 1050e                        |x86_64

UOS |1060e                        |ARM_64、x86_64

UOS |1070e                        |x86_64

2.2 本地环境规划

本次实践为个人测试环境，操作系统版本为Ubuntu 22.04.1。

hostname |IP地址             |操作系统版本               |内核版本                       |部署项目      |部署方式

jeven01      |192.168.3.88| Ubuntu 22.04.1 LTS| 5.15.0-117-generic |KWDB - 2.2.0| 单节点裸机部署

2.3 本次实践说明

本次实践旨在帮助用户在Ubuntu系统中快速完成 KWDB数据库的部署与初始化配置，特别适合初次接触 KWDB 的新手用户。

• 主要内容包括：

1. 在Ubuntu环境下单节点裸机搭建KWDB 数据库，简化部署流程，提升操作效率；

2. 指导用户完成数据库的基本操作，如连接、用户创建、数据写入与查询等；

3. 帮助用户快速入门，掌握 KWDB 的使用基础，为后续深入学习和应用打下坚实基础。

三、部署KWDB数据库

3.1 下载KWDB软件包

创建下载目录/data/kwdb

mkdir -p /data/kwdb && cd /data/kwdb

执行以下命令，下载KWDB安装包。

wget https://gitee.com/kwdb/kwdb/releases/download/V2.2.0/KWDB-2.2.0-ubuntu22.04-x86_64-debs.tar.gz

• 执行以下命令，解压KWDB软件包。

tar -xzf KWDB-2.2.0-ubuntu22.04-x86_64-debs.tar.gz

• 查看软件包解压后，内容如下所示：

root@jeven01:/data/kwdb# ll kwdb_install/
total 52
drwxr-xr-x 4 root root  4096 Mar 31 07:22 ./
drwxr-xr-x 3 root root  4096 May  5 15:58 ../
-rwxr-xr-x 1 root root  2024 Mar 31 07:11 add_user.sh*
-rw-r--r-- 1 root root  3605 Mar 31 07:12 .construction_var
-rw-r--r-- 1 root root   465 Mar 31 07:11 deploy.cfg
-rwxr-xr-x 1 root root 24410 Mar 31 07:11 deploy.sh*
drwxr-xr-x 2 root root  4096 Mar 31 07:22 packages/
drwxr-xr-x 2 root root  4096 Mar 31 07:11 utils/
root@jeven01:/data/kwdb#

3.2 编辑配置文件

在解压目录 kwdb_install/ 中，编辑 deploy.cfg 配置文件以设置安全模式、管理用户和服务端口等信息。

vim kwdb_install/deploy.cfg

[global]
# Whether to turn on secure mode
secure_mode=tls
# Management KaiwuDB user
management_user=kaiwudb
# KaiwuDB cluster http port
rest_port=8080
# KaiwuDB service port
kaiwudb_port=26257
# KaiwuDB data directory
data_root=/var/lib/kaiwudb
# CPU usage[0-1]
# cpu=1
[local]
# local node configuration
node_addr=192.168.3.88
# section cluster is optional
#[cluster]
# remote node addr,split by ','
#node_addr=127.0.0.2,127.0.0.3
# ssh info
#ssh_port=22
#ssh_user=admin

deploy.cfg 配置文件说明

• 全局配置（[global]）

• 本地节点配置（[local]）

配置项            默认值        说明

node_addr 无                   指定本地节点对外提供服务的 IP 地址，通常设置为 0.0.0.0 表示监听所有网络接口

3.3 添加脚本运行权限

进入KWDB软件目录，如下所示：

root@jeven01:/data/kwdb# cd kwdb_install/
root@jeven01:/data/kwdb/kwdb_install# ls
add_user.sh  deploy.cfg  deploy.sh  packages  utils

执行以下命令，为 deploy.sh 脚本添加运行权限。

chmod +x ./deploy.sh

3.4 安装前准备工作

执行以下命令，我们手动安装 libprotobuf23 库。

apt install libprotobuf23 -y

3.5 安装KWDB数据库

我们使用部署脚本 deploy.sh 一键完成KWDB的安装与配置，如下所示：

./deploy.sh install --single

在安装过程中，系统会提示您输入新增用户 jeven 的密码，请按指示自行输入。请注意，本次实践基于配置为4核CPU和8GB内存的虚拟机环境。由于该配置可能触发“CPU规格不满足要求”的警告，建议根据实际需求调整虚拟机规格以避免此类警告。提升机器的硬件配置（如增加CPU核心数）可以有效解决这一问题。

安装成功后，会出现以下提示信息。

3.6 启动KWDB节点

执行以下命令，重新加载 systemd 守护进程的配置文件。

systemctl daemon-reload

启动KWDB数据库，如下所示：

./deploy.sh start

执行以下命令，设置KWDB服务开自启。

systemctl enable kaiwudb

3.7 查看KWDB数据库状态

我们可以使用systemctl status kaiwudb命令，查看KWDB服务状态。

systemctl status kaiwudb

四、访问KWDB数据库

如果在安装过程中由于等待时间过长而未设置用户密码，或者遇到密码遗忘、登录失败等情况，可以通过执行 add_user.sh 脚本来创建新的数据库用户。此脚本提供了一种简便的方法来重新设定访问凭据，确保我们能够顺利恢复对数据库的管理与操作。

./add_user.sh

我们执行以下命令，使用刚才新创建kwdbuser用户连接KWDB 数据库。

kwbase sql --certs-dir=/etc/kaiwudb/certs  --host=192.168.3.88    --host=192.168.3.88 -u kwdbuser

五、用户基本管理

5.1 查看当前所有用户

使用show users;命令，我们可以查询到KWDB数据库所有用户。

kwdbuser@192.168.3.88:26257/defaultdb> show users;
  username |  options   | member_of
-----------+------------+------------
  admin    | CREATEROLE | {}
  kwdbuser |            | {admin}
  root     | CREATEROLE | {admin}
(3 rows)
Time: 2.317329ms

kwdbuser@192.168.3.88:26257/defaultdb>

5.2 新建用户

我们新建liwu用户。默认情况下，该用户无法创建角色，但可以登录 KaiwuDB 服务器。

CREATE USER liwu;

我们还可以在创建用户的时候指定用户密码，例如，我们创建wangming用户，并设置密码。

CREATE USER wangming WITH PASSWORD 'wangming1234';

5.3 删除用户

测试删除用户操作前，我们查看当前用户列表如下：

kwdbuser@192.168.3.88:26257/defaultdb>  show users;
  username |  options   | member_of
-----------+------------+------------
  admin    | CREATEROLE | {}
  kwdbuser |            | {admin}
  liwu     |            | {}
  root     | CREATEROLE | {admin}
  wangming |            | {}
(5 rows)
Time: 2.453489ms

我们删除用户liwu，如下操作：

ｄｒｏｐ USER liwu;

重新查询用户列表，我们可以看到liwu用户已经被删除。

kwdbuser@192.168.3.88:26257/defaultdb> ｄｒｏｐ USER liwu;
ｄｒｏｐ USER 1
Time: 8.121764ms
kwdbuser@192.168.3.88:26257/defaultdb> show users;
  username |  options   | member_of
-----------+------------+------------
  admin    | CREATEROLE | {}
  kwdbuser |            | {admin}
  root     | CREATEROLE | {admin}
  wangming |            | {}
(4 rows)
Time: 2.031695ms

5.4 修改密码

我们修改wangming用户的密码，如下所示：

ALTER USER wangming WITH PASSWORD 'wm1234';

我们退出当前数据库会话，重新使用wangming用户进行登录测试，可以看到成功访问KWDB数据库。

kwbase sql --certs-dir=/etc/kaiwudb/certs --host=192.168.3.88 -u wangming

5.5 修改权限

默认情况下，该新建的普通用户无法创建角色，但可以登录 KaiwuDB 服务器。如果使用普通用户创建用户，会出现以下提示报错。

root@jeven01:/data/kwdb/kwdb_install# kwbase sql --certs-dir=/etc/kaiwudb/certs --host=192.168.3.88 -u wangming
#
# Welcome to the KWDB SQL shell.
# All statements must be terminated by a semicolon.
# To exit, type: \q.
#
Enter password:
# Server version: KaiwuDB 2.2.0 (x86_64-linux-gnu, built 2025/03/31 07:20:02, go1.16.15, gcc 11.4.0) (same version as client)
# Cluster ID: 840ed4c1-ac58-4d39-aa51-9d49ed010198
#
# Enter \? for a brief introduction.
#
wangming@192.168.3.88:26257/defaultdb> CREATE USER liwu;
ERROR: user wangming does not have CREATEROLE privilege
SQLSTATE: 42501
wangming@192.168.3.88:26257/defaultdb>

我们重新使用kwdbuser用户登录后，查看当前系统的角色列表。

root@jeven01:/data/kwdb/kwdb_install#  kwbase sql --certs-dir=/etc/kaiwudb/certs --host=192.168.3.88 -u kwdbuser
#
# Welcome to the KWDB SQL shell.
# All statements must be terminated by a semicolon.
# To exit, type: \q.
#
Enter password:
# Server version: KaiwuDB 2.2.0 (x86_64-linux-gnu, built 2025/03/31 07:20:02, go1.16.15, gcc 11.4.0) (same version as client)
# Cluster ID: 4335d3f6-5648-4bd3-b181-ed48b29cd7a4
#
# Enter \? for a brief introduction.
#
kwdbuser@192.168.3.88:26257/defaultdb>  SHOW ROLES;
  username |  options   | member_of
-----------+------------+------------
  admin    | CREATEROLE | {}
  kwdbuser |            | {admin}
  root     | CREATEROLE | {admin}
  wangming |            | {}
(4 rows)
Time: 2.620027ms
kwdbuser@192.168.3.88:26257/defaultdb>

若要将普通用户提升为具有管理员权限的角色，您可以将 admin 角色授予该用户。例如，将用户 wangming 设置为 admin 角色，即可赋予其管理员权限。

ｇｒａｎｔ admin TO wangming;

参考以下命令，可以允许 username 用户在 db_name.table_name 表上执行查询和插入数据的操作。

ｇｒａｎｔ ｓｅｌｅｃｔ, ｉｎｓｅｒｔ ON TABLE db_name.table_name TO username;

六、数据库操作

6.1 创建数据库

创建数据库：例如我们要创建一个名为 school 的数据库

test@192.168.3.88:26257/defaultdb> CREATE DATABASE school;
CREATE DATABASE
Time: 9.151614ms

6.2 删除数据库

删除数据库：我们先创建一个test测试的数据库，然后删除该test数据库。

ｄｒｏｐ DATABASE test;

6.3 查询数据库

查询数据库：使用以下命令，查询当前所有的数据库列表。

show databases;

进入数据库：我们可以使用以下命令，进入school数据库。

test@192.168.3.88:26257/defaultdb> use school;
SET
Time: 493.971µs
test@192.168.3.88:26257/school>

七、 数据表操作

7.1 创建数据表

在已有的数据库中创建一张数据表。例如，在 school 数据库中创建 students 表。

CREATE TABLE students (
    student_id INT PRIMARY KEY,
    name STRING NOT NULL,
    age INT,
    grade STRING,
    birth DATE
);

7.2 查看所有表

可以执行以下命令，查看当前school数据库下的所有表。

kwdbuser@192.168.3.88:26257/defaultdb> SHOW TABLES;
  table_name | table_type
-------------+-------------
  students   | BASE TABLE
(1 row)
Time: 1.324024ms

7.3 查看表结构

查看表结构：我们查看students表的字段定义和类型，可以使用执行以下命令。

SHOW COLUMNS FROM students;

7.4 修改表结构

当想要修改表结构，例如为现有students表添加新的联系方式字段，我们可以执行以下命令。

ALTER TABLE students ADD COLUMN phone STRING;

我们重新查询表结构，可以看到新的字段 phone 已经成功添加。

SHOW COLUMNS FROM students;

在执行删除列操作之前，可以临时关闭 sql_safe_updates 选项。请注意，这样做可能会带来数据丢失的风险，请确保已经备份重要数据。

SET sql_safe_updates = false;

执行删除操作后，我们可以看到该数据表已经成功删除该phone字段。

ALTER TABLE students ｄｒｏｐ COLUMN phone;

7.5 删除数据表

可执行以下命令，进行删除数据表操作。

ｄｒｏｐ table test;

八、数据操作

8.1 写入数据

我们向 students表中插入多条测试记录，如下所示：

ｉｎｓｅｒｔ INTO students (student_id, name, age, grade, birth) VALUES
(1001, '张三', 15, '高一', '2009-08-01'),
(1002, '李四', 16, '高二', '2008-05-12'),
(1003, '王五', 17, '高三', '2007-03-22');

8.2 查询数据

查询该数据表的所有内容，如下所示：

kwdbuser@192.168.3.88:26257/defaultdb> ｓｅｌｅｃｔ * FROM students;
  student_id | name | age | grade |           birth
-------------+------+-----+-------+----------------------------
        1001 | 张三 |  15 | 高一  | 2009-08-01 00:00:00+00:00
        1002 | 李四 |  16 | 高二  | 2008-05-12 00:00:00+00:00
        1003 | 王五 |  17 | 高三  | 2007-03-22 00:00:00+00:00
(3 rows)
Time: 1.03096ms
kwdbuser@192.168.3.88:26257/defaultdb>

按条件查询：例如，我们要查询所有属于高一的学生。

kwdbuser@192.168.3.88:26257/defaultdb> ｓｅｌｅｃｔ name, age FROM students WHERE grade = '高一';
  name | age
-------+------
  张三 |  15
(1 row)
Time: 823.682µs

排序查询：例如，我们需要按年龄降序排列所有学生。

kwdbuser@192.168.3.88:26257/defaultdb> ｓｅｌｅｃｔ * FROM students ORDER BY age DESC;
  student_id | name | age | grade |           birth
-------------+------+-----+-------+----------------------------
        1003 | 王五 |  17 | 高三  | 2007-03-22 00:00:00+00:00
        1002 | 李四 |  16 | 高二  | 2008-05-12 00:00:00+00:00
        1001 | 张三 |  15 | 高一  | 2009-08-01 00:00:00+00:00
(3 rows)
Time: 1.125357ms

聚合函数：例如，我们需要统计每个年级的学生人数。

ｓｅｌｅｃｔ grade, COUNT(*) AS total_students FROM students GROUP BY grade;

8.3 更新数据

更新特定记录的信息，如将 王五 的年龄改为19：

ｕｐｄａｔｅ students SET age = 19 WHERE name = '王五';

更新后，我们再在重新查询数据表内容，可以看到已经成功修改。

ｓｅｌｅｃｔ * from students;

8.4 删除数据

删除符合条件的记录，如删除 student_id 为 1003 的记录。

ｄｅｌｅｔｅ FROM students WHERE student_id = 1003;

九、总结

通过本次实践，我们全面掌握了KWDB数据库的部署流程及其基础操作，验证了其在多种应用场景下的高性能表现与良好的易用性。KWDB 凭借高效的查询处理能力以及灵活的数据管理机制，显著简化了复杂数据环境下的操作难度。本指南旨在为使用者提供一套清晰的操作路径，帮助快速入门并构建稳定的数据服务基础。随着对 KWDB 的进一步探索与深入应用，将有助于挖掘其更多高级功能与性能潜力。