Introduce New Command Processing Chapter to Documentation

From: "David G(dot) Johnston" <david(dot)g(dot)johnston(at)gmail(dot)com>
To: PostgreSQL Hackers <pgsql-hackers(at)lists(dot)postgresql(dot)org>
Subject: Introduce New Command Processing Chapter to Documentation
Date: 2025-03-11 22:52:04
Message-ID: CAKFQuwYVnT5iEx294NiJhxv-+FTub1iGqVOOxC4vcgB9OPRQ9g@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

Hey.

A while back there was an expressed belief that we have too many chapters
in our documentation. Recently, I wrote some user-facing documentation
involving query plans with WindowAgg nodes and was informed that placing it
under "Performance Tips" was the existing best fit. That didn't feel
right. I pondered on things a bit and came up with the following idea.

Remove three chapters from "The SQL Language" part, demoting them under a
new "Command Processing" chapter (net reduction of 2). The demoted
chapters are "Concurrency Control", "Parallel Query", and "Performance
Tips". The "Performance Tips" sections of Explain and Statistics don't
seem like "tips" so I laterally moved them directly under "Command
Processing". I then handled the lack of a natural place to insert the
WindowAgg explanation code by also adding a "Processing Nodes" chapter. (I
haven't looked to see how much of Explain could be moved here.)

The attached patch implements the above. The WindowAgg code is just my
proposal from the other thread and wouldn't be part of the initial commit.
Just the mechanical refactoring bits.

I'd probably also move the pending "NULL Values Overview" section from
"Data Definition" to "Command Processing".

Here are the new TOC fragments:

II. The SQL Language
4. SQL Syntax
5. Data Definition
6. Data Manipulation
7. Queries
8. Data Types
9. Functions and Operators
10. Type Conversion
11. Indexes
12. Full Text Search
13. Command Processing

13.1. Using EXPLAIN
13.1.1. EXPLAIN Basics
13.1.2. EXPLAIN ANALYZE
13.1.3. Caveats

13.2. Statistics Used by the Planner
13.2.1. Single-Column Statistics
13.2.2. Extended Statistics

13.3. Parallel Query
13.3.1. How Parallel Query Works
13.3.2. When Can Parallel Query Be Used?
13.3.3. Parallel Plans
13.3.4. Parallel Safety

13.4. Concurrency Control
13.4.1. Introduction
13.4.2. Transaction Isolation
13.4.3. Explicit Locking
13.4.4. Data Consistency Checks at the Application Level
13.4.5. Serialization Failure Handling
13.4.6. Caveats
13.4.7. Locking and Indexes

13.5. Processing Nodes
13.5.1. WindowAgg

13.6. Performance Tips
13.6.1. Controlling the Planner with Explicit JOIN Clauses
13.6.2. Populating a Database
13.6.3. Non-Durable Settings

David J.

Attachment Content-Type Size
v0-0001-Introduce-new-processing.sgml-chapter.patch text/x-patch 166.0 KB

Browse pgsql-hackers by date

  From Date Subject
Next Message Peter Geoghegan 2025-03-11 22:59:09 Re: Adding skip scan (including MDAM style range skip scan) to nbtree
Previous Message Jeff Davis 2025-03-11 22:38:34 Re: Statistics import and export: difference in statistics of materialized view dumped