目录	语言	组件
`chusql-engine/`	Haskell	执行引擎：词法分析与AST、表达式求值、关系代数、内存表、服务端接口
`chusql-storage/`	Rust	存储引擎：磁盘IO、B+树、缓冲池、WAL、崩溃恢复、并发控制
`chusql-web/`	前端	浏览器端管理客户端

架构分层

Haskell部分

作为函数式编程语言，从语言层面契合SQL语句解析和代数数学运算，同时有强大的类型安全系统。

SQL词法分析、AST
语义分析：表/列存在性与类型检查（执行前的关卡）
事务处理
查询优化、内存表管理
关系代数运算
服务端接口与请求相应

Rust部分

高性能、内存安全且具有强大并行异步编程能力的现代编程语言。

磁盘IO
B+树、页面管理
缓冲池
WAL
事务日志和崩溃恢复
并发控制

前端部分

前端部分目前还没想好选型架构，暂且使用简单前端三件套做一个简单的仿CLI WebUI即可。后期可能会加上Rust编写的CLI前端

Rust和Haskell部分的通信通过管道实现，后期跨平台到Linux后使用Unix Domain Socket

如果找到了较好的Rust+Haskell集成方法也会及时替换

性能基准

三个基准，各管一件事，主基准是全链路（Haskell 引擎和 Rust 存储进程一起启动，跑真实情景）：

基准	位置	测什么
全链路	`benchmark/fullchain/`	SQL 文本 → 引擎 → 命名管道 → Rust → WAL/堆表/索引 → 落盘，整条路
查询层	`benchmark/chusql-engine/`	只用内存数据，隔离出优化器与连接算法的效果
存储层	`benchmark/chusql-storage/`	Rust 侧页 IO / B+ 树 / 堆表 / WAL 的微基准

全链路：Haskell + Rust 一起跑

cd chusql-storage && cargo build --release     # 先编译存储进程（找不到 release 会用 debug 并提醒你）
cd benchmark/fullchain
stack run chusql-fullchain                     # 默认 users = orders = 200
stack run chusql-fullchain -- 1000 1000        # 换规模
# 改过 chusql-engine 源码之后，先 stack build --force-dirty 再跑（原因见"计时怎么做"的坑四）

它做的事：造一个临时数据目录和独立管道名 → 起 Rust 存储进程 → 用引擎的 IPC 存储连上去 → 按真实情景跑一遍（建表、逐条 INSERT、全表 SELECT、过滤、JOIN、按主键点查）→ 校验行数 → 收摊。

每条语句都是整条链路：SQL 文本真的要过词法/语法分析、语义检查、关系代数，再走管道到 Rust，经 WAL（fsync）、堆表、B+ 树、页缓冲池落到磁盘，结果再原路返回。计时用墙上时钟（单调时钟），不是 CPU 时间——这条链路大部分工夫花在等 IO 和跨进程往返上。

实测（每条语句平均耗时）

指标	200 × 200	500 × 500	1000 × 1000
单条 `INSERT`（整条语句）	2.66 ms	2.86 ms	2.88 ms
同一条 `INSERT`（原始 IPC，不经引擎）	2.50 ms	2.85 ms	2.77 ms
多行 `INSERT`（100 行/条）	—	—	0.059 ms/行
`SELECT * FROM users`	0.4 ms	1.0 ms	1.9 ms
`SELECT name FROM users WHERE age > 90`	0.3 ms	0.8 ms	2.7 ms
`SELECT ... JOIN ... WHERE`	0.9 ms	2.4 ms	5.3 ms
`SELECT name FROM users WHERE id = k`	0.2 ms	0.2 ms	0.2 ms
`DELETE FROM users WHERE id = k`（删 1 行）	—	—	4.8 ms
`DELETE FROM users`（删全部 1000 行）	—	—	20.2 ms
`SELECT ... WHERE code = k`（无索引 → 建索引后）	—	—	1.8 ms → 0.2 ms

