[DOC] [PBCKP-128] [skip travis] Describe catchup dry-run flag

indrups · indrups · commit 141e96a0e6cd · 2022-05-23T15:07:27.000+03:00
diff --git a/doc/pgprobackup.xml b/doc/pgprobackup.xml
@@ -3563,6 +3563,14 @@ pg_probackup catchup -b <replaceable>catchup_mode</replaceable> --source-pgdata=
       of threads with the <option>--threads</option> option:
      <programlisting>
 pg_probackup catchup -b <replaceable>catchup_mode</replaceable> --source-pgdata=<replaceable>path_to_pgdata_on_remote_server</replaceable> --destination-pgdata=<replaceable>path_to_local_dir</replaceable> --stream --threads=<replaceable>num_threads</replaceable>
+</programlisting>
+    </para>
+    <para>
+      Before cloning/synchronising a <productname>PostgreSQL</productname> instance, you can run the
+      <command>catchup</command> command with the <option>--dry-run</option> flag
+      to estimate the size of data files to be transferred, but make no changes on disk:
+      <programlisting>
+pg_probackup catchup -b <replaceable>catchup_mode</replaceable> --source-pgdata=<replaceable>path_to_pgdata_on_remote_server</replaceable> --destination-pgdata=<replaceable>path_to_local_dir</replaceable> --stream --dry-run
 </programlisting>
     </para>
     <para>
@@ -3576,7 +3584,7 @@ pg_probackup catchup --source-pgdata=/master-pgdata --destination-pgdata=/replic
     <para>
       Another example shows how you can add a new remote standby server with the <productname>PostgreSQL</productname> data directory <filename>/replica-pgdata</filename> by running the <command>catchup</command> command in the <literal>FULL</literal> mode
       on four parallel threads:
-<programlisting>
+      <programlisting>
 pg_probackup catchup --source-pgdata=/master-pgdata --destination-pgdata=/replica-pgdata -p 5432 -d postgres -U remote-postgres-user --stream --backup-mode=FULL --remote-host=remote-hostname --remote-user=remote-unix-username -j 4
 </programlisting>
     </para>
@@ -4482,7 +4490,7 @@ pg_probackup archive-get -B <replaceable>backup_dir</replaceable> --instance <re
 pg_probackup catchup -b <replaceable>catchup_mode</replaceable>
 --source-pgdata=<replaceable>path_to_pgdata_on_remote_server</replaceable>
 --destination-pgdata=<replaceable>path_to_local_dir</replaceable>
-[--help] [-j | --threads=<replaceable>num_threads</replaceable>] [--stream]
+[--help] [-j | --threads=<replaceable>num_threads</replaceable>] [--stream] [--dry-run]
 [--temp-slot] [-P | --perm-slot] [-S | --slot=<replaceable>slot_name</replaceable>]
 [--exclude-path=<replaceable>PATHNAME</replaceable>]
 [-T <replaceable>OLDDIR</replaceable>=<replaceable>NEWDIR</replaceable>]
@@ -4571,6 +4579,19 @@ pg_probackup catchup -b <replaceable>catchup_mode</replaceable>
       </listitem>
       </varlistentry>
 
+      <varlistentry>
+<term><option>--dry-run</option></term>
+      <listitem>
+      <para>
+        Displays the total size of the files to be transferred by <command>catchup</command>.
+        This flag initiates a trial run of <command>catchup</command>, which does
+        not actually create, delete or move files on disk. WAL streaming is skipped with <option>--dry-run</option>.
+        This flag also allows you to check that
+        all the options are correct and cloning/synchronising is ready to run.
+      </para>
+      </listitem>
+      </varlistentry>
+
       <varlistentry>
 <term><option>-x</option>=<replaceable>path_prefix</replaceable></term>
 <term><option>--exclude-path</option>=<replaceable>path_prefix</replaceable></term>
@@ -4591,17 +4612,6 @@ pg_probackup catchup -b <replaceable>catchup_mode</replaceable>
       </listitem>
       </varlistentry>
 
-      <varlistentry>
-<term><option>--stream</option></term>
-      <listitem>
-      <para>
-        Copies the instance in <link linkend="pbk-stream-mode">STREAM</link> WAL delivery mode,
-        including all the necessary WAL files by streaming them from
-        the instance server via replication protocol.
-      </para>
-      </listitem>
-      </varlistentry>
-
       <varlistentry>
 <term><option>--temp-slot</option></term>
       <listitem>
