# Hnusql

**Repository Path**: cwwtest/hnusql

## Basic Information

- **Project Name**: Hnusql
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-07-09
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# hnusql 原型数据库系统 — 使用文档

> Hunan University SQL — 基于 MySQL 8.0 源码分析设计的轻量级 RDBMS 原型

---

## 速查卡片

```bash
# 编译（build/ 已有预编译产物，可跳过）
cd /home/w/2026/hnusql/build
cmake .. -DCMAKE_BUILD_TYPE=Debug && cmake --build . -j$(nproc)

# === 方式 A: 本地 Shell（最简单，只需设计 1+2+8）===
./local_shell                  # 直接在本机敲 SQL，无需网络

# === 方式 B: 完整服务器 + 远程客户端 ===
./hnusqld --port=3307          # 默认端口 3307
# 另开终端:
python3 ../cli.py 3307                          # root 用户 (密码 1)
python3 ../cli.py 3307 -u guest                 # guest 用户 (无密码, 只读)
python3 ../cli.py 3307 -u root -p 1             # root + 显式密码
python3 ../test_client.py 3307                  # 自动测试脚本

# 运行全部测试
ctest                          # CTest 一键运行

> 📖 **SQL 测试手册:** [`SQL测试手册.md`](SQL测试手册.md) — 覆盖全部已实现功能的测试 SQL 语句集

---

---

## 目录

- [速查卡片](#速查卡片)
- [1. 环境要求](#1-环境要求)
- [2. 项目结构](#2-项目结构)
- [3. 快速开始](#3-快速开始)
- [3.1 本地 Shell（三层最小系统）](#31-本地-shell三层最小系统)
- [4. 各子系统编译与运行](#4-各子系统编译与运行)
- [5. 一键构建与测试](#5-一键构建与测试)
- [6. 启动完整服务器](#6-启动完整服务器)
- [7. 客户端连接示例](#7-客户端连接示例)
- [8. 管理工具](#8-管理工具)
- [9. 备份与恢复](#9-备份与恢复)
- [10. 常见问题](#10-常见问题)
- [附录: SQL 测试手册](#附录-sql-测试手册)

---

## 1. 环境要求

| 依赖 | 版本 | 说明 |
|------|------|------|
| GCC / Clang | GCC 9+ 或 Clang 12+ | C++17 标准 |
| CMake | 3.16+ | 构建系统 |
| pthread | 系统自带 | 多线程支持 |
| 操作系统 | Linux (推荐 Ubuntu 20.04+) | 或 WSL2 |

```bash
# Ubuntu/Debian 安装依赖
sudo apt install g++ cmake make

