On 2024-Sep-26, Florents Tselai wrote: > Attached an idea. > The A/B example may be wordy / redundant,
Yeah, it seems a little wordy to me, how about something like the attached? > but the -e note on the distinction between installing binaries / creating > an extension I think it's important. Hmm, ok, but I think that's a slightly unrelated topic because the shlib is not a database object. Maybe it would be more appropriate to add a mention of this directly in the docs for -e instead of trying to cram it in the note about other database objects. I'll wait for you to propose something for that part. -- Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/
>From 82865cf57d28e07e2d8254020b3b98671487b1dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=81lvaro=20Herrera?= <[email protected]> Date: Sat, 25 Oct 2025 19:26:28 +0300 Subject: [PATCH v2] Add note to pg_dump/pg_restore pages Author: Florents Tselai <[email protected]> Discussion: https://postgr.es/m/[email protected] --- doc/src/sgml/ref/pg_dump.sgml | 41 +++++++++----------------------- doc/src/sgml/ref/pg_restore.sgml | 20 ++++++++-------- 2 files changed, 21 insertions(+), 40 deletions(-) diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml index fd4ecf01a0a..17b5be26615 100644 --- a/doc/src/sgml/ref/pg_dump.sgml +++ b/doc/src/sgml/ref/pg_dump.sgml @@ -261,16 +261,6 @@ PostgreSQL documentation dump if its extension is specified by <option>--extension</option>. </para> - <note> - <para> - When <option>-e</option> is specified, - <application>pg_dump</application> makes no attempt to dump any other - database objects that the selected extension(s) might depend upon. - Therefore, there is no guarantee that the results of a - specific-extension dump can be successfully restored by themselves - into a clean database. - </para> - </note> </listitem> </varlistentry> @@ -445,16 +435,6 @@ PostgreSQL documentation <xref linkend="pg-dump-examples"/> below. </para> - <note> - <para> - When <option>-n</option> is specified, <application>pg_dump</application> - makes no attempt to dump any other database objects that the selected - schema(s) might depend upon. Therefore, there is no guarantee - that the results of a specific-schema dump can be successfully - restored by themselves into a clean database. - </para> - </note> - <note> <para> Non-schema objects such as large objects are not dumped when <option>-n</option> is @@ -596,16 +576,6 @@ PostgreSQL documentation be dumped. </para> - <note> - <para> - When <option>-t</option> is specified, <application>pg_dump</application> - makes no attempt to dump any other database objects that the selected - table(s) might depend upon. Therefore, there is no guarantee - that the results of a specific-table dump can be successfully - restored by themselves into a clean database. - </para> - </note> - </listitem> </varlistentry> @@ -1689,6 +1659,17 @@ CREATE DATABASE foo WITH TEMPLATE template0; </programlisting> </para> + <para> + When options <option>-e</option>, <option>-n</option> or <option>-t</option> + are specified, <application>pg_dump</application> makes no attempt to dump + any other database objects that the selected object(s) might depend upon. + Therefore, there is no guarantee that the results of a dump so generated + can be successfully restored by themselves into a clean database. + For example, if a table whose definition includes a foreign key is + specified to be restore, the table referenced by the foreign key is + not automatically restored. + </para> + <para> When a dump without schema is chosen and the option <option>--disable-triggers</option> is used, <application>pg_dump</application> emits commands diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml index a468a38361a..8ceff99714d 100644 --- a/doc/src/sgml/ref/pg_restore.sgml +++ b/doc/src/sgml/ref/pg_restore.sgml @@ -452,16 +452,6 @@ PostgreSQL documentation specify table(s) in a particular schema. </para> - <note> - <para> - When <option>-t</option> is specified, <application>pg_restore</application> - makes no attempt to restore any other database objects that the - selected table(s) might depend upon. Therefore, there is no - guarantee that a specific-table restore into a clean database will - succeed. - </para> - </note> - <note> <para> This flag does not behave identically to the <option>-t</option> @@ -1089,6 +1079,16 @@ PostgreSQL documentation <refsect1 id="app-pgrestore-notes"> <title>Notes</title> + <para> + When options <option>-n</option> or <option>-t</option> are specified, + <application>pg_restore</application> makes no attempt to restore + any other database objects that the selected table(s) or schema(s) + might depend upon. Therefore, there is no guarantee that a specific-table + restore into a clean database will succeed. For example, if a table + whose definition includes a foreign key is specified to be restore, the + table referenced by the foreign key is not automatically restored. + </para> + <para> If your installation has any local additions to the <literal>template1</literal> database, be careful to load the output of -- 2.47.3
