From 82865cf57d28e07e2d8254020b3b98671487b1dc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81lvaro=20Herrera?= <alvherre@kurilemu.de>
Date: Sat, 25 Oct 2025 19:26:28 +0300
Subject: [PATCH v2] Add note to pg_dump/pg_restore pages

Author: Florents Tselai <florents.tselai@gmail.com>
Discussion: https://postgr.es/m/284C4D55-4F90-4AA0-84C8-1E6A28DDF271@gmail.com
---
 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