Make pg_basebackup ask the server to estimate the total backup size, by default.

This commit changes pg_basebackup so that it specifies PROGRESS option in
BASE_BACKUP replication command whether --progress is specified or not.
This causes the server to estimate the total backup size and report it in
pg_stat_progress_basebackup.backup_total, by default. This is reasonable
default because the time required for the estimation would not be so large
in most cases.

Also this commit adds new option --no-estimate-size to pg_basebackup.
This option prevents the server from the estimation, and so is useful to
avoid such estimation time if it's too long.

Author: Fujii Masao
Reviewed-by: Magnus Hagander, Amit Langote
Discussion: https://postgr.es/m/CABUevEyDPPSjP7KRvfTXPdqOdY5aWNkqsB5aAXs3bco5ZwtGHg@mail.gmail.com

2 files changed, 29 insertions, 20 deletions

diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index 89853a16d82..5bffdcce10d 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -4392,10 +4392,7 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid,
      <entry><structfield>backup_total</structfield></entry>
      <entry><type>bigint</type></entry>
      <entry>
-      Total amount of data that will be streamed. If progress reporting
-      is not enabled in <application>pg_basebackup</application>
-      (i.e., <literal>--progress</literal> option is not specified),
-      this is <literal>0</literal>. Otherwise, this is estimated and
+      Total amount of data that will be streamed. This is estimated and
       reported as of the beginning of
       <literal>streaming database files</literal> phase. Note that
       this is only an approximation since the database
@@ -4403,7 +4400,10 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid,
       and WAL log may be included in the backup later. This is always
       the same value as <structfield>backup_streamed</structfield>
       once the amount of data streamed exceeds the estimated
-      total size.
+      total size. If the estimation is disabled in
+      <application>pg_basebackup</application>
+      (i.e., <literal>--no-estimate-size</literal> option is specified),
+      this is <literal>0</literal>.
      </entry>
     </row>
     <row>
diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml
index 29bf2f9b979..90638aad0e2 100644
--- a/doc/src/sgml/ref/pg_basebackup.sgml
+++ b/doc/src/sgml/ref/pg_basebackup.sgml
@@ -460,21 +460,6 @@ PostgreSQL documentation
         in this case the estimated target size will increase once it passes the
         total estimate without WAL.
        </para>
-       <para>
-        When this is enabled, the backup will start by enumerating the size of
-        the entire database, and then go back and send the actual contents.
-        This may make the backup take slightly longer, and in particular it
-        will take longer before the first data is sent.
-       </para>
-       <para>
-        Whether this is enabled or not, the
-        <structname>pg_stat_progress_basebackup</structname> view
-        report the progress of the backup in the server side. But note
-        that the total amount of data that will be streamed is estimated
-        and reported only when this option is enabled. In other words,
-        <literal>backup_total</literal> column in the view always
-        indicates <literal>0</literal> if this option is disabled.
-       </para>
       </listitem>
      </varlistentry>
 
@@ -552,6 +537,30 @@ PostgreSQL documentation
        </para>
       </listitem>
      </varlistentry>
+
+     <varlistentry>
+      <term><option>--no-estimate-size</option></term>
+      <listitem>
+       <para>
+        This option prevents the server from estimating the total
+        amount of backup data that will be streamed, resulting in the
+        <literal>backup_total</literal> column in the
+        <structname>pg_stat_progress_basebackup</structname>
+        to be <literal>0</literal>.
+       </para>
+       <para>
+        Without this option, the backup will start by enumerating
+        the size of the entire database, and then go back and send
+        the actual contents. This may make the backup take slightly
+        longer, and in particular it will take longer before the first
+        data is sent. This option is useful to avoid such estimation
+        time if it's too long.
+       </para>
+       <para>
+        This option is not allowed when using <option>--progress</option>.
+       </para>
+      </listitem>
+     </varlistentry>
     </variablelist>
    </para>