简介：这是一份基于C++实现的MiniSQL数据库管理系统源码，面向高校数据库课程学生与底层内核开发者，可作为CMU15445 BusTub框架的扩展实验参考，解决从SQL解析到存储执行全链路的入门难题。资源共389个文件，压缩包仅1.07MB，核心部分由头文件与CC/CPP源文件组成，其中头文件用于模块接口声明，源文件承载缓冲池管理、B+树索引、记录管理、元数据目录及基于锁的事务并发控制等实现；此外还包含CMAKE构建脚本、Python自动化测试、Yacc语法定义等辅助开发文件。目前已有79人学习。读者通过阅读和编译此工程，既可对比学习数据库各核心模块的协作流程，又能深入理解数据页淘汰、索引增删查与锁调度的具体编码思路，支持在现有框架上二次开发，适用于课程实验、期末项目或数据库内核入门研究。
1. MiniSQL是什么：一份C++课程设计源码，值得读懂而不是跑通就删
数据库管理系统课程设计周，很多人的状态是：从网上下到一个“基于C++的MiniSQL数据库管理系统.zip”，解压，make，跑通几条 SELECT 就认为完事了。等到面试被问一句“你的 B+树索引是怎么维护的”，直接哑火。关于C++的MiniSQL，它不是一个工业级数据库，它是一套麻雀虽小五脏俱全的教学源码，覆盖了SQL解析、表管理、记录存储、B+树索引和简单执行引擎。你这门课值不值得做，取决于你从这份源码里拿走多少，而不是能不能跑。本篇文章的目标很直接：不只让你看懂这类源码怎么运行，更让你理解它背后每一层在解决什么问题，拿到其他源码包也能照方抓药。这类项目不算很大，但它非常适合想从零搞清楚“数据库到底怎么工作”的开发者。
2. 拿到源码先别编译：MiniSQL的模块划分与三个关键入口文件
很多初学者拿到 zip 包第一件事就是双击 Makefile 编译，然后被一堆编译错误劝退。我一般会先按住手，花半小时把目录结构过一遍，搞清楚一件事：数据库管理系统的源码，永远是“解析、执行、存储”三件事在多个文件里跳来跳去。你先把这些跳动的路线画出来，编译只是填充细节。
2.1 MiniSQL 的经典三层结构：解析层、执行层、存储层
你打开任意一份 MiniSQL 源码，大概率能看到这三个层次。第一层是解析层，一般叫 Interpreter 或者 Parser，任务是把用户输入的 SQL 文本变成程序能理解的结构化中间表示。第二层是执行层，也叫 Executor，拿到中间表示后，负责决定先做什么、后做什么，比如先查表还是先建索引。第三层是存储层，对应 TableManager、RecordManager、IndexManager 这类命名，负责管理文件里的页面、记录和 B+树节点。
这个结构化分层不是 MiniSQL 原创，MySQL、PostgreSQL 也是这么拆的。好处是每一层只通过接口和上下层对话，你把解析层从手写改成 lex/yacc 生成的，不影响存储层。一般 MiniSQL 源码里，这三个层分别对应不同的 .h 和 .cpp 文件：
- 解析层：SQLParser 或 Interpreter，包含词法扫描函数和语法分析函数。
- 执行层：API 层封装，比如
execSelect、execInsert这类函数，负责调度存储接口。 - 存储层：表和索引的文件读写，是最底层的字节操作。
读源码时建议从执行层的函数列表入手，比如execDropTable调用了哪些存储函数，顺着调用链一层层往下读。这个调用链读通后，你看到任何一句 SQL，脑子里就能立刻浮现它将要触发的文件路径和内存结构，这会成为调试时最大的本钱。
2.2 先读这三个文件，往往比先编译更有价值
具体到这类 MiniSQL 源码，有三个文件基本可以视为命门。第一个是定义表结构 schema 的头文件，比如Table.h，里面定义了字段名、字段类型、字段长度，它是整个系统的“世界模型”。第二个是RecordManager或RecordFile的实现，记录怎么读写、怎么标记删除都在这里。第三个是BPlusTree或IndexManager的实现文件，这是所有源码里最容易写崩的部分，也是面试官最可能问到的部分。
为什么先读这三个？因为数据结构决定算法，也决定你能在哪调试。先看 schema 定义，你能知道系统支持哪些数据类型，比如 int 占 4 字节、float 占 4 字节、char(n) 是定长字符串；如果字符串按定长存储，那么写记录时不足 n 字节的部分必须填充，否则后续读出来的字符串很可能带着垃圾尾。
// Table.h 里的典型字段结构定义 struct Field { std::string name; // 字段名 enum { INT, FLOAT, CHAR } type; // 字段类型 int length; // 仅 CHAR 类型有效，表示该字段最大长度 };这段结构体定义说明了三件事。name是字段的对外名字，SQL 里的列名最终都映射到这里。type枚举决定了序列化和比较的方式，int 和 float 按数值比较，char 按字符串比较。length对 char 类型来说是硬约束，往表里插数据时，写入按这个长度补齐，取出时也要按这个长度截断，否则会出现“字符串后边挂着一串不可见字符”的经典翻车现场。
2.3 编译命令和 Makefile 调整：不想让报错追着跑就先统一标准
拿到源码后，先看根目录有没有 Makefile 或 CMakeLists.txt。正常 MiniSQL 源码会带一个 Makefile，核心编译参数通常是：
g++ -std=c++11 -O2 -Wall -o minidb \ main.cpp \ parser.cpp \ executor.cpp \ record.cpp \ btree.cpp \ -lpthread这条命令里每个参数都有讲究。-std=c++11指定语言标准，很多老源码用 C++ 早期语法，比如把NULL当 0 用，在 C++11 里虽然兼容但会出警告；-O2开优化，B+树在 debug 模式和无优化模式下性能差距极大，课程测试时如果跑大批量插入，优化开关直接影响能否在超时前完成；-Wall是为了把可疑代码暴露出来，比如未初始化指针、类型转换。
如果你是在 Windows 上用 Visual Studio 打开这套源码，常见问题是 C++ 标准库头文件差异。老源码里常写#include <stdio.h>和#include <stdlib.h>，在 VS 里也兼容，但不建议换掉。如果在 macOS 上编译，偶尔会遇到strcasecmp这类 POSIX 函数不可用，需要自己实现一个大小写不敏感比较函数，或者用std::transform转小写再比较。
编译时有一个经验：第一次编译不要带-O2，先用-g -Wall保证能断点调试。因为优化开高后，代码的执行顺序会被重排，你打断点看到的变量值可能已经变了。跑通功能后再开-O2做性能验证。
3. 把 SQL 变成可执行动作：解析器的词法、语法与语义三层关卡
解析器是整个 MiniSQL 源码中最“像编译原理”的部分，也是很多第一次读源码的人最容易迷路的地方。很多源码包里写得很乱，因为解析器天然充满分支判断和状态流转。但只要你按词法、语法、语义三层去读，就能理清头绪。
3.1 词法分析：Token 的类型与边界问题
词法分析的任务，是把用户输入的一长串字符切分成“单词”，这些单词叫 Token。MiniSQL 里的 Token 大致有几类：关键字（select、insert、delete）、标识符（表名、列名）、数值常量（整数和浮点数）、字符串常量（单引号括起来的内容）、运算符和界符（括号、逗号、分号、等号）。
// 一个典型的 Token 定义 struct Token { enum Type { KEYWORD, // 关键字 IDENTIFIER, // 标识符（表名、列名） INTEGER, // 整数常量 FLOAT, // 浮点常量 STRING, // 字符串常量 OPERATOR, // = < > , ( ) ; 等 END // 输入结束 } type; std::string text; // 原始字符串 int intVal; // 整数常量时可用 float floatVal; // 浮点常量时可用 };注意这里的边界问题：词法分析最容易出 bug 的地方是字符串常量里出现空格和特殊字符。比如insert into student values (1, 'li ming')，如果词法扫描器见空格就断 Token，那'li和ming'会被切成两个 Token，后面的语法分析直接报错。正确做法是：遇到单引号后一直读，直到下一个单引号，中间的所有字符都属于这个字符串常量。很多源码在这里因为指针没有正确越过结尾引号，导致读出来的字符串少一个或多一个字符，进而影响后续记录存储。
3.2 递归下降语法分析：parseSelect 的骨架和参数含义
词法分析把字符切成 Token 流后，语法分析的任务是判断这些 Token 串起来是否符合 SQL 语法，同时把关键信息提取出来。MiniSQL 的语法分析基本都用手写递归下降实现，因为它简单直接，不需要引入 extern 工具生成代码。
class Parser { public: // 顶层入口，根据第一个 Token 决定进入哪条 SQL 解析路径 void parse() { if (lookahead.type == Token::KEYWORD) { if (lookahead.text == "select") parseSelect(); else if (lookahead.text == "insert") parseInsert(); else if (lookahead.text == "delete") parseDelete(); else if (lookahead.text == "create") parseCreate(); else if (lookahead.text == "drop") parseDrop(); else error("unexpected keyword: " + lookahead.text); } else { error("SQL must start with a keyword"); } } private: void parseSelect() { match("select"); // 先解析列名列表，直到发现 from while (lookahead.text != "from") { selectCols.push_back(lookahead.text); match(Token::IDENTIFIER); if (lookahead.text == ",") match(","); } match("from"); tableName = lookahead.text; match(Token::IDENTIFIER); // where 子句是可选的 if (lookahead.text == "where") { match("where"); condition = parseCondition(); } expect(";"); } };这段代码的逻辑是：从select这个关键字开始，先收集目标列名，遇到from后读表名，再往后看有没有where，如果有就去解析条件表达式。这里最容易写错的参数是parseCondition()，它要处理=、<、>和逻辑运算and、or。不少 MiniSQL 只支持单条件 where，如果你的源码支持where age > 18 and name = 'tom'，条件解析必须递归地处理左操作数、运算符、右操作数，然后再处理与/或。写的时候要注意and优先级高于or，否则a or b and c的含义就错了。
3.3 语义检查：表不存在、列不存在、类型不匹配
语法正确不等于可以执行。语义检查负责判断 SQL 里提到的表名是否在系统目录中存在，列名是否在该表中存在，插入的值类型是否匹配。MiniSQL 里通常有一个 Catalog 模块维护这些元数据：一张“表之表”记录有哪些表，每张表有哪些字段，哪个字段建了索引。
语义检查放在语法分析之后、执行之前的时机最好。很多初版源码把检查散落在执行函数里，结果就是每执行一个语句都要重复做同样的事。合理的做法是构建一个Query结构体，把解析结果汇总进去：
struct Query { std::string type; // SELECT / INSERT / DELETE / CREATE std::string tableName; std::vector<std::string> columns; Condition cond; // where 条件 };查表是否存在时，看一眼 Catalog 里的 map 即可，不存在则直接报错。查列是否存在则遍历该表的字段名列表，O(n) 就够。这里要注意的是类型匹配：如果你往 int 字段里插入字符串，需要在语义检查时就拦截，不要等到存储层序列化时才发现问题，那时定位栈会复杂得多。
我遇到过一份源码，语义检查只做了一半：查了表存在性，没查列存在性，结果 INSERT 时按列名找字段下标，下标记为 -1，然后照样写记录，写完数据读了三个月才发现所有插入都是错位存储。检查这种问题最简单的方式是给语义检查函数写一行日志，每次检查通过时打印“table ok, columns ok, type ok”，跑一批 SQL 就能看到哪层拦截失效。
4. 记录怎么落盘，索引怎么加速：存储层与 B+树的实现细节
解析和语义检查只是前端，真正决定 MiniSQL 能不能存得住数据的，是存储层。这里的核心目标是理解两个问题：一条记录在文件里长什么样，以及索引结构如何改变记录的查找路径。
4.1 定长记录的序列化：字段布局与内存对齐
MiniSQL 的表文件一般按定长记录存储，因为定长记录计算偏移极其简单，第 n 条记录的位置就是文件头大小 + n * 记录大小。极少数实现用变长记录，那要额外引入偏移表，复杂度高出不少。课程设计里除非题目明确要求，否则不推荐做变长。
// 记录序列化：把结构体写入 char 数组 void serializeRecord(const Record& rec, char* buf, const TableSchema& schema) { int offset = 0; for (size_t i = 0; i < schema.fields.size(); ++i) { if (schema.fields[i].type == Field::INT) { int val = rec.ints[i]; memcpy(buf + offset, &val, sizeof(int)); offset += sizeof(int); } else if (schema.fields[i].type == Field::FLOAT) { float val = rec.floats[i]; memcpy(buf + offset, &val, sizeof(float)); offset += sizeof(float); } else { // CHAR // 定长字符串，不足 length 的部分填 '\0' memset(buf + offset, 0, schema.fields[i].length); memcpy(buf + offset, rec.strs[i].c_str(), std::min((int)rec.strs[i].length(), schema.fields[i].length)); offset += schema.fields[i].length; } } }这段代码的核心是维护offset游标，每写完一个字段就前进对应字节数。这里最隐蔽的坑是 C++ 结构体对齐：如果你直接把整条记录定义为一个 struct，int 和 char 混排时编译器会自动填充 padding 字节，同一个 struct 在不同编译器下大小都可能不同。上面这种逐字段写入 char 数组的方式，主动避开了结构体对齐问题，每个字段的偏移都是纯手工计算，得到的结果可预测。定长字符串补齐\0是关键操作，否则后续strcmp或std::string构造会读越界。
4.2 表文件组织：文件头加上数据页的平面结构
MiniSQL 的表通常就是一个二进制文件，文件开头是文件头，存记录数、每条记录大小、已删除位置位图等元信息，之后全是一条接一条的定长记录。删除一条记录时，不会物理删掉那条数据，而是标记删除位为 1，新插入时优先复用这些空位。
const int HEADER_SIZE = 128; // 文件头预留 128 字节 const int BITMAP_OFFSET = 32; // 位图从偏移 32 字节开始 void insertRecord(const Record& rec) { fstream file("student.tbl", ios::binary | ios::in | ios::out); int slot = findFreeSlot(file); file.seekp(HEADER_SIZE + slot * recordSize); serializeRecord(rec, buf, schema); file.write(buf, recordSize); file.close(); }文件头预留 128 字节算是比较保守的做法，里面即使只用了 64 字节，也能为以后扩展留下空间。BITMAP_OFFSET = 32意味着位图从第 32 字节开始，自己定义文件格式时，这个布局必须前后一致。常见的坑是：写入时用了seekp，读取时用了seekg，在同一个 fstream 上两者状态互相干扰，导致读到错误位置。解决方法是读取时重新 open 文件，或操作之间调用clear()恢复流状态。
这里有一个需要自己拿主意的参数：每条记录大小上限。如果 schema 里定义了 5 个 char(255) 字段，一条记录就是 1275 字节，文件头 128 字节微不足道。但如果 char 长度设到 65535，记录大小会非常大，文件读写效率肉眼可见地下降，所以课程设计里 char 长度通常限制在 255 以内，这是 MiniSQL 项目里常见的隐含边界。
4.3 B+树索引：为什么用它，以及入门实现的关键参数
MiniSQL 要求必须创建索引来加速查找，绝大多数实现选择 B+树而不是哈希索引，原因是：B+树支持范围查询（><条件），哈希只支持等值；B+树永远平衡，查找时间稳定在树高级别；叶子节点之间有链表指针，顺序扫描整棵索引树非常高效。哈希索引虽然在单条等值查询上可能更快，但不满足课程设计对“支持范围查询”的考察要求。
B+树的几个关键参数必须理解：
- 阶数 order：每个节点最多允许的子节点数。order 越大树越矮，但单个节点内的线性查找成本上升。
- 叶子节点：存实际键值和记录 ID；内部节点只存键值和指向子节点的指针，不存记录。
- 分裂策略：当节点键值数超过 order 时，必须分裂成两个节点，并把中间键提升到父节点。
// B+树叶子插入：找到叶子后按序插入，超过阶数就分裂 bool insertKey(BTreeNode* leaf, const BKey& key, const RecordId& rid) { // 用 upper_bound 找到第一个大于 key 的位置 auto it = std::upper_bound(leaf->keys.begin(), leaf->keys.end(), key); size_t pos = it - leaf->keys.begin(); leaf->keys.insert(it, key); leaf->recordIds.insert(leaf->recordIds.begin() + pos, rid); // 超过阶数上限后触发分裂 if (leaf->keys.size() >= order) { splitLeaf(leaf); } return true; }upper_bound是标准库里专为已排序序列做的二分查找，插入前 keys 有序，插入后依然有序。分裂时机是判断keys.size() >= order，如果你是初学者，建议把分裂逻辑独立成单独函数，先写叶子分裂，再写内部节点分裂，最后写根节点分裂。因为根节点分裂会产生新的根，那部分容易写崩。
分裂的时候有一个经常翻车的选择：中间键是上提到父节点还是留在左子节点。对于叶子节点，中间键通常留在左子节点，同时复制一份上提到父节点，因为叶子节点的键必须全部保留；对于内部节点，中间键上提到父节点后不会再留在原节点。如果你的源码搞反了这个，索引会丢失键值，表现为明明插入了数据，索引却查不到。这种 bug 非常难发现，因为表扫描能查到，只有强制走索引时才暴露。
5. 避坑合集：MiniSQL 调试里最常翻车的 5 个现场
在调试这类数据库管理系统源码时，经验往往比能力更值钱。下面这五个问题出现的概率极高，每一条我都用“现象、原因、解决办法”三段式记录，方便快速对照。
5.1 复现：写进去的数据读出来是乱码，且越界崩溃
现象：插入一条含 char 字段的记录，再 SELECT 出来，字符串尾部出现一串不可见字符；当字符串长度接近字段上限时，程序偶尔崩溃在 memcpy。
原因：字符串没有填充\0，或者 memcpy 拷贝的长度超过了目标字段长度，直接越界写坏内存。定长 char 字段，写入时长度必须严格限定为min(字符串长度, 字段长度)，超出部分不写。再有是读端问题：读出时按字段长度拷贝到临时缓冲区，但临时缓冲区没有多留一个字节放结束符，构造std::string时读到缓冲区末尾后面继续读。
解决：写入时统一先memset整个字段区域为 0，再拷贝。读出时分配length + 1个字节，强制在buf[length] = '\0'。字符串比较用strncmp或转成std::string再比较，不能用strcmp，因为填充的\0可能让比较提前结束。
5.2 复现：SELECT 语句查询引号内字符时查不到，或查错数据
现象：where name = 'tom'能查到，换成Tom就查不到；或者插入带空格的'li ming'后，按li去查居然也能命中。
原因：比较时用了区分大小写的精确匹配，MiniSQL 一般按大小写敏感处理，这本身不是 bug，问题在词法和语义层的长度裁剪。如果截断逻辑把'li ming的尾部截掉了，索引里存的 key 就变成li，导致后续任何li*前缀都能命中。
解决：先确认词法层读出的字符串是否完整。在解析后不打断点，直接打印 token 的 text 值与长度，肉眼确认引号边界。字符串比较统一走一个函数：先比较长度，再逐字节比较，两处逻辑不要各写各的。
5.3 复现：建了索引，查询却仍然全表扫描，性能上不去
现象：插入几万条记录后，做等值 SELECT 很快，但范围查询非常慢；或者 EXPLAIN 显示没走索引。
原因：执行器代码里根本没有“根据 where 条件判断是否能走索引”的逻辑。很多简易 MiniSQL 只把索引用于唯一性判断，查询还是顺着表文件从头扫到尾。再有一种情况：索引键值用的是字符串，但条件里的字符串没有走索引定义时的比较规则，索引查找路径永远匹配不上。
解决：给执行器加一个条件判断函数：条件字段上有索引，且运算符是=、<、>时，先查 B+树获取一组 RecordId，再按这些 ID 读记录；否则退回表扫描。判断逻辑里要区分主键和普通索引键的边界。
5.4 复现：连续执行大量 INSERT 后，内存占用暴涨，最终 OOM
现象：程序跑 2 万条 INSERT 后内存占用到几个 GB，随后崩溃。检查代码发现索引插入节点用的new，但删除表或关闭数据库时没有逐节点回收。
原因：B+树节点在堆上分配，析构函数只释放了根节点，子节点全部泄漏。更隐蔽的是缓存池（BufferPool）里的页面没有做 LRU 淘汰，新页面不断加入，旧页面永不移除。
解决：给 B+树写一个destroyTree(Node*)的递归删除函数，析构时调用。BufferPool 限定最大页面数，超过后按最近最少使用淘汰，把脏页写回文件。这一步看似无趣，但实验数据一大，没有它程序必崩。
5.5 复现：where 条件的逻辑运算结果不对，and和or混用时查错
现象：where age > 18 or age = 16 and name = 'tom'，按直觉应该是or左边整体和and右边组合，但结果却是两边的条件被平级处理，超出预期。
原因：解析条件表达式时没有考虑运算符优先级。如果不做层级区分，所有布尔运算符按同一优先级从左到右执行，结果必然乱。C++ 里&&优先级高于||，SQL 里and优先级也高于or，解析器必须在递归过程中优先吃掉and。
解决：条件解析拆两层：parseAndExpr()里循环调用parseConditionAtom()，处理单个比较表达式并以and连接；parseOrExpr()里循环调用parseAndExpr()。这样上层先拆or，下层再拆and，优先级自然就对了。
6. 从能跑到可控：回归验证、两个进阶方向和一个收尾技巧
当你把上面这些坑都填平，MiniSQL 源码就算真正拿下了。接下来要做的不只是运行，而是可控地运行。
6.1 用 SQL 脚本做冒烟测试与回归验证
写一个测试脚本，覆盖建表、插入、修改、删除、查询、建索引、删表全部路径。每次改动后跑一遍，只要任何一条 SQL 行为变化，立刻知道改崩了哪里。用一个简单的 bash 循环可批量执行：
# 把测试用例按行写入 test.sql while read -r sql_line; do echo "==> $sql_line" ./minidb --sql "$sql_line" done < test.sql这里比较关键的是，结果对比不要靠人眼，把每条 SQL 的输出重定向到文本文件，再用diff对比上次的运行结果，任何差异都会被精确定位到某一条语句。
6.2 两个进阶方向：事务日志与 ORDER BY
第一个方向是加 WAL（预写日志）机制，插入或删除前先追加一条日志记录，崩溃后回放日志恢复数据，这是数据库管理系统的核心可靠性保证。第二个方向是给 SELECT 的结果做内存排序，实现 ORDER BY，这能让你理解排序在数据库执行引擎里到底在哪个阶段介入，是拿到全部记录后，还是索引扫描过程中同步进行。
6.3 收尾技巧：用随机数构造数据集测索引边界
很多课程设计卡在“数据量一大就崩”，但手边又没有现成大数据集。最平常的解决办法是用 C++ 随机数生成测试数据，循环插入 10 万条记录，每条的键值用均匀分布随机生成。这样能逼出三个问题：索引分裂是否稳定、文件是否无限膨胀、查询是否有性能拐点。养成这个习惯后，遇到任何数据库源码，我都会先写一段随机数灌压脚本，再做功能测试——顺序反过来，往往测不出真实问题。希望这些实战细节帮你在 MiniSQL 源码上少走弯路，把课程设计变成真正的数据库内核入门课。
本文还有配套的精品资源，点击获取
