begriffs open source - ai-pg/blob - full-docs/man1/pg_archivecleanup.1

   1 '\" t
   2 .\"     Title: pg_archivecleanup
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "PG_ARCHIVECLEANUP" "1" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 pg_archivecleanup \- clean up PostgreSQL WAL archive files
  32 .SH "SYNOPSIS"
  33 .HP \w'\fBpg_archivecleanup\fR\ 'u
  34 \fBpg_archivecleanup\fR [\fIoption\fR...] \fIarchivelocation\fR \fIoldestkeptwalfile\fR
  35 .SH "DESCRIPTION"
  36 .PP
  37 pg_archivecleanup
  38 is designed to be used as an
  39 archive_cleanup_command
  40 to clean up WAL file archives when running as a standby server (see
  41 Section\ \&26.2)\&.
  42 pg_archivecleanup
  43 can also be used as a standalone program to clean WAL file archives\&.
  44 .PP
  45 To configure a standby server to use
  46 pg_archivecleanup, put this into its
  47 postgresql\&.conf
  48 configuration file:
  49 .sp
  50 .if n \{\
  51 .RS 4
  52 .\}
  53 .nf
  54 archive_cleanup_command = \*(Aqpg_archivecleanup \fIarchivelocation\fR %r\*(Aq
  55 .fi
  56 .if n \{\
  57 .RE
  58 .\}
  59 .sp
  60 where
  61 \fIarchivelocation\fR
  62 is the directory from which WAL segment files should be removed\&.
  63 .PP
  64 When used within
  65 archive_cleanup_command, all WAL files logically preceding the value of the
  66 %r
  67 argument will be removed from
  68 \fIarchivelocation\fR\&. This minimizes the number of files that need to be retained, while preserving crash\-restart capability\&. Use of this parameter is appropriate if the
  69 \fIarchivelocation\fR
  70 is a transient staging area for this particular standby server, but
  71 \fInot\fR
  72 when the
  73 \fIarchivelocation\fR
  74 is intended as a long\-term WAL archive area, or when multiple standby servers are recovering from the same archive location\&.
  75 .PP
  76 When used as a standalone program all WAL files logically preceding the
  77 \fIoldestkeptwalfile\fR
  78 will be removed from
  79 \fIarchivelocation\fR\&. In this mode, if you specify a
  80 \&.partial
  81 or
  82 \&.backup
  83 file name, then only the file prefix will be used as the
  84 \fIoldestkeptwalfile\fR\&. This treatment of
  85 \&.backup
  86 file name 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
  87 000000010000003700000010:
  88 .sp
  89 .if n \{\
  90 .RS 4
  91 .\}
  92 .nf
  93 pg_archivecleanup \-d archive 000000010000003700000010\&.00000020\&.backup
  94
  95 pg_archivecleanup:  keep WAL file "archive/000000010000003700000010" and later
  96 pg_archivecleanup:  removing file "archive/00000001000000370000000F"
  97 pg_archivecleanup:  removing file "archive/00000001000000370000000E"
  98 .fi
  99 .if n \{\
 100 .RE
 101 .\}
 102 .PP
 103 pg_archivecleanup
 104 assumes that
 105 \fIarchivelocation\fR
 106 is a directory readable and writable by the server\-owning user\&.
 107 .SH "OPTIONS"
 108 .PP
 109 pg_archivecleanup
 110 accepts the following command\-line arguments:
 111 .PP
 112 \fB\-b\fR
 113 .br
 114 \fB\-\-clean\-backup\-history\fR
 115 .RS 4
 116 Remove backup history files as well\&. See
 117 Section\ \&25.3.2
 118 for details about backup history files\&.
 119 .RE
 120 .PP
 121 \fB\-d\fR
 122 .br
 123 \fB\-\-debug\fR
 124 .RS 4
 125 Print lots of debug logging output on
 126 stderr\&.
 127 .RE
 128 .PP
 129 \fB\-n\fR
 130 .br
 131 \fB\-\-dry\-run\fR
 132 .RS 4
 133 Print the names of the files that would have been removed on
 134 stdout
 135 (performs a dry run)\&.
 136 .RE
 137 .PP
 138 \fB\-V\fR
 139 .br
 140 \fB\-\-version\fR
 141 .RS 4
 142 Print the
 143 pg_archivecleanup
 144 version and exit\&.
 145 .RE
 146 .PP
 147 \fB\-x \fR\fB\fIextension\fR\fR
 148 .br
 149 \fB\-\-strip\-extension=\fR\fB\fIextension\fR\fR
 150 .RS 4
 151 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:
 152 \-x \&.gz\&.
 153 .RE
 154 .PP
 155 \fB\-?\fR
 156 .br
 157 \fB\-\-help\fR
 158 .RS 4
 159 Show help about
 160 pg_archivecleanup
 161 command line arguments, and exit\&.
 162 .RE
 163 .SH "ENVIRONMENT"
 164 .PP
 165 The environment variable
 166 \fBPG_COLOR\fR
 167 specifies whether to use color in diagnostic messages\&. Possible values are
 168 always,
 169 auto
 170 and
 171 never\&.
 172 .SH "NOTES"
 173 .PP
 174 pg_archivecleanup
 175 is designed to work with
 176 PostgreSQL
 177 8\&.0 and later when used as a standalone utility, or with
 178 PostgreSQL
 179 9\&.0 and later when used as an archive cleanup command\&.
 180 .PP
 181 pg_archivecleanup
 182 is written in C and has an easy\-to\-modify source code, with specifically designated sections to modify for your own needs
 183 .SH "EXAMPLES"
 184 .PP
 185 On Linux or Unix systems, you might use:
 186 .sp
 187 .if n \{\
 188 .RS 4
 189 .\}
 190 .nf
 191 archive_cleanup_command = \*(Aqpg_archivecleanup \-d /mnt/standby/archive %r 2>>cleanup\&.log\*(Aq
 192 .fi
 193 .if n \{\
 194 .RE
 195 .\}
 196 .sp
 197 where the archive directory is physically located on the standby server, so that the
 198 \fIarchive_command\fR
 199 is accessing it across NFS, but the files are local to the standby\&. This will:
 200 .sp
 201 .RS 4
 202 .ie n \{\
 203 \h'-04'\(bu\h'+03'\c
 204 .\}
 205 .el \{\
 206 .sp -1
 207 .IP \(bu 2.3
 208 .\}
 209 produce debugging output in
 210 cleanup\&.log
 211 .RE
 212 .sp
 213 .RS 4
 214 .ie n \{\
 215 \h'-04'\(bu\h'+03'\c
 216 .\}
 217 .el \{\
 218 .sp -1
 219 .IP \(bu 2.3
 220 .\}
 221 remove no\-longer\-needed files from the archive directory
 222 .RE