简介这份资源是面向计算机专业学生与数据库内核学习者的C版MiniSQL数据库管理系统完整源码参考CMU15445 BusTub框架并针对原MiniSQL实验指导做了修改与扩展可用于课程设计、数据库实验或自学SQL解析与执行引擎的实现原理。压缩包共389个文件约1.07MB以131个h头文件、100个cc与51个cpp源文件为主体另有34个py脚本、9个cmake构建配置及若干txt、sh、md说明文档覆盖词法语法解析、缓冲池、B树索引、记录管理、Catalog元数据与锁管理器等模块。已有79人学习下载。读者可据此获得一套可编译运行的轻量级数据库内核参考实现理解页面缓存读写、索引增删查改与并发控制的具体落地方式并借助构建脚本与测试用例快速搭建实验环境、对照排查编译与运行问题。1. 从一份能跑通的 C MiniSQL 源码说起它到底解决了谁的痛点如果你正在做数据库课程设计或者想找一个能塞进简历、面试时讲得清楚的 C 项目那这份基于 C 的 MiniSQL 数据库管理系统源码包值得你花一个下午拆开看。它不是玩具级的命令行计算器而是一个带缓冲池、B 树索引、记录管理和锁管理器的完整 SQL 解析执行引擎参考了 CMU15445 的 BusTub 框架同时兼容原 MiniSQL 实验指导的要求。换句话说你拿到的是一套能编译、能建表、能插数据、能走索引的数据库内核骨架而不是一堆散落的算法题。这份资源适合三类人第一类是被课程设计逼到墙角、需要一份可运行参考实现的学生第二类是刷完 C 语法但没碰过真实系统编程、想通过一个项目理解「页、槽、索引、事务」怎么落地的自学者第三类是做嵌入式或边缘场景、想裁剪一个轻量 SQL 引擎的工程师。它解决的核心问题是把数据库理论课上那些抽象概念——缓冲池替换策略、B 树分裂合并、记录序列化、锁粒度——变成你能单步调试的代码。源码包里能看到minisql_yacc.c、minisql_lex.c、parser.c、syntax_tree.c这些文件说明 SQL 词法语法分析链路是完整的不是只给你一个执行器空壳。2. 拆包先看构建链路Bazel、glog 与 gtest 怎么串起来2.1 为什么这个项目用 Bazel 而不是 CMake拿到源码包第一件事不是急着写代码而是把构建系统摸清楚。这份 MiniSQL 用的是 Bazel根目录下有BUILD.bazel和glog.bzl还带了gtest_unittest.cc。很多同学第一次看到 Bazel 会懵因为平时写 C 习惯 CMake 或者直接 g 一把梭。但 Bazel 在这里是有道理的数据库项目模块多、依赖关系复杂Bazel 的 target 粒度能让你单独编译parser、buffer_pool、b_plus_tree这些模块改一个文件不会全量重编。glog.bzl的存在说明日志库 glog 是通过自定义规则引入的不是系统级安装这样换机器时依赖不会丢。常见做法是先用 Bazel 把整个项目跑通再决定要不要迁移到 CMake。如果你所在的环境没有 Bazel也可以手动写一个 CMakeLists.txt把parser.c、syntax_tree.c、minisql_lex.c、minisql_yacc.c以及执行器相关源文件加进去链接 glog 和 gtest。但要注意minisql_yacc.c和minisql_lex.c通常是 flex/bison 生成的如果你改了.l或.y文件需要重新生成不能只改.c。2.2 编译前必须确认的三个环境项在动手编译之前先把下面这张表里的东西核对一遍少一个都会在链接阶段翻车。检查项要求不满足时的典型报错C 标准C17 及以上std::optional未定义、string_view找不到Bazel 版本与 BUILD 文件语法兼容no such attribute copts或 workspace 规则报错glog / gtest能通过glog.bzl拉取或本地已装undefined reference to google::InitGoogleLoggingflex / bison若需重新生成词法语法文件minisql_yacc.c缺失或语法错误我一般会先跑一条最小验证命令确认 Bazel 能识别 target# 列出所有可构建目标先看有没有解析错误 bazel query //... # 只编译核心库不跑测试快速暴露依赖问题 bazel build //:minisql_core这两条命令的逻辑是bazel query不触发实际编译只做 BUILD 文件解析能最快发现 target 名写错、依赖缺失的问题bazel build指定核心库而不是全部是为了避免测试代码的编译错误干扰你对主链路的判断。参数上如果你机器上 Bazel 缓存目录空间紧张可以加--disk_cache/tmp/bazel_cache把缓存挪到临时目录避免把 home 分区撑爆。2.3 跑通第一个单元测试gtest 是你的安全网源码包里带了gtest_unittest.cc这不是摆设。数据库内核最怕的是「改一处、崩三处」而单元测试就是你的后悔药。先跑测试再改代码能让你知道哪些行为是基线。# 运行所有测试输出失败详情 bazel test //... --test_outputerrors # 只跑某个测试目标比如缓冲池相关 bazel test //test:buffer_pool_test --test_outputall--test_outputerrors的意思是只在失败时打印完整输出通过时保持安静适合快速回归--test_outputall则会打印所有测试的日志适合你第一次跑、想看清楚每个用例在干什么。如果测试直接段错误优先检查glog初始化有没有在main里调用google::InitGoogleLogging(argv[0])很多崩溃是因为日志库没初始化就写日志。3. 缓冲池与 B 树索引数据库最核心的两块怎么调3.1 缓冲池管理页面读写与替换策略的落点缓冲池是数据库和磁盘之间的黑匣子。这份 MiniSQL 的缓冲池实现了数据库文件页面的缓存管理提供对硬盘页面进行读取和写回的操作。你需要在代码里找到BufferPoolManager相关的类重点看三个方法FetchPage、UnpinPage、FlushPage。FetchPage负责把指定 page_id 的页面从磁盘拉到内存帧里如果帧满了就触发替换UnpinPage减少引用计数让页面可以被淘汰FlushPage把脏页写回磁盘。常见做法是先用 LRU 或者 Clock 替换策略把功能跑通再考虑优化。如果你在调试时发现数据插进去查不到八成是脏页没写回或者UnpinPage的is_dirty参数传错了。下面这段伪代码展示了典型的页面访问流程// 从缓冲池获取页面page_id 是磁盘页号 Page *page buffer_pool-FetchPage(page_id); if (page nullptr) { // 所有帧都被占用且无法淘汰通常是忘记 Unpin LOG(ERROR) FetchPage failed, pool exhausted; return false; } // 在页面上写入记录标记为脏页 char *data page-GetData(); memcpy(data offset, record, record_size); // 用完必须 Unpin第二个参数 true 表示脏页需要写回 buffer_pool-UnpinPage(page_id, true);逻辑说明FetchPage返回的页面指针在UnpinPage之前不能被淘汰这是引用计数的基本约束。参数is_dirtytrue告诉缓冲池这个页面被修改过淘汰前必须写回磁盘如果你改了数据却传false数据就丢了而且这种 bug 很难查因为内存里看着是对的。我一般会在UnpinPage之后把页面指针置空防止后续误用已经可能被淘汰的页面。3.2 B 树索引插入、删除、查找的边界条件索引管理支持 B 树索引提供高效的插入、删除、查找和迭代遍历操作。B 树是这份源码里最容易翻车的模块因为分裂和合并的边界条件特别多。你需要重点关注BPlusTree的Insert、Remove、GetValue三个方法以及内部节点和叶子节点的分裂逻辑。一个实用的调试习惯是先写一个最小测试只插 3 个键打印树结构再插到触发分裂观察根节点变化然后删除到触发合并看树能不能正确收缩。下面是一个构造测试用例的代码片段// 创建一个阶数为 4 的 B 树阶数决定节点最大子节点数 BPlusTreeint, int tree(test_index, 4); // 插入键值对观察分裂 for (int i 1; i 10; i) { tree.Insert(i, i * 100); } // 查找验证 int value; bool found tree.GetValue(7, value); // 期望 found true 且 value 700 // 删除后再次查找验证合并逻辑 tree.Remove(7); found tree.GetValue(7, value); // 期望 found false参数说明阶数4意味着每个内部节点最多 4 个孩子、最少 2 个孩子根节点除外。阶数越小分裂越频繁越容易暴露边界 bug阶数越大树越矮但节点内查找变慢。调试阶段建议用小阶数比如 3 或 4这样几十个键就能触发多轮分裂合并。如果你发现删除后树结构不对优先检查叶子节点的next指针有没有在合并时正确更新迭代遍历依赖这个指针。3.3 记录管理与元数据Catalog 怎么管表和索引记录管理支持表的创建、删除、插入、更新和查询操作元数据管理实现了 Catalog Manager用于管理数据库对象如表格和索引的元数据。Catalog 相当于数据库的「户口本」表名、列定义、索引信息都从这里查。你需要找到Catalog类里的CreateTable、GetTable、CreateIndex等方法理解它怎么把元数据序列化到系统表或者独立文件里。常见坑是建表时列类型和长度没对齐导致插入时记录序列化错位。比如你定义varchar(20)但实际写入时按int去解析读出来就是乱码。我一般会在CreateTable之后立刻调一次GetTable把返回的 schema 打印出来确认列顺序、类型、偏移量都对。另外索引的元数据要和表绑定删表时记得把关联索引一起清理否则下次建同名索引会冲突。4. 并发控制与锁管理器事务并发访问的避坑清单4.1 锁管理器怎么加锁和解锁并发控制提供了锁管理器支持事务的并发访问控制。这份源码里的锁管理器通常支持共享锁和排他锁你需要关注LockManager的LockShared、LockExclusive、Unlock三个方法。锁的粒度和加锁顺序直接决定会不会死锁。一个常见的实现是给每个资源维护一个锁请求队列事务按顺序排队。如果你在测试时发现两个事务互相等待、程序卡死那就是死锁了。调试阶段可以先用单线程跑通再开两个线程模拟并发。下面是一个加锁解锁的调用示例// 事务开始获取事务 ID txn_id_t txn lock_manager-BeginTxn(); // 对资源 R 加共享锁用于读 lock_manager-LockShared(txn, R); // 读操作... // 升级为排他锁前必须先释放共享锁否则容易死锁 lock_manager-Unlock(txn, R); lock_manager-LockExclusive(txn, R); // 写操作... // 事务结束释放所有锁 lock_manager-Unlock(txn, R); lock_manager-CommitTxn(txn);逻辑说明锁升级从共享到排他是死锁高发区因为两个事务可能同时持有共享锁、同时申请排他锁互相等对方释放。常见做法是尽量避免锁升级或者在升级前统一加锁顺序。参数上txn_id_t是事务标识R是资源标识通常用(table_id, page_id, slot_id)或者(index_id, key)来表示。如果你发现解锁后其他事务还是拿不到锁检查Unlock有没有正确唤醒等待队列。4.2 并发场景下的三个典型翻车点第一个翻车点忘记在异常路径解锁。如果读操作中途return或抛异常锁没释放其他事务就永久阻塞。解决办法是用 RAII 封装锁或者确保每条路径都走到Unlock。第二个翻车点锁粒度过粗。如果直接给整张表加排他锁并发度极低测试时看着没问题一上多线程就退化成串行。常见做法是锁到页级或槽级但粒度越细管理开销越大需要权衡。第三个翻车点事务提交前崩溃锁状态没恢复。如果锁管理器只在内存里维护状态进程重启后锁就丢了但数据可能处于不一致状态。这份源码如果没做持久化锁那它更适合教学而非生产你要清楚这个边界。5. 常见问题排查从编译报错到运行崩溃的实战记录5.1 编译链接阶段的三个高频报错现象一undefined reference to yylex。原因通常是minisql_lex.c没有被加入编译目标或者 flex 生成的文件名和 BUILD 里写的不一致。解决方法是检查BUILD.bazel的srcs列表确认minisql_lex.c和minisql_yacc.c都在里面并且没有重复定义。现象二fatal error: glog/logging.h: No such file or directory。原因是 glog 头文件路径没配好。如果用的是glog.bzl自定义规则检查includes属性如果是系统安装确认-I路径指向 glog 的 include 目录。我一般会先用find / -name logging.h -path *glog*定位实际路径再改构建文件。现象三error: ‘std::filesystem’ has not been declared。原因是 C 标准低于 C17或者编译器没开-lstdcfs。解决方法是把copts改成-stdc17并在链接时加上-lstdcfs老版本 GCC 需要。5.2 运行时的数据不一致与段错误现象插入数据后查询返回空但磁盘文件大小在增长。原因通常是缓冲池的脏页没写回或者索引和记录不同步。解决方法是先调FlushPage强制写回再查如果还是空检查 B 树的键类型和记录的主键类型是否一致比如一个用int一个用int64_t比较时就会出错。现象程序在FetchPage或UnpinPage处段错误。原因多半是页面指针为空还继续用或者page_id越界。解决方法是在每次FetchPage后加空指针判断并在UnpinPage后把指针置空。另外检查page_id是否超过了磁盘文件的实际页数越界访问会直接崩。现象多线程测试时结果随机错误。原因是锁没加对或者共享数据结构没有保护。解决方法是先用单线程跑通所有逻辑再逐步加并发每加一个共享资源就问自己「这个资源被几个线程访问锁在哪」。5.3 测试用例跑不过时的定位顺序先看是编译失败还是断言失败。编译失败查 BUILD 文件和头文件路径断言失败看期望值和实际值差在哪。如果测试直接崩溃用gdb跑# 在 gdb 下运行测试崩溃时打印调用栈 gdb --args ./bazel-bin/test/buffer_pool_test (gdb) run (gdb) btbt打印的调用栈能直接告诉你崩在哪个函数、哪一行。常见的是空指针解引用和数组越界。如果栈里全是标准库函数那问题多半在你传入的参数上往回翻一层看自己的代码。6. 进阶用法把 MiniSQL 改造成你自己的实验平台6.1 替换缓冲池策略并验证命中率默认的 LRU 策略在顺序扫描场景下命中率很差因为顺序扫描会把缓存全部冲掉。你可以试着实现一个 LRU-K 或者 Clock 策略然后用同一组查询对比命中率。具体做法是在BufferPoolManager里加一个命中计数器每次FetchPage命中就加一测试结束后打印hit_count / total_fetch。我一般会跑两遍同样的查询序列第一遍预热第二遍统计这样数据更稳定。6.2 给 B 树加一个范围扫描接口原生的GetValue只能点查但实际查询经常需要WHERE id BETWEEN 10 AND 20。你可以在叶子节点层加一个Scan方法从起始键定位到叶子然后沿着next指针遍历到结束键。注意边界起始键可能不存在需要找到第一个大于等于它的位置结束键也要判断是否包含。这个改造能让你理解数据库范围查询的底层代价。6.3 用 gtest 写回归测试锁住你的修改每次改完核心模块跑一遍bazel test //...应该成为习惯。我自己的做法是每修一个 bug就补一个对应的测试用例确保它不会再犯。比如你修了 B 树删除时的合并 bug就写一个「插入 100 个键、删除 50 个、再查找剩余 50 个」的测试。从那以后我每次动索引代码都强制走一遍全量测试加新增用例不然真的不敢提交。希望这份源码包能帮你把数据库内核从「背八股」变成「能上手改」哪怕只跑通一个建表插查的流程也比只看书强得多。本文还有配套的精品资源点击获取