public inbox for pgsql-docs@postgresql.org
help / color / mirror / Atom feedFrom: Laurenz Albe <laurenz.albe@cybertec.at>
To: Radoulov, Dimitre <cichomitiko@gmail.com>
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: Documentation clarification request: pg_dumpall and Large Objects
Date: Thu, 04 Dec 2025 19:11:44 +0100
Message-ID: <b8358ac2148b9daf30c27b50a8cb9c8f2c4e40f9.camel@cybertec.at> (raw)
In-Reply-To: <CAGJBphS4TLNvAyNcWj_NSfer9SoDzco35apkT+8-wqXCthSK6w@mail.gmail.com>
References: <CAGJBphSX2oMPPu=VM4U8NP4+qffFH_483tFQCJ_s-mOcN3DLDw@mail.gmail.com>
<d4ab85597252c7a529f64ffd5cc5b09d92504df4.camel@cybertec.at>
<CAGJBphS4TLNvAyNcWj_NSfer9SoDzco35apkT+8-wqXCthSK6w@mail.gmail.com>
On Thu, 2025-12-04 at 18:12 +0100, Radoulov, Dimitre wrote:
> Il Gio 4 Dic 2025, 16:50 Laurenz Albe <laurenz.albe@cybertec.at> ha scritto:
> > On Thu, 2025-12-04 at 13:12 +0100, Radoulov, Dimitre wrote:
> > > I would like to request a clarification in the pg_dumpall
> > > documentation regarding Large Objects (LOBs). The current
> > > documentation does not explicitly state whether pg_dumpall includes
> > > Large Objects in its output.
> >
> > I admit that you have to go by circumstantial evidence here. But rather
> > than explicitly naming large objects, perhaps it would be useful to add something
> > like
> >
> > pg_dumpall is primarily intended as a tool to upgrade database clusters.
> > As such, it by default exports all data of the entire cluster.
> > The only part of the state of a database cluster that is *not* included
> > in the output of pg_dumpall are the configuration files and database parameters
> > changed with ALTER SYSTEM.
>
> Thank you again for your time and for considering the suggestion.
Attached is a patch for such a change.
I'll add it to the next commitfest.
Yours,
Laurenz Albe
Attachments:
[text/x-patch] v1-0001-pg_dumpall-doc-clarify-scope-and-suggested-use.patch (2.7K, 2-v1-0001-pg_dumpall-doc-clarify-scope-and-suggested-use.patch)
download | inline diff:
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
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: laurenz.albe@cybertec.at, cichomitiko@gmail.com, pgsql-docs@lists.postgresql.org
Subject: Re: Documentation clarification request: pg_dumpall and Large Objects
In-Reply-To: <b8358ac2148b9daf30c27b50a8cb9c8f2c4e40f9.camel@cybertec.at>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox