玉衡数据库 用户手册

YuhengDB v0.9 | 全中文关键字数据库 | 单文件整合版

一、快速开始

方式1:本机使用(命令行+内置服务器)

bin\yuheng.exe

启动后:命令行交互 + 服务器自动开启(端口5555)。

方式2:纯服务器模式

bin\yuheng.exe -s

只跑服务器,无交互界面(适合挂机/开机自启)。

方式3:远程连接(客户端)

bin\yuheng_client.exe
连接 192.168.1.100 5555;    # 连服务器
用户名: admin                 # 输入用户名
密码: ***                     # 输入密码(不回显)

二、固定命令(免分号)

三、SQL命令参考

3.1 表管理

创建表 表名(列名 类型 [约束], ...);
删除表 表名;
显示表;
结构 表名;

示例:

创建表 文章(编号 整数 主键 自增, 标题 文本 非空, 正文 文本, 标签 文本 默认 '未分类', 发布时间 日期时间);

3.2 数据操作

插入到 表名 值(值, ...);                -- 自增列填0,空值填"空"
更新 表名 设 列 = 值 [当 条件];
删除 从 表名 [当 条件];

示例:

插入到 文章 值(0, '我的博客', '正文内容...', 空, '2026-08-12 01:00:00');
更新 文章 设 标签 = '技术' 当 编号 = 1;
删除 从 文章 当 编号 = 2;

3.3 查询

查询 * 从 表名 [当 条件] [排序 按 列 升序|降序] [限制 数量];
查询 列1 [为 别名], 列2 从 表名 [当 条件];
查询 去重 列 从 表名;
查询 聚合(列) 从 表名 [当 条件];           -- 计数/总和/平均/最大/最小
查询 列, 聚合(列) 从 表名 分组 按 列;
查询 * 从 表A 左连接 表B 当 表A.列 = 表B.列;
查询 * 从 表A, 表B 当 表A.列 = 表B.列;
查询 * 从 表名 当 列 在(查询 列 从 表2);   -- 子查询
查询 函数(列) 从 表名;                     -- 函数列投影
解释 查询...;                              -- 执行计划(是否走索引)

3.4 条件运算符

• 比较:= != < <= > >=
• 逻辑:且(AND) / 或(OR)
• 模糊:列 像 '模式'(%任意多字符,_单字符)
• 范围:列 在(值, 值...) / 列 在 低值 和 高值 之间
• 空值:列 = 空(NULL参与比较不成立)

3.5 函数

• 日期:年(日期) 月(日期) 日(日期)
• 文本:长度(文本) 大写(文本) 小写(文本) 拼接(a, b)
• 聚合:计数 总和 平均 最大 最小

四、数据类型与约束

创建表 学生(学号 整数 主键 自增, 姓名 文本 非空, 邮箱 文本 唯一,
             班级 文本 默认 '一班', 班级号 整数 引用 班级(编号));

五、高级功能

5.1 事务

开始事务;
插入到 文章 值(0, '草稿', '...', 空, 空);
回滚;            -- 撤销事务内所有修改
提交;            -- 生效

5.2 备份与恢复

备份 到 'data/backup1.dat';      -- 整库备份
恢复 从 'data/backup1.dat';      -- 从备份恢复

5.3 多数据库

创建库 测试库;
使用 测试库;      -- 切换(类似MySQL的USE)
显示库;

5.4 视图

创建视图 优秀学生 为 查询 * 从 学生 当 成绩 >= 80;
显示视图;
查询 * 从 优秀学生;     -- 像表一样查询
删除视图 优秀学生;

5.5 用户权限(网络版)

创建用户 张三 密码 'zhang123' 读写;     -- 权限:管理员/读写/只读
显示用户;
删除用户 李四;

权限说明:只读用户禁止写操作(插入/更新/删除/建表);用户管理仅管理员可操作。用户存于 data/users.dat。

5.6 索引

• 主键/唯一列自动建B树索引
• 等值查询自动走索引(EXPLAIN可验证)
• 索引在启动/删除行后自动重建

5.7 导出CSV

导出 文章 到 'data/文章.csv';    -- 默认导出到 data/表名.csv

5.8 Web管理界面(对标Navicat)

在命令行输入 显示网页版; 自动打开浏览器进入Web管理界面(端口8080)。纯服务器模式(-s)启动时自动启用。

功能:

1. 左侧树:数据库 → 表列表(含行数),点击表显示表结构 + 数据分页浏览(每页100行,支持翻页)
2. SQL编辑器:输入任意SQL命令执行(查询/插入/更新/删除),结果以表格展示,Ctrl+Enter快速执行
3. 顶部刷新按钮:重新加载表列表

访问地址: http://127.0.0.1:8080

六、服务器配置(server.ini)

端口 = 5555                    ; 监听端口
密码 = 123456                  ; 默认admin用户初始密码
慢查询阈值 = 1000              ; 超过该毫秒数记录到 data/slow.log

七、运维与日志

• 命令耗时:每条命令自动显示 (耗时 X.X 毫秒)
• 慢查询日志:超过阈值写入 data/slow.log
• 数据库文件:data/yuheng.dat(存储格式v8,磁盘分页,兼容v1-v7自动迁移)
• 用户文件:data/users.dat

八、常见问题(FAQ)

九、项目架构

include/   词法/语法/存储/执行/索引/网络/命令 接口
src/       各模块实现
tests/     39+ 测试文件(回归基线)
bin/       yuheng.exe(主程序) + yuheng_client.exe(客户端)
data/      数据库/用户/日志(运行时生成)
docs/      文档

模块:lexer(词法) → parser(语法) → executor(执行) + storage(存储) + btree(索引) + net_server(网络) + builtin(固定命令) + logger(日志)。

十、容量与限制

• 单文本:65,535字符;单表32列;单库32表+32视图
• 单表行数:动态增长,磁盘分页存储(8KB页+64页LRU缓存),内存占用恒定,实测5,000行流畅
• 性能:万行以下亚毫秒级查询,插入约0.14ms/行(含保存)
• 已知限制:数据全量落盘(非增量)、排序为冒泡、并发为全局锁串行