/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 表格

| 特性 | heap(行存) | parquet(列存) | zedstore(行列混存) | |------------|-----------|-------------|-----------------| | OLTP 写入 | ★★★★★ | ★★☆☆☆ | ★★★★☆ | | OLAP 扫描 | ★★☆☆☆ | ★★★★★ | ★★★★☆ | | ... | ... | ... | ... |

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 条"读完本文你将掌握"的收益说明

---

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

| 主题类别 | 典型技术点 | 关联大纲章节 | |------------|------------------------------------------|------------| | 行存 | heap, HOT-update, vacuum, FSM, VM | 一、表组织结构 | | 列存(磁盘) | parquet, orc, lance, vortex | 一、表组织结构 | | 列存(内存) | arrow, monetdb in-memory, DuckDB | 一、表组织结构 | | 行列混存 | zedstore, vops | 一、表组织结构 | | 追加写优化 | LSM-Tree, HStore/HBase | 一、表组织结构 | | 有序存储 | cluster table, 索引组织表 | 一、表组织结构 | | 冷热分层 | Iceberg, Delta Lake, Hudi | 一、表组织结构 | | 传统索引 | btree, hash, bitmap, brin, bloom, gin | 二、索引组织结构 | | 全文索引 | gin+tsvector, BM25, zombodb | 二、索引组织结构 | | 向量索引 | hnsw, ivfflat, pgvectorscale, vectorchord| 二、索引组织结构 | | 特殊索引 | partial/expression/include/global index | 二、索引组织结构 | | 数据类型 | vector, jsonb, tsvector, range, array | 三、数据类型和操作符 | | 扫描算法 | seq/index/bitmap/index-only scan | 四、扫描&计算 | | Join 算法 | nested loop, hash join, merge join | 四、扫描&计算