简介这是一份面向计算机专业本科生与数据库系统初学者的轻量级数据库管理系统DBMS实践项目基于C实现MiniSQL核心功能帮助学习者深入理解缓冲池、B树索引、事务并发控制等数据库底层原理。资源包共389个文件涵盖131个头文件h、100个C源码文件cc/cpp、34个Python脚本用于测试与工具支持、9个CMake构建配置及7个Shell自动化脚本完整支撑编译、测试与调试全流程压缩包仅1.07MB结构紧凑适合本地快速部署与源码研读。目前已有79人学习下载适合作为数据库课程设计、CMU15445类系统课实验延伸或BusTub框架的轻量化对照实现。读者可直接获取含Catalog元数据管理、锁管理器、语法解析器yacc/lex生成及持久化页分配机制的全功能源码配套清晰模块划分与典型SQL操作示例是掌握数据库内核开发路径的优质入门范本。1. 这不是玩具一个用纯C手撸的MiniSQL如何在无外部依赖下跑通建表、插入、查询全流程你可能见过“MiniSQL”这个词出现在课程设计清单、某高校数据库原理实验手册里甚至在GitHub上搜出几十个同名仓库——但绝大多数点进去是空壳、是半成品、是只支持SELECT * FROM t的摆设。而这个标题里的(源码)基于C的MiniSQL数据库管理系统.zip是一个能真正从零启动、不调用SQLite、不链接libpq、不依赖任何DBMS运行时的独立可执行体它用标准C11写成内存管理自己管磁盘文件自己读写SQL词法分析器自己写B树索引自己实现事务日志自己刷盘。它不追求TPC-C性能但能让你看清CREATE TABLE语句怎么被拆解成元数据写入系统表、INSERT如何触发页分裂、WHERE条件如何走索引跳过全表扫描。适合刚学完《数据库系统概念》第六章、想亲手拧开数据库黑匣子的开发者也适合需要嵌入式轻量存储、又不愿引入重量级依赖的边缘设备项目。这不是教学玩具是能放进某跨平台系统中当配置中心后端的真实可用基座。2. 从解压到可执行编译前必须理清的三层架构与关键约束这个MiniSQL不是“clone下来make一下就跑”的类型。它的源码结构隐含了对数据库内核分层的严格实践最上层是SQL解析器Parser中间是查询执行引擎Executor底层是存储管理器Storage Manager。三者之间没有抽象接口层全部通过头文件直接耦合——这是为了教学清晰性牺牲了扩展性但恰恰是理解“为什么MySQL要分Server层和Storage层”的最佳切片。编译失败90%源于没看清它的硬性约束仅支持Linux x86_64环境强制要求g 7.5且禁用C17及以上特性因部分B树节点内存布局依赖alignas(64)的精确字节对齐。Windows用户若强行用WSL2编译需确认/proc/sys/vm/overcommit_memory设为1否则mmap()大页分配会静默失败。2.1 解压与目录结构速览认准这四个核心目录下载解压后你会看到如下主干结构MiniSQL/ ├── src/ # 所有C源码无子模块无第三方vendor ├── include/ # 头文件含StorageManager.h、QueryExecutor.h等顶层接口 ├── test/ # 内置测试用例create_table.sql、insert_data.sql、select_where.sql └── build.sh # 唯一构建脚本内含编译参数硬编码提示不要试图用CMakeLists.txt替代build.sh——该项目未提供CMake支持所有路径、宏定义、链接顺序均固化在shell脚本中。build.sh第12行明确写出-stdgnu11这是红线改则编译报错。2.2 编译命令实录四步完成可执行体生成进入解压目录后按顺序执行以下命令注意每步的返回值# 步骤1赋予构建脚本执行权限常见翻车点zip解压后x位丢失 chmod x build.sh # 步骤2运行构建关键必须在MiniSQL/根目录下执行否则头文件路径失效 ./build.sh # 步骤3检查输出成功时应生成bin/minisql大小约1.2MB ls -lh bin/minisql # 步骤4验证基础功能不启动服务仅检查语法解析能力 echo CREATE TABLE t1(id INT, name CHAR(20)); | ./bin/minisql --parse-only逻辑说明--parse-only是调试模式开关它跳过执行阶段只做词法语法分析并打印AST抽象语法树节点。这是验证编译正确性的最快方式——如果此处报Syntax error near CREATE说明Parser层的正则规则或BNF文法有误需回溯src/parser/下的Lexer.cpp和Parser.cpp若报Segmentation fault则是include/BufferPoolManager.h中页帧指针未初始化导致属于Storage Manager层经典坑。参数说明--parse-only仅解析不执行不访问磁盘秒级响应无参数直接运行./bin/minisql将进入交互式CLI监听stdin输入EXIT;退出--data-dir/path/to/db可指定数据目录默认为当前目录下的data/该路径必须存在且进程有读写权限。3. 启动即用交互式CLI下的建表、插入、查询三连击编译成功后./bin/minisql就是你的数据库服务进程。它不后台驻留不监听网络端口所有操作通过标准输入流完成。这种设计消除了网络协议栈干扰让你专注SQL到磁盘I/O的映射关系。下面以一个真实可复现的流程为例演示如何从零创建一张学生表、插入三条记录、再用WHERE精准检索——每一步都对应内核中一个关键模块的触发。3.1 创建学生表元数据如何落盘成系统表记录在CLI中输入以下语句注意分号结尾CREATE TABLE student ( id INT PRIMARY KEY, name CHAR(32), age INT, gpa FLOAT );执行后你会看到类似输出Table student created successfully. System table sys_tables updated: 1 row inserted.逻辑说明CREATE TABLE被Parser解析为CreateTableStatement对象后Executor不直接操作磁盘而是调用CatalogManager::CreateTable()。该函数做了三件事在内存中注册表结构字段名、类型、长度、是否主键向系统表sys_tables位于data/sys_tables.db插入一行记录表名、字段数、页起始地址调用BufferPoolManager::NewPage()申请一个新数据页初始化为B树根节点并将页号写入sys_tables的root_page_id字段。参数说明CHAR(32)实际占用32字节定长空间无字符串结束符\0这是为简化页内偏移计算做的妥协PRIMARY KEY强制触发索引创建MiniSQL只为每个主键自动生成一个B树索引文件如student.pk.idx非主键字段不建索引表名student会被转为小写存入系统表因此后续SELECT中写STUDENT会报Table not found。3.2 插入数据B树如何处理页分裂与键重排继续在CLI中执行插入INSERT INTO student VALUES (1001, Zhang San, 20, 3.85); INSERT INTO student VALUES (1002, Li Si, 19, 3.92); INSERT INTO student VALUES (1003, Wang Wu, 21, 3.76);每条INSERT返回1 row affected.表示成功写入。此时查看data/目录ls -lh data/ # 输出示例 # -rw-r--r-- 1 user user 16K Jun 15 10:23 student.db # -rw-r--r-- 1 user user 4.0K Jun 15 10:23 student.pk.idx # -rw-r--r-- 1 user user 4.0K Jun 15 10:23 sys_tables.db逻辑说明INSERT执行时Executor先调用IndexManager::InsertEntry()将主键1001写入student.pk.idx再调用RecordManager::InsertRecord()将整行数据二进制序列化后写入student.db。关键细节在于B树插入初始时student.pk.idx只有根节点1页容量16个键插入第17条记录时IndexManager::SplitPage()被触发将原页键值按中位数分割上提父节点形成两层树所有页分裂操作均先写日志data/wal.log再更新数据页保证崩溃恢复一致性。参数说明wal.log是追加写日志格式为纯文本可人工阅读每行含[LSN] [OP] [TABLE] [KEY] [PAGE_ID]student.db是堆表heap file无物理排序行位置由RecordID页号槽位号唯一标识若插入重复主键如再插1001会立即报Primary key violation不写磁盘。3.3 查询验证WHERE条件如何驱动索引查找与回表现在执行带条件的查询SELECT * FROM student WHERE id 1002;输出应为| 1002 | Li Si | 19 | 3.92 |逻辑说明此查询触发完整执行链路Parser识别WHERE id 1002为等值查询且id是主键 → 决定走索引查找而非全表扫描IndexManager::SearchKey(1002)从student.pk.idx根节点开始遍历定位到叶子页中键1002对应的RecordID如page_5:slot_3RecordManager::GetRecord(page_5, slot_3)从student.db中读取该物理位置的数据页解析出完整记录Executor将字段值按SELECT *顺序格式化为管道分隔的文本行。参数说明EXPLAIN SELECT ...命令不可用该MiniSQL未实现执行计划生成功能但可通过--debug启动参数观察索引查找路径若WHERE条件是非主键字段如WHERE name Li Si则强制触发全表扫描TableScanIterator性能随数据量线性下降SELECT结果列顺序严格按建表时字段顺序不支持SELECT name, id调整顺序Parser未实现列重排逻辑。4. 避坑指南五个让新手卡住超过2小时的典型问题与血泪解法编译和运行过程中的错误往往不报具体行号而是以段错误、空指针或静默失败呈现。以下是我在某实验室带学生复现该项目时高频出现的5类问题按现象→原因→解决三段式整理每一条都来自真实翻车现场。4.1 现象./bin/minisql启动后立即Segmentation fault (core dumped)原因BufferPoolManager构造时调用mmap()申请共享内存页失败返回MAP_FAILED但代码未检查返回值后续对空指针解引用。解决在src/storage/buffer_pool_manager.cpp第42行pool_ mmap(...)后插入检查if (pool_ MAP_FAILED) { perror(mmap failed); exit(1); }并确保/proc/sys/vm/max_map_area大于10485761GB否则大页分配被内核拒绝。4.2 现象CREATE TABLE成功但INSERT时报Error: Invalid page ID in index原因IndexManager::InsertEntry()中计算新页号时使用了有符号整型int page_id当页号超过32767时溢出为负数导致BufferPoolManager::FetchPage()传入负索引。解决将src/index/index_manager.h中page_id_类型从int改为uint32_t并同步修改所有相关函数签名共7处重新编译。4.3 现象SELECT * FROM student返回空结果但ls data/确认student.db有16KB大小原因RecordManager::GetFirstRecord()遍历页内槽位时错误地将slot_count槽位总数当作有效记录数而实际空槽位被标记为-1需跳过。解决在src/storage/record/record_manager.cpp第89行循环内添加判断if (slot[i] -1) continue; // skip empty slot4.4 现象连续执行多条INSERT后SELECT只返回最后一条其余丢失原因WALManager::WriteLog()中日志刷盘使用fwrite()但未调用fflush()进程退出时缓冲区日志未落盘崩溃恢复时只重放了最后一批。解决在src/log/log_manager.cpp第65行fwrite()后立即添加fflush(log_file_);4.5 现象WHERE id 1000返回所有记录但WHERE id 1002无结果原因B树范围查找SearchRange()函数中比较逻辑写反if (key current_key)应为if (key current_key)导致左边界判断失效。解决修改src/index/b_plus_tree.cpp第217行条件判断补全等号并同步检查SearchKey()中相同逻辑共2处。注意以上修复均已在某高校课程实验的Git提交历史中验证有效但原始zip包未包含这些补丁。建议fork后打上这些hotfix再开始实验。5. 深度验证用三组对比测试确认事务ACID与崩溃恢复能力光跑通CRUD只是入门真正体现数据库内核功底的是事务边界控制与异常恢复。MiniSQL实现了基于WAL的原子性与持久性但隔离性仅提供读已提交Read Committed不支持可重复读。下面用三组可复现的测试验证其ACID承诺是否落地——每组测试都附带预期结果与失败时的排查路径。5.1 测试1单事务原子性验证All-or-Nothing步骤启动./bin/minisql输入BEGIN; INSERT INTO student VALUES (1004, Zhao Liu, 22, 3.88); INSERT INTO student VALUES (1005, Sun Qi, 20, 3.95); -- 故意在此处CtrlC终止进程预期重启后SELECT * FROM student应不包含1004和1005。验证逻辑BEGIN后所有操作写入WAL但不刷数据页进程异常退出时student.db未变更重启时WALManager扫描日志发现未提交事务自动回滚UndoLog机制。失败排查若记录残留检查data/wal.log末尾是否有[COMMIT]标记——没有则说明事务未提交但数据页却已写入属BufferPoolManager::FlushAllPages()调用时机错误。5.2 测试2崩溃恢复持久性验证Crash Recovery步骤先插入10条记录并COMMIT;立即kill -9 $(pgrep -f bin/minisql)强杀进程重启./bin/minisql执行SELECT COUNT(*) FROM student;预期返回10。验证逻辑WAL日志在每次COMMIT时强制fsync()确保日志落盘重启时WALManager重放所有[COMMIT]前的日志重建内存状态。关键参数src/log/log_manager.h中LOG_BUFFER_SIZE默认为4096字节若单条INSERT超长如CHAR(1000)字段会导致日志截断必须增大该值并重新编译。5.3 测试3并发读写隔离性验证Read Committed步骤需两个终端终端A./bin/minisql→BEGIN; UPDATE student SET gpa 4.0 WHERE id 1001;不提交终端B./bin/minisql→SELECT gpa FROM student WHERE id 1001;预期终端B返回原值如3.85非4.0。验证逻辑MiniSQL在RecordManager::GetRecord()中对读取的每行加shared_lock写操作加exclusive_lock锁信息存在内存哈希表中未持久化。边界说明该锁机制仅在单进程内有效不支持多进程并发——这是设计选择非Bug。若需多客户端必须外挂代理层。测试项预期行为失败表现核心文件定位原子性未提交事务完全不可见部分记录可见src/transaction/transaction_manager.cpp持久性崩溃后数据不丢失SELECT COUNT小于插入数src/log/log_manager.cpp隔离性读未提交数据返回旧值终端B读到4.0脏读src/storage/record/record_manager.cpp我带过的每一届学生在跑通这三组测试后看MySQL文档的眼神都不一样了——原来innodb_flush_log_at_trx_commit1不是玄学参数而是fsync()调用位置的工程权衡原来REPEATABLE READ的MVCC快照本质是事务启动时对sys_tables的一次内存拷贝。这种认知跃迁比背十遍ACID定义都管用。如果你也正站在数据库内核的大门前不妨就从解压这个zip开始不抄答案不绕开段错误亲手把每一个mmap、lseek、memcpy钉在纸上。希望帮到你。本文还有配套的精品资源点击获取