为什么一个开发者会想要自己动手写一个数据库这听起来像是只有数据库内核团队才会做的事。但如果你深入思考一下会发现这背后隐藏着巨大的价值当你亲手实现一个最简单的键值存储时你才能真正理解 ACID、B树、WAL预写式日志这些概念是如何从一行行代码中“长”出来的而不是停留在书本上的名词。很多开发者在使用 MySQL、PostgreSQL 时对索引、事务隔离级别、锁机制的理解是模糊的。遇到慢查询只能机械地加索引遇到死锁只能重启应用。这种“黑盒”式的使用让很多性能优化和问题排查变成了玄学。而“从零写数据库”这个项目正是打破这种黑盒认知的最佳实践。它不是为了替代生产级的数据库而是为了给你一把打开数据库内核世界的钥匙。本文将带你从零开始用大约 500 行左右的代码实现一个具备基础 CRUD、持久化到磁盘、简单事务支持的内存键值数据库。我们将从最核心的数据结构设计开始一步步实现存储引擎、序列化、网络层可选并最终让它能响应简单的 SQL 命令。读完本文你将不仅获得一个可以运行的玩具数据库更重要的是你将建立起对数据库核心组件工作方式的直观理解未来在面对任何数据库相关问题时都能从原理层面进行思考。1. 我们到底要解决什么问题从“用户”到“创造者”的认知跃迁在开始写代码之前我们必须明确这个项目的目标。它不是为了追求性能或功能完备性而是要解答以下几个核心问题数据如何持久化内存中的数据如何在程序重启后不丢失这就引出了“存储引擎”的概念。我们会实现一个最简单的追加日志Append-Only Log和内存索引。如何快速查找数据如果每次查询都扫描整个文件效率是 O(N)。我们需要引入索引数据结构。这里我们会实现一个最经典的B树的简化版来理解多级索引和磁盘页的概念。什么是事务原子性Atomicity、一致性Consistency、隔离性Isolation、持久性Durability这 ACID 四特性在代码层面如何体现我们将通过预写式日志WAL来实现最基本的原子性和持久性。客户端如何与服务器通信我们将设计一个简单的文本协议类似 Redis 的 RESP 或自定义协议并实现一个网络服务层。通过亲手解决这些问题你将完成从数据库“用户”到“创造者”视角的转变。下次当你执行BEGIN TRANSACTION时你脑子里浮现的将不再是魔法而是日志文件的刷盘操作。2. 核心概念与架构设计我们的微型数据库取名MiniDB。在动手前先勾勒出它的核心架构。----------------------- | Client (CLI) | ---------------------- | (Text Protocol, e.g., SET key value) ----------v------------ | Network Server | (可选初期可先做嵌入式) | (TCP Socket, 解析协议) | ---------------------- | ----------v------------ | Query Parser | (解析 SET, GET 等命令) ---------------------- | ----------v------------ | Storage Engine | -- 核心 | ------------------ | | | In-Memory Index| | (例如HashMap 或 BTree) | | (key - value) | | | ------------------ | | | Disk Storage | | (追加日志文件 data.log) | | (Append-Only Log)| | | ------------------ | -----------------------核心组件解释存储引擎Storage Engine数据库的心脏。负责数据的存储、检索和管理。我们的设计采用经典的LSM-TreeLog-Structured Merge-Tree思想简化版内存表MemTable一个有序的内存数据结构如跳表或红黑树用于缓存最新的写入操作提供快速的读取。预写日志WAL一个只追加Append-Only的文件。任何写入操作在应用到内存表之前必须先持久化到 WAL 中。这是保证持久性Durability和崩溃恢复的关键。静态排序表SSTable当内存表大小达到阈值时将其冻结并异步刷写到磁盘形成一个不可变的、排序的键值对文件。多个 SSTable 文件通过后台合并Compaction来清理过期数据。网络层/协议负责与客户端通信。为了简单我们初期可以跳过网络先做一个嵌入式的库通过函数调用操作。后期可以增加一个简单的 TCP 服务器使用类似 Redis 的SET key value文本协议。查询解析与执行解析客户端发来的命令如GET,SET,DELETE并调用存储引擎的相应接口。技术选型编程语言本文以Go语言为例。Go 的简洁性、强大的标准库和并发原语非常适合此类系统编程。当然你也可以用 Java、Python、Rust 等实现原理相通。核心数据结构内存索引初期使用标准库的map后期为了引入范围查询和有序性可以替换为B树或跳表Skip List。3. 环境准备与项目初始化确保你的开发环境已就绪。3.1 安装 Go访问 golang.org 下载并安装 Go版本 1.16 即可。安装后在终端验证go version3.2 创建项目目录mkdir minidb cd minidb go mod init github.com/yourusername/minidb3.3 项目结构规划创建以下目录和文件这是一个清晰的项目布局minidb/ ├── go.mod ├── main.go # 程序入口CLI或服务器 ├── storage/ │ ├── engine.go # 存储引擎接口定义 │ ├── memory.go # 内存表MemTable实现 │ ├── wal.go # 预写日志WAL实现 │ └── sstable.go # SSTable 实现进阶 ├── protocol/ │ └── parser.go # 命令解析器 └── cmd/ └── client.go # 简单的测试客户端可选4. 第一步实现存储引擎核心 - 内存表与 WAL让我们从最核心的存储引擎开始。先实现一个带 WAL 的简单内存键值存储。4.1 定义存储引擎接口 (storage/engine.go)接口定义了引擎对外提供的能力。// storage/engine.go package storage // Engine 存储引擎接口 type Engine interface { // Put 写入键值对 Put(key, value []byte) error // Get 读取键对应的值 Get(key []byte) ([]byte, error) // Delete 删除键标记删除 Delete(key []byte) error // Close 关闭引擎释放资源 Close() error }4.2 实现内存表 (storage/memory.go)内存表是存储在内存中的有序结构。初期我们用sync.Map保证并发安全但它无序。为了后续支持范围查询这里我们使用github.com/google/btree包来实现一个有序的内存表。先安装这个包go get github.com/google/btree// storage/memory.go package storage import ( bytes github.com/google/btree sync ) // Item 代表存储在 BTree 中的键值对 type Item struct { Key []byte Value []byte } // Less 实现 btree.Item 接口用于排序 func (i Item) Less(than btree.Item) bool { return bytes.Compare(i.Key, than.(Item).Key) 0 } // MemTable 内存表 type MemTable struct { mu sync.RWMutex tree *btree.BTree size uint64 // 当前数据大小用于判断是否需要刷盘 } func NewMemTable() *MemTable { return MemTable{ tree: btree.New(32), // 32 是 BTree 的度 } } func (m *MemTable) Put(key, value []byte) { m.mu.Lock() defer m.mu.Unlock() item : Item{Key: key, Value: value} // 如果 key 已存在Replace 会替换旧值 if old : m.tree.ReplaceOrInsert(item); old ! nil { // 更新 size减去旧值大小加上新值大小 m.size - uint64(len(old.(Item).Value)) } m.size uint64(len(key) len(value)) } func (m *MemTable) Get(key []byte) ([]byte, bool) { m.mu.RLock() defer m.mu.RUnlock() item : m.tree.Get(Item{Key: key}) if item nil { return nil, false } return item.(Item).Value, true } func (m *MemTable) Delete(key []byte) { // 在 LSM-Tree 中删除是一个标记。我们插入一个 value 为 nil 的项作为墓碑标记。 m.Put(key, nil) } func (m *MemTable) Size() uint64 { m.mu.RLock() defer m.mu.RUnlock() return m.size }4.3 实现预写日志 WAL (storage/wal.go)WAL 是保证数据不丢失的关键。任何写入操作必须先成功追加到 WAL 文件才能应用到内存表。// storage/wal.go package storage import ( encoding/binary os sync ) // WALEntry 表示 WAL 中的一个条目 type WALEntry struct { Op byte // 操作类型0-Put, 1-Delete KeyLen uint32 ValueLen uint32 Key []byte Value []byte } type WAL struct { file *os.File mu sync.Mutex offset int64 // 当前写入偏移量 } func OpenWAL(path string) (*WAL, error) { file, err : os.OpenFile(path, os.O_RDWR|os.O_CREATE|os.O_APPEND, 0644) if err ! nil { return nil, err } stat, _ : file.Stat() return WAL{file: file, offset: stat.Size()}, nil } // WriteEntry 将一条记录追加到 WAL func (w *WAL) WriteEntry(entry *WALEntry) error { w.mu.Lock() defer w.mu.Unlock() buf : make([]byte, 144len(entry.Key)len(entry.Value)) pos : 0 buf[pos] entry.Op pos binary.BigEndian.PutUint32(buf[pos:], entry.KeyLen) pos 4 binary.BigEndian.PutUint32(buf[pos:], entry.ValueLen) pos 4 copy(buf[pos:], entry.Key) pos len(entry.Key) copy(buf[pos:], entry.Value) // pos len(entry.Value) // 不需要再移动 pos _, err : w.file.Write(buf) if err nil { w.offset int64(len(buf)) // 通常需要调用 Sync 来确保数据落盘这里为了性能可以先不调用风险是崩溃可能丢失最后一条记录。 // w.file.Sync() } return err } // ReadEntries 从 WAL 文件头开始读取所有记录用于崩溃恢复 func (w *WAL) ReadEntries(callback func(*WALEntry) error) error { w.mu.Lock() defer w.mu.Unlock() // 移动到文件开始 if _, err : w.file.Seek(0, 0); err ! nil { return err } for { header : make([]byte, 144) // Op KeyLen ValueLen n, err : w.file.Read(header) if err ! nil || n ! len(header) { // EOF or error break } entry : WALEntry{} entry.Op header[0] entry.KeyLen binary.BigEndian.Uint32(header[1:5]) entry.ValueLen binary.BigEndian.Uint32(header[5:9]) kvBuf : make([]byte, entry.KeyLenentry.ValueLen) n, err w.file.Read(kvBuf) if err ! nil || uint32(n) ! entry.KeyLenentry.ValueLen { break // 文件损坏 } entry.Key kvBuf[:entry.KeyLen] entry.Value kvBuf[entry.KeyLen:] if err : callback(entry); err ! nil { return err } } return nil } func (w *WAL) Close() error { return w.file.Close() } // Reset 清空 WAL通常在 MemTable 成功刷写到 SSTable 后调用 func (w *WAL) Reset() error { w.mu.Lock() defer w.mu.Unlock() if err : w.file.Truncate(0); err ! nil { return err } if _, err : w.file.Seek(0, 0); err ! nil { return err } w.offset 0 return nil }5. 组装存储引擎整合 MemTable 与 WAL现在我们创建一个结构体来实现Engine接口它内部组合了 MemTable 和 WAL。// storage/engine_impl.go package storage import ( errors path/filepath ) const ( OpPut 0 OpDelete 1 ) // MiniDBEngine 是存储引擎的具体实现 type MiniDBEngine struct { mem *MemTable wal *WAL dataDir string // 后续可以添加immutable MemTables, SSTables 列表等 } func Open(dataDir string) (*MiniDBEngine, error) { if err : os.MkdirAll(dataDir, 0755); err ! nil { return nil, err } walPath : filepath.Join(dataDir, wal.log) wal, err : OpenWAL(walPath) if err ! nil { return nil, err } engine : MiniDBEngine{ mem: NewMemTable(), wal: wal, dataDir: dataDir, } // 启动时恢复重放 WAL 到内存表 if err : engine.recoverFromWAL(); err ! nil { wal.Close() return nil, err } return engine, nil } func (e *MiniDBEngine) recoverFromWAL() error { return e.wal.ReadEntries(func(entry *WALEntry) error { switch entry.Op { case OpPut: e.mem.Put(entry.Key, entry.Value) case OpDelete: e.mem.Delete(entry.Key) // 在内存中标记删除 } return nil }) } func (e *MiniDBEngine) Put(key, value []byte) error { // 1. 先写 WAL entry : WALEntry{ Op: OpPut, KeyLen: uint32(len(key)), ValueLen: uint32(len(value)), Key: key, Value: value, } if err : e.wal.WriteEntry(entry); err ! nil { return err } // 2. 再更新内存表 e.mem.Put(key, value) // 3. (可选) 检查内存表大小触发刷盘 // if e.mem.Size() threshold { e.flushMemTable() } return nil } func (e *MiniDBEngine) Get(key []byte) ([]byte, error) { value, ok : e.mem.Get(key) if !ok { // 后续需要在这里查询 SSTables return nil, errors.New(key not found) } // 如果 value 是 nil说明这是一个删除标记 if value nil { return nil, errors.New(key not found (deleted)) } return value, nil } func (e *MiniDBEngine) Delete(key []byte) error { // 删除也是写入一个特殊的标记 entry : WALEntry{ Op: OpDelete, KeyLen: uint32(len(key)), ValueLen: 0, Key: key, Value: nil, } if err : e.wal.WriteEntry(entry); err ! nil { return err } e.mem.Delete(key) return nil } func (e *MiniDBEngine) Close() error { // 关闭前可以尝试将内存表刷盘 // e.flushMemTable() return e.wal.Close() }6. 实现命令行接口与测试有了存储引擎我们可以先创建一个简单的命令行程序来测试它。6.1 主程序入口 (main.go)// main.go package main import ( bufio fmt github.com/yourusername/minidb/storage os strings ) func main() { if len(os.Args) 2 { fmt.Println(Usage: minidb data_directory) os.Exit(1) } dataDir : os.Args[1] engine, err : storage.Open(dataDir) if err ! nil { fmt.Printf(Failed to open engine: %v\n, err) os.Exit(1) } defer engine.Close() fmt.Printf(MiniDB started. Data directory: %s\n, dataDir) fmt.Println(Commands: SET key value, GET key, DEL key, EXIT) scanner : bufio.NewScanner(os.Stdin) for { fmt.Print(minidb ) if !scanner.Scan() { break } line : scanner.Text() parts : strings.Fields(line) if len(parts) 0 { continue } cmd : strings.ToUpper(parts[0]) switch cmd { case SET: if len(parts) ! 3 { fmt.Println(Usage: SET key value) continue } err : engine.Put([]byte(parts[1]), []byte(parts[2])) if err ! nil { fmt.Printf(Error: %v\n, err) } else { fmt.Println(OK) } case GET: if len(parts) ! 2 { fmt.Println(Usage: GET key) continue } val, err : engine.Get([]byte(parts[1])) if err ! nil { fmt.Printf(Error: %v\n, err) } else { fmt.Printf(\%s\\n, string(val)) } case DEL: if len(parts) ! 2 { fmt.Println(Usage: DEL key) continue } err : engine.Delete([]byte(parts[1])) if err ! nil { fmt.Printf(Error: %v\n, err) } else { fmt.Println(OK) } case EXIT: fmt.Println(Bye!) return default: fmt.Println(Unknown command. Use SET, GET, DEL, or EXIT.) } } }6.2 运行与测试编译并运行go build -o minidb main.go mkdir -p /tmp/minidb_data ./minidb /tmp/minidb_data交互测试MiniDB started. Data directory: /tmp/minidb_data Commands: SET key value, GET key, DEL key, EXIT minidb SET name Alice OK minidb GET name Alice minidb SET age 30 OK minidb GET age 30 minidb DEL age OK minidb GET age Error: key not found (deleted) minidb EXIT Bye!验证持久化退出程序后查看/tmp/minidb_data目录会发现一个wal.log文件。这就是我们的预写日志。重新启动程序输入GET name你应该还能看到Alice。数据成功恢复了7. 进阶实现 SSTable 与 Compaction目前所有数据都在内存和 WAL 中内存有限。接下来实现 LSM-Tree 的另一个核心将内存表刷写到磁盘形成 SSTable。7.1 SSTable 文件格式SSTable 是排序的、不可变的键值对集合。一个简单的格式可以是[Entry1][Entry2]...[EntryN][Index][Footer]其中每个 Entry 是KeyLen | ValueLen | Key | Value。Index 是Key | FileOffset的列表用于快速定位。Footer 包含索引的起始偏移量等元数据。7.2 刷写 MemTable 到 SSTable当MemTable.Size()超过某个阈值如 1MB时触发刷写。将当前的 MemTable 标记为“不可变”Immutable MemTable。在一个新的后台 Goroutine 中遍历这个不可变 MemTableBTree 有序将键值对顺序写入一个新的.sst文件。为这个 SSTable 文件在内存中维护一个索引如最小键、最大键、文件路径。刷写完成后清空 WAL 文件因为数据已持久化到 SSTable。7.3 读取流程优化现在的Get只查内存表。修改Get逻辑先查活跃的 MemTable。如果没找到按时间顺序从新到旧查询不可变的 MemTable如果有。如果还没找到则查询磁盘上的 SSTable 文件列表同样从新到旧。查询 SSTable 时先利用内存中的索引判断 key 是否可能在该文件中然后读取文件进行二分查找。7.4 Compaction合并随着 SSTable 文件增多查询会变慢且空间放大。需要后台合并过程将多个旧的、有重叠键范围的 SSTable 合并成一个新的、更大的 SSTable。在合并过程中丢弃被标记删除的键墓碑标记和重复的旧值。合并完成后删除旧的 SSTable 文件。这部分代码量较大但它是理解 LSM-Tree 如何平衡读写和空间放大的关键。实现后你的 MiniDB 就具备了处理远超内存容量数据的能力。8. 常见问题与排查思路在实现和运行 MiniDB 的过程中你可能会遇到以下问题问题现象可能原因排查方式解决方案程序启动失败报“权限被拒绝”数据目录没有写入权限检查dataDir路径的权限 (ls -ld)更改目录权限或换一个可写目录GET一个刚SET的值返回key not foundWAL 写入成功但内存表更新失败或恢复时 WAL 损坏1. 检查Put方法中 WAL 写和内存表写的顺序。2. 检查 WAL 文件是否完整。确保先写 WAL成功后更新内存表。实现 WAL 校验和。程序崩溃重启后部分数据丢失WAL 没有及时调用Sync()操作系统缓存未落盘检查WAL.WriteEntry方法是否在关键操作后调用了file.Sync()在WriteEntry中或定期调用Sync()牺牲一些性能换取更强的持久性。内存占用持续增长不释放MemTable 满了但没有触发刷盘或 SSTable 合并策略有问题1. 检查MemTable.Size()和刷盘阈值。2. 检查 Compaction 逻辑是否正常执行。合理设置刷盘阈值实现并调试 Compaction 后台任务。执行DEL后磁盘空间没有减少LSM-Tree 的删除是标记删除空间在 Compaction 时才回收检查 SSTable 文件是否在合并后删除确保 Compaction 完成后删除旧的 SSTable 文件。范围查询如SCAN性能差内存表使用 HashMap无序或 SSTable 索引不够高效检查内存表和 SSTable 的索引结构将内存表换成有序结构如 BTree为 SSTable 实现稀疏索引。9. 最佳实践与工程建议即使是一个教学项目遵循好的工程实践也能让你收获更多单元测试是必须的为storage包下的每个组件MemTable, WAL, Engine编写单元测试。使用 Go 的testing包。测试覆盖正常流程和边界情况如空值、大键值、并发读写。善用 Go 的并发原语数据库是高度并发的。使用sync.RWMutex保护内存结构使用 Channel 协调后台的刷盘和合并任务。注意避免死锁。配置化将刷盘阈值、SSTable 大小、合并策略等参数提取为配置便于调试和优化。添加度量指标在代码中添加简单的计数器统计读写次数、耗时、内存表大小、SSTable 数量等。这能帮助你理解数据库的行为。实现一个简单的网络服务器将引擎封装成一个 TCP 服务器使用简单的文本协议如SET key value\n。这会让它更像一个真正的数据库。研究现有系统在实现每个功能时去阅读 LevelDB、RocksDB 甚至 SQLite 的文档和设计论文。对比你的设计和它们的选择理解背后的权衡。性能剖析使用 Go 的pprof工具分析瓶颈在哪里。是锁竞争是序列化还是磁盘 I/O通过这个项目你亲手搭建了数据库最核心的存储引擎。你理解了数据如何从内存到磁盘如何通过 WAL 保证持久性以及 LSM-Tree 如何通过追加写和后台合并来优化写性能。这些知识是理解 Redis AOF、Kafka 日志存储、HBase 存储等众多现代存储系统的基石。下一步你可以选择深入任何一个方向实现更高效的 BTree 索引、支持完整的事务MVCC、实现 SQL 解析层、或者尝试用 Raft 协议构建一个分布式版本。每一步深入都会让你对“数据库”这三个字有更深刻的理解。建议将你的代码放到 GitHub 上这是你技术思考最好的证明。