PostgreSQL Code-Analysis Coverage Map

Contents:

• What this doc is (and isn’t)
• Target version
• Doc-type legend
• Status legend
• Coverage at a glance
• Coverage by subcategory
  • overview
  • storage-engine
  • txn-recovery
  • query-processing
  • server-architecture
  • monitoring-stats
  • system-catalog
  • ddl-schema
  • replication-ha
  • client-protocol
  • extensibility
  • base-infra
  • i18n-text
  • utilities
• Evolution-doc backlog
• Theory and README anchor strategy
• Non-goals / out of scope
• How to grow this map
• Adjacent reading

What this doc is (and isn’t)

This is the coverage map for knowledge/code-analysis/postgres/. It answers a single question: what’s planned, what’s written, and what’s deliberately out of scope?

It is the PostgreSQL analog of cubrid-coverage.md, with one difference of kind: the CUBRID tree was tracked after most docs already existed, so its map reads “covered / open.” This PostgreSQL tree is being built from a fixed authoring backlog, so this map reads “planned / in progress / done” against that backlog. Every module slug below is drawn from the analysis plan’s module catalog — none are invented here.

It deliberately is not:

• A per-doc catalog with summaries — that is README.md, generated from each doc’s summary: frontmatter.
• An architectural map of the system — that is postgres-architecture-overview.md, the seven-axis router that leads with the shared-memory-machine thesis and forward-references every detail doc.
• A complete enumeration of every PostgreSQL source file. Coverage here is pitched at module granularity: one planned postgres-<module>.md per row. We do not track per-symbol gaps — the per-doc position-hint tables already pin canonical symbols.

Use this doc when planning the next authoring batch, or when you want a single-screen answer to “is X planned/written yet, or is it out of scope?”.

Target version

The whole tree is written against the cloned source at REL_18_STABLE, commit 273fe94 (REL_18_4-39-g273fe94852b, PostgreSQL 18.x) under /data/hgryoo/references/postgres. The version pin is durable-over-current: a released stable branch so the per-doc “Source verification (as of )” records do not rot when a beta churns.

PG18 features are in scope — async I/O (storage/aio/), WAL summarization, incremental backup, and the shared-memory cumulative-stats subsystem (introduced PG15). PG19-only items are out of scope and must not be asserted (see Non-goals). references: frontmatter paths are written relative to that tree with the full src/... prefix (e.g. src/backend/access/transam/xlog.c).

Doc-type legend

The tree has four doc types (the first three mirror CUBRID; the fourth is new for PostgreSQL):

Type	Shape	Frontmatter marker
Module doc	7-section template (Theoretical Background → Common DBMS Design → PostgreSQL’s Approach → Source Walkthrough → Source verification → Beyond PostgreSQL → Sources)	subcategory: <subcat>
Overview doc	router / axis shape (not 7-section)	subcategory: overview
Detail doc	chapter-by-chapter deep dive companion	doc_type: detail
Evolution doc	version-by-version progression of one subsystem	doc_type: evolution

Status legend

Status	Meaning
done	written, EN reviewer loop closed (KO mirror may trail)
in progress	being authored now
planned	in the backlog, not yet started

The campaign is now complete. All 117 module docs, all 15 overview/coverage/status docs (including this map), and all 7 evolution docs are done — EN authored, KO mirrored, meta frontmatter present. 13 PG-relevant research papers have been ingested into knowledge/research/dbms-papers/.

Coverage at a glance

The campaign is complete: 117 module docs + 15 overview/coverage/status docs (1 architecture overview + 13 section-overview routers + this coverage map + 1 translation-status doc) + 7 evolution docs = 139 docs total, all written EN+KO+meta against REL_18_STABLE (commit 273fe94). This is broader than the CUBRID baseline (~88 true module docs) by design — PostgreSQL has more first-class subsystems (pluggable access methods, a real extensibility surface, logical replication, a cumulative-stats subsystem). Korean mirrors live under knowledge/ko/code-analysis/postgres/. 13 PG-relevant research papers have been ingested into knowledge/research/dbms-papers/ (design-of-postgres, implementation-of-postgres, postgres-storage-system, postgres-data-model, postgres-next-generation, ssi-ports-grittner, ssi-cahill, making-si-serializable, berenson-isolation, gist, lehman-yao, seltzer-yigit-hash, fong-optimizer).

Coverage by subcategory

The “P” column is the cross-reference priority from the plan’s module catalog (1 = write first). The “Source anchor” column names the canonical source roots for that module (symbols, not lines).

overview

Doc (slug)	Source anchor	P	Status
postgres-architecture-overview	seven-axis spine; postmaster/, storage/ipc/, access/transam/, miscadmin.h	1	done
postgres-coverage	— (this map)	2	done
postgres-overview-storage-engine	router over storage-engine	2	done
postgres-overview-txn-recovery	router over txn-recovery	2	done
postgres-overview-query-processing	router over query-processing	2	done
postgres-overview-server-architecture	router over server-architecture	2	done
postgres-overview-monitoring-stats	router over monitoring-stats	3	done
postgres-overview-system-catalog	router over system-catalog	3	done
postgres-overview-ddl-schema	router over ddl-schema	3	done
postgres-overview-replication-ha	router over replication-ha	3	done
postgres-overview-client-protocol	router over client-protocol	3	done
postgres-overview-extensibility	router over extensibility	3	done
postgres-overview-base-infra	router over base-infra	3	done
postgres-overview-i18n-text	router over i18n-text	3	done
postgres-overview-utilities	router over utilities	3	done

storage-engine

Source roots: access/{heap,nbtree,gin,gist,spgist,brin,hash,index,table,common,tablesample}, storage/{buffer,smgr,page,freespace,file,large_object,aio}.

Doc (slug)	Source anchor	P	Status
postgres-page-layout	storage/page/{bufpage,checksum}.c, include/storage/{bufpage,itemptr}.h	1	done
postgres-buffer-manager	storage/buffer/{bufmgr,freelist,buf_init,localbuf}.c, README	1	done
postgres-smgr-md	storage/smgr/{smgr,md}.c	2	done
postgres-aio	storage/aio/* (PG18 async I/O)	2	done
postgres-table-am	access/table/*, include/access/tableam.h	1	done
postgres-heap-am	access/heap/{heapam,heapam_handler,hio,pruneheap}.c, README.HOT	1	done
postgres-toast	access/common/{toast_internals,detoast,toast_compression}.c, access/heap/heaptoast.c	2	done
postgres-visibility-map	access/heap/visibilitymap.c	2	done
postgres-free-space-map	storage/freespace/*	3	done
postgres-nbtree	access/nbtree/*, README	1	done
postgres-gin	access/gin/*, README	3	done
postgres-gist	access/gist/*, README	3	done
postgres-spgist	access/spgist/*, README	4	done
postgres-brin	access/brin/*, README	4	done
postgres-hash-index	access/hash/*, README	4	done
postgres-index-am	access/index/*, include/access/amapi.h	2	done
postgres-table-sampling	access/tablesample/*, include/access/tsmapi.h	4	done
postgres-data-checksums	storage/page/checksum.c, common/checksum_helper.c, src/bin/pg_checksums	3	done
postgres-large-objects	storage/large_object/*, libpq/be-fsstubs.c	4	done
postgres-sequences	access/sequence/*, commands/sequence.c	3	done

txn-recovery

Source roots: access/transam/*, storage/ipc/procarray.c, commands/vacuum*, utils/time/snapmgr.c.

Doc (slug)	Source anchor	P	Status
postgres-mvcc-snapshots	utils/time/snapmgr.c, access/heap/heapam_visibility.c, storage/ipc/procarray.c	1	done
postgres-procarray	storage/ipc/procarray.c (owns procarray internals; mvcc-snapshots references it)	1	done
postgres-xact	access/transam/xact.c, README	1	done
postgres-xlog-wal	access/transam/{xlog,xloginsert,xlogreader}.c, README	1	done
postgres-wal-records-rmgr	access/transam/{rmgr,xlogutils,generic_xlog}.c, access/rmgrdesc/*	3	done
postgres-slru	access/transam/slru.c (substrate)	2	done
postgres-clog-commit-ts	access/transam/{clog,subtrans,commit_ts}.c	2	done
postgres-multixact	access/transam/multixact.c	3	done
postgres-two-phase-commit	access/transam/{twophase,twophase_rmgr}.c	2	done
postgres-recovery-redo	access/transam/{xlogrecovery,xlogprefetcher,timeline}.c	1	done
postgres-checkpoint	access/transam/xlog.c (ckpt path), postmaster/checkpointer.c	2	done
postgres-vacuum	commands/{vacuum,vacuumparallel}.c, access/heap/vacuumlazy.c	1	done
postgres-autovacuum	postmaster/autovacuum.c	2	done
postgres-xid-wraparound-freeze	access/heap/heapam.c (freeze), access/transam/varsup.c	2	done

query-processing

Source roots: parser, rewrite, optimizer, executor, nodes, statistics, jit.

Doc (slug)	Source anchor	P	Status
postgres-parser	parser/{gram.y,scan.l,parse_*}.c	1	done
postgres-analyze-transform	parser/analyze.c, parser/parse_*	2	done
postgres-rewriter	rewrite/{rewriteHandler,rewriteDefine}.c	2	done
postgres-planner-overview	optimizer/plan/planner.c, README	1	done
postgres-path-generation	optimizer/path/*	1	done
postgres-join-ordering	optimizer/path/{joinpath,joinrels}.c, optimizer/geqo/*	2	done
postgres-cost-model	optimizer/path/costsize.c, utils/adt/selfuncs.c	2	done
postgres-plan-creation	optimizer/plan/{createplan,setrefs,subselect}.c	2	done
postgres-prep-rewrites	optimizer/prep/*	3	done
postgres-extended-statistics	statistics/*, commands/analyze.c	2	done
postgres-executor	executor/{execMain,execProcnode,execTuples}.c	1	done
postgres-expression-eval	executor/{execExpr,execExprInterp}.c	2	done
postgres-scan-nodes	executor/{nodeSeqscan,nodeIndexscan,nodeIndexonlyscan,nodeBitmapHeapscan,nodeTidscan,nodeTidrangescan}.c	2	done
postgres-join-nodes	executor/{nodeNestloop,nodeHashjoin,nodeMergejoin,nodeHash}.c	2	done
postgres-agg-sort-nodes	executor/{nodeAgg,nodeSort,nodeGroup,nodeWindowAgg,nodeIncrementalSort}.c	2	done
postgres-parallel-query	executor/{execParallel,nodeGather,nodeGatherMerge}.c, access/transam/README.parallel	2	done
postgres-portals-prepared	tcop/pquery.c, commands/{prepare,portalcmds}.c, utils/cache/plancache.c	2	done
postgres-jit	jit/*, jit/llvm/*	4	done
postgres-tuplesort	utils/sort/{tuplesort,tuplestore}.c	3	done
postgres-node-trees	nodes/*, include/nodes/*	2	done

server-architecture

Source roots: postmaster, tcop, storage/{lmgr,ipc,sync}, utils/init.

Doc (slug)	Source anchor	P	Status
postgres-postmaster	postmaster/{postmaster,launch_backend,pmchild}.c	1	done
postgres-backend-lifecycle	tcop/{postgres,utility}.c, utils/init/{postinit,miscinit}.c	1	done
postgres-shared-memory-ipc	storage/ipc/{shmem,ipci,procsignal,shm_mq,dsm,dsa}.c	1	done
postgres-lock-manager	storage/lmgr/{lock,proc,deadlock,lmgr}.c, README	1	done
postgres-lwlock-spinlock	storage/lmgr/{lwlock,s_lock}.c, include/storage/spin.h, port/atomics	1	done
postgres-ssi-predicate-locking	storage/lmgr/predicate.c, include/storage/predicate_internals.h, README-SSI	2	done
postgres-latch-signals	storage/ipc/{latch,waiteventset}.c, postmaster/interrupt.c	2	done
postgres-background-workers	postmaster/bgworker.c, storage/ipc/{dsm,dsa}.c	3	done
postgres-aux-processes	postmaster/{bgwriter,walwriter,checkpointer,startup,syslogger}.c	2	done

monitoring-stats

Source roots: utils/activity/*.

Doc (slug)	Source anchor	P	Status
postgres-cumulative-stats	utils/activity/pgstat*.c (shared-mem stats, PG15 redesign)	2	done
postgres-wait-events-progress	utils/activity/{wait_event,backend_status,backend_progress}.c, wait_event_names.txt codegen	3	done

system-catalog

Source roots: catalog, utils/cache.

Doc (slug)	Source anchor	P	Status
postgres-system-catalogs	catalog/{catalog,heap,pg_*}.c, include/catalog/*	1	done
postgres-relcache	utils/cache/relcache.c	1	done
postgres-catcache-syscache	utils/cache/{catcache,syscache,lsyscache}.c	1	done
postgres-cache-invalidation	utils/cache/inval.c, storage/ipc/sinvaladt.c	2	done
postgres-dependency-tracking	catalog/{dependency,objectaddress}.c	2	done
postgres-namespace-search-path	catalog/namespace.c	3	done

ddl-schema

Source roots: commands, partitioning, rewrite/rowsecurity.c.

Doc (slug)	Source anchor	P	Status
postgres-ddl-execution	tcop/utility.c, commands/{tablecmds,define}.c	1	done
postgres-alter-table	commands/tablecmds.c	2	done
postgres-index-creation	commands/indexcmds.c, catalog/index.c	2	done
postgres-constraints	commands/{typecmds,constraint}.c, catalog/pg_constraint.c	3	done
postgres-triggers	commands/trigger.c	2	done
postgres-event-triggers	commands/event_trigger.c	4	done
postgres-partitioning	partitioning/*, catalog/partition.c, executor/execPartition.c	2	done
postgres-row-level-security	rewrite/rowsecurity.c, commands/policy.c	3	done
postgres-copy	commands/{copy,copyfrom,copyto,copyfromparse}.c	3	done
postgres-matview	commands/matview.c	4	done

replication-ha

Source roots: replication/*, backup, postmaster/{walsummarizer,pgarch}.

Doc (slug)	Source anchor	P	Status
postgres-wal-sender-receiver	replication/{walsender,walreceiver,walreceiverfuncs}.c	1	done
postgres-replication-slots	replication/{slot,slotfuncs}.c	2	done
postgres-logical-decoding	replication/logical/{decode,reorderbuffer,snapbuild,logical}.c	2	done
postgres-logical-replication-apply	replication/logical/{worker,launcher,tablesync}.c	3	done
postgres-pgoutput	replication/pgoutput/*	4	done
postgres-synchronous-replication	replication/syncrep.c	3	done
postgres-archiving-walsummary	postmaster/{pgarch,walsummarizer}.c, access/transam/xlogarchive.c	3	done
postgres-backup-basebackup	backup/*	2	done
postgres-incremental-backup	backup/* (summary consumer), src/bin/pg_combinebackup	3	done

client-protocol

Source roots: libpq, tcop/postgres.c. (Backend-side libpq only — see non-goals.)

Doc (slug)	Source anchor	P	Status
postgres-wire-protocol	tcop/postgres.c (msg loop), libpq/{pqcomm,pqformat}.c	1	done
postgres-authentication	libpq/{auth,auth-scram,auth-sasl,crypt}.c	2	done
postgres-tls-gssapi	libpq/{be-secure,be-secure-gssapi,be-secure-openssl}.c	3	done

extensibility

Source roots: foreign, commands/{extension,foreigncmds}, src/pl.

Doc (slug)	Source anchor	P	Status
postgres-fdw	foreign/foreign.c, commands/foreigncmds.c, include/foreign/fdwapi.h (in-core mechanism only)	2	done
postgres-extensions	commands/extension.c	2	done
postgres-hooks	scattered *_hook globals (planner/executor/ProcessUtility/shmem)	3	done
postgres-plpgsql	src/pl/plpgsql/src/*	2	done
postgres-spi	executor/spi.c	3	done
postgres-custom-scan	include/nodes/extensible.h, executor/nodeCustom.c	4	done

base-infra

Source roots: utils/{mmgr,error,fmgr,adt,mb,misc,sort,resowner,hash}.

Doc (slug)	Source anchor	P	Status
postgres-memory-contexts	utils/mmgr/{mcxt,aset,generation,slab,bump}.c, README	1	done
postgres-error-handling	utils/error/{elog,assert}.c	1	done
postgres-fmgr	utils/fmgr/{fmgr,funcapi}.c	2	done
postgres-datatypes-adt	utils/adt/* (numeric, varlena, datetime, jsonb, arrays, ranges)	2	done
postgres-guc-parameters	utils/misc/{guc,guc_tables}.c	2	done
postgres-resource-owners	utils/resowner/resowner.c	3	done
postgres-dynahash	utils/hash/dynahash.c, lib/*	3	done

i18n-text

Source roots: tsearch, utils/adt/pg_locale*.

Doc (slug)	Source anchor	P	Status
postgres-collation-providers	utils/adt/{pg_locale,pg_locale_icu,pg_locale_libc,pg_locale_builtin}.c, commands/collationcmds.c	3	done
postgres-encoding	utils/mb/*	3	done
postgres-full-text-search	tsearch/*, GIN integration	3	done

utilities

Source roots: src/bin/*, bootstrap, catalog/genbki.pl.

Doc (slug)	Source anchor	P	Status
postgres-initdb-bootstrap-genbki	src/bin/initdb, bootstrap/bootstrap.c, catalog/genbki.pl + pg_*.dat → .bki codegen	2	done
postgres-pg-dump-restore	src/bin/pg_dump/*	2	done
postgres-pg-upgrade	src/bin/pg_upgrade/*	3	done
postgres-pg-basebackup	src/bin/pg_basebackup/*	3	done
postgres-pg-rewind	src/bin/pg_rewind/*	4	done
postgres-pg-waldump	src/bin/pg_waldump/*	4	done
postgres-psql	src/bin/psql/*	3	done
postgres-pg-ctl-controldata	src/bin/{pg_ctl,pg_controldata}, control-file handling in xlog.c	3	done

Evolution-doc backlog

Evolution docs (doc_type: evolution) trace a single subsystem’s architectural progression across major releases — one ## per era, a timeline Mermaid, before/after structural diffs, and cross-links to the current-state module doc(s). An evolution doc is justified only when a subsystem has ≥3 architecturally distinct eras. All are planned; each follows its subsystem’s current-state module doc(s).

Evolution doc (slug)	Arc	Status
postgres-evolution-replication	WAL file shipping → streaming (9.0) → sync/cascading (9.1–9.2) → logical decoding (9.4) → pub/sub logical replication (10) → improvements (14–18, incl. failover slots)	done
postgres-evolution-vacuum-visibility	lazy vacuum → HOT (8.3) → visibility map (8.4) → freeze map (9.6) → parallel vacuum (13) → autovacuum + wraparound hardening	done
postgres-evolution-partitioning	inheritance/constraint-exclusion → declarative (10) → partition-wise join/agg (11) → runtime pruning (11) → improvements	done
postgres-evolution-parallel-query	introduced (9.6) → parallel join/agg (10) → parallel index build (11), parallel vacuum (13), parallel-aware nodes	done
postgres-evolution-statistics	stats-collector process → extended statistics (10) → shared-memory cumulative stats (15)	done
postgres-evolution-pluggable-storage	fixed heap → table access method API (12) → custom AMs, columnar landscape	done
postgres-evolution-io-async	buffered I/O → posix_fadvise prefetch → WAL prefetch (15) → async I/O io_uring/worker (18)	done

Theory and README anchor strategy

Each module doc’s “Theoretical Background” (§1) and “Beyond PostgreSQL” (§6) sections draw from four anchor sources, in priority order:

1. In-tree README for that subsystem — PostgreSQL’s analog of CUBRID’s vendor decks, except current and accurate. These are first-class design docs and must be mined in the Theoretical/Approach sections and cited in sources:. Known READMEs (confirm per module): access/transam/README (+ README.parallel), access/nbtree/README, access/gin/README, access/gist/README, access/spgist/README, access/brin/README, access/hash/README, access/heap/README.HOT, storage/buffer/README, storage/lmgr/README + README-SSI, optimizer/README, replication/README, utils/mmgr/README.
2. knowledge/research/dbms-papers/ — the curated primary-source tree. PG-relevant captures already present: aries.md (→ recovery-redo, xlog-wal), systemr.md + systemr-optimizer.md (→ planner, cost-model), occ.md (→ mvcc, ssi), btree.md (→ nbtree), rstar-tree.md (→ gist), scalable-lock-manager.md (→ lock-manager), goes-around.md + fntdb07-architecture.md (→ architecture-overview, design-philosophy).
3. knowledge/research/dbms-general/ — database-internals.md, database-system-concepts.md (generic textbook framing); also Designing Data-Intensive Applications for replication/consistency.
4. PG-specific papers (landed — 13 captures in dbms-papers/ + raw PDFs in raw/dbms/papers/): design-of-postgres (→ architecture-overview, design-philosophy, extensibility), implementation-of-postgres (→ storage, no-overwrite/MVCC lineage), postgres-storage-system, postgres-data-model, postgres-next-generation, ssi-ports-grittner + ssi-cahill + making-si-serializable (→ ssi-predicate-locking), berenson-isolation (→ mvcc-snapshots, ssi), gist (→ gist), lehman-yao (→ nbtree), seltzer-yigit-hash (→ hash-index), fong-optimizer (→ planner, cost-model). All 13 are present; module docs may cite them directly.

Non-goals / out of scope

These will not get their own docs unless the constraint changes:

• contrib/ entirely. The tree is core-only. contrib/postgres_fdw, pg_stat_statements, bloom, and every other contrib module are not analyzed. The in-core mechanisms they build on are covered: postgres-fdw.md documents the in-core FDW machinery (foreign/, fdwapi.h) and may name postgres_fdw as the canonical example only; postgres-hooks.md documents the hook globals pg_stat_statements rides on, not the extension itself.
• PG19-only features. The version pin is REL_18_STABLE (commit 273fe94). PG19-only items must not be asserted as present — notably the XLOG2 resource manager and the online data-checksums worker BackendTypes (B_DATACHECKSUMSWORKER_*). PG18 features (async I/O, WAL summarization, incremental backup, cumulative stats) are in scope.
• Client drivers other than backend libpq. The client-protocol subcategory covers the backend (server-side) FE/BE wire protocol, auth, and TLS/GSSAPI under src/backend/libpq/ + tcop/postgres.c. The client-side libpq library (src/interfaces/libpq), ECPG, and other language drivers (JDBC, psqlODBC, the Python/Go/Rust drivers) are out of scope.
• Test frameworks. The regression-test harness (src/test/regress, pg_regress), TAP tests (src/test/perl, src/bin/**/t/*.pl), the isolation tester (src/test/isolation), and src/test/modules are not documented as a subject. Coverage of the engine invariants those tests exercise belongs in the corresponding subsystem doc, not in a doc about the test harness.
• Per-symbol coverage. This map is at module granularity. We do not track which functions/structs lack prose — the per-doc position-hint tables already pin canonical symbols.
• Build/packaging and platform glue. src/tools, config/, the meson / autoconf build, src/port / src/common are touched only where a module doc needs them (e.g. port/atomics for spinlocks); they get no standalone doc.

How to grow this map

When a doc moves status (e.g. an author starts or finishes one):

1. Update its Status cell in the matching subcategory table (planned → in progress → done).
2. Bump updated: here (and in the KO mirror, per the bilingual rule).
3. Re-run /kb-index knowledge/code-analysis/postgres to refresh README.md.

When a new module appears in the source tree that the plan’s catalog did not anticipate:

1. Decide its subcategory (one of the thirteen above).
2. Add a planned row naming the slug and source anchor, and record the decision in the plan’s module catalog (.omc/plans/postgres-analysis-plan.md §6) so the two stay in sync.

When a non-goal becomes a goal (e.g. a decision to analyze a specific contrib module):

1. Move it from Non-goals into the matching subcategory table as a planned row, with a brief note on what changed.

Adjacent reading

• README.md — per-doc catalog (auto-generated from frontmatter summary:).
• postgres-architecture-overview.md — the seven-axis spine: process model, shared-memory/IPC substrate, the WAL durability spine, storage and pluggable access methods, query pipeline, catalog+cache layer, extensibility surface; one Mermaid per axis, forward-referencing every detail doc.
• .omc/plans/postgres-analysis-plan.md — the operational authoring plan (axis set §4, taxonomy §5, module catalog §6, DoD §8) this map tracks.
• knowledge/methodology/code-analysis-doc.md — the 7-section playbook the module docs are written against.
• cubrid-coverage.md — the CUBRID coverage map this one is modelled on.