From 7df17cbe5e32226c72a63fb6c97b308908dcf849 Mon Sep 17 00:00:00 2001 From: Nitin Motiani Date: Fri, 4 Apr 2025 14:34:48 +0000 Subject: [PATCH v5 4/5] 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. --- 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 d7595a7e546..18bc67d61fc 100644 --- a/doc/src/sgml/ref/pg_dump.sgml +++ b/doc/src/sgml/ref/pg_dump.sgml @@ -287,6 +287,7 @@ 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. @@ -1234,6 +1235,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. + + + + @@ -1783,6 +1810,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 2295df62d03..5a929162702 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. @@ -842,6 +845,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-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 +1292,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 + + + -- 2.49.0.1266.g31b7d2e469-goog