From 2d438278debf43215e2185611d2f996d09886268 Mon Sep 17 00:00:00 2001
From: Vaibhave Sekar <vsekar@microsoft.com>
Date: Sun, 25 Jan 2026 10:54:00 +0000
Subject: [PATCH] doc: warn about post-data-only schema dumps with parallel
 restore.

---
 doc/src/sgml/ref/pg_dump.sgml | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 5ba167b33e7..cc410e00d7f 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -1272,6 +1272,17 @@ PostgreSQL documentation
           and constraints other than validated check constraints.
           Pre-data items include all other data definition items.
          </para>
+           <note>
+            <para>
+             Archives that contain only <option>post-data</option> omit table entries.
+             When such an archive is restored in parallel, constraint creation can
+             fail because <application>pg_restore</application> cannot order foreign
+             keys that depend on tables not present in the archive.  To avoid this,
+             take a schema-inclusive dump (for example, <option>--schema-only</option>
+             or the default), then filter sections at restore time, or restore the
+             post-data-only archive with <option>-j1</option>.
+            </para>
+           </note>
        </listitem>
      </varlistentry>
 
-- 
2.43.0