barman - Backup and Recovery Manager for PostgreSQL
Barman is an administration tool for disaster recovery of
PostgreSQL servers written in Python and maintained by 2ndQuadrant. Barman
can perform remote backups of multiple servers in business critical
environments and helps DBAs during the recovery phase.
- -h, --help
- Show a help message and exit.
- -v, --version
- Show program version number and exit.
- -c CONFIG, --config
CONFIG
- Use the specified configuration file.
- --color
{never,always,auto}, --colour {never,always,auto}
- Whether to use colors in the output (default: auto)
- -q, --quiet
- Do not output anything. Useful for cron scripts.
- -d, --debug
- debug output (default: False)
- --log-level
{NOTSET,DEBUG,INFO,WARNING,ERROR,CRITICAL}
- Override the default log level
- -f {json,console}, --format
{json,console}
- output format (default: 'console')
Important: every command has a help option
- archive-wal
SERVER_NAME
- Get any incoming xlog file (both through standard archive_command and
streaming replication, where applicable) and moves them in the WAL archive
for that server. If necessary, apply compression when requested by the
user.
- backup
SERVER_NAME
- Perform a backup of SERVER_NAME using parameters specified in the
configuration file. Specify all as SERVER_NAME to perform a backup of all
the configured servers.
- --immediate-checkpoint
- forces the initial checkpoint to be done as quickly as possible. Overrides
value of the parameter immediate_checkpoint, if present in the
configuration file.
- --no-immediate-checkpoint
- forces to wait for the checkpoint. Overrides value of the parameter
immediate_checkpoint, if present in the configuration file.
- --reuse-backup
[INCREMENTAL_TYPE]
- Overrides reuse_backup option behaviour. Possible values for
INCREMENTAL_TYPE are:
- •
- off: do not reuse the last available backup;
- •
- copy: reuse the last available backup for a server and create a
copy of the unchanged files (reduce backup time);
- •
- link: reuse the last available backup for a server and create a
hard link of the unchanged files (reduce backup time and space);
link is the default target if --reuse-backup is used and
INCREMENTAL_TYPE is not explicit.
- --retry-times
- Number of retries of base backup copy, after an error. Used during both
backup and recovery operations. Overrides value of the parameter
basebackup_retry_times, if present in the configuration file.
- --no-retry
- Same as --retry-times 0
- --retry-sleep
- Number of seconds of wait after a failed copy, before retrying. Used
during both backup and recovery operations. Overrides value of the
parameter basebackup_retry_sleep, if present in the configuration
file.
- -j, --jobs
- Number of parallel workers to copy files during backup. Overrides value of
the parameter parallel_jobs, if present in the configuration file.
- --bwlimit KBPS
- maximum transfer rate in kilobytes per second. A value of 0 means no
limit. Overrides 'bandwidth_limit' configuration option. Default is
undefined.
- --wait, -w
- wait for all required WAL files by the base backup to be archived
- --wait-timeout
- the time, in seconds, spent waiting for the required WAL files to be
archived before timing out
- check-backup
SERVER_NAME BACKUP_ID
- Make sure that all the required WAL files to check the consistency of a
physical backup (that is, from the beginning to the end of the full
backup) are correctly archived. This command is automatically invoked by
the cron command and at the end of every backup operation.
- check
SERVER_NAME
- Show diagnostic information about SERVER_NAME, including: Ssh connection
check, PostgreSQL version, configuration and backup directories, archiving
process, streaming process, replication slots, etc. Specify all as
SERVER_NAME to show diagnostic information about all the configured
servers.
- --nagios
- Nagios plugin compatible output
- cron
- Perform maintenance tasks, such as enforcing retention policies or WAL
files management.
- --keep-descriptors
- Keep the stdout and the stderr streams of the Barman subprocesses attached
to this one. This is useful for Docker based installations.
- delete SERVER_NAME
BACKUP_ID
- Delete the specified backup. Backup ID shortcuts section below for
available shortcuts.
- diagnose
- Collect diagnostic information about the server where barman is installed
and all the configured servers, including: global configuration, SSH
version, Python version, rsync version, as well as current configuration
and status of all servers.
- get-wal [OPTIONS]
SERVER_NAME WAL_NAME
- Retrieve a WAL file from the xlog archive of a given server. By default,
the requested WAL file, if found, is returned as uncompressed content to
STDOUT. The following options allow users to change this behaviour:
- -o OUTPUT_DIRECTORY
- destination directory where the get-wal will deposit the requested
WAL
- -P, --partial
- retrieve also partial WAL files (.partial)
- -z
- output will be compressed using gzip
- -j
- output will be compressed using bzip2
- -p SIZE
- peek from the WAL archive up to SIZE WAL files, starting from the
requested one. 'SIZE' must be an integer >= 1. When invoked with this
option, get-wal returns a list of zero to 'SIZE' WAL segment names, one
per row.
- -t, --test
- test both the connection and the configuration of the requested PostgreSQL
server in Barman for WAL retrieval. With this option, the 'WAL_NAME'
mandatory argument is ignored.
- list-backup
SERVER_NAME
- Show available backups for SERVER_NAME. This command is useful to retrieve
a backup ID. For example:
-
servername 20111104T102647 - Fri Nov 4 10:26:48 2011 - Size: 17.0 MiB - WAL Size: 100 B
-
In this case, *20111104T102647* is the backup ID.
- list-files
[OPTIONS] SERVER_NAME BACKUP_ID
- List all the files in a particular backup, identified by the server name
and the backup ID. See the Backup ID shortcuts section below for available
shortcuts.
- --target
TARGET_TYPE
- Possible values for TARGET_TYPE are:
- •
- data: lists just the data files;
- •
- standalone: lists the base backup files, including required WAL
files;
- •
- wal: lists all the WAL files between the start of the base backup
and the end of the log / the start of the following base backup (depending
on whether the specified base backup is the most recent one
available);
- •
- full: same as data + wal.
The default value is standalone.
- list-server
- Show all the configured servers, and their descriptions.
- put-wal [OPTIONS]
SERVER_NAME
- Receive a WAL file from a remote server and securely store it into the
SERVER_NAME incoming directory. The WAL file is retrieved from the STDIN,
and must be encapsulated in a tar stream together with a MD5SUMS file to
validate it. This command is meant to be invoked through SSH from a remote
barman-wal-archive utility (part of barman-cli package). Do not use this
command directly unless you take full responsibility of the content of
files.
- -t, --test
- test both the connection and the configuration of the requested PostgreSQL
server in Barman to make sure it is ready to receive WAL files.
- rebuild-xlogdb
SERVER_NAME
- Perform a rebuild of the WAL file metadata for SERVER_NAME (or every
server, using the all shortcut) guessing it from the disk content. The
metadata of the WAL archive is contained in the xlog.db file, and every
Barman server has its own copy.
- receive-wal
SERVER_NAME
- Start the stream of transaction logs for a server. The process relies on
pg_receivewal/pg_receivexlog to receive WAL files from the PostgreSQL
servers through the streaming protocol.
- --stop
- stop the receive-wal process for the server
- --reset
- reset the status of receive-wal, restarting the streaming from the current
WAL file of the server
- --create-slot
- create the physical replication slot configured with the slot_name
configuration parameter
- --drop-slot
- drop the physical replication slot configured with the slot_name
configuration parameter
- recover [OPTIONS]
SERVER_NAME BACKUP_ID DESTINATION_DIRECTORY
- Recover a backup in a given directory (local or remote, depending on the
--remote-ssh-command option settings). See the Backup ID shortcuts section
below for available shortcuts.
- --target-tli
TARGET_TLI
- Recover the specified timeline.
- --target-time
TARGET_TIME
- Recover to the specified time.
You can use any valid unambiguous representation (e.g:
"YYYY-MM-DD HH:MM:SS.mmm").
- --target-xid
TARGET_XID
- Recover to the specified transaction ID.
- --target-lsn
TARGET_LSN
- Recover to the specified LSN (Log Sequence Number). Requires PostgreSQL 10
or above.
- --target-name
TARGET_NAME
- Recover to the named restore point previously created with the
pg_create_restore_point(name) (for PostgreSQL 9.1 and above users).
- --target-immediate
- Recover ends when a consistent state is reached (end of the base
backup)
- --exclusive
- Set target (time, XID or LSN) to be non inclusive.
- --target-action
ACTION
- Trigger the specified action once the recovery target is reached. Possible
actions are: pause (PostgreSQL 9.1 and above), shutdown (PostgreSQL 9.5
and above) and promote (ditto). This option requires a target to be
defined, with one of the above options.
- --tablespace
NAME:LOCATION
- Specify tablespace relocation rule.
- --remote-ssh-command
SSH_COMMAND
- This options activates remote recovery, by specifying the secure shell
command to be launched on a remote host. This is the equivalent of the
"ssh_command" server option in the configuration file for remote
recovery. Example: 'ssh postgres@db2'.
- --retry-times RETRY_TIMES
- Number of retries of data copy during base backup after an error.
Overrides value of the parameter basebackup_retry_times, if present in the
configuration file.
- --no-retry
- Same as --retry-times 0
- --retry-sleep
- Number of seconds of wait after a failed copy, before retrying. Overrides
value of the parameter basebackup_retry_sleep, if present in the
configuration file.
- --bwlimit
KBPS
- maximum transfer rate in kilobytes per second. A value of 0 means no
limit. Overrides 'bandwidth_limit' configuration option. Default is
undefined.
- -j , --jobs
- Number of parallel workers to copy files during recovery. Overrides value
of the parameter parallel_jobs, if present in the configuration file.
Works only for servers configured through rsync/SSH.
- --get-wal,
--no-get-wal
- Enable/Disable usage of get-wal for WAL fetching during recovery. Default
is based on recovery_options setting.
- --network-compression,
--no-network-compression
- Enable/Disable network compression during remote recovery. Default is
based on network_compression configuration setting.
- --standby-mode
- Specifies whether to start the PostgreSQL server as a standby. Default is
undefined.
- replication-status
[OPTIONS] SERVER_NAME
- Shows live information and status of any streaming client attached to the
given server (or servers). Default behaviour can be changed through the
following options:
- --minimal
- machine readable output (default: False)
- --target
TARGET_TYPE
- Possible values for TARGET_TYPE are:
- •
- hot-standby: lists only hot standby servers
- •
- wal-streamer: lists only WAL streaming clients, such as
pg_receivewal
- •
- all: any streaming client (default)
- show-backup
SERVER_NAME BACKUP_ID
- Show detailed information about a particular backup, identified by the
server name and the backup ID. See the Backup ID shortcuts section below
for available shortcuts. For example:
-
Backup 20150828T130001:
Server Name : quagmire
Status : DONE
PostgreSQL Version : 90402
PGDATA directory : /srv/postgresql/9.4/main/data
Base backup information:
Disk usage : 12.4 TiB (12.4 TiB with WALs)
Incremental size : 4.9 TiB (-60.02%)
Timeline : 1
Begin WAL : 0000000100000CFD000000AD
End WAL : 0000000100000D0D00000008
WAL number : 3932
WAL compression ratio: 79.51%
Begin time : 2015-08-28 13:00:01.633925+00:00
End time : 2015-08-29 10:27:06.522846+00:00
Begin Offset : 1575048
End Offset : 13853016
Begin XLOG : CFD/AD180888
End XLOG : D0D/8D36158
WAL information:
No of files : 35039
Disk usage : 121.5 GiB
WAL rate : 275.50/hour
Compression ratio : 77.81%
Last available : 0000000100000D95000000E7
Catalog information:
Retention Policy : not enforced
Previous Backup : 20150821T130001
Next Backup : - (this is the latest base backup)
- show-server
SERVER_NAME
- Show information about SERVER_NAME, including: conninfo, backup_directory,
wals_directory and many more. Specify all as SERVER_NAME to show
information about all the configured servers.
- status
SERVER_NAME
- Show information about the status of a server, including: number of
available backups, archive_command, archive_status and many more. For
example:
-
Server quagmire:
Description: The Giggity database
Passive node: False
PostgreSQL version: 9.3.9
pgespresso extension: Not available
PostgreSQL Data directory: /srv/postgresql/9.3/data
PostgreSQL 'archive_command' setting: rsync -a %p barman@backup:/var/lib/barman/quagmire/incoming
Last archived WAL: 0000000100003103000000AD
Current WAL segment: 0000000100003103000000AE
Retention policies: enforced (mode: auto, retention: REDUNDANCY 2, WAL retention: MAIN)
No. of available backups: 2
First available backup: 20150908T003001
Last available backup: 20150909T003001
Minimum redundancy requirements: satisfied (2/1)
- switch-wal
SERVER_NAME
- Execute pg_switch_wal() on the target server (from PostgreSQL 10), or
pg_switch_xlog (for PostgreSQL 8.3 to 9.6).
- --force
- Forces the switch by executing CHECKPOINT before pg_switch_xlog().
IMPORTANT: executing a CHECKPOINT might increase I/O load on a
PostgreSQL server. Use this option with care.
- --archive
- Wait for one xlog file to be archived. If after a defined amount of time
(default: 30 seconds) no xlog file is archived, Barman will terminate with
failure exit code. Available also on standby servers.
- --archive-timeout
TIMEOUT
- Specifies the amount of time in seconds (default: 30 seconds) the archiver
will wait for a new xlog file to be archived before timing out. Available
also on standby servers.
- switch-xlog
SERVER_NAME
- Alias for switch-wal (kept for back-compatibility)
- sync-backup
SERVER_NAME BACKUP_ID
- Command used for the synchronisation of a passive node with its primary.
Executes a copy of all the files of a BACKUP_ID that is present on
SERVER_NAME node. This command is available only for passive nodes, and
uses the primary_ssh_command option to establish a secure connection with
the primary node.
- sync-info
SERVER_NAME [LAST_WAL [LAST_POSITION]]
- Collect information regarding the current status of a Barman server, to be
used for synchronisation purposes. Returns a JSON output representing
SERVER_NAME, that contains: all the successfully finished backup, all the
archived WAL files, the configuration, last WAL file been read from the
xlog.db and the position in the file.
- LAST_WAL
- tells sync-info to skip any WAL file previous to that (incremental
synchronisation)
- LAST_POSITION
- hint for quickly positioning in the xlog.db file (incremental
synchronisation)
- sync-wals
SERVER_NAME
- Command used for the synchronisation of a passive node with its primary.
Executes a copy of all the archived WAL files that are present on
SERVER_NAME node. This command is available only for passive nodes, and
uses the primary_ssh_command option to establish a secure connection with
the primary node.
Rather than using the timestamp backup ID, you can use any of the
following shortcuts/aliases to identity a backup for a given server:
- first
- Oldest available backup for that server, in chronological order.
- last
- Latest available backup for that server, in chronological order.
- latest
- same ast last.
- oldest
- same ast first.
Barman has been extensively tested, and is currently being used in
several production environments. However, we cannot exclude the presence of
bugs.
Any bug can be reported via the Sourceforge bug tracker. Along the
bug submission, users can provide developers with diagnostics information
obtained through the barman diagnose command.
In alphabetical order:
- •
- Gabriele Bartolini <gabriele.bartolini@2ndquadrant.it>
(architect)
- •
- Jonathan Battiato <jonathan.battiato@2ndquadrant.it>
(QA/testing)
- •
- Giulio Calacoci <giulio.calacoci@2ndquadrant.it> (developer)
- •
- Francesco Canovai <francesco.canovai@2ndquadrant.it>
(QA/testing)
- •
- Leonardo Cecchi <leonardo.cecchi@2ndquadrant.it> (developer)
- •
- Gianni Ciolli <gianni.ciolli@2ndquadrant.it> (QA/testing)
- •
- Britt Cole <britt.cole@2ndquadrant.com> (documentation)
- •
- Marco Nenciarini <marco.nenciarini@2ndquadrant.it> (project
leader)
- •
- Rubens Souza <rubens.souza@2ndquadrant.it> (QA/testing)
Past contributors:
- •
- Carlo Ascani
- •
- Stefano Bianucci
- •
- Giuseppe Broccolo
- •
- Homepage: <http://www.pgbarman.org/>
- •
- Documentation: <http://docs.pgbarman.org/>
- •
- Professional support: <http://www.2ndQuadrant.com/>
Barman is the property of 2ndQuadrant Limited and its code is
distributed under GNU General Public License v3.
Copyright (C) 2011-2020 2ndQuadrant Limited -
<http://www.2ndQuadrant.com/>.
2ndQuadrant Limited <https://www.2ndQuadrant.com>.