public inbox for pgsql-docs@postgresql.org
help / color / mirror / Atom feedDocumentation clarification request: pg_dumpall and Large Objects
8+ messages / 3 participants
[nested] [flat]
* Documentation clarification request: pg_dumpall and Large Objects
@ 2025-12-04 12:12 Radoulov, Dimitre <cichomitiko@gmail.com>
0 siblings, 1 reply; 8+ messages in thread
From: Radoulov, Dimitre @ 2025-12-04 12:12 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org
Hello,
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.
In the source code (pg_dumpall.c), there is a comment indicating
that pg_dumpall forces all pg_dump output to plain text. Since Large
Objects are only included by pg_dump when using -b or non-text
archive formats (custom/tar), pg_dumpall cannot include LOBs in its
output.
This behavior is clear from the implementation, but not from the
documentation.
I propose adding an explicit note such as:
"pg_dumpall does not include Large Objects (BLOBs). To back up
Large Objects, use pg_dump -b per database."
This clarification would help prevent user confusion during
cluster-wide backup procedures.
Thank you.
Best regards,
Dimitre Radoulov
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Documentation clarification request: pg_dumpall and Large Objects
@ 2025-12-04 15:50 Laurenz Albe <laurenz.albe@cybertec.at>
parent: Radoulov, Dimitre <cichomitiko@gmail.com>
0 siblings, 1 reply; 8+ messages in thread
From: Laurenz Albe @ 2025-12-04 15:50 UTC (permalink / raw)
To: Radoulov, Dimitre <cichomitiko@gmail.com>; pgsql-docs@lists.postgresql.org
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.
>
> This behavior is clear from the implementation, but not from the
> documentation.
>
> I propose adding an explicit note such as:
>
> "pg_dumpall does not include Large Objects (BLOBs). To back up
> Large Objects, use pg_dump -b per database."
At the beginning of the "pg_dumpall" page we see:
pg_dumpall is a utility for writing out (“dumping”) all PostgreSQL databases
of a cluster into one script file. [...].
It does this by calling pg_dump for each database in the cluster.
And the pg_dump documentation says:
-b
--large-objects
--blobs (deprecated)
Include large objects in the dump. This is the default behavior except when
--schema, --table, --schema-only, --statistics-only, or --no-data is specified.
Since pg_dumpall dumps the databases (and not parts of the databases), it will
automatically dump large objects too.
But 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.
Yours,
Laurenz Albe
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Documentation clarification request: pg_dumpall and Large Objects
@ 2025-12-04 17:12 Radoulov, Dimitre <cichomitiko@gmail.com>
parent: Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 1 reply; 8+ messages in thread
From: Radoulov, Dimitre @ 2025-12-04 17:12 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: pgsql-docs@lists.postgresql.org
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.
> >
> > This behavior is clear from the implementation, but not from the
> > documentation.
> >
> > I propose adding an explicit note such as:
> >
> > "pg_dumpall does not include Large Objects (BLOBs). To back up
> > Large Objects, use pg_dump -b per database."
>
> At the beginning of the "pg_dumpall" page we see:
>
> pg_dumpall is a utility for writing out (“dumping”) all PostgreSQL
> databases
> of a cluster into one script file. [...].
> It does this by calling pg_dump for each database in the cluster.
>
> And the pg_dump documentation says:
>
> -b
> --large-objects
> --blobs (deprecated)
>
> Include large objects in the dump. This is the default behavior except
> when
> --schema, --table, --schema-only, --statistics-only, or --no-data is
> specified.
>
> Since pg_dumpall dumps the databases (and not parts of the databases), it
> will
> automatically dump large objects too.
>
> But 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 for the clarification.
I believe the confusion comes from the historical behavior of pg_dump in
older PostgreSQL versions.
Since pg_dumpall delegates to pg_dump, and pg_dump’s default behavior has
included LOBs since 7.1, the current behavior is consistent with your
explanation.
Thank you again for your time and for considering the suggestion.
Best regards
Dimitre
>
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Documentation clarification request: pg_dumpall and Large Objects
@ 2025-12-04 18:11 Laurenz Albe <laurenz.albe@cybertec.at>
parent: Radoulov, Dimitre <cichomitiko@gmail.com>
0 siblings, 1 reply; 8+ messages in thread
From: Laurenz Albe @ 2025-12-04 18:11 UTC (permalink / raw)
To: Radoulov, Dimitre <cichomitiko@gmail.com>; +Cc: pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Documentation clarification request: pg_dumpall and Large Objects
@ 2026-02-27 22:23 Laurenz Albe <laurenz.albe@cybertec.at>
parent: Laurenz Albe <laurenz.albe@cybertec.at>
0 siblings, 2 replies; 8+ messages in thread
From: Laurenz Albe @ 2026-02-27 22:23 UTC (permalink / raw)
To: Radoulov, Dimitre <cichomitiko@gmail.com>; +Cc: pgsql-docs@lists.postgresql.org
On Thu, 2025-12-04 at 19:11 +0100, Laurenz Albe wrote:
> 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.
>
> Attached is a patch for such a change.
Commit 763aaa06f0 has changed the situation: with the addition of other formats
than the plain format, it no longer makes sense to say that pg_dumpall
is not useful for backup. Still, we should clarify what is *not* included.
The attached patch does that and in passing improves the readability.
Yours,
Laurenz Albe
Attachments:
[text/x-patch] v2-0001-pg_dumpall-doc-add-more-clarity.patch (2.3K, 2-v2-0001-pg_dumpall-doc-add-more-clarity.patch)
download | inline diff:
From 42ffb83a38aecb6297435bc29b7441698851008f Mon Sep 17 00:00:00 2001
From: Laurenz Albe <laurenz.albe@cybertec.at>
Date: Fri, 27 Feb 2026 23:18:09 +0100
Subject: [PATCH v2] pg_dumpall doc: add more clarity
Add a sentence that describes the parts of a cluster's state that are
*not* included in the output.
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. Also, add a reference to
pg_restore, since not all output formats are restored with pg_dump.
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 | 11 ++++++++---
1 file changed, 8 insertions(+), 3 deletions(-)
diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml
index 49e5c99b09e..c5a69d0c93d 100644
--- a/doc/src/sgml/ref/pg_dumpall.sgml
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -36,14 +36,19 @@ 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 an SQL script file or an archive. The output contains
- <acronym>SQL</acronym> commands that can be used as input to <xref
- linkend="app-psql"/> to restore the databases. It does this by
+ of a cluster into an SQL script file or an archive. It does this by
calling <xref linkend="app-pgdump"/> for each database in the cluster.
+ The output contains <acronym>SQL</acronym> commands that can be used
+ as input to <xref linkend="app-psql"/> or <xref linkend="app-pgrestore"/>
+ 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.)
+ 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>
--
2.53.0
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Documentation clarification request: pg_dumpall and Large Objects
@ 2026-02-28 09:45 Radoulov, Dimitre <cichomitiko@gmail.com>
parent: Laurenz Albe <laurenz.albe@cybertec.at>
1 sibling, 0 replies; 8+ messages in thread
From: Radoulov, Dimitre @ 2026-02-28 09:45 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: pgsql-docs@lists.postgresql.org
Il Ven 27 Feb 2026, 23:23 Laurenz Albe <laurenz.albe@cybertec.at> ha
scritto:
> On Thu, 2025-12-04 at 19:11 +0100, Laurenz Albe wrote:
> > 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.
> >
> > Attached is a patch for such a change.
>
> Commit 763aaa06f0 has changed the situation: with the addition of other
> formats
> than the plain format, it no longer makes sense to say that pg_dumpall
> is not useful for backup. Still, we should clarify what is *not* included.
>
> The attached patch does that and in passing improves the readability.
>
Thank you for the update.
Best regards
Dimitre
>
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Documentation clarification request: pg_dumpall and Large Objects
@ 2026-03-29 17:55 Tom Lane <tgl@sss.pgh.pa.us>
parent: Laurenz Albe <laurenz.albe@cybertec.at>
1 sibling, 1 reply; 8+ messages in thread
From: Tom Lane @ 2026-03-29 17:55 UTC (permalink / raw)
To: Laurenz Albe <laurenz.albe@cybertec.at>; +Cc: Radoulov, Dimitre <cichomitiko@gmail.com>; pgsql-docs@lists.postgresql.org
Laurenz Albe <laurenz.albe@cybertec.at> writes:
> Commit 763aaa06f0 has changed the situation: with the addition of other formats
> than the plain format, it no longer makes sense to say that pg_dumpall
> is not useful for backup. Still, we should clarify what is *not* included.
> The attached patch does that and in passing improves the readability.
Pushed with trivial grammatical adjustments. I also failed to resist
the temptation to improve the newly-added text nearby.
regards, tom lane
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Documentation clarification request: pg_dumpall and Large Objects
@ 2026-03-29 18:12 Laurenz Albe <laurenz.albe@cybertec.at>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 0 replies; 8+ messages in thread
From: Laurenz Albe @ 2026-03-29 18:12 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Radoulov, Dimitre <cichomitiko@gmail.com>; pgsql-docs@lists.postgresql.org
On Sun, 2026-03-29 at 13:55 -0400, Tom Lane wrote:
> Laurenz Albe <laurenz.albe@cybertec.at> writes:
> > Commit 763aaa06f0 has changed the situation: with the addition of other formats
> > than the plain format, it no longer makes sense to say that pg_dumpall
> > is not useful for backup. Still, we should clarify what is *not* included.
>
> > The attached patch does that and in passing improves the readability.
>
> Pushed with trivial grammatical adjustments. I also failed to resist
> the temptation to improve the newly-added text nearby.
Thank you,
Laurenz Albe
^ permalink raw reply [nested|flat] 8+ messages in thread
end of thread, other threads:[~2026-03-29 18:12 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2025-12-04 12:12 Documentation clarification request: pg_dumpall and Large Objects Radoulov, Dimitre <cichomitiko@gmail.com>
2025-12-04 15:50 ` Laurenz Albe <laurenz.albe@cybertec.at>
2025-12-04 17:12 ` Radoulov, Dimitre <cichomitiko@gmail.com>
2025-12-04 18:11 ` Laurenz Albe <laurenz.albe@cybertec.at>
2026-02-27 22:23 ` Laurenz Albe <laurenz.albe@cybertec.at>
2026-02-28 09:45 ` Radoulov, Dimitre <cichomitiko@gmail.com>
2026-03-29 17:55 ` Tom Lane <tgl@sss.pgh.pa.us>
2026-03-29 18:12 ` Laurenz Albe <laurenz.albe@cybertec.at>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox