granicus.if.org Git - postgresql/blob - doc/src/sgml/pgarchivecleanup.sgml

   1 <!-- doc/src/sgml/pgarchivecleanup.sgml -->
   2
   3 <sect1 id="pgarchivecleanup">
   4  <title>pg_archivecleanup</title>
   5
   6  <indexterm zone="pgarchivecleanup">
   7   <primary>pg_archivecleanup</primary>
   8  </indexterm>
   9
  10  <para>
  11   <application>pg_archivecleanup</> is designed to cleanup an archive when used
  12   as an <literal>archive_cleanup_command</literal> when running with
  13   <literal>standby_mode = on</literal>. <application>pg_archivecleanup</> can
  14   also be used as a standalone program to clean WAL file archives.
  15  </para>
  16
  17  <para>
  18   <application>pg_archivecleanup</application> features include:
  19  </para>
  20  <itemizedlist>
  21   <listitem>
  22    <para>
  23     Written in C, so very portable and easy to install
  24    </para>
  25   </listitem>
  26   <listitem>
  27    <para>
  28     Easy-to-modify source code, with specifically designated
  29     sections to modify for your own needs
  30    </para>
  31   </listitem>
  32  </itemizedlist>
  33
  34  <sect2>
  35   <title>Usage</title>
  36
  37   <para>
  38    To configure a standby
  39    server to use <application>pg_archivecleanup</>, put this into its
  40    <filename>recovery.conf</filename> configuration file:
  41 <programlisting>
  42 archive_cleanup_command = 'pg_archivecleanup <replaceable>archiveDir</> %r'
  43 </programlisting>
  44    where <replaceable>archiveDir</> is the directory from which WAL segment
  45    files should be restored.
  46   </para>
  47   <para>
  48    When used within <literal>archive_cleanup_command</literal>,
  49    all WAL files logically preceding the value of the <literal>%r</>
  50    will be removed <replaceable>archivelocation</>. This minimizes
  51    the number of files that need to be retained, while preserving
  52    crash-restart capability.  Use of this parameter is appropriate if the
  53    <replaceable>archivelocation</> is a transient staging area for this
  54    particular standby server, but <emphasis>not</> when the
  55    <replaceable>archivelocation</> is intended as a long-term WAL archive area.
  56   </para>
  57   <para>
  58    The full syntax of <application>pg_archivecleanup</>'s command line is
  59 <synopsis>
  60 pg_archivecleanup <optional> <replaceable>option</> ... </optional> <replaceable>archivelocation</> <replaceable>restartwalfile</>
  61 </synopsis>
  62    When used as a standalone program all WAL files logically preceding the
  63    <literal>restartwalfile</> will be removed <replaceable>archivelocation</>.
  64    In this mode, if you specify a <filename>.backup</> file name, then only the file prefix
  65    will be used as the <literal>restartwalfile</>. This allows you to remove
  66    all WAL files archived prior to a specific base backup without error.
  67    For example, the following example will remove all files older than
  68    WAL file name <filename>000000010000003700000010</>:
  69 <programlisting>
  70 pg_archivecleanup -d archive 000000010000003700000010.00000020.backup
  71
  72 pg_archivecleanup:  keep WAL files 000000010000003700000010 and later
  73 pg_archivecleanup:  removing "archive/00000001000000370000000F"
  74 pg_archivecleanup:  removing "archive/00000001000000370000000E"
  75 </programlisting>
  76    <application>pg_archivecleanup</application> assumes that
  77    <replaceable>archivelocation</> is a directory readable and writable by the
  78    server-owning user.
  79   </para>
  80  </sect2>
  81
  82  <sect2>
  83   <title><application>pg_archivecleanup</> Options</title>
  84
  85    <para>
  86     <application>pg_archivecleanup</application> accepts the following command-line arguments:
  87
  88     <variablelist>
  89
  90      <varlistentry>
  91       <term><option>-d</option></term>
  92       <listitem>
  93        <para>
  94         Print lots of debug logging output on <filename>stderr</>.
  95        </para>
  96       </listitem>
  97      </varlistentry>
  98
  99     </variablelist>
 100    </para>
 101
 102  </sect2>
 103
 104  <sect2>
 105   <title>Examples</title>
 106
 107   <para>On Linux or Unix systems, you might use:
 108 <programlisting>
 109 archive_cleanup_command = 'pg_archivecleanup -d /mnt/standby/archive %r 2>>cleanup.log'
 110 </programlisting>
 111    where the archive directory is physically located on the standby server,
 112    so that the <literal>archive_command</> is accessing it across NFS,
 113    but the files are local to the standby.
 114    This will:
 115   </para>
 116   <itemizedlist>
 117    <listitem>
 118     <para>
 119      produce debugging output in <filename>cleanup.log</>
 120     </para>
 121    </listitem>
 122    <listitem>
 123     <para>
 124      remove no-longer-needed files from the archive directory
 125     </para>
 126    </listitem>
 127   </itemizedlist>
 128
 129  </sect2>
 130
 131  <sect2>
 132   <title>Supported server versions</title>
 133
 134   <para>
 135    <application>pg_archivecleanup</application> is designed to work with
 136    <productname>PostgreSQL</> 8.0 and later when used as a standalone utility,
 137    or with <productname>PostgreSQL</> 9.0 and later when used as an
 138    archive cleanup command.
 139   </para>
 140  </sect2>
 141
 142  <sect2>
 143   <title>Author</title>
 144
 145   <para>
 146    Simon Riggs <email>simon@2ndquadrant.com</email>
 147   </para>
 148  </sect2>
 149
 150 </sect1>