docusaurus build butdocusaurus start, so the dev server every maintainer runsA developer-oriented handbook for the Cloudberry kernel: storage, indexing, the catalog, the executor (single-node and distributed), the dual optimizer (PostgreSQL planner and ORCA), transactions, HA/recovery, and resource management.
21 chapters and 104 sections, in an introduction plus five parts.
The model is Egor Rogov's PostgreSQL 14 Internals (Postgres Professional, 2022-2023, ISBN 978-5-6045970-4-0, postgrespro.com/community/books/internals) — not its table of contents, which is organised differently, but its method: explain a mechanism by reading the source that implements it and running the system that uses it. That book is copyrighted and carries no licence grant, so nothing here is taken from it: the prose is written from the Cloudberry source, the figures are drawn for this handbook, and the sessions are captured from a running cluster. Two passages in Chapter 3 credit Rogov for a pg_buffercache helper view and for the practice of disabling autovacuum during an experiment.
index.md chapter 1, and the landing page part-2-storage-data-layout/ Part I ch02 .. ch08 part-3-transactions-mvcc-concurrency/ Part II ch09 .. ch12 part-4-query-processing/ Part III ch13 .. ch19 part-5-high-availability-recovery/ Part IV ch20 part-6-resource-management/ Part V ch21 figures/ 64 SVG figures _components/ one MDX component and its stylesheet
Each part directory carries a _category_.json, so the sidebar can be generated from the directory structure. The introduction is a part directory of its own, which is why there are six directories for five parts.
The directory is written for Docusaurus and is intended to be pulled into apache/cloudberry-site the same way the PXF docs are — as a git submodule with a sparse checkout limited to this path, served by its own docs plugin instance with an autogenerated sidebar.
It is self-contained. A site can point a docs plugin at this directory and build, with no component registration and no additions to the site‘s stylesheet; _components/ ships the one component these pages need, each page imports it itself, and the leading underscore keeps the directory out of the plugin’s page routing. Verified by building against a site with an empty customCss that registers nothing.
One optional extra: 113 diagrams are mermaid fenced blocks. A site with @docusaurus/theme-mermaid enabled draws them; without it they degrade to readable code blocks.
Reading the files straight on GitHub mostly works — prose, tables, code excerpts, captured sessions and the mermaid diagrams all render. The 37 figures that are laid out in HTML rather than drawn as SVG do not: they are written as an MDX component, which GitHub shows as literal markup.
title="path/to/file.c — enclosing_function()", naming 201 distinct files, so a reader can go straight to the source they were read from. Excerpts name the function, struct or macro that encloses them rather than a line number: a line number stops being true the moment a patch lands above it, while a symbol name survives edits and is what a reader actually greps for. 199 of those paths are tracked in git; the remaining two — src/include/pg_config.h and contrib/pax_storage/pax-cdbinit--1.0.sql — are generated, by configure and by the PAX build respectively, and exist only in a configured tree. Ten further excerpts name a path with a word of context after it, or name a header without a line. Other fenced blocks — SQL input, shell input, captured output, diagrams — are not citations and carry no path.#define, a multi-line enum folded onto one line, an argument list replaced by ..., or two neighbouring regions of one file shown together with an inline marker for the second. Read a block as the handbook's rendering of that code, and the title as the place to go for the original.psql output, nearly all paired with the input that produced them, taken from a running cluster. They are transcripts, not illustrations.§N, §N.M and §N.M.K resolve to the chapter, section or subsection they name, as do references of the form “Chapter N”. Only references to the page you are already on are left as plain text. The tree builds clean under Docusaurus's broken-link and broken-anchor checks; set onBrokenLinks/onBrokenAnchors to throw on the consuming site to keep it that way.The chapters describe a specific point in the tree's history. File and line references drift as the code changes; the prose is the durable part and the citations are the perishable part. Naming symbols instead of lines makes them a good deal less perishable, but a function can still be renamed or split. Two things follow:
main forever.title="file — symbol()" convention is machine-readable on purpose: a CI job can check that every cited path still exists and that the named symbol is still defined in it, which catches the worst classes of drift — a file that moved or was deleted, or a function that was renamed — without needing to re-read the prose. Such a job should resolve paths against git ls-files and skip the two generated files named above, which are absent from a clean checkout.Corrections are welcome as ordinary pull requests against the chapter file.