# 验证版本
g++ --version    # 应 >= 9.0
cmake --version  # 应 >= 3.16
```

## 2. 项目结构

```
hnusql/
├── README.md                            ← 本文档
├── 工作清单.md                            ← 课程设计任务书
├── 验证方案.md                            ← MySQL 插件版验证流程
├── hnusql系统架构与设计关联说明.md          ← 9 个设计的关系
│
├── hnusql_handler/      # 设计二 — 存储引擎接口子系统
│   ├── handler_interface.h              # StorageEngine 抽象接口 (对应 MySQL handler)
│   ├── plugin_registry.h                # PluginRegistry 引擎注册表
│   ├── test_handler_interface.cc        # 单元测试 (12 项)
│   └── CMakeLists.txt
│
├── hnusql_engine/       # 设计一 — 存储引擎实现 (hnusql 独立版)
│   ├── ha_hnusql_standalone.h/cc        # 基于 StorageEngine 的 .hnu 文件引擎
│   ├── test_engine.cc                   # 集成测试 (9 项)
│   └── CMakeLists.txt
│
├── hnusql_storage/      # 设计一 — 存储引擎 (MySQL 插件版)
│   ├── ha_hnusql.h/cc                   # 继承 MySQL handler 的引擎
│   ├── hnusql存储引擎实现说明.md
│   └── CMakeLists.txt                   # 需放入 MySQL 源码树编译
│
├── hnusql_server/       # 设计七 — 线程与内存子系统
│   ├── thd.h                            # THD 线程描述符
│   ├── thread_pool.h                    # 线程池 (1连接=1线程)
│   ├── memory_pool.h                    # Arena 内存分配器
│   ├── server.cc                        # 服务器主程序
│   ├── test_server.cc                   # 单元测试 (9 项)
│   └── CMakeLists.txt
│
├── hnusql_network/      # 设计六 — 网络通信子系统
│   ├── vio.h                            # VIO 层 (TCP 封装)
│   ├── protocol.h                       # MySQL 文本协议
│   ├── tcp_listener.h                   # TCP 监听器
│   ├── network_server.cc                # 完整网络服务器
│   ├── test_network.cc                  # 单元测试 (8 项)
│   └── CMakeLists.txt
│
├── hnusql_parser/       # 设计八 — 查询解析与优化
│   ├── token.h                          # 词法分析器
│   ├── ast.h                            # AST 节点定义
│   ├── parser.h                         # 递归下降语法解析器
│   ├── executor.h                       # 执行器 (AST → 引擎调用)
│   ├── test_parser.cc                   # 单元测试 (16 项)
│   └── CMakeLists.txt
│
├── hnusql_security/     # 设计九 — 安全管理子系统
│   ├── auth.h                           # 认证 + 授权 + 用户管理
│   ├── secure_server.cc                 # 带安全控制的服务器
│   ├── test_security.cc                 # 单元测试 (11 项)
│   └── CMakeLists.txt
│
├── hnusql_log/          # 设计五 — 日志子系统
│   ├── log.h                            # Error Log + Query Log
│   ├── test_log.cc                      # 单元测试 (6 项)
│   └── CMakeLists.txt
│
├── hnusql_admin/        # 设计三 — 核心管理工具
│   ├── admin.h                          # mysqladmin 风格管理工具
│   ├── test_admin.cc                    # 单元测试 (5 项)
│   └── CMakeLists.txt
│
├── hnusql_backup/       # 设计四 — 备份子系统
│   ├── backup.h                         # mysqldump 风格备份/恢复
│   ├── test_backup.cc                   # 单元测试 (5 项)
│   └── CMakeLists.txt
│
├── build_all.sh                         # 一键编译脚本
├── test_all.sh                          # 一键测试脚本
├── cli.py                               # 交互式客户端 (Python, MySQL 文本协议)
├── test_client.py                       # 自动测试客户端 (Python, 协议验证)
├── CMakeLists.txt                       # 顶层 CMake (统一编译)
├── hnusqld.cc                           # 服务器入口 (集成所有子系统)
├── local_shell.cc                        # 本地 Shell (只依赖设计 1+2+8, 无需网络)
├── SQL测试手册.md                        # 全部已实现功能的 SQL 测试集
└── README.md                            # ← 本文档
```

## 3. 快速开始

> **提示：** `build/` 目录已包含预编译产物（`hnusqld` + 9 个 `test_*`），可直接跳到第 2 步运行测试或第 3 步启动服务器。

```bash
cd /home/w/2026/hnusql

# 1. 统一编译 (所有子系统 + 服务器)
mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Debug
cmake --build . -j$(nproc)

# 2. 运行全部测试 (81 项)
ctest                                  # 方式A: CTest 一键运行
# 或逐个运行:
for t in test_*; do echo -n "$t ... "; timeout 8 ./$t 2>&1 | grep -oP '\d+(?= passed)' | xargs echo; done

# 3. 启动服务器
./hnusqld --port=3307

# 4. 用项目客户端连接
python3 ../cli.py 3307          # root (密码 1)
python3 ../cli.py 3307 -u guest # guest (无密码, 只读)
```

**三步启动：**

```bash
cd /home/w/2026/hnusql/build
cmake .. && cmake --build . -j$(nproc)   # 编译
./hnusqld                                 # 启动 (默认 3307 端口)
# 另开终端: python3 ../cli.py 3307  (root 密码 1)
```

**预期输出：**

```
=== hnusql_handler ===      结果: 12 passed, 0 failed
=== hnusql_engine ===       ===== 9 passed, 0 failed =====
=== hnusql_server ===       ===== 9 passed, 0 failed =====
=== hnusql_network ===      8 passed
=== hnusql_parser ===       ===== 16 passed, 0 failed =====
=== hnusql_security ===     ===== 11 passed, 0 failed =====
=== hnusql_log ===          ===== 6 passed, 0 failed =====
=== hnusql_admin ===        ===== 5 passed, 0 failed =====
=== hnusql_backup ===       ===== 5 passed, 0 failed =====
                            ─────────────────
                            总计: 81 tests
```

## 3.1 本地 Shell（三层最小系统）

如果你只想理解 SQL 解析 → 引擎调用 → 磁盘存储这条核心链路，可以用 `local_shell`。它 **只依赖设计 1+2+8**，不涉及网络、线程、安全、日志：

```
设计二 (接口层)  →  设计一 (引擎实现)  →  设计八 (解析+执行)
```

```bash
# 编译
cd /home/w/2026/hnusql/build
cmake .. -DCMAKE_BUILD_TYPE=Debug
cmake --build . --target local_shell -j$(nproc)

# 运行
./local_shell
```

进入后就能直接敲 SQL：

```
╔══════════════════════════════════════╗
║  hnusql 本地 Shell v1.0              ║
║  引擎 + 接口 + 解析执行              ║
╚══════════════════════════════════════╝

hnusql[1]> CREATE TABLE students (id INT PRIMARY KEY, name VARCHAR(100));
  → Query OK — Table 'students' created

hnusql[2]> INSERT INTO students VALUES (1, 'Alice'), (2, 'Bob');
  → Query OK, 2 row(s) affected

hnusql[3]> SELECT * FROM students;
  +----+-------+
  | id | name  |
  +----+-------+
  | 1  | Alice |
  | 2  | Bob   |
  +----+-------+
  2 row(s) in set

hnusql[4]> SELECT * FROM students WHERE id = 2;
  → 索引点查，只返回 id=2 的行

hnusql[5]> quit
  → Bye
```

**数据持久化在 `/tmp/hnusql_data/<数据库>/<表名>.hnu`**，程序退出后数据不丢失。

**可选：命令行历史和编辑**

```bash
sudo apt install libreadline-dev    # 安装后重新 cmake + make，自动启用 ↑↓ 翻历史、左右移动光标
```

**对比三种运行方式：**

| 方式 | 依赖的设计 | 适用场景 |
|------|-----------|---------|
| `./local_shell` | 1+2+8 | 本机单用户，理解核心链路 |
| `./hnusqld --port=3307` + `python3 cli.py 3307` | 全部 9 个 | 多用户 TCP 连接，完整功能 |
| `./hnusqld`（stdin 模式） | 1+2+7 | 单用户，有线程框架但无网络 |

## 4. 各子系统编译与运行

每个子系统**独立编译，独立运行**，通过 CMake 的 `INTERFACE` 库引用上层依赖。

### 4.1 设计二 (接口层) — 无依赖

```bash
cd hnusql_handler && mkdir -p build && cd build
cmake .. && cmake --build . -j$(nproc)
./test_handler_interface
```

### 4.2 设计一 (引擎) — 依赖设计二

```bash
cd hnusql_engine && mkdir -p build && cd build
cmake .. && cmake --build . -j$(nproc)
./test_engine
```

### 4.3 设计七 (服务器框架) — 依赖设计一+二

```bash
cd hnusql_server && mkdir -p build && cd build
cmake .. && cmake --build . -j$(nproc)
./test_server               # 运行测试
./hnusqld                   # 启动交互式服务器 (stdin 模式)
```

### 4.4 设计六 (网络) — 依赖设计一+二+七

```bash
cd hnusql_network && mkdir -p build && cd build
cmake .. && cmake --build . -j$(nproc)
./test_network              # 运行测试 (启动 echo 服务器)
./hnusqld_net               # 启动 TCP 服务器 (端口 3307)
```

### 4.5 设计八 (解析器) — 依赖设计一+二

```bash
cd hnusql_parser && mkdir -p build && cd build
cmake .. && cmake --build . -j$(nproc)
./test_parser
```

### 4.6 设计九 (安全) — 依赖设计一+二+六+七+八

```bash
cd hnusql_security && mkdir -p build && cd build
cmake .. && cmake --build . -j$(nproc)
./test_security
./hnusqld_secure            # 启动带认证的服务器 (端口 3308)
```

### 4.7 设计五 (日志)

```bash
cd hnusql_log && mkdir -p build && cd build
cmake .. && cmake --build . -j$(nproc)
./test_log
```

### 4.8 设计三 (管理工具)

```bash
cd hnusql_admin && mkdir -p build && cd build
cmake .. && cmake --build . -j$(nproc)
./test_admin
```

### 4.9 设计四 (备份工具)

```bash
cd hnusql_backup && mkdir -p build && cd build
cmake .. && cmake --build . -j$(nproc)
./test_backup
```

## 5. 一键构建与测试

项目根目录已提供两个脚本，可直接使用：

```bash
# 一键编译全部 9 个子系统
bash /home/w/2026/hnusql/build_all.sh

