Backup commands¶
Backup commands are those that works directly on backups already existing in Barman’s backup catalog.
Note
Remember a backup ID can be retrieved with barman list-backups <server_name>
Backup ID shortcuts¶
Barman allows you to use special keywords to identify a specific backup:
last/latest : identifies the newest backup in the catalog
first/oldest : identifies the oldest backup in the catalog
last-failed : identifies the newest failed backup in the catalog
Using those keywords with Barman commands allows you to execute actions without knowing the exact ID of a backup for a server. For example we can issue:
barman delete <server_name> oldest
to remove the oldest backup available in the catalog and reclaim disk space.
check-backup¶
Starting with version 2.5, you can check that all required WAL files for
the consistency of a full backup have been correctly archived by
barman with the check-backup command:
barman check-backup <server_name> <backup_id>
Important
This command is automatically invoked by cron and at the end of a backup operation. This means that, under normal circumstances, you should never need to execute it.
In case one or more WAL files from the start to the end of the backup
have not been archived yet, barman will label the backup as
WAITING_FOR_WALS . The cron command will continue to check that
missing WAL files are archived, then label the backup as DONE .
In case the first required WAL file is missing at the end of the backup,
such backup will be marked as FAILED . It is therefore important
that you verify that WAL archiving (whether via streaming or
archive_command ) is properly working before executing a backup
operation - especially when backing up from a standby server.
delete¶
You can delete a given backup with:
barman delete <server_name> <backup_id>
The delete command accepts any Backup ID shortcuts to identify backups.
keep¶
If you have a backup which you wish to keep beyond the retention policy of the server then you can make it an archival backup with:
barman keep <server_name> <backup_id> [--target TARGET, --status, --release]
Possible values for TARGET are:
If the --status option is provided then Barman will report the
archival status of the backup. This will either be the recovery target
of full or standalone for archival backups or nokeep for
backups which have not been flagged as archival.
If the --release option is provided then Barman will release the
keep flag from this backup. This will remove its archival status and
make it available for deletion, either directly or by retention policy.
Once a backup has been flagged as an archival backup, the behaviour of Barman will change as follows:
This can be reverted by removing the keep flag with
barman keep <server_name> <backup_id> --release .
Warning
Once a standalone archival backup is not required by the retention policy of a server barman cron will remove the WALs between that backup and the begin_wal value of the next most recent backup. This means that while it is safe to change the target from full to standalone , it is not safe to change the target from standalone to full because there is no guarantee the necessary WALs for a recovery to the latest point in time will still be available.
list-files¶
You can list the files (base backup and required WAL files) for a given backup with:
barman list-files [--target TARGET_TYPE] <server_name> <backup_id>
With the --target TARGET_TYPE option, it is possible to choose the
content of the list for a given backup.
Possible values for TARGET_TYPE are:
The default value for TARGET_TYPE is standalone .
Important
The list-files command facilitates interaction with external tools, and can therefore be extremely useful to integrate Barman into your archiving procedures.
recover¶
The recover command is used to recover a whole server after a backup
is executed using the backup command.
This is achieved issuing a command like the following:
barman@backup$ barman recover <server_name> <backup_id> /path/to/recover/dir
Important
Do not issue a recover command using a target data directory where a PostgreSQL instance is running. In that case, remember to stop it before issuing the recovery. This applies also to tablespace directories.
At the end of the execution of the recovery, the selected backup is recovered locally and the destination path contains a data directory ready to be used to start a PostgreSQL instance.
Important
Running this command as user barman , it will become the database superuser.
The specific ID of a backup can be retrieved using the :ref:``list-backups`<list-backups>` command.
Important
Barman does not currently keep track of symbolic links inside PGDATA (except for tablespaces inside pg_tblspc). We encourage system administrators to keep track of symbolic links and to add them to the disaster recovery plans/procedures in case they need to be restored in their original location.
The recovery command has several options that modify the command behavior.
Remote recovery¶
Add the --remote-ssh-command <COMMAND> option to the invocation of
the recovery command. Doing this will allow Barman to execute the copy
on a remote server, using the provided command to connect to the remote
host.
Note
It is advisable to use the postgres user to perform the recovery on the remote host.
Important
Do not issue a recover command using a target data directory where a PostgreSQL instance is running. In that case, remember to stop it before issuing the recovery. This applies also to tablespace directories.
Known limitations of the remote recovery are:
Tablespace remapping¶
Barman is able to automatically remap one or more tablespaces using the
recover command with the –tablespace option. The option accepts a pair
of values as arguments using the NAME:DIRECTORY format:
NAME is the identifier of the tablespace
DIRECTORY is the new destination path for the tablespace
If the destination directory does not exists, Barman will try to create it (assuming you have the required permissions).
Point in time recovery¶
Barman wraps PostgreSQL’s Point-in-Time Recovery (PITR), allowing you to specify a recovery target, either as a timestamp, as a restore label, or as a transaction ID.
Important
The earliest PITR for a given backup is the end of the base backup itself. If you want to recover at any point in time between the start and the end of a backup, you must use the previous backup. From Barman 2.3 you can exit recovery when consistency is reached by using –target-immediate option (available only for PostgreSQL 9.4 and newer).
The recovery target can be specified using one of the following mutually exclusive options:
–target-time TARGET_TIME : to specify a timestamp
–target-xid TARGET_XID : to specify a transaction ID
–target-lsn TARGET_LSN : to specify a Log Sequence Number (LSN) -
requires PostgreSQL 10 or higher
–target-name TARGET_NAME : to specify a named restore point
- previously created with the pg_create_restore_point(name) function
- –target-immediaterecovery ends when a consistent state is reached
(that is the end of the base backup process) [^RECOVERY_TARGET_IMMEDIATE]
Important
Recovery target via time, XID and LSN .. IMPORTANT:: subsequent to the end of the backup. If you want to recover to a point in time between the start and the end of a backup, you must recover from the previous backup in the catalogue.
You can use the --exclusive option to specify whether to stop
immediately before or immediately after the recovery target.
Barman allows you to specify a target timeline for recovery, using the
target-tli option. The notion of timeline goes beyond the scope of
this document; you can find more details in the PostgreSQL
documentation, as mentioned in the “Before you start” section.
Barman 2.4 introduces support for --target-action option, accepting
the following values:
shutdown : once recovery target is reached, PostgreSQL is shut down [^TARGET_SHUTDOWN]
pause : once recovery target is reached, PostgreSQL is started in pause
state, allowing users to inspect the instance 2
promote : once recovery target is reached, PostgreSQL will exit recovery
and is promoted as a master 3
Important
By default, no target action is defined (for back compatibility). The –target-action option requires a Point In Time Recovery target to be specified.
- For more detailed information on the above settings, please consult the
Barman 2.4 also adds the --standby-mode option for the recover
command which, if specified, properly configures the recovered instance
as a standby by creating a standby.signal file (from PostgreSQL 12)
or by adding standby_mode = on to the generated recovery
configuration. Further information on standby mode is available in the
PostgreSQL documentation.
Fetching WALs from the Barman server¶
The barman recover command can optionally configure PostgreSQL to
fetch WALs from Barman during recovery. This is enabled by setting the
recovery_options global/server configuration option to 'get-wal'
as described in the get-wal section . If recovery_options is not set
or is empty then Barman will instead copy the WALs required for recovery
while executing the barman recover command.
The --get-wal and --no-get-wal options can be used to override
the behaviour defined by recovery_options . Use --get-wal with
barman recover to enable the fetching of WALs from the Barman
server, alternatively use --no-get-wal to disable it.
show-backup¶
You can retrieve all the available information for a particular backup of a given server with:
barman show-backup <server_name> <backup_id>
The show-backup command accepts any Backup ID shortcuts to identify
backups.
