schema: review-report-v2
slug: commitfest-7381-review
source: postgresql-master
title: "CommitFest 7381 Review: doc: Document Linux cgroup memory limits"
verdict: ready-for-committer
target: "CommitFest 7381 — staged diff on doc/src/sgml/runtime.sgml (+51 lines, new <sect2 id=\"linux-memory-cgroups\">)"
base: 6f3bdadaadc4692050ca20dff53d3890088b9272
head: 6f3bdadaadc4692050ca20dff53d3890088b9272
blocker_verified: 0
blocker_unverified: 0

CommitFest 7381 Review: doc: Document Linux cgroup memory limits

Scope

The patch adds a new <sect2 id="linux-memory-cgroups"> titled "Linux Control Group Memory Limits" to doc/src/sgml/runtime.sgml, placed between the existing linux-memory-overcommit section and the linux-huge-pages section. It documents:

• cgroup v2 memory.max limits
• OOM killer behavior within a cgroup
• postmaster crash-restart behavior when a backend is OOM-killed
• which PostgreSQL memory (shared buffers, per-session work_mem, etc.) counts towards the cgroup limit
• huge pages caveat (not counted towards cgroup usage by default)
• cross-references to 8 existing GUC/section anchors (all verified to resolve)

Verdict

PostgreSQL readiness: ready-for-committer

Blocker split: 0 verified / 0 unverified

The patch is technically accurate, well-structured, and fills a genuine documentation gap for operators running PostgreSQL in containers. All factual claims about cgroup v2 behavior were verified against the kernel documentation and the PostgreSQL postmaster source code. All cross-references resolve. SGML is well-formed. The 5 findings are all MINOR or NIT — completeness suggestions that would improve the documentation but do not represent errors. The patch is suitable for committer application; the nits can be addressed at the committer's discretion or in a follow-up.

Deterministic verdict logic

• 0 surviving BLOCKER findings → not waiting-on-author
• 0 correctness/security MAJOR findings → not needs-review
• 0 test-only MAJOR findings → not ready-for-committer (test follow-up required)
• 3 MINOR + 2 NIT docs findings, all verified → ready-for-committer

Findings Summary

Verification Summary

All 5 findings were independently verified by the pg-finding-verifier seat. No findings were refuted.

Verification methodology

1. Read the actual added lines (1441–1490) of doc/src/sgml/runtime.sgml in the read-only worktree.
2. Fetched the authoritative Linux kernel cgroup-v2 documentation and confirmed all factual claims:

• memory.max is the v2 hard limit file
• v1 equivalent is memory.limit_in_bytes
• memory.oom.group kills all tasks together when set
• memory_hugetlb_accounting mount option results in SIGBUS on charge failure

1. Inspected SGML conventions in the same file/codebase (<see>, <secondary>, <systemitem>, <option> are all established elements).
2. Built disposable scratch worktree copies, applied candidate edits, ran git apply --check and xmllint --noout --nonet on each patched file — no new parse errors introduced.
3. Full make docs/FOP build was not run (no doc build infrastructure in scratch environment); xmllint structural check is the strongest available automated gate.

Repair Validation Summary

All 5 findings have concrete provided repair patches (unified diffs bound to frozen HEAD). Repair validation status is partial for all findings: git apply --check succeeded and xmllint --noout --nonet confirmed no new structural errors in the edited regions, but a full DocBook HTML/PDF render was not possible in the disposable scratch environment (no DTD catalog/FOP toolchain).

Patch application order note

F1+F2+F4 and F3 both touch the sizing paragraph around lines 1484–1494. If both are applied, F3 should be applied after the F1+F2+F4 patch. F5 is independent and applies cleanly in any order. All three patches were validated independently against the original staged diff.

Changed-Code Coverage

Status: not-applicable

The patch is documentation-only: it adds SGML prose to doc/src/sgml/runtime.sgml (a new <sect2> subsection on Linux cgroup memory limits). There are no changed C/C++/SQL/catalog/test files, no changed executable implementation lines, no changed branches, and no changed functions. Coverage instrumentation is not applicable to SGML documentation files.

Security Assessment