# 一键运行全部测试
bash /home/w/2026/hnusql/test_all.sh
```

也可以通过 CTest 统一运行（需先完成统一编译）：

```bash
cd /home/w/2026/hnusql/build
ctest                      # 运行全部 9 个测试
ctest --output-on-failure  # 失败时显示详细输出
ctest -R test_parser       # 只运行匹配名称的测试
```

## 6. 启动完整服务器

### 方式 1: 基础 TCP 服务器 (端口 3307)

```bash
cd hnusql_network/build
./hnusqld_net

# 输出:
# ╔══════════════════════════════════════╗
# ║  hnusql 服务器 v0.2  (+设计六 网络)   ║
# ╚══════════════════════════════════════╝
# [init] 引擎已注册
# [network] 监听 0.0.0.0:3307
# [server] 服务器就绪
```

**用项目客户端连接：**

```bash
cd /home/w/2026/hnusql
python3 cli.py 3307
```

### 方式 2: 安全服务器 (端口 3308, 带认证和权限)

```bash
cd hnusql_security/build
./hnusqld_secure

# [security] 默认用户已创建: root(*), guest(SELECT only)
# [server] 安全服务器就绪, 端口 3308
```

**连接测试：**

```bash
# root 用户 — 全部权限, 密码 1
python3 cli.py 3308 -u root -p 1

# guest 用户 — 只有 SELECT, 无密码
python3 cli.py 3308 -u guest
```

### 方式 3: 交互式服务器 (stdin, 用于调试)

```bash
cd hnusql_server/build
./hnusqld

# 输入 SQL:
hnusql[1]> SELECT * FROM t;
hnusql[1]> QUIT;
```

## 7. 客户端连接示例

### 用项目 CLI 连接

```bash
# root 用户 (全部权限, 默认密码 1)
cd /home/w/2026/hnusql
python3 cli.py 3307

# guest 用户 (只读, 无密码)
python3 cli.py 3307 -u guest

# 自定义用户 (需先用 root 创建)
python3 cli.py 3307 -u alice -p pass123

# 在 hnusql> 提示符下执行:
hnusql> SELECT 1;
hnusql> CREATE TABLE students (id INT, name VARCHAR(100)) ENGINE=HNUSQL;
hnusql> INSERT INTO students VALUES (1, 'Alice');
hnusql> SELECT * FROM students;
hnusql> UPDATE students SET name = 'Alicia' WHERE id = 1;
hnusql> DELETE FROM students WHERE id = 1;
hnusql> SHOW TABLES;
hnusql> quit;
```

### 用 Python 连接

```python
import socket
import struct

def mysql_query(host, port, sql):
    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    sock.connect((host, port))

    # 读握手
    data = sock.recv(1024)

    # 发送握手响应 (简化: root 无密码)
    resp = bytearray(64)
    resp[0:4] = struct.pack('<I', 0x80020008)
    resp[4:8] = struct.pack('<I', 0x00FFFFFF)
    resp[8] = 33
    resp[32:36] = b'root\x00'
    resp[36] = 0
    sock.send(struct.pack('<I', len(resp))[:3] + b'\x01' + resp)

    # 读认证 OK
    sock.recv(1024)

    # 发送查询
    payload = b'\x03' + sql.encode()
    sock.send(struct.pack('<I', len(payload))[:3] + b'\x00' + payload)

    # 读结果
    response = sock.recv(4096)
    sock.close()
    return response

# 使用
result = mysql_query("127.0.0.1", 3307, "SELECT * FROM students")
print(result)
```

## 8. 管理工具

### 8.1 命令行管理

```bash
# 编译
cd hnusql_admin/build
cmake .. && cmake --build .

# 创建管理工具 CLI
# (需要自行编写 main, 使用 AdminTool 类)

# 或在代码中使用:
#include "admin.h"
using namespace hnusql;

DatabaseManager mgr("/tmp/hnusql_data");
mgr.create_database("mydb");
mgr.drop_database("mydb");
auto dbs = mgr.list_databases();  // 列出所有数据库
```

### 8.2 ServerStatus 查询

```cpp
ServerStatus st;
st.uptime_seconds = 7200;
st.active_connections = 5;
std::cout << st.to_string() << std::endl;
// Uptime: 7200 sec  Threads: 5  Questions: 999  Memory: 128 MB
```

## 9. 备份与恢复

### 9.1 全库备份

```bash
cd hnusql_backup/build
cmake .. && cmake --build .

