db-foundation-course

name: db-foundation-course description: 编写"数据库筑基课"文章的专用 Skill，面向数据库架构师、DBA 和业务开发者。输入一个筑基课文章标题及相关参考资料（技术文档、产品手册、开源项目地址、deepwiki、论文等），输出图文并茂、结构完整的 Markdown 筑基课文章，保存至项目 markdown/ 目录。适用主题覆盖：表存储结构（heap/parquet/arrow/zedstore/LSM-Tree/HStore等）、索引结构（btree/gin/brin/hnsw/ivfflat/bloom等）、数据类型与操作符（vector/jsonb/tsvector/range/array等）、优化器扫描算法（seq scan/index scan/bitmap scan/join/agg/并行等）、场景化实践（时序/GIS/RAG/全文检索/图数据/数据湖等）以及事务/锁/并发/安全等周边主题。只要用户提及"筑基课"、"数据库原理"、"数据库内核"写作，或给出了数据库存储/索引/扫描相关的技术文档让你写成教程，都应使用此 Skill。

数据库筑基课 Skill

核心目标：让数据库架构师、DBA、业务开发者学完每篇筑基课后，能将知识直接用于工作实践，打下坚实基础。

一、工作流程总览

输入: 文章标题 + 参考资料(URL / 文档 / 论文 / 代码仓库)
  │
  ├─ Step 1: 读取参考资料
  ├─ Step 2: 按"标准文章结构"起草提纲
  ├─ Step 3: 逐节撰写内容（含图表、代码、示例）
  ├─ Step 4: 自检（逻辑 / 代码 / 事实）
  └─ Step 5: 输出 Markdown 文件 → markdown/<slug>.md

二、标准文章结构（模板）

每篇筑基课文章必须包含以下 12 个章节，可根据主题适当增减子节：

# 数据库筑基课 - <标题>

> 所属系列: [数据库筑基课大纲](链接)  
> 难度: ★☆☆ / ★★☆ / ★★★  
> 适合角色: 架构师 / DBA / 业务开发者

---

## 0. 导读（Why Read This）
## 1. 背景与痛点（Background & Pain Points）
## 2. 核心原理（Core Principles）
## 3. 数据结构 / 存储格式 / 算法详解（Deep Dive）
## 4. 优势与适合场景（Strengths & Use Cases）
## 5. 劣势与不适合场景（Weaknesses & Anti-Patterns）
## 6. 竞品 / 横向技术对比（Comparison）
## 7. 实操与最佳实践（Hands-on & Best Practices）
## 8. 性能调优（Performance Tuning）
## 9. 思考与边界（Thinking & Boundaries）
## 10. 常见问题（FAQ）
## 11. 扩展阅读（Further Reading）

三、各章节撰写指南

§ 0 导读

• 一句话点明本文解决什么问题
• 给出"读完本文你能做到什么"的 3 条 bullet

§ 1 背景与痛点

• 说明技术/功能出现前的痛苦场景（具体，有数字）
• 用对比图或叙事说明"没有它时有多难"
• 可画 mermaid 时序图 / 流程图表达痛点

§ 2 核心原理

• 先用一张总览图（mermaid / SVG / text diagram）展示整体架构
• 然后逐层展开
• 原理说明时配合类比（例如 heap 的 fsm 就像"停车场空位管理牌"）

§ 3 深度解析

根据主题选择合适的子节，参考如下分类：

存储结构类（heap/parquet/arrow/zedstore/LSM等）

• file layout（文件级结构）→ block/page layout（块级结构）→ tuple/record layout（行级结构）
• 写入流程 / 读取流程 / 更新流程 / 删除流程
• 垃圾回收 / 压缩 / Compaction
• 索引与存储的协同

索引结构类（btree/gin/brin/hnsw/bloom等）

• 索引构建算法
• 索引 page/node 的内部结构
• 搜索算法（贪婪/二分/图遍历等）
• 索引维护（插入/删除/分裂/合并）

扫描与计算类（seq scan/index scan/join/agg/并行等）

• 算法伪代码 or 流程图
• 代价模型（cost model）简介
• 执行计划解读（EXPLAIN 输出示例）

数据类型类（vector/jsonb/tsvector等）

• 内部存储表达
• 支持的操作符与函数
• 索引配合使用

§ 4 优势与适合场景

• 用表格列出：场景 → 为什么适合 → 典型案例

§ 5 劣势与不适合场景

• 明确说明边界：什么情况会变慢 / 出问题 / 不应使用
• 给出替代方案

§ 6 竞品/横向对比

• 至少对比 2～3 个同类技术，使用 Markdown 表格
• 维度：性能 / 压缩比 / 写入/读取模式 / 事务支持 / 生态 / 适用场景

§ 7 实操与最佳实践

• 给出可运行的 SQL 或代码示例
• 至少 1 个完整的场景化 Demo（建表→写入→查询→分析）
• 列出 DBA 常用的监控/诊断 SQL
• 标注关键 GUC 参数及推荐值

§ 8 性能调优

• 调优思路：从 EXPLAIN → 瓶颈定位 → 参数/DDL 调整
• 列出 TOP 5 调优手段

§ 9 思考与边界

• 给出 2～3 个"扩展问题"（类似原文的"扩展问题"章节）
• 每个问题都给出分析过程，不只给答案
• 点明该技术的本质取舍（trade-off）