CLEAN — no security issues. (from pg-security-reviewer seat)

The patch is documentation-only with no C, SQL, catalog, GUC-default, authentication, TLS, or extension-script changes. The PG-specific vulnerability classes (privilege escalation, SECURITY DEFINER search_path, catalog-write TOCTOU, SQL injection, crypto/TLS, superuser guards) are not applicable.

The documentation content was reviewed for security-sensitive operational guidance:

• OOM-kill → postmaster crash-restart semantics: accurate
• Memory sizing guidance: sound operational advice
• Huge-pages caveat: accurate and security-useful (warns admins that huge-page memory can escape cgroup accounting)
• No recommendation to disable OOM protection
• External URL (https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html): official kernel.org HTTPS documentation, consistent with existing citations in the same file

Thread Reconciliation

Status: no-thread-found

The patch was posted to pgsql-hackers on 2026-10-01 by joao.detomini@enterprisedb.com as Thread-ID 657829. No reviews or replies have been posted to this thread as of the review date. A related but separate thread (Thread-ID 657840, subject "Exposing the cgroup memory limit to SQL?") exists but discusses a different feature proposal and contains no review of this documentation patch.

All 5 findings are classified as new (no prior discussion in the thread).

Detailed Findings

<filename>memory.max</filename> file.  (Version 1 uses different files
and is not covered here; in version 1 the equivalent file is
<filename>memory.limit_in_bytes</filename>.)

the OOM killer terminates a process of the cgroup (or, if the cgroup has
<filename>memory.oom.group</filename> set, all processes in the cgroup).
The OOM victim could be the postmaster itself.

total stays below the limit.  Note that this list is not exhaustive;
other per-process memory such as <xref linkend="guc-temp-buffers"/>,
WAL buffers, and catalog caches also counts towards the cgroup usage.

(see <xref linkend="guc-huge-pages"/>) is by default not counted towards
the memory usage of the cgroup, unless the cgroup v2 mount option
<option>memory_hugetlb_accounting</option> is used; with that option, a
charge failure results in <systemitem>SIGBUS</systemitem> rather than
an OOM kill.

<indexterm>
 <primary>cgroup</primary>
 <see>control group</see>
</indexterm>

Verified Clean (Non-Findings)

• SGML well-formedness: PASS — xmllint --noout reports no well-formedness errors in the new section.
• Cross-reference target integrity: PASS — all 8 <xref linkend="..."/> targets verified to exist in the doc tree.
• Section ID uniqueness: PASS — linux-memory-cgroups appears exactly once in the entire doc tree.
• Section placement: PASS — placed between linux-memory-overcommit and linux-huge-pages within <sect1 id="kernel-resources">, forming a coherent progression.
• Technical accuracy: PASS — all factual claims about cgroup v2 behavior verified against kernel documentation and PostgreSQL postmaster source code.
• DocBook style compliance: PASS — correct use of <firstterm>, <filename>, <varname>, <productname>, <xref>; two-space sentence separation maintained; indexterm placement follows existing pattern.

Aggregated Test Plan

Residual Risk

Low. The patch is documentation-only with no runtime impact. All findings are MINOR/NIT completeness suggestions. The repair patches are concrete and validated structurally but not rendered (full doc build unavailable in scratch environment). The committer should run make html or equivalent to confirm the rendered output before applying any repair patches.

Provenance

Validator

• Validator: run-scoped validate_review_artifact.py (SHA-256 edbcb304ffbd062627196c1ee0ce3d9b60cae80dd7b201e420335fea0a31979e)
• Result: ok: pg-review-artifact-v2 is structurally complete
• Artifact: review-artifact-v2.json (run-scoped v2 JSON artifact, validated before rendering)

Hard Constraints Compliance

• The reviewed worktree was not modified (read-only).
• All candidate repair patches were validated only in disposable scratch worktree copies.
• No commits, pushes, or staging operations were performed.
• All citations use repo-relative paths.
• No local absolute paths or credentials are persisted in durable output.
• Every run/repair claim came from a seat that executed it.
• The v2 artifact passed the SHA-256-bound validator before rendering.