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 |
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 |