四条结论：

写入是 fsync 说了算，和数据量无关。 单条 INSERT 约 2.7 ms。能单独量出来的落盘成本约 1.0 ms （写日志 0.43 + 清日志 0.42 + 表数据 flush 0.15），其余是这几次同步落盘之间的等待和跨进程往返。表从 200 行长到 1000 行，单条耗时基本不动——插一行和插一千行的落盘代价几乎一样。所以想快就得多行一起提交：VALUES (...), (...), ... 一条语句 100 行，每行 2.88 ms → 0.059 ms（约 49 倍）。
点查是 O(1)。 按主键查一行 0.2 ms（其中原始 IPC 索引查找 0.07 ms），1000 行时仍是 0.2 ms。建在别的列上的索引也一样：WHERE code = k 从 1.8 ms（没有索引，退回扫描）降到 0.2 ms。
删除的代价和"删几行"无关了。 删 1 行 4.8 ms、删全部 1000 行 20.2 ms：前者就贵在一次全表扫描 + 一次落盘，后者是同一笔扫描加上 1000 次 O(1) 的行级删除。改之前，删 1 行也要把整张表重写一遍并重建整棵索引。
单表查询与那张表的行数成正比（1000 行 1.9 ms，约 2 µs/行）。查询层现在的设计是把表拉进内存算，这个数字就是"拉 1000 行过管道 + 在内存里过一遍"的价钱。

P2 这一版改了什么

四件事，都对应"把整表操作换成行级/批量操作"：

① 行级 DELETE。 B+ 树加 delete（惰性删除：只摘叶子里的键，不合并节点）；堆表把槽位长度置 0（读侧本来就把"长度 0"当作没有这一行）；查询层的 DELETE 改成 "扫一遍算出要删哪些 id → delete_keys 一次删掉"，不再 replaceAll 重写整表。
② 多索引 + CREATE INDEX + 规划器选路。 优化器把"单列等值条件"标成点查节点 Lookup 别名表列值；到底有没有索引由存储层回答——没有就回 no_index，查询层退回全表扫描。这样索引元数据只存在数据字典一处，加索引不用改优化器。边界写在下面：只支持单列整数索引，而且索引列必须唯一。
③ 批量插入。 语法支持 INSERT INTO t (...) VALUES (...), (...), ...：一条语句走一次 WAL、一次 fsync。
④ 列统计。 数据字典里每列记"不同值个数"（内存里按值哈希精确维护，上限 4096 之后转下界），随 catalog.json 落盘，启动时扫一遍表重建，所以重启后数字仍然准；插入/删除实时更新。

一个必须讲清楚的取舍：索引列必须唯一

原来的索引只服务 id，"唯一"是默认成立的前提。要做通用索引就必须回答一个问题： 一个列上有重复值时，"走索引取一行"和"全表扫一遍再筛"还能得到同一个答案吗？ 现在不能——索引的每个键只放得下一个行位置。所以这一版的规则是：

建索引时查重，有重复值就报错、不建（不留半成品）；
索引列上插入重复值会被拒绝（老代码是"覆盖索引条目"，那会让老行再也查不到）。

真正的解法是让 B+ 树支持重复键（键后面带上行号，再做叶子链上的范围扫描），那要把 B+ 树的 i64 定长键换成内存可比较的变长字节键——和"复合键"是同一块地基，留到单独一轮做。这条限制记在根 README 和 projectplan.txt 里，不是忘了。

顺带修掉一个旧 bug：点查节点原来会把别名前缀丢掉，于是 SELECT u.name FROM users u WHERE u.id = 1 取不到列（投影按 u.name 找，回来的行却是 name）。现在 Lookup 也带着别名，回来的一行和 Scan 别名表 长得一样，并且补了对照测试。

全链路这一版改了什么：别再为语义检查搬整个库

