diff options
Diffstat (limited to 'doc/src/sgml/ref')
| -rw-r--r-- | doc/src/sgml/ref/allfiles.sgml | 1 | ||||
| -rw-r--r-- | doc/src/sgml/ref/pgarchivecleanup.sgml | 203 |
2 files changed, 204 insertions, 0 deletions
diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml index 5b4692fb6d8..f3b577119bd 100644 --- a/doc/src/sgml/ref/allfiles.sgml +++ b/doc/src/sgml/ref/allfiles.sgml @@ -179,6 +179,7 @@ Complete list of usable sgml source files in this directory. <!ENTITY dropuser SYSTEM "dropuser.sgml"> <!ENTITY ecpgRef SYSTEM "ecpg-ref.sgml"> <!ENTITY initdb SYSTEM "initdb.sgml"> +<!ENTITY pgarchivecleanup SYSTEM "pgarchivecleanup.sgml"> <!ENTITY pgBasebackup SYSTEM "pg_basebackup.sgml"> <!ENTITY pgConfig SYSTEM "pg_config-ref.sgml"> <!ENTITY pgControldata SYSTEM "pg_controldata.sgml"> diff --git a/doc/src/sgml/ref/pgarchivecleanup.sgml b/doc/src/sgml/ref/pgarchivecleanup.sgml new file mode 100644 index 00000000000..779159d7fc2 --- /dev/null +++ b/doc/src/sgml/ref/pgarchivecleanup.sgml @@ -0,0 +1,203 @@ +<!-- doc/src/sgml/ref/pgarchivecleanup.sgml --> + +<refentry id="pgarchivecleanup"> + <indexterm zone="pgarchivecleanup"> + <primary>pg_archivecleanup</primary> + </indexterm> + + <refmeta> + <refentrytitle><application>pg_archivecleanup</application></refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo>Application</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>pg_archivecleanup</refname> + <refpurpose>clean up <productname>PostgreSQL</productname> WAL archive files</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>pg_archivecleanup</command> + <arg rep="repeat"><replaceable>option</replaceable></arg> + <arg choice="plain"><replaceable>archivelocation</replaceable></arg> + <arg choice="plain"><replaceable>oldestkeptwalfile</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <application>pg_archivecleanup</> is designed to be used as an + <literal>archive_cleanup_command</literal> to clean up WAL file archives when + running as a standby server (see <xref linkend="warm-standby">). + <application>pg_archivecleanup</> can also be used as a standalone program to + clean WAL file archives. + </para> + + <para> + To configure a standby + server to use <application>pg_archivecleanup</>, put this into its + <filename>recovery.conf</filename> configuration file: +<programlisting> +archive_cleanup_command = 'pg_archivecleanup <replaceable>archivelocation</> %r' +</programlisting> + where <replaceable>archivelocation</> is the directory from which WAL segment + files should be removed. + </para> + <para> + When used within <xref linkend="archive-cleanup-command">, all WAL files + logically preceding the value of the <literal>%r</> argument will be removed + from <replaceable>archivelocation</>. This minimizes the number of files + that need to be retained, while preserving crash-restart capability. Use of + this parameter is appropriate if the <replaceable>archivelocation</> is a + transient staging area for this particular standby server, but + <emphasis>not</> when the <replaceable>archivelocation</> is intended as a + long-term WAL archive area, or when multiple standby servers are recovering + from the same archive location. + </para> + <para> + When used as a standalone program all WAL files logically preceding the + <replaceable>oldestkeptwalfile</> will be removed from <replaceable>archivelocation</>. + In this mode, if you specify a <filename>.backup</> file name, then only the file prefix + will be used as the <replaceable>oldestkeptwalfile</>. This allows you to remove + all WAL files archived prior to a specific base backup without error. + For example, the following example will remove all files older than + WAL file name <filename>000000010000003700000010</>: +<programlisting> +pg_archivecleanup -d archive 000000010000003700000010.00000020.backup + +pg_archivecleanup: keep WAL file "archive/000000010000003700000010" and later +pg_archivecleanup: removing file "archive/00000001000000370000000F" +pg_archivecleanup: removing file "archive/00000001000000370000000E" +</programlisting> + </para> + <para> + <application>pg_archivecleanup</application> assumes that + <replaceable>archivelocation</> is a directory readable and writable by the + server-owning user. + </para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para> + <application>pg_archivecleanup</application> accepts the following command-line arguments: + + <variablelist> + + <varlistentry> + <term><option>-d</option></term> + <listitem> + <para> + Print lots of debug logging output on <filename>stderr</>. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-n</option></term> + <listitem> + <para> + Print the names of the files that would have been removed on <filename>stdout</> (performs a dry run). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-V</></term> + <term><option>--version</></term> + <listitem> + <para> + Print the <application>pg_archivecleanup</application> version and exit. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-x</option> <replaceable>extension</></term> + <listitem> + <para> + When using the program as a standalone utility, provide an extension + that will be stripped from all file names before deciding if they + should be deleted. This is typically useful for cleaning up archives + that have been compressed during storage, and therefore have had an + extension added by the compression program. For example: <literal>-x + .gz</literal>. + </para> + + <para> + Note that the + <filename>.backup</> file name passed to the program should not + include the extension. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-?</></term> + <term><option>--help</></term> + <listitem> + <para> + Show help about <application>pg_archivecleanup</application> command line + arguments, and exit. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para> + <application>pg_archivecleanup</application> is designed to work with + <productname>PostgreSQL</> 8.0 and later when used as a standalone utility, + or with <productname>PostgreSQL</> 9.0 and later when used as an + archive cleanup command. + </para> + + <para> + <application>pg_archivecleanup</application> is written in C and has an + easy-to-modify source code, with specifically designated sections to modify + for your own needs + </para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para>On Linux or Unix systems, you might use: +<programlisting> +archive_cleanup_command = 'pg_archivecleanup -d /mnt/standby/archive %r 2>>cleanup.log' +</programlisting> + where the archive directory is physically located on the standby server, + so that the <varname>archive_command</> is accessing it across NFS, + but the files are local to the standby. + This will: + </para> + <itemizedlist> + <listitem> + <para> + produce debugging output in <filename>cleanup.log</> + </para> + </listitem> + <listitem> + <para> + remove no-longer-needed files from the archive directory + </para> + </listitem> + </itemizedlist> + </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="pgstandby"></member> + </simplelist> + </refsect1> +</refentry> |