From 8867a64f4d0c6c530bc001b8db73802f25284d15 Mon Sep 17 00:00:00 2001
From: Laurenz Albe <laurenz.albe@cybertec.at>
Date: Thu, 4 Dec 2025 19:09:17 +0100
Subject: [PATCH v1] pg_dumpall doc: clarify scope and suggested use

Add a paragraph that clarifies that pg_dumpall is mostly an upgrade
tool and describes the parts of a cluster's state that are *not*
included in the dump.

In the spirit of added clarity, swap two sentences in the introductory
paragraph.  Without that, it is not clear what the "it" at the beginning
of the second sentence is referring to.

Author: Laurenz Albe <laurenz.albe@cybertec.at>
Discussion: https://postgr.es/m/CAGJBphSX2oMPPu%3DVM4U8NP4%2BqffFH_483tFQCJ_s-mOcN3DLDw%40mail.gmail.com
---
 doc/src/sgml/ref/pg_dumpall.sgml | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml
index 8834b7ec141..f46f2e70b7f 100644
--- a/doc/src/sgml/ref/pg_dumpall.sgml
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -33,16 +33,25 @@ PostgreSQL documentation
   <para>
    <application>pg_dumpall</application> is a utility for writing out
    (<quote>dumping</quote>) all <productname>PostgreSQL</productname> databases
-   of a cluster into one script file.  The script file contains
-   <acronym>SQL</acronym> commands that can be used as input to <xref
-   linkend="app-psql"/> to restore the databases.  It does this by
-   calling <xref linkend="app-pgdump"/> for each database in the cluster.
+   of a cluster into one script file.  It does this by calling
+   <xref linkend="app-pgdump"/> for each database in the cluster.
+   The resulting script file contains <acronym>SQL</acronym> commands that
+   can be used as input to <xref linkend="app-psql"/> to restore the databases.
    <application>pg_dumpall</application> also dumps global objects
    that are common to all databases, namely database roles, tablespaces,
    and privilege grants for configuration parameters.
    (<application>pg_dump</application> does not save these objects.)
   </para>
 
+  <para>
+   <application>pg_dumpall</application> is primarily intended as a tool
+   for upgrading database clusters (see <xref linkend="upgrading-via-pgdumpall"/>).
+   As such, it by default exports all data of the entire cluster.  The only
+   part of a database cluster's state that is <emphasis>not</emphasis> included
+   in the output of <application>pg_dumpall</application> are the configuration
+   files and database parameters changed with <xref linkend="sql-altersystem"/>.
+  </para>
+
   <para>
    Since <application>pg_dumpall</application> reads tables from all
    databases you will most likely have to connect as a database
-- 
2.52.0