| 1 |
<!-- |
| 2 |
doc/src/sgml/ref/pgarchivecleanup.sgml |
| 3 |
PostgreSQL documentation |
| 4 |
--> |
| 5 |
|
| 6 |
<refentry id="pgarchivecleanup"> |
| 7 |
<indexterm zone="pgarchivecleanup"> |
| 8 |
<primary>pg_archivecleanup</primary> |
| 9 |
</indexterm> |
| 10 |
|
| 11 |
<refmeta> |
| 12 |
<refentrytitle><application>pg_archivecleanup</application></refentrytitle> |
| 13 |
<manvolnum>1</manvolnum> |
| 14 |
<refmiscinfo>Application</refmiscinfo> |
| 15 |
</refmeta> |
| 16 |
|
| 17 |
<refnamediv> |
| 18 |
<refname>pg_archivecleanup</refname> |
| 19 |
<refpurpose>clean up <productname>PostgreSQL</productname> WAL archive files</refpurpose> |
| 20 |
</refnamediv> |
| 21 |
|
| 22 |
<refsynopsisdiv> |
| 23 |
<cmdsynopsis> |
| 24 |
<command>pg_archivecleanup</command> |
| 25 |
<arg rep="repeat"><replaceable>option</replaceable></arg> |
| 26 |
<arg choice="plain"><replaceable>archivelocation</replaceable></arg> |
| 27 |
<arg choice="plain"><replaceable>oldestkeptwalfile</replaceable></arg> |
| 28 |
</cmdsynopsis> |
| 29 |
</refsynopsisdiv> |
| 30 |
|
| 31 |
<refsect1> |
| 32 |
<title>Description</title> |
| 33 |
|
| 34 |
<para> |
| 35 |
<application>pg_archivecleanup</application> is designed to be used as an |
| 36 |
<literal>archive_cleanup_command</literal> to clean up WAL file archives when |
| 37 |
running as a standby server (see <xref linkend="warm-standby"/>). |
| 38 |
<application>pg_archivecleanup</application> can also be used as a standalone program to |
| 39 |
clean WAL file archives. |
| 40 |
</para> |
| 41 |
|
| 42 |
<para> |
| 43 |
To configure a standby |
| 44 |
server to use <application>pg_archivecleanup</application>, put this into its |
| 45 |
<filename>postgresql.conf</filename> configuration file: |
| 46 |
<programlisting> |
| 47 |
archive_cleanup_command = 'pg_archivecleanup <replaceable>archivelocation</replaceable> %r' |
| 48 |
</programlisting> |
| 49 |
where <replaceable>archivelocation</replaceable> is the directory from which WAL segment |
| 50 |
files should be removed. |
| 51 |
</para> |
| 52 |
<para> |
| 53 |
When used within <xref linkend="guc-archive-cleanup-command"/>, all WAL files |
| 54 |
logically preceding the value of the <literal>%r</literal> argument will be removed |
| 55 |
from <replaceable>archivelocation</replaceable>. This minimizes the number of files |
| 56 |
that need to be retained, while preserving crash-restart capability. Use of |
| 57 |
this parameter is appropriate if the <replaceable>archivelocation</replaceable> is a |
| 58 |
transient staging area for this particular standby server, but |
| 59 |
<emphasis>not</emphasis> when the <replaceable>archivelocation</replaceable> is intended as a |
| 60 |
long-term WAL archive area, or when multiple standby servers are recovering |
| 61 |
from the same archive location. |
| 62 |
</para> |
| 63 |
<para> |
| 64 |
When used as a standalone program all WAL files logically preceding the |
| 65 |
<replaceable>oldestkeptwalfile</replaceable> will be removed from <replaceable>archivelocation</replaceable>. |
| 66 |
In this mode, if you specify a <filename>.partial</filename> or <filename>.backup</filename> |
| 67 |
file name, then only the file prefix will be used as the |
| 68 |
<replaceable>oldestkeptwalfile</replaceable>. This treatment of <filename>.backup</filename> |
| 69 |
file name allows you to remove |
| 70 |
all WAL files archived prior to a specific base backup without error. |
| 71 |
For example, the following example will remove all files older than |
| 72 |
WAL file name <filename>000000010000003700000010</filename>: |
| 73 |
<programlisting> |
| 74 |
pg_archivecleanup -d archive 000000010000003700000010.00000020.backup |
| 75 |
|
| 76 |
pg_archivecleanup: keep WAL file "archive/000000010000003700000010" and later |
| 77 |
pg_archivecleanup: removing file "archive/00000001000000370000000F" |
| 78 |
pg_archivecleanup: removing file "archive/00000001000000370000000E" |
| 79 |
</programlisting> |
| 80 |
</para> |
| 81 |
<para> |
| 82 |
<application>pg_archivecleanup</application> assumes that |
| 83 |
<replaceable>archivelocation</replaceable> is a directory readable and writable by the |
| 84 |
server-owning user. |
| 85 |
</para> |
| 86 |
</refsect1> |
| 87 |
|
| 88 |
<refsect1> |
| 89 |
<title>Options</title> |
| 90 |
|
| 91 |
<para> |
| 92 |
<application>pg_archivecleanup</application> accepts the following command-line arguments: |
| 93 |
|
| 94 |
<variablelist> |
| 95 |
|
| 96 |
<varlistentry> |
| 97 |
<term><option>-b</option></term> |
| 98 |
<term><option>--clean-backup-history</option></term> |
| 99 |
<listitem> |
| 100 |
<para> |
| 101 |
Remove backup history files as well. |
| 102 |
See <xref linkend="backup-base-backup"/> for details about backup |
| 103 |
history files. |
| 104 |
</para> |
| 105 |
</listitem> |
| 106 |
</varlistentry> |
| 107 |
|
| 108 |
<varlistentry> |
| 109 |
<term><option>-d</option></term> |
| 110 |
<term><option>--debug</option></term> |
| 111 |
<listitem> |
| 112 |
<para> |
| 113 |
Print lots of debug logging output on <filename>stderr</filename>. |
| 114 |
</para> |
| 115 |
</listitem> |
| 116 |
</varlistentry> |
| 117 |
|
| 118 |
<varlistentry> |
| 119 |
<term><option>-n</option></term> |
| 120 |
<term><option>--dry-run</option></term> |
| 121 |
<listitem> |
| 122 |
<para> |
| 123 |
Print the names of the files that would have been removed on <filename>stdout</filename> (performs a dry run). |
| 124 |
</para> |
| 125 |
</listitem> |
| 126 |
</varlistentry> |
| 127 |
|
| 128 |
<varlistentry> |
| 129 |
<term><option>-V</option></term> |
| 130 |
<term><option>--version</option></term> |
| 131 |
<listitem> |
| 132 |
<para> |
| 133 |
Print the <application>pg_archivecleanup</application> version and exit. |
| 134 |
</para> |
| 135 |
</listitem> |
| 136 |
</varlistentry> |
| 137 |
|
| 138 |
<varlistentry> |
| 139 |
<term><option>-x <replaceable class="parameter">extension</replaceable></option></term> |
| 140 |
<term><option>--strip-extension=<replaceable class="parameter">extension</replaceable></option></term> |
| 141 |
<listitem> |
| 142 |
<para> |
| 143 |
Provide an extension |
| 144 |
that will be stripped from all file names before deciding if they |
| 145 |
should be deleted. This is typically useful for cleaning up archives |
| 146 |
that have been compressed during storage, and therefore have had an |
| 147 |
extension added by the compression program. For example: <literal>-x |
| 148 |
.gz</literal>. |
| 149 |
</para> |
| 150 |
|
| 151 |
</listitem> |
| 152 |
</varlistentry> |
| 153 |
|
| 154 |
<varlistentry> |
| 155 |
<term><option>-?</option></term> |
| 156 |
<term><option>--help</option></term> |
| 157 |
<listitem> |
| 158 |
<para> |
| 159 |
Show help about <application>pg_archivecleanup</application> command line |
| 160 |
arguments, and exit. |
| 161 |
</para> |
| 162 |
</listitem> |
| 163 |
</varlistentry> |
| 164 |
</variablelist> |
| 165 |
</para> |
| 166 |
</refsect1> |
| 167 |
|
| 168 |
<refsect1> |
| 169 |
<title>Environment</title> |
| 170 |
|
| 171 |
<para> |
| 172 |
The environment variable <envar>PG_COLOR</envar> specifies whether to use |
| 173 |
color in diagnostic messages. Possible values are |
| 174 |
<literal>always</literal>, <literal>auto</literal> and |
| 175 |
<literal>never</literal>. |
| 176 |
</para> |
| 177 |
</refsect1> |
| 178 |
|
| 179 |
<refsect1> |
| 180 |
<title>Notes</title> |
| 181 |
|
| 182 |
<para> |
| 183 |
<application>pg_archivecleanup</application> is designed to work with |
| 184 |
<productname>PostgreSQL</productname> 8.0 and later when used as a standalone utility, |
| 185 |
or with <productname>PostgreSQL</productname> 9.0 and later when used as an |
| 186 |
archive cleanup command. |
| 187 |
</para> |
| 188 |
|
| 189 |
<para> |
| 190 |
<application>pg_archivecleanup</application> is written in C and has an |
| 191 |
easy-to-modify source code, with specifically designated sections to modify |
| 192 |
for your own needs |
| 193 |
</para> |
| 194 |
</refsect1> |
| 195 |
|
| 196 |
<refsect1> |
| 197 |
<title>Examples</title> |
| 198 |
|
| 199 |
<para>On Linux or Unix systems, you might use: |
| 200 |
<programlisting> |
| 201 |
archive_cleanup_command = 'pg_archivecleanup -d /mnt/standby/archive %r 2>>cleanup.log' |
| 202 |
</programlisting> |
| 203 |
where the archive directory is physically located on the standby server, |
| 204 |
so that the <varname>archive_command</varname> is accessing it across NFS, |
| 205 |
but the files are local to the standby. |
| 206 |
This will: |
| 207 |
</para> |
| 208 |
<itemizedlist> |
| 209 |
<listitem> |
| 210 |
<para> |
| 211 |
produce debugging output in <filename>cleanup.log</filename> |
| 212 |
</para> |
| 213 |
</listitem> |
| 214 |
<listitem> |
| 215 |
<para> |
| 216 |
remove no-longer-needed files from the archive directory |
| 217 |
</para> |
| 218 |
</listitem> |
| 219 |
</itemizedlist> |
| 220 |
</refsect1> |
| 221 |
|
| 222 |
</refentry> |