DOC: review retention-related pbk docs - PBCKP-95

Author: Liudmila Mantrova

doc/pgprobackup.xml

@@ -1475,7 +1475,7 @@ pg_probackup checkdb [-B <replaceable>backup_dir</replaceable> [--instance <repl
       enough to specify the backup instance of this cluster for
       <application>pg_probackup</application> to determine the required
       connection options. However, if <literal>-B</literal> and
-      <literal>--instance</literal> options are ommitted, you have to provide
+      <literal>--instance</literal> options are omitted, you have to provide
       <link linkend="pbk-connection-opts">connection options</link> and
       <replaceable>data_dir</replaceable> via environment
       variables or command-line options.
@@ -2364,7 +2364,8 @@ primary_conninfo = 'user=backup passfile=/var/lib/pgsql/.pgpass port=5432 sslmod
         <listitem>
         <para>
           <literal>expire-time</literal> — the point in time
-          when a pinned backup can be removed by retention purge.
+          when a pinned backup can be removed in accordance with retention
+          policy. This attribute is only available for pinned backups.
         </para>
         </listitem>
         <listitem>
@@ -2808,17 +2809,19 @@ pg_probackup show -B <replaceable>backup_dir</replaceable> [--instance <replacea
   <refsect2 id="pbk-configuring-retention-policy">
     <title>Configuring Retention Policy</title>
     <para>
-      With <application>pg_probackup</application>, you can set retention policies for backups
-      and WAL archive. All policies can be combined together in any
-      way.
+      With <application>pg_probackup</application>, you can configure
+      retention policy to remove redundant backups, clean up unneeded
+      WAL files, as well as pin specific backups to ensure they are
+      kept for the specified time, as explained in the sections below.
+      All these actions can be combined together in any way.
     </para>
+
     <refsect3 id="pbk-retention-policy">
-      <title>Backup Retention Policy</title>
+      <title>Removing Redundant Backups</title>
       <para>
         By default, all backup copies created with <application>pg_probackup</application> are
         stored in the specified backup catalog. To save disk space,
-        you can configure retention policy and periodically clean up
-        redundant backup copies accordingly.
+        you can configure retention policy to remove redundant backup copies.
       </para>
       <para>
         To configure retention policy, set one or more of the
@@ -2841,56 +2844,51 @@ pg_probackup show -B <replaceable>backup_dir</replaceable> [--instance <replacea
         <emphasis role="strong">the number of days</emphasis> from the
         current moment. For example, if
         <literal>retention-window=7</literal>, <application>pg_probackup</application> must
-        delete all backup copies that are older than seven days, with
-        all the corresponding WAL files.
+        keep at least one backup copy that is older than seven days, with
+        all the corresponding WAL files, and all the backups that follow.
       </para>
       <para>
         If both <option>--retention-redundancy</option> and
-        <option>--retention-window</option> options are set,
-        <application>pg_probackup</application> keeps backup copies that satisfy at least one
-        condition. For example, if you set
-        <literal>--retention-redundancy=2</literal> and
-        <literal>--retention-window=7</literal>, <application>pg_probackup</application> purges
-        the backup catalog to keep only two full backup copies and all
-        backups that are newer than seven days:
+        <option>--retention-window</option> options are set, both these
+        conditions have to be taken into account when purging the backup
+        catalog. For example, if you set <literal>--retention-redundancy=2</literal>
+        and <literal>--retention-window=7</literal>,
+        <application>pg_probackup</application> has to keep two full backup
+        copies, as well as all the backups required to ensure recoverability
+        for the last seven days:
       </para>
       <programlisting>
 pg_probackup set-config -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --retention-redundancy=2 --retention-window=7
 </programlisting>
+
+      <para>
+        To clean up the backup catalog in accordance with retention policy,
+        you have to run the <xref linkend="pbk-delete"/> command with
+        <link linkend="pbk-retention-opts">retention flags</link>, as shown
+        below, or use the <xref linkend="pbk-backup"/> command with
+        these flags to process the outdated backup copies right when the new
+        backup is created.
+      </para>
+
       <para>
-        To clean up the backup catalog in accordance with retention
-        policy, run:
+        For example, to remove all backup copies that no longer satisfy the
+        defined retention policy, run the following command with the
+        <literal>--delete-expired</literal> flag:
       </para>
       <programlisting>
 pg_probackup delete -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --delete-expired
 </programlisting>
-      <para>
-        <application>pg_probackup</application> deletes all backup copies that do not conform to
-        the defined retention policy.
-      </para>
       <para>
         If you would like to also remove the WAL files that are no
-        longer required for any of the backups, add the
+        longer required for any of the backups, you should also specify the
         <option>--delete-wal</option> flag:
       </para>
       <programlisting>
 pg_probackup delete -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> --delete-expired --delete-wal
 </programlisting>
-      <note>
-        <para>
-          Alternatively, you can use the
-          <option>--delete-expired</option>,
-          <option>--merge-expired</option>,
-          <option>--delete-wal</option> flags and the
-          <option>--retention-window</option> and
-          <option>--retention-redundancy</option> options together
-          with the <xref linkend="pbk-backup"/> command to
-          remove and merge the outdated backup copies once the new
-          backup is created.
-        </para>
-      </note>
+
       <para>
-        You can set or override the current retention policy by
+        You can also set or override the current retention policy by
         specifying <option>--retention-redundancy</option> and
         <option>--retention-window</option> options directly when
         running <command>delete</command> or <command>backup</command>
@@ -2911,6 +2909,7 @@ pg_probackup delete -B <replaceable>backup_dir</replaceable> --instance <replace
         <xref linkend="pbk-backup"/> or
         <xref linkend="pbk-delete"/> commands.
       </para>
+
       <para>
         Suppose you have backed up the <replaceable>node</replaceable>
         instance in the <replaceable>backup_dir</replaceable> directory,
@@ -2963,9 +2962,10 @@ BACKUP INSTANCE 'node'
           The <literal>Time</literal> field for the merged backup displays the time
           required for the merge.
         </para>
+
     </refsect3>
     <refsect3 id="pbk-backup-pinning">
-      <title>Backup Pinning</title>
+      <title>Pinning Backups</title>
       <para>
         If you need to keep certain backups longer than the
         established retention policy allows, you can pin them
@@ -3004,8 +3004,8 @@ pg_probackup show -B <replaceable>backup_dir</replaceable> --instance <replaceab
 </programlisting>
       </para>
       <para>
-        If the backup is pinned, the <literal>expire-time</literal>
-        attribute displays its expiration time:
+        If the backup is pinned, it has the <literal>expire-time</literal>
+        attribute that displays its expiration time:
       <programlisting>
 ...
 recovery-time = '2017-05-16 12:57:31'
@@ -3015,34 +3015,65 @@ data-bytes = 22288792
 </programlisting>
       </para>
       <para>
-        Only pinned backups have the <literal>expire-time</literal>
-        attribute in the backup metadata.
+        You can unpin the backup by setting the <option>--ttl</option> option to zero:
       </para>
+      <programlisting>
+pg_probackup set-backup -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> -i <replaceable>backup_id</replaceable> --ttl=0
+</programlisting>
+
       <note>
         <para>
           A pinned incremental backup implicitly pins all
-          its parent backups.
+          its parent backups. If you unpin such a backup later,
+          its implicitly pinned parents will also be automatically unpinned.
         </para>
       </note>
-      <para>
-        You can unpin the backup by setting the
-        <option>--ttl</option> option to zero using the
-        <xref linkend="pbk-set-backup"/> command. For example:
-      </para>
-      <programlisting>
-pg_probackup set-backup -B <replaceable>backup_dir</replaceable> --instance <replaceable>instance_name</replaceable> -i <replaceable>backup_id</replaceable> --ttl=0
-</programlisting>
 
     </refsect3>
     <refsect3 id="pbk-wal-archive-retention-policy">
-      <title>WAL Archive Retention Policy</title>
+      <title>Configuring WAL Archive Retention Policy</title>
+      <para>
+        When <link linkend="pbk-setting-up-continuous-wal-archiving">continuous
+        WAL archiving</link> is enabled, archived WAL segments can take a lot
+        of disk space. Even if you delete old backup copies from time to time,
+        the <literal>--delete-wal</literal> flag can
+        purge only those WAL segments that do not apply to any of the
+        remaining backups in the backup catalog. However, if point-in-time
+        recovery is critical only for the most recent backups, you can
+        configure WAL archive retention policy to keep WAL archive of
+        limited depth and win back some more disk space.
+      </para>
+
+      <para>
+        To configure WAL archive retention policy, you have to run the
+        <xref linkend="pbk-set-config"/> command with the
+        <literal>--wal-depth</literal> option that specifies the number
+        of backups that can be used for PITR.
+        This setting applies to all the timelines, so you should be able to perform
+        PITR for the same number of backups on each timeline, if available.
+        <link linkend="pbk-backup-pinning">Pinned backups</link> are
+        not included into this count: if one of the latest backups
+        is pinned, <application>pg_probackup</application> ensures that
+        PITR is possible for one extra backup.
+      </para>
+
       <para>
-        By default, <application>pg_probackup</application> purges
-        only redundant WAL segments that cannot be applied to any of the
-        backups in the backup catalog. To save disk space,
-        you can configure WAL archive retention policy, which allows to
-        keep WAL of limited depth measured in backups per timeline.
+       To remove WAL segments that do not satisfy the defined WAL archive
+       retention policy, you simply have to run the <xref linkend="pbk-delete"/>
+       or <xref linkend="pbk-backup"/> command with the <literal>--delete-wal</literal>
+       flag. For archive backups, WAL segments between <literal>Start LSN</literal>
+       and <literal>Stop LSN</literal> are always kept intact, so such backups
+       remain valid regardless of the <literal>--wal-depth</literal> setting
+       and can still be restored, if required.
       </para>
+
+      <para>
+        You can also use the <option>--wal-depth</option> option
+        with the <xref linkend="pbk-delete"/> and <xref linkend="pbk-backup"/>
+        commands to override the previously defined WAL archive retention
+        policy and purge old WAL segments on the fly.
+      </para>
+
       <para>
         Suppose you have backed up the <literal>node</literal>
         instance in the <replaceable>backup_dir</replaceable> directory and
@@ -3096,8 +3127,8 @@ ARCHIVE INSTANCE 'node'
 </programlisting>
       <para>
         If you would like, for example, to keep only those WAL
-        segments that can be applied to the last valid backup, use the
-        <option>--wal-depth</option> option:
+        segments that can be applied to the latest valid backup, set the
+        <option>--wal-depth</option> option to 1:
       </para>
       <programlisting>
 pg_probackup delete -B <replaceable>backup_dir</replaceable> --instance node --delete-wal --wal-depth=1
@@ -3123,12 +3154,6 @@ ARCHIVE INSTANCE 'node'
 ===============================================================================================================================
  1    0           0/0          000000010000000000000048  000000010000000000000049  1           72kB  228.00  7          OK
 </programlisting>
-      <note>
-        <para>
-          <link linkend="pbk-backup-pinning">Pinned backups</link> are
-          ignored for the purpose of WAL Archive Retention Policy fulfilment.
-        </para>
-      </note>
     </refsect3>
   </refsect2>
   <refsect2 id="pbk-merging-backups">
@@ -4130,7 +4155,7 @@ pg_probackup archive-get -B <replaceable>backup_dir</replaceable> --instance <re
             The <literal>immediate</literal> value stops the recovery
             after reaching the consistent state of the specified
             backup, or the latest available backup if the
-            <option>-i</option>/<option>--backup_id</option> option is omitted.
+            <option>-i</option>/<option>--backup-id</option> option is omitted.
             This is the default behavior for STREAM backups.
           </para>
         </listitem>