From 6d3a9f9d9e45525e1f1dfee3be932adc185d0391 Mon Sep 17 00:00:00 2001 From: Nitin Motiani Date: Mon, 8 Jun 2026 11:33:43 +0000 Subject: [PATCH v19 3/3] Add documentation for pipe 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. --- doc/src/sgml/ref/pg_dump.sgml | 56 ++++++++++++++++++++++++++ doc/src/sgml/ref/pg_restore.sgml | 68 +++++++++++++++++++++++++++++++- 2 files changed, 123 insertions(+), 1 deletion(-) diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml index 774be23b4f9..5e6d7339669 100644 --- a/doc/src/sgml/ref/pg_dump.sgml +++ b/doc/src/sgml/ref/pg_dump.sgml @@ -297,6 +297,7 @@ PostgreSQL documentation specifies the target directory instead of a file. In this case the directory is created by pg_dump unless the directory exists and is empty. + This option and can't be used together. @@ -1212,6 +1213,32 @@ PostgreSQL documentation + + + + + 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 + is also specified. + + + The pipe 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 . + See below. + + + + @@ -1790,6 +1817,35 @@ CREATE DATABASE foo WITH TEMPLATE template0; + + To use pipe to dump a database into a directory-format archive + (the directory dumpdir needs to exist before running the command). + + +$ pg_dump -Fd mydb --pipe="cat > dumpdir/%f" + + + + + To use pipe to dump a database into a directory-format archive + in parallel with 5 worker jobs (the directory dumpdir needs to exist + before running the command). + + +$ pg_dump -Fd mydb -j 5 --pipe="cat > dumpdir/%f" + + + + + To use pipe to compress and dump a database into a + directory-format archive (the directory dumpdir needs to + exist before running the command). + + +$ pg_dump -Fd mydb --pipe="gzip > dumpdir/%f.gz" + + + To reload an archive file into a (freshly created) database named newdb: diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml index b6c5299c36e..2b59ac8667b 100644 --- a/doc/src/sgml/ref/pg_restore.sgml +++ b/doc/src/sgml/ref/pg_restore.sgml @@ -96,7 +96,10 @@ PostgreSQL documentation 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 can't be set + at the same time. + If neither this option nor is specified, + the standard input is used. @@ -827,6 +830,32 @@ PostgreSQL documentation + + + + + 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 is also specified. + + + The pipe 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 . + This is same as the of pg-dump. + See below. + + + + @@ -1257,6 +1286,43 @@ CREATE DATABASE foo WITH TEMPLATE template0; $ pg_restore -L db.list db.dump + + To use pg_restore with pipe 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 dumpdir. + + +$ pg_restore -C -Fd -d postgres --pipe="cat dumpdir/%f" + + + + + To use pg_restore with pipe 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 dumpdir. And all files are + gzip compressed. + + +$ pg_restore -C -Fd -d postgres --pipe="cat dumpdir/%f.gz | gunzip" + + + + + To use pipe along with 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 db.list file is the same as one used in the previous example with + + +$ pg_restore -C -Fd -d postgres --pipe="cat dumpdir/%f" -L db.list + + + -- 2.55.0.699.gb54405d56f-goog