§ 10 FAQ

• 至少 5 条，Q&A 格式

§ 11 扩展阅读

• 分类列出：官方文档 / 论文 / 源码路径 / 博客 / 相关筑基课章节

四、图表规范

4.1 优先使用 mermaid（流程 / 关系 / 时序）

graph TD
    A[Client] --> B[Buffer Pool]
    B --> C{命中?}
    C -- Yes --> D[直接返回]
    C -- No --> E[从磁盘读取 Block]

4.2 存储结构用 text diagram（清晰表达 layout）

File Layout:
┌─────────────────────────────────┐
│  Block 0  │  Block 1  │  ...    │
│  (8KB)    │  (8KB)    │         │
└─────────────────────────────────┘

Block Layout:
┌──────────────┬────────────────────────┐
│  Page Header │  Line Pointers (lp[])  │
├──────────────┴────────────────────────┤
│         Free Space                    │
├───────────────────────────────────────┤
│  Tuple N  │ ... │  Tuple 2  │ Tuple 1 │
└───────────────────────────────────────┘

4.3 对比用 Markdown 表格

4.4 SVG（复杂的多层结构，如 HNSW 图）

在确实需要 SVG 时，使用简洁的 <svg> 内联图，宽度限制在 700px 以内。

五、代码示例规范

-- 【示例】创建 heap 表并观察存储结构
CREATE TABLE tbl_demo (
    id    BIGSERIAL PRIMARY KEY,
    name  TEXT,
    score FLOAT
) WITH (fillfactor = 80);

-- 插入测试数据
INSERT INTO tbl_demo (name, score)
SELECT 'user_' || g, random() * 100
FROM generate_series(1, 100000) g;

-- 查看物理文件路径
SELECT pg_relation_filepath('tbl_demo');

-- 查看 block 内容（需要 pageinspect 插件）
SELECT * FROM heap_page_items(get_raw_page('tbl_demo', 0)) LIMIT 5;

• 代码块必须标注语言（sql / bash / python / json）
• 关键行加注释
• 示例数据量适中（不超过百万行，能快速运行）

六、自检清单（输出前必须核对）

在生成最终文件前，逐项检查：

□ 文章结构是否覆盖了 12 个标准章节（允许合并，不允许缺失关键章节）
□ 每个技术概念是否有对应的图示（layout/流程图/对比表）
□ 所有 SQL / 代码示例是否语法正确（逐行检查关键字、括号、引号）
□ 核心原理是否有"类比"帮助理解
□ 对比章节是否客观（不只夸自己，要说出竞品优势）
□ 边界/不适合场景是否明确
□ 扩展阅读的链接格式是否正确
□ 文件名格式是否符合 <YYYYMMDD>_<slug>.md
□ 文章开头是否有"所属系列"链接 和 "难度/角色"标注

七、文件命名与保存

# 目录: markdown/
# 命名: YYYYMMDD_<topic-slug>.md
# 示例:
markdown/20240919_heap-storage.md
markdown/20241015_parquet-columnar.md
markdown/20250624_hnsw-vector-index.md

保存完毕后，输出：

1. 文件的绝对路径
2. 文章的章节目录（TOC）
3. 3 条"读完本文你将掌握"的收益说明

八、主题速查表（常用参考）

九、参考资料获取策略

当用户提供的参考资料为 URL 时：

1. 使用 web_fetch 获取完整内容
2. 如果是 GitHub/DeepWiki 地址，重点关注 README、核心源码注释、设计文档
3. 如果是论文，重点提炼：摘要 → 核心贡献 → 关键算法 → 实验结论
4. 整理成内部知识后按标准结构输出

十、示例输出片段（heap 文章节选）

## 1. 背景与痛点

数据库最基础的问题：**一条记录写到哪里？怎么找回来？**

在 heap 之前，如果要自己实现存储，可能会想到顺序存文件——但这样读一条记录需要扫全表。
heap 的设计解决了三个核心问题：

| 问题           | heap 的解法            |
|--------------|----------------------|
| 写到哪里？      | FSM 快速找空闲 block    |
| 怎么定位一行？  | ctid = (blockNum, lp) |
| 怎么回收空间？  | vacuum + autovacuum   |

## 2. 核心原理

### 整体架构

​```
Table Files:
  main:  tbl.1, tbl.2, ...   ← 数据文件（每个最大 1GB）
  fsm:   tbl_fsm              ← 空闲空间图（Free Space Map）
  vm:    tbl_vm               ← 可见性图（Visibility Map）
​```

### Block 内部结构

​```
┌─────────────────────────────────────────┐  ← Block（默认 8KB）
│  PageHeaderData (24B)                   │
│  lp[1] lp[2] lp[3] ...  lp[N]         │  ← Line Pointers（4B each）
│                                         │
│  ← Free Space →                         │
│                                         │
│  Tuple 3    Tuple 2    Tuple 1          │  ← 从尾部向前增长
└─────────────────────────────────────────┘

ctid = (BlockNum, lp_index)
例：ctid=(0,1) 表示第0块，第1条记录
​```

以上即为"数据库筑基课"Skill 的完整指南。 每次生成文章后，务必运行自检清单，确认内容逻辑正确、代码可运行，再保存文件。