.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` 
.    ds C' 
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "PG_BACKUPCLUSTER 1"
.TH PG_BACKUPCLUSTER 1 "2023-05-24" "Debian" "Debian PostgreSQL infrastructure"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
pg_backupcluster \- simple pg_basebackup and pg_dump front\-end
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBpg_backupcluster\fR [\fIoptions\fR] \fIversion\fR \fIcluster\fR \fIaction\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBpg_backupcluster\fR provides a simple interface to create PostgreSQL cluster
backups using \fBpg_basebackup\fR\|(1) and \fBpg_dump\fR\|(1).
.PP
To ease integration with \fBsystemd\fR operation, the alternative syntax
"\fBpg_basebackup\fR \fIversion\fR\fB\-\fR\fIcluster\fR \fIaction\fR" is also supported.
.SH "ACTIONS"
.IX Header "ACTIONS"
.IP "\fBcreatedirectory\fR" 4
.IX Item "createdirectory"
Create /var/backups and /var/backups/\fIversion\fR\-\fIcluster\fR.
This action can be run as root to create the directories required for backups.
All other actions will also attempt to create the directories when missing, but
can of course only do that when running as root. They will switch to the
cluster owner after this step.
.IP "\fBbasebackup\fR" 4
.IX Item "basebackup"
Backup using \fBpg_basebackup\fR\|(1). The resulting basebackup contains the \s-1WAL\s0
files required to run recovery on startup.
.IP "\fBdump\fR" 4
.IX Item "dump"
Backup using \fBpg_dump\fR\|(1). Global objects (users, tablespaces) are dumped
using \fBpg_dumpall\fR\|(1) \fB\-\-globals\-only\fR. Individual databases are dumped into
PostgreSQL's custom format.
.IP "\fBexpirebasebackups\fR \fIN\fR" 4
.IX Item "expirebasebackups N"
Remove all but last the \fIN\fR basebackups.
.IP "\fBexpiredumps\fR \fIN\fR" 4
.IX Item "expiredumps N"
Remove all but last the \fIN\fR dumps.
.IP "\fBreceivewal\fR" 4
.IX Item "receivewal"
Launch pg_receivewal. \s-1WAL\s0 files are gzip-compressed in \s-1PG 10+.\s0
.IP "\fBcompresswal\fR" 4
.IX Item "compresswal"
Compress \s-1WAL\s0 files in archive.
.IP "\fBarchivecleanup\fR" 4
.IX Item "archivecleanup"
Remove obsolete \s-1WAL\s0 files from archive using \fBpg_archivecleanup\fR\|(1).
.IP "\fBlist\fR" 4
.IX Item "list"
Show dumps, basebackups, and \s-1WAL,\s0 with size.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-c \-\-checkpoint=spread|fast\fR" 4
.IX Item "-c --checkpoint=spread|fast"
Passed to \fBpg_basebackup\fR. Default is \fBspread\fR.
.IP "\fB\-k \-\-keep\-on\-error\fR" 4
.IX Item "-k --keep-on-error"
Keep faulty backup directory on error. By default backups are delete on error.
.IP "\fB\-v \-\-verbose\fR" 4
.IX Item "-v --verbose"
Verbose output, even when not running on a terminal.
.SH "FILES"
.IX Header "FILES"
.IP "/var/backups" 4
.IX Item "/var/backups"
Default root directory for cluster backup directories.
.IP "/var/backups/\fIversion\fR\-\fIcluster\fR" 4
.IX Item "/var/backups/version-cluster"
Default directory for cluster backups.
.IP "/var/backups/\fIversion\fR\-\fIcluster\fR/\fItimestamp\fR\fB.basebackup\fR" 4
.IX Item "/var/backups/version-cluster/timestamp.basebackup"
Backup from \fBpg_backupcluster ... basebackup\fR.
.RS 4
.ie n .IP "\*(C`config.tar.gz\*(C'" 4
.el .IP "\f(CW\*(C`config.tar.gz\*(C'\fR" 4
.IX Item "config.tar.gz"
Tarball of cluster configuration directory (postgresql.conf, pg_hba.conf, ...)
in /etc/postgresql.
.ie n .IP "\fItablespace\fR\*(C`.tar.gz\*(C', \*(C`pg_wal.tar.gz\*(C', \*(C`backup_manifest\*(C'" 4
.el .IP "\fItablespace\fR\f(CW\*(C`.tar.gz\*(C'\fR, \f(CW\*(C`pg_wal.tar.gz\*(C'\fR, \f(CW\*(C`backup_manifest\*(C'\fR" 4
.IX Item "tablespace.tar.gz, pg_wal.tar.gz, backup_manifest"
Tablespace and \s-1WAL\s0 tarballs and backup info written by \fBpg_basebackup\fR.
.ie n .IP "\*(C`status\*(C'" 4
.el .IP "\f(CW\*(C`status\*(C'\fR" 4
.IX Item "status"
Completion timestamp of backup run.
.RE
.RS 4
.RE
.IP "/var/backups/\fIversion\fR\-\fIcluster\fR/\fItimestamp\fR\fB.dump\fR" 4
.IX Item "/var/backups/version-cluster/timestamp.dump"
Backup from \fBpg_backupcluster ... dump\fR.
.RS 4
.ie n .IP "\*(C`config.tar.gz\*(C'" 4
.el .IP "\f(CW\*(C`config.tar.gz\*(C'\fR" 4
.IX Item "config.tar.gz"
Tarball of cluster configuration directory (postgresql.conf, pg_hba.conf, ...)
in /etc/postgresql.
.ie n .IP "\*(C`createcluster.opts\*(C'" 4
.el .IP "\f(CW\*(C`createcluster.opts\*(C'\fR" 4
.IX Item "createcluster.opts"
Options (encoding, locale, data checksums) to be passed to \fBpg_createcluster\fR
for restoring this cluster.
.ie n .IP "\*(C`globals.sql\*(C'" 4
.el .IP "\f(CW\*(C`globals.sql\*(C'\fR" 4
.IX Item "globals.sql"
Global objects (roles, tablespaces) from \fBpg_dumpall \-\-globals\-only\fR.
.ie n .IP "\*(C`databases.sql\*(C'" 4
.el .IP "\f(CW\*(C`databases.sql\*(C'\fR" 4
.IX Item "databases.sql"
\&\s-1SQL\s0 commands to create databases and restore database-level options.
.ie n .IP "\fIdatabase\fR\*(C`.dump\*(C'" 4
.el .IP "\fIdatabase\fR\f(CW\*(C`.dump\*(C'\fR" 4
.IX Item "database.dump"
Database dumps from \fBpg_dump \-\-format=custom\fR.
.ie n .IP "\*(C`status\*(C'" 4
.el .IP "\f(CW\*(C`status\*(C'\fR" 4
.IX Item "status"
Completion timestamp of backup run.
.RE
.RS 4
.RE
.IP "/var/backups/\fIversion\fR\-\fIcluster\fR/\fBwal\fR" 4
.IX Item "/var/backups/version-cluster/wal"
\&\s-1WAL\s0 files from \fBpg_receivewal\fR.
.SH "CAVEATS"
.IX Header "CAVEATS"
For dump-style backups, not all properties of the original cluster are preserved:
.IP "\(bu" 2
In PostgreSQL 10 and earlier, \s-1ALTER ROLE ... IN DATABASE\s0 is not supported.
.IP "\(bu" 2
Not all \fBinitdb\fR options are carried over. Currently supported are \fB\-\-encoding\fR,
\&\fB\-\-lc\-collate\fR, \fB\-\-lc\-collate\fR, and \fB\-k \-\-data\-checksums\fR.
.PP
The earliest PostgreSQL version supported for dumps is 9.3.
For basebackups, the earliest supported version is 9.1.
\&\fBreceivewal\fR (and hence archive recovery) are supported in 9.5 and later.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBpg_restorecluster\fR\|(1),
\&\fBpg_dump\fR\|(1), \fBpg_dumpall\fR\|(1),
\&\fBpg_basebackup\fR\|(1), \fBpg_receivewal\fR\|(1), \fBpg_archivecleanup\fR\|(1).
.SH "AUTHOR"
.IX Header "AUTHOR"
Christoph Berg <myon@debian.org>