# 编写备份脚本或使用代码:
```

```cpp
#include "backup.h"
using namespace hnusql;

BackupTool backup("/tmp/hnusql_data");

// 备份整个数据库
backup.backup_database("mydb", "/tmp/mydb_dump.sql");

// 备份指定表
backup.backup_tables("mydb", {"t1", "t2"}, "/tmp/tables_dump.sql");
```

### 9.2 恢复

```cpp
backup.restore("/tmp/mydb_dump.sql");
// 输出:
// [restore] CREATE TABLE `t1` (
// Restored 1 statements from /tmp/mydb_dump.sql
```

### 9.3 生成的 SQL 文件格式

```sql
-- hnusql dump v1.0
-- Database: testdb
-- Date: 2026-07-07 15:30:00

CREATE DATABASE IF NOT EXISTS `testdb`;
USE `testdb`;

--
-- Table: `students`
--
DROP TABLE IF EXISTS `students`;
CREATE TABLE `students` (
  `data` VARCHAR(32) NOT NULL
) ENGINE=HNUSQL;

INSERT INTO `students` VALUES
  (0x01000000416C696365...),
  (0x02000000426F6200...),
  (0x03000000436861726C6965...);
```

## 10. 常见问题

### Q: 编译报 "undefined reference to pthread_create"

**A:** CMakeLists.txt 中需要添加 `find_package(Threads REQUIRED)` 和链接 `Threads::Threads`。

### Q: 测试报 "Address already in use"

**A:** 之前运行的 test_network 或 hnusqld_net 进程未退出。运行：

```bash
pkill test_network
pkill hnusqld_net
```

### Q: 客户端连接不上

**A:** 检查服务器是否正在运行，端口是否正确：

```bash
# 启动服务器
cd /home/w/2026/hnusql/build && ./hnusqld --port=3307 &

# 验证端口监听
ss -tlnp | grep 3307

# 连接
cd /home/w/2026/hnusql
python3 cli.py 3307
```

### Q: "Permission denied" 写入数据目录

**A:** 确保 `/tmp/hnusql_data/` 存在且可写：

```bash
mkdir -p /tmp/hnusql_data
chmod 755 /tmp/hnusql_data
```

### Q: 如何只用某个子系统?

**A:** 每个子系统独立编译，不依赖其他目录。例如只用设计一+二：

```bash
cd hnusql_engine && mkdir -p build && cd build
cmake .. && cmake --build . -j$(nproc)
./test_engine
```

### Q: 如何添加新的存储引擎?

**A:** 
1. 继承 `hnusql::StorageEngine` (设计二)
2. 实现 4 个纯虚函数: `open_table()`, `close_table()`, `rnd_init()`, `rnd_next()`
3. 可选实现: `write_row()`, `update_row()`, `delete_row()`, `create_table()`
4. 通过 `PluginRegistry::instance().register_engine()` 注册

参考 `hnusql_engine/ha_hnusql_standalone.cc` 的完整实现。

---

---

## 附录: SQL 测试手册

详见 **[SQL测试手册.md](SQL测试手册.md)**，覆盖以下全部已实现功能的可执行 SQL 测试语句：

| 分类 | 内容 |
|------|------|
| DDL | CREATE TABLE (INT/VARCHAR/DOUBLE/TEXT/PRIMARY KEY/NOT NULL/ENGINE), DROP TABLE |
| DML | INSERT (单行/多行/指定列), SELECT (全表/投影/WHERE), UPDATE (SET/WHERE), DELETE (WHERE) |
| 查询子句 | WHERE (比较/AND/OR), ORDER BY (ASC/DESC), LIMIT/OFFSET |
| 聚合函数 | COUNT, AVG, SUM, MAX, MIN |
| 数据库管理 | USE, SHOW TABLES, SHOW DATABASES, CREATE/DROP DATABASE (API) |
| 安全 | CREATE/DROP USER, GRANT/REVOKE, SET PASSWORD, 认证/授权 (7种权限位) |
| 协议 | COM_QUERY, COM_QUIT, COM_PING, COM_INIT_DB |
| 客户端 | `cli.py` (交互式), `test_client.py` (自动化) |

---

**项目版本**: v1.0  
**最后更新**: 2026-07-08  
**许可证**: GPL-2.0 (参照 MySQL)

 netsh interface portproxy add v4tov4 listenport=3307 listenaddress=0.0.0.0 connectport=3307
  connectaddress=172.19.84.101