commit 8152fdc26428b55d34f4ec9158d0112aa2379aab Author: Nitin Motiani 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 pg_dump and must not exist before. + This option and can't be used + together. @@ -1272,6 +1274,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-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 . + See below. + + + + @@ -1784,6 +1812,35 @@ CREATE DATABASE foo WITH TEMPLATE template0; + + To use pipe-command to dump a database into a directory-format archive + (the directory dumpdir needs to exist before running the command). + + +$ pg_dump -Fd mydb --pipe-command="cat > dumpdir/%f" + + + + + To use pipe-command 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-command="cat > dumpdir/%f" + + + + + To use pipe-command 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-command="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 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 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. @@ -851,6 +854,34 @@ 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-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 + . + This is same as the of pg-dump. + See below. + + + + @@ -1263,6 +1294,43 @@ CREATE DATABASE foo WITH TEMPLATE template0; $ pg_restore -L db.list db.dump + + 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 dumpdir. + + +$ pg_restore -C -Fd -d postgres --pipe-commnad="cat dumpdir/%f" + + + + + 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 dumpdir. And all files are + gzip compressed. + + +$ pg_restore -C -Fd -d postgres --pipe-commnad="cat dumpdir/%f.gz | gunzip" + + + + + To use pipe-command 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-commnad="cat dumpdir/%f" -L db.list + + +