原来的 runStatementM 每条语句都先取一次整库快照（把所有表的所有行都拉过管道），只为了给语义检查看列名。可是语义检查（Semantic.check）和查询优化（relOpCols）只看列，一行数据都不碰，行数据是白搬的——而且每条语句都搬一次，于是单条语句的开销随库变大而线性增长。

改法：给 MonadStorage 加一个 schema（只要表结构，不要行），默认实现退化成"快照 + 抹掉行", IPCStorage 覆盖成"只问数据字典要结构"（一次 list_catalog 往返，约 0.07 ms），Engine.runStatementM 改用它。

1000 × 1000 下的效果：

指标	改前	改后	倍率
`INSERT INTO users`	3.65 ms	2.67 ms	1.4x
`INSERT INTO orders`	5.61 ms	2.91 ms	1.9x
`SELECT * FROM users`	6.7 ms	2.0 ms	3.4x
`SELECT ... WHERE age > 90`	6.6 ms	1.7 ms	3.9x
`SELECT ... JOIN ... WHERE`	11.2 ms	4.0 ms	2.8x
`SELECT ... WHERE id = k`	3.3 ms	0.2 ms	16x

改完之后单条 INSERT 的耗时和"原始 IPC 插入"持平（2.67 vs 2.68 ms）—— 引擎侧的每条语句开销已经小到量不出来，剩下全是存储层的落盘成本。

查询层：等值连接改成哈希表

Join 原来是"两边两两配对再筛"：25 万对，每对拼一次行、按列名查两次值，单对约 0.66 µs，乘起来就是 165 ms 上下——这正是下表"未优化"那一列的全部耗时。现在条件是 a = b 这种两列等值时，先拿右表建哈希表、再拿左表逐行探测，配对次数降到 1000 次哈希查找；认不出等值键时自动退回嵌套循环，输出顺序与原来完全一致。

数据规模 users / orders 各 500 行（配对 25 万对），中位数，单位 ms：

查询	结果行数	改前未优化	改后未优化	改前优化后	改后优化后
`JOIN` + `WHERE u.age > 90`	45	110.4 ms	0.267 ms	8.9 ms	0.30 ms
`JOIN`（无 WHERE，只有投影）	500	135.7 ms	0.397 ms	111.3 ms	0.549 ms
`JOIN` + `WHERE` + `ORDER BY` + `LIMIT 10`	10	130.9 ms	0.336 ms	9.2 ms	0.320 ms
单表 `WHERE age > 90`（对照组）	45	0.095 ms	0.084 ms	0.149 ms	0.13 ms

连接类查询约 300 倍；换成 2000 行 / 400 万对时是 500~900 倍（嵌套循环是 O(左 × 右)，哈希连接是线性，规模越大省得越多）。

需要注意：表里"优化器开/关"的比值从原来的 12~17 倍降到了 1.0 倍左右—— 不是优化器变差了，是分母变了：原来那十几倍几乎全来自"条件把配对次数从 25 万筛到 2.25 万"，而连接本身只要 0.4 ms 之后，下推省下的时间已不占主导。看性能要看绝对耗时，不是比值。

存储层：写入路径

单条 INSERT 的完整流程（清 WAL → 写 WAL → 改数据 → 落盘 → 清 WAL）原来约 3.8 ms，现在约 2.5 ms：

WAL 文件句柄常驻：原来每条操作要 open/close 三次，而 append 模式下开完再 fsync 比看起来的 open 更贵；实测单次追加 990 µs → 507 µs。
写前那次清空只截断、不单独 fsync：紧跟其后的 append 会 fsync，那一次会把截断一起落下去。这一项从 522~600 µs 降到 11.6 µs。

写入路径的瓶颈是 fsync 次数，不是数据量。剩下的时间基本都是"真落盘"，而这是 WAL 语义要求的：再往下压就要动"每条操作都截断 WAL"这个设计本身（真正的数据库是顺序追加 + 检查点，而不是写一条清一次）。

其余微基准（n = 2000）：页顺序写 15~~17 µs/页（含 flush）、页顺序读 4.1~~4.5 µs/页、 B+ 树插入 17.9 µs/次、点查 14.8~16.1 µs/次、堆表扫描 0.5 µs/行。

计时怎么做（四个坑都踩过了）

坑一：Haskell 是惰性的，不强制求值就等于没测。 只写 let r = evalRelOp db plan，r 根本没被算出来，测到的是"定义一个变量"的时间。所以每次必须把结果算到底（项目里是逐行把列数累加起来当校验和，或者把行数 evaluate 出来）。

坑二：Windows 上 CPU 时钟的精度只有约 15.6 毫秒。 毫秒级的用例直接测会得到 0.0 ms 这种没意义的数字。查询层基准用自适应批量（同一用例连跑 k 次，k 翻倍到一批超过 0.3 秒再折算成单次），把时钟误差摊薄；全链路基准因为是 IO 密集、单次就有毫秒级，直接用墙上单调时钟。

坑三：机器会漂移。 同一份代码、同一天、前后隔半小时，指标能整体差 15~25%（温度、后台进程都算）。所以：改前改后必须同一时段交叉测；小于 2 倍的差异，没交叉验证之前不要当结论。

坑四（本项目的专属坑）：小心链到旧引擎。 benchmark/fullchain 和 chusql-engine 在同一个 stack 项目里，改完引擎源码后 stack 有时不会把依赖库重新拷进基准项目的安装目录——于是你测的是旧引擎，而且数字看起来"合理"。改过引擎就先 stack build --force-dirty。 （这一条是实测踩出来的：一次"改动没效果"的排查，最后发现是引擎库的时间戳比源码还旧。）

试过但没留下的（别重复踩）

想法	结果	结论	为什么
给 Haskell 库加 `-O2`	加完 8 项全部慢 15~25%；去掉后重建再测，一样慢	已回退	这次"变慢"是机器漂移，不是 `-O2` 造成的——但回退后也没测出 `-O2` 的好处。结论：没有证据，要么同轮交叉测再下判断，要么别加
换掉缓冲池的 `min_by_key` 淘汰	池 1024 / 工作集超池：随机读 7.9 µs vs 池 16：5.1 µs	未做	差距是真的（缺页时多扫 1024 个候选页），但只影响"工作集大于池"的随机读，绝对量 ~2.8 µs/次；而写入路径是 2500 µs/次，不在一个量级
把投影下推进 `Scan`（Scan 自带列清单）	未做	待定	能消掉"无 WHERE 的 JOIN"多出来的那趟投影（约 25%，0.1 ms 级），但要改 `RelOp` 类型、`relOpCols`、Eval 和一堆测试
非唯一索引（一个键多条记录）	未做	待定	要 B+ 树允许重复键（键后面带行号）+ 叶子链上的范围扫描；和"复合键"共用同一块地基：键从 `i64` 定长槽位改成内存可比较的变长字节键
只给索引加"唯一"检查、不改插入语义	未做	已否	那样建索引时唯一、之后插重复值仍会把老行"挤"出索引，查询结果就和全表扫不一致了——宁可插入时报错

怎么加用例

全链路：在 benchmark/fullchain/src/Main.hs 的 runScenarios 里加 benchSql label sql 就行；要验证结果就照着 [校验] 那一段写断言（现在的两个校验是 age > 90 的行数和 JOIN 的行数）。
查询层：在 benchmark/chusql-engine/src/Main.hs 的 queries 列表里加一条 SQL 字符串，其余全自动（自动翻译、优化、跑两遍、比结果、算加速比）。
存储层：在 benchmark/chusql-storage/benches/storage.rs 里加一段 bench(...) / bench_once(...)。

想在文档里引用数字，记得把数据规模、机器、时间一起写上——脱离这些谈"快了几倍"没有意义。

最近更新：2026-09-25

README.md Unescape Escape

ChuSQL

仓库布局