004-pg_dump_documentation_v4.patch

commit 8152fdc26428b55d34f4ec9158d0112aa2379aab
Author: Nitin Motiani <nitinmotiani@google.com>
Date:   Fri Apr 4 14:34:48 2025 +0000

    Add documentation for pipe-command in pg_dump and pg_restore
    
    * Add the descriptions of the new flags and constraints
      regarding which mode and other flags they can't be used with.
    * Explain the purpose of the flags.
    * Add a few examples of the usage of the flags.

diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index bfc1e7b3524..24f443c8cf4 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -287,6 +287,8 @@ PostgreSQL documentation
         specifies the target directory instead of a file. In this case the
         directory is created by <command>pg_dump</command> and must not exist
         before.
+	This option and <option>--pipe-command</option> can't be used
+	together.
        </para>
       </listitem>
      </varlistentry>
@@ -1272,6 +1274,32 @@ PostgreSQL documentation
       </listitem>
      </varlistentry>
 
+     <varlistentry>
+      <term><option>--pipe-command</option></term>
+      <listitem>
+       <para>
+        This option is only supported with the directory output
+	format. It can be used to write to multiple streams which
+	otherwise would not be possible with the directory mode.
+	For each stream, it starts a process which runs the
+	specified command and pipes the pg_dump output to this
+	process. 
+        This option is not valid if <option>--file</option>
+        is also specified.
+       </para>
+       <para>
+        The pipe-command can be used to perform operations like compress
+	using a custom algorithm, filter, or write the output to a cloud
+	storage etc. The user would need a way to pipe the final output of
+ 	each stream to a file. To handle that, the pipe command supports a format
+	specifier %f. And all the instances of %f in the command string
+	will be replaced with the corresponding file name which
+	would have been used in the directory mode with <option>--file</option>.
+        See <xref linkend="pg-dump-examples"/> below.
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry>
       <term><option>--quote-all-identifiers</option></term>
       <listitem>
@@ -1784,6 +1812,35 @@ CREATE DATABASE foo WITH TEMPLATE template0;
 </screen>
   </para>
 
+  <para>
+   To use pipe-command to dump a database into a directory-format archive
+   (the directory <literal>dumpdir</literal> needs to exist before running the command).
+
+<screen>
+<prompt>$</prompt> <userinput>pg_dump -Fd mydb --pipe-command="cat > dumpdir/%f"</userinput>
+</screen>
+  </para>
+
+  <para>
+   To use pipe-command to dump a database into a directory-format archive
+   in parallel with 5 worker jobs (the directory <literal>dumpdir</literal> needs to exist
+   before running the command).
+
+<screen>
+<prompt>$</prompt> <userinput>pg_dump -Fd mydb -j 5 --pipe-command="cat > dumpdir/%f"</userinput>
+</screen>
+  </para>
+
+  <para>
+   To use pipe-command to compress and dump a database into a
+   directory-format archive (the directory <literal>dumpdir</literal> needs to
+   exist before running the command).
+
+<screen>
+<prompt>$</prompt> <userinput>pg_dump -Fd mydb --pipe-command="gzip > dumpdir/%f.gz"</userinput>
+</screen>
+  </para>
+
   <para>
    To reload an archive file into a (freshly created) database named
    <literal>newdb</literal>:
diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index f14e5866f6c..c6da280bd3e 100644
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -93,7 +93,10 @@ PostgreSQL documentation
        <para>
        Specifies the location of the archive file (or directory, for a
        directory-format archive) to be restored.
-       If not specified, the standard input is used.
+       This option and <option>--pipe-command</option> can't be set
+       at the same time.
+       If neither this option nor <option>--pipe-command</option> is specified,
+       the standard input is used.
        </para>
       </listitem>
      </varlistentry>
@@ -851,6 +854,34 @@ PostgreSQL documentation
       </listitem>
      </varlistentry>
 
+     <varlistentry>
+      <term><option>--pipe-command</option></term>
+      <listitem>
+       <para>
+        This option is only supported with the directory output
+	format. It can be used to read from multiple streams which
+	otherwise would not be possible with the directory mode.
+        For each stream, it starts a process which runs the
+	specified command and pipes its output to the pg_restore process.
+        This option is not valid if <option>filename</option>
+        is also specified.
+       </para>
+       <para>
+        The pipe-command can be used to perform operations like
+	decompress using a custom algorithm, filter, or read from
+	a cloud storage. When reading from the pg_dump output,
+	the user would need a way to read the correct file in each 
+	stream. To handle that, the pipe command supports a format
+	specifier %f. And all the instances of %f in the command string
+	will be replaced with the corresponding file name which
+	would have been used in the directory mode with
+	<option>filename</option>.
+	This is same as the <option>--pipe-command</option> of pg-dump.
+        See <xref linkend="app-pgrestore-examples"/> below.
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry>
       <term><option>--with-data</option></term>
       <listitem>
@@ -1263,6 +1294,43 @@ CREATE DATABASE foo WITH TEMPLATE template0;
 <prompt>$</prompt> <userinput>pg_restore -L db.list db.dump</userinput>
 </screen></para>
 
+  <para>
+   To use pg_restore with pipe-command to recreate from a dump in
+   directory-archive format. The database should not exist beforehand.
+   Assume in this example that the dump in directory-archive format is
+   stored in <literal>dumpdir</literal>.
+
+<screen>
+<prompt>$</prompt> <userinput>pg_restore -C -Fd -d postgres --pipe-commnad="cat dumpdir/%f"</userinput>
+</screen>
+  </para>
+
+  <para>
+   To use pg_restore with pipe-command to first decompress and then
+   recreate from a dump in directory-archive format. The database
+   should not exist beforehand.
+   Assume in this example that the dump in directory-archive format is
+   stored in <literal>dumpdir</literal>. And all files are
+   <literal>gzip</literal> compressed.
+
+<screen>
+<prompt>$</prompt> <userinput>pg_restore -C -Fd -d postgres --pipe-commnad="cat dumpdir/%f.gz | gunzip"</userinput>
+</screen>
+  </para>
+
+  <para>
+   To use pipe-command along with <option>-L</option> to recreate only
+   selectd items from a dump in the directory-archive format.
+   The database should not exist beforehand.
+   Assume in this example that the dump in directory-archive format is
+   stored in dumpdir.
+   The <literal>db.list</literal> file is the same as one used in the previous example with <option>-L</option>
+
+<screen>
+<prompt>$</prompt> <userinput>pg_restore -C -Fd -d postgres --pipe-commnad="cat dumpdir/%f" -L db.list</userinput>
+</screen>
+  </para>
+
  </refsect1>
 
  <refsect1>