.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` 
.    ds C' 
'br\}
.el\{\
.    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
.\" ========================================================================
.\"
.IX Title "PG_BACKUPCLUSTER 1"
.TH PG_BACKUPCLUSTER 1 2024-04-15 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 WAL
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. WAL files are gzip-compressed in PG 10+.
.IP \fBcompresswal\fR 4
.IX Item "compresswal"
Compress WAL files in archive.
.IP \fBarchivecleanup\fR 4
.IX Item "archivecleanup"
Remove obsolete WAL files from archive using \fBpg_archivecleanup\fR\|(1).
.IP \fBlist\fR 4
.IX Item "list"
Show dumps, basebackups, and WAL, 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 WAL 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"
SQL 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"
WAL 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, ALTER ROLE ... IN DATABASE 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>