barman.recovery_executor module#

This module contains the methods necessary to perform a recovery

class barman.recovery_executor.Assertion(filename, line, key, value)#

Bases: tuple

_asdict()#: Return a new dict which maps field names to their values.

_field_defaults = {}#

_fields = ('filename', 'line', 'key', 'value')#

classmethod _make(iterable)#: Make a new Assertion object from a sequence or iterable

_replace(**kwds)#: Return a new Assertion object replacing specified fields with new values

filename#: Alias for field number 0

key#: Alias for field number 2

line#: Alias for field number 1

value#: Alias for field number 3

class barman.recovery_executor.CombineOperation(config, server, backup_manager)View on GitHub #

Bases: RecoveryOperation

Operation responsible for combining a chain of backups (full + incrementals).

Variables:: NAME – the name of the operation

NAME = 'barman-combine'#

_abc_impl = <_abc._abc_data object>#

_combine_backups(backup_info, destination, tablespaces, remote_command, is_last_operation)View on GitHub #

Perform the combination of incrementals + full backups to the destination.

When this is the last operation in the recovery chain, the output of the combination will be placed in the root of destination and tablespaces mapped to their final destination, honoring relocation, if requested. Otherwise, it will be placed in the data directory of the respective volatile backup i.e. *destination*/<backup_id>/data, *destination*/<backup_id>/<tbspc>, etc.

Parameters:

backup_info (barman.infofile.LocalBackupInfo) – The incremental backup to combine with its ascendants
destination (str) – The directory where the combined backup will be placed
tablespaces (dict[str,str]|None) – A dictionary mapping tablespace names to their target directories. This is the relocation chosen by the user when invoking the restore command. If None, it means no relocation was chosen
remote_command (str|None) – The SSH remote command to use for the recovery, in case of a remote recovery. If None, it means the recovery is local
is_last_operation (bool) – Whether this is the last operation in the recovery chain

Return barman.infofile.VolatileBackupInfo:

The respective volatile backup info of backup_info which reflects all changes performed by the operation

_execute(backup_info, destination, tablespaces, remote_command, recovery_info, safe_horizon, is_last_operation)View on GitHub #

Execute the operation for a given backup.

Parameters:

backup_info (barman.infofile.LocalBackupInfo) – An object representing the backup
destination (str) – The destination directory where the output of the operation will be stored
tablespaces (dict[str,str]|None) – A dictionary mapping tablespace names to their target directories. This is the relocation chosen by the user when invoking the restore command. If None, it means no relocation was chosen
remote_command (str|None) – The SSH remote command to use for the recovery, in case of a remote recovery. If None, it means the recovery is local
recovery_info (dict[str,any]) – A dictionary that populated with metadata about the recovery process
safe_horizon (datetime.datetime|None) – The safe horizon of the backup. Any file rsync-copied after this time has to be checked with checksum
is_last_operation (bool) – Whether this is the last operation in the recovery chain

Return barman.infofile.VolatileBackupInfo:

The respective volatile backup info of backup_info which reflects all changes performed by the operation

_fetch_remote_status()View on GitHub #

Gather info from the remote server.

Info includes the path to the pg_combinebackup client and its version.

If the staging location is remote, it attempts to find pg_combinebackup in the remote server. If the staging location is local, it attempts to find pg_combinebackup in the Barman host.

Return dict[str, str|bool]:: the pg_combinebackup client information of the remote server
Raises:: barman.exceptions.CommandNotFoundException – if pg_combinebackup it not found on the target server

_get_backup_chain_paths(backup_info)View on GitHub #

Get the path of each backup in the chain, from the full backup to the specified incremental backup.

Parameters:: backup_info (barman.infofile.LocalBackupInfo) – The incremental backup
Return Iterator[barman.infofile.LocalBackupInfo]:: iterator of paths of the backups in the chain, going from the full to the incremental backup pointed by backup_info

_get_tablespace_mapping(backup_info, vol_backup_info, tablespaces, is_last_operation)View on GitHub #

Get the mapping of tablespaces from the source to their destination directories.

If this is the last operation, tablespaces are mapped to their final destination, honoring relocation, if requested. Otherwise, they are mapped to their directory in the volatile backup’s directory (in the staging directory).

Parameters:

backup_info (barman.infofile.LocalBackupInfo) – The backup info to process
vol_backup_info (barman.infofile.VolatileBackupInfo) – The equivalent volatile backup info of the backup being processed by the operation
tablespaces (dict[str,str]|None) – A dictionary mapping tablespace names to their target directories. This is the relocation chosen by the user when invoking the restore command. If None, it means no relocation was chosen
is_last_operation (bool) – Whether this is the last operation in the recovery chain

Return dict[str,str]:

A mapping of source tablespace directories to their destination directories

_run_pg_combinebackup(backup_info, output_dest, tablespace_mapping, remote_command)View on GitHub #

Run the pg_combinebackup utility to combine backup chain.

If this operation is running on a remote server, it will execute it directly on the remote node. Otherwise, it is run locally.

Parameters:

backup_info (barman.infofile.LocalBackupInfo) – The incremental backup to combine with its ascendants
output_dest (str) – The destination directory where the combined backup will be placed
tablespace_mapping (dict[str,str]) – A mapping of source tablespace directories to their destination directories
remote_command (str|None) – The SSH remote command to use for the recovery, in case of a remote recovery. If None, it means the recovery is local

Raises:

barman.exceptions.DataTransferFailure – If the combine operation fails

_should_execute(backup_info)View on GitHub #

Check if the combine operation should be executed on the given backup.

Note

This method is a no-op in the case of incremental backups as only the leaf backup in the chain will execute this operation (i.e., this class does not use _execute_on_chain()). It’s implemented only to satisfy the interface of the base class RecoveryOperation.

Parameters:: backup_info (barman.infofile.LocalBackupInfo) – The backup info to check
Raises:: NotImplementedError – This method is not applicable for incremental backups.

class barman.recovery_executor.ConfigIssueDetectionView on GitHub #

Bases: object

DANGEROUS_OPTIONS = ['data_directory', 'config_file', 'hba_file', 'ident_file', 'external_pid_file', 'ssl_cert_file', 'ssl_key_file', 'ssl_ca_file', 'ssl_crl_file', 'unix_socket_directory', 'unix_socket_directories', 'include', 'include_dir', 'include_if_exists']#

detect_issues(filename)View on GitHub #

This method looks for any possible issue with PostgreSQL location options such as data_directory, config_file, etc. It returns a dictionary with the dangerous options that have been found.

Parameters:: str (filename) – the Postgres configuration file
Returns:: clashes [Assertion]

class barman.recovery_executor.ConfigurationFileMangelerView on GitHub #

Bases: object

OPTIONS_TO_MANGLE = {'archive_command': 'false', 'recovery_target': None, 'recovery_target_action': None, 'recovery_target_inclusive': None, 'recovery_target_lsn': None, 'recovery_target_name': None, 'recovery_target_time': None, 'recovery_target_timeline': None, 'recovery_target_xid': None}#

mangle_options(filename, backup_filename=None, append_lines=None)View on GitHub #

This method modifies the given PostgreSQL configuration file, commenting out the given settings, and adding the ones generated by Barman.

If backup_filename is passed, keep a backup copy.

Parameters:

filename – the PostgreSQL configuration file
backup_filename – config file backup copy. Default is None.
append_lines – Additional lines to add to the config file

Returns:

[Assertion]

class barman.recovery_executor.DecompressOperation(config, server, backup_manager)View on GitHub #

Bases: RecoveryOperation

Operation responsible for decompressing backups.

Decompresses the backup content using the respective compression handler to the specified destination directory.

Variables:

NAME – str: The name of the operation, used for identification
BASE_TARBALL_NAME – str: The name of the backup tarball file

BASE_TARBALL_NAME = 'base'#

NAME = 'barman-decompress'#

_abc_impl = <_abc._abc_data object>#

_decompress_backup(backup_info, destination, tablespaces, is_last_operation)View on GitHub #

Decompresses a backup and restores its contents to the specified destination.

This method handles decompression of both the base backup tarball and any associated tablespaces, using the appropriate compression method as specified in the backup information. It supports relocation of tablespaces if requested and logs debug information about the decompression process.

Parameters:

backup_info (barman.infofile.LocalBackupInfo) – Information about the backup to be decompressed.
destination (str) – The target directory where the decompressed files will be placed.
tablespaces (dict) – Optional mapping of tablespace names to their relocation paths.
is_last_operation (bool) – Indicates if this is the final operation in the

recovery process, affecting tablespace relocation.

Returns:: Result of the recovery execution chain.
Return type:: barman.infofile.VolatileBackupInfo
Raises:: AttributeError – If the backup uses an unsupported or unknown compression format.

_execute(backup_info, destination, tablespaces, remote_command, recovery_info, safe_horizon, is_last_operation)View on GitHub #

Execute the operation for a given backup.

Parameters:

backup_info (barman.infofile.LocalBackupInfo) – An object representing the backup
destination (str) – The destination directory where the output of the operation will be stored
tablespaces (dict[str,str]|None) – A dictionary mapping tablespace names to their target directories. This is the relocation chosen by the user when invoking the restore command. If None, it means no relocation was chosen
remote_command (str|None) – The SSH remote command to use for the recovery, in case of a remote recovery. If None, it means the recovery is local
recovery_info (dict[str,any]) – A dictionary that populated with metadata about the recovery process
safe_horizon (datetime.datetime|None) – The safe horizon of the backup. Any file rsync-copied after this time has to be checked with checksum
is_last_operation (bool) – Whether this is the last operation in the recovery chain

Return barman.infofile.VolatileBackupInfo:

The respective volatile backup info of backup_info which reflects all changes performed by the operation

_should_execute(backup_info)View on GitHub #

Check if the decompression operation should be executed on the given backup.

Parameters:: backup_info (barman.infofile.LocalBackupInfo) – The backup info to check
Return bool:: True if the operation should be executed, False otherwise

class barman.recovery_executor.DecryptOperation(config, server, backup_manager)View on GitHub #

Bases: RecoveryOperation

Operation responsible for decrypting backups.

Decrypts the backup content using the respective encryption handler to the specified destination directory.

Variables:: NAME – str: The name of the operation, used for identification

NAME = 'barman-decryption'#

_abc_impl = <_abc._abc_data object>#

_decrypt_backup(backup_info, destination)View on GitHub #

Decrypt the given backup into the local staging path.

Note

We don’t need to check whether this is the last operation because encrypted backups are always in ‘tar’ format. This format requires decryption to a staging path before decompression can occur elsewhere.

Parameters:

backup_info (barman.infofile.LocalBackupInfo) – The backup to be decrypted.
destination (str) – Path to the directory where the backup will be restored.

_execute(backup_info, destination, tablespaces, remote_command, recovery_info, safe_horizon, is_last_operation)View on GitHub #

Execute the operation for a given backup.

Parameters:

backup_info (barman.infofile.LocalBackupInfo) – An object representing the backup
destination (str) – The destination directory where the output of the operation will be stored
tablespaces (dict[str,str]|None) – A dictionary mapping tablespace names to their target directories. This is the relocation chosen by the user when invoking the restore command. If None, it means no relocation was chosen
remote_command (str|None) – The SSH remote command to use for the recovery, in case of a remote recovery. If None, it means the recovery is local
recovery_info (dict[str,any]) – A dictionary that populated with metadata about the recovery process
safe_horizon (datetime.datetime|None) – The safe horizon of the backup. Any file rsync-copied after this time has to be checked with checksum
is_last_operation (bool) – Whether this is the last operation in the recovery chain

Return barman.infofile.VolatileBackupInfo:

The respective volatile backup info of backup_info which reflects all changes performed by the operation

_get_command_interface(remote_command)View on GitHub #

Returns a command interface for executing commands locally.

Note

This method overrides the default behavior to ensure that decryption always occurs on the local machine, regardless of the configuration for staging location. It achieves this by always returning a local

command interface.

Parameters:: remote_command (str|None) – The SSH remote command to use for the recovery, in case of a remote recovery. If None, it means the recovery is local
Return barman.fs.UnixLocalCommand:: The command interface for executing operations

_should_execute(backup_info)View on GitHub #

Check if the decryption operation should be executed on the given backup.

Parameters:: backup_info (barman.infofile.LocalBackupInfo) – The backup info to check
Return bool:: True if the operation should be executed, False otherwise

class barman.recovery_executor.MainRecoveryExecutor(backup_manager)View on GitHub #

Bases: RemoteConfigRecoveryExecutor

Main recovery executor.

This executor is used to deal with more complex recovery scenarios, which require one or more among these operations: backup decryption, backup decompression, or backup combination.

_backup_copy(backup_info, dest, tablespaces=None, remote_command=None, safe_horizon=None, recovery_info=None)View on GitHub #

Perform the backup copy operation.

This method orchestrates the execution of all operations required to successfully copy the contents of a backup, including decryption, decompression, and combination of incremental backups.

Parameters:

backup_info (barman.infofile.LocalBackupInfo) – The backup info to process
dest (str) – The destination directory for the recovery
tablespaces (dict[str,str]|None) – A dictionary mapping tablespace names to their target directories. This is the relocation chosen by the user when invoking the restore command. If None, it means no relocation was chosen
remote_command (str|None) – The SSH remote command to use for the recovery, in case of a remote recovery. If None, it means the recovery is local
recovery_info (dict[str,any]) – A dictionary that populated with metadata about the recovery process
safe_horizon (datetime.datetime|None) – The safe horizon of the backup. Any file rsync-copied after this time has to be checked with checksum

Return barman.infofile.VolatileBackupInfo:

The volatile backup info of the final backup after all operations have been executed.

_build_operations_pipeline(backup_info, remote_command=None)View on GitHub #

Build a list of required operations to be executed on the target backup.

This method ensures that all required operations are included and in their correct order.

Parameters:

backup_info (barman.infofile.LocalBackupInfo) – The backup info to process
remote_command (str|None) – The SSH remote command to use for the recovery, in case of a remote recovery. If None, it means the recovery is local

Return list[RecoveryOperation]:

A list of operations to be executed in order

_handle_deprecated_staging_options(operation, remote_command)View on GitHub #

Context manager to handle the deprecated staging options local_staging_path and recovery_staging_path.

This context manager temporarily maps local_staging_path and recovery_staging_path to staging_path. staging_location is always set to “local” when using the deprecated options to guarantee a consistent use of the staging area without adding extra complexity.

This ensures that, even if using deprecated options, operations are still able to rely only on the new options, without having to handle multiple scenarios themselves.

Once out of this context manager, the original values are restored in the configuration object.

Parameters:

operation (RecoveryOperation) – The operation to be executed
remote_command (str|None) – The SSH remote command to use for the recovery, in case of a remote recovery. If None, it means the recovery is local

class barman.recovery_executor.RecoveryExecutor(backup_manager)View on GitHub #

Bases: object

Class responsible of recovery operations

__init__(backup_manager)View on GitHub #

Constructor

Parameters:: backup_manager (barman.backup.BackupManager) – the BackupManager owner of the executor

_analyse_temporary_config_files(recovery_info)View on GitHub #

Analyse temporary configuration files and identify dangerous options

Mark all the dangerous options for the user to review. This procedure also changes harmful options such as ‘archive_command’.

Parameters:: recovery_info (dict) – dictionary holding all recovery parameters

_backup_copy(backup_info, dest, tablespaces=None, remote_command=None, safe_horizon=None, recovery_info=None)View on GitHub #

Perform the actual copy of the base backup for recovery purposes

First, it copies one tablespace at a time, then the PGDATA directory.

Bandwidth limitation, according to configuration, is applied in the process.

TODO: manage configuration files if outside PGDATA.

Parameters:

backup_info (barman.infofile.LocalBackupInfo) – the backup to recover
dest (str) – the destination directory
tablespaces (dict[str,str]|None) – a tablespace name -> location map (for relocation)
remote_command (str|None) – default None. The remote command to recover the base backup, in case of remote backup.
safe_horizon (datetime.datetime|None) – anything after this time has to be checked with checksum

_backup_copy_failure_message(e)View on GitHub #: Write the backup failure message to the output.

_conf_files_exist(conf_files, backup_info, recovery_info)View on GitHub #

Determine whether the conf files in the supplied list exist in the backup represented by backup_info.

Returns a map of conf_file:exists.

_copy_conf_files_to_tempdir(backup_info, recovery_info, remote_command=None)View on GitHub #

Copy conf files from the backup location to a temporary directory so that they can be checked and mangled.

Returns a list of the paths to the temporary conf files.

_copy_temporary_config_files(dest, remote_command, recovery_info)View on GitHub #

Copy modified configuration files using rsync in case of remote recovery

Parameters:

dest (str) – destination directory of the recovery
remote_command (str) – ssh command for remote connection
recovery_info (dict) – Dictionary containing all the recovery parameters

_generate_archive_status(recovery_info, remote_command, required_xlog_files)View on GitHub #

Populate the archive_status directory

Parameters:

recovery_info (dict) – Dictionary containing all the recovery parameters
remote_command (str) – ssh command for remote connection
required_xlog_files (tuple) – list of required WAL segments

_generate_recovery_conf(recovery_info, backup_info, dest, immediate, exclusive, remote_command, target_name, target_time, target_tli, target_xid, target_lsn, standby_mode)View on GitHub #

Generate recovery configuration for PITR

Parameters:

recovery_info (dict) – Dictionary containing all the recovery parameters
backup_info (barman.infofile.LocalBackupInfo) – representation of a backup
dest (str) – destination directory of the recovery
immediate (bool|None) – end recovery as soon as consistency is reached
exclusive (boolean) – exclusive backup or concurrent
remote_command (str) – ssh command for remote connection
target_name (str) – recovery target name for PITR
target_time (str) – recovery target time for PITR
target_tli (str) – recovery target timeline for PITR
target_xid (str) – recovery target transaction id for PITR
target_lsn (str) – recovery target LSN for PITR
standby_mode (bool|None) – standby mode

_map_temporary_config_files(recovery_info, backup_info, remote_command)View on GitHub #

Map configuration files, by filling the ‘temporary_configuration_files’ array, depending on remote or local recovery. This array will be used by the subsequent methods of the class.

Parameters:

recovery_info (dict) – Dictionary containing all the recovery parameters
backup_info (barman.infofile.LocalBackupInfo) – a backup representation
remote_command (str) – ssh command for remote recovery

_retrieve_safe_horizon(recovery_info, backup_info, dest)View on GitHub #

Retrieve the safe_horizon for smart copy

If the target directory contains a previous recovery, it is safe to pick the least of the two backup “begin times” (the one we are recovering now and the one previously recovered in the target directory). Set the value in the given recovery_info dictionary.

Parameters:

recovery_info (dict) – Dictionary containing all the recovery parameters
backup_info (barman.infofile.LocalBackupInfo) – a backup representation
dest (str) – recovery destination directory

_set_pitr_targets(recovery_info, backup_info, dest, wal_dest, target_name, target_time, target_tli, target_xid, target_lsn, target_immediate, target_action)View on GitHub #

Set PITR targets - as specified by the user

Parameters:

recovery_info (dict) – Dictionary containing all the recovery parameters
backup_info (barman.infofile.LocalBackupInfo) – representation of a backup
dest (str) – destination directory of the recovery
wal_dest (str|None) – the destination directory for WALs when doing PITR
target_name (str|None) – recovery target name for PITR
target_time (str|None) – recovery target time for PITR
target_tli (str|None) – recovery target timeline for PITR
target_xid (str|None) – recovery target transaction id for PITR
target_lsn (str|None) – recovery target LSN for PITR
target_immediate (bool|None) – end recovery as soon as consistency is reached
target_action (str|None) – recovery target action for PITR

_setup(backup_info, remote_command, dest, recovery_conf_filename)View on GitHub #

Prepare the recovery_info dictionary for the recovery, as well as temporary working directory

Parameters:

backup_info (barman.infofile.LocalBackupInfo) – representation of a backup
remote_command (str) – ssh command for remote connection
recovery_conf_filename (str|None) – filename for storing recovery configurations

Return dict:

recovery_info dictionary, holding the basic values for a recovery

_start_backup_copy_message()View on GitHub #: Write the start backup copy message to the output.

_xlog_copy(required_xlog_files, wal_dest, remote_command)View on GitHub #

Restore WAL segments

Parameters:

required_xlog_files – list of all required WAL files
wal_dest – the destination directory for xlog recover
remote_command – default None. The remote command to recover the xlog, in case of remote backup.

close()View on GitHub #: Cleanup operations for a recovery

recover(backup_info, dest, wal_dest=None, tablespaces=None, remote_command=None, target_tli=None, target_time=None, target_xid=None, target_lsn=None, target_name=None, target_immediate=False, exclusive=False, target_action=None, standby_mode=None, recovery_conf_filename=None)View on GitHub #

Performs a recovery of a backup

This method should be called in a closing context

Parameters:

backup_info (barman.infofile.BackupInfo) – the backup to recover
dest (str) – the destination directory
wal_dest (str|None) – the destination directory for WALs when doing PITR. See _set_pitr_targets() for more details.
tablespaces (dict[str,str]|None) – a tablespace name -> location map (for relocation)
remote_command (str|None) – The remote command to recover the base backup, in case of remote backup.
target_tli (str|None) – the target timeline
target_time (str|None) – the target time
target_xid (str|None) – the target xid
target_lsn (str|None) – the target LSN
target_name (str|None) – the target name created previously with pg_create_restore_point() function call
target_immediate (str|None) – end recovery as soon as consistency is reached
exclusive (bool) – whether the recovery is exclusive or not
target_action (str|None) – The recovery target action
standby_mode (bool|None) – standby mode
recovery_conf_filename (str|None) – filename for storing recovery configurations

class barman.recovery_executor.RecoveryOperation(config, server, backup_manager)View on GitHub #

Bases: ABC

A base class for recovery operations.

This class defines the interface for recovery operations that can be executed on backups. Subclasses must implement the _should_execute() and _execute() methods, which checks if the operation should be executed and executes the actual operation, respectively.

This class also provides utility methods for executing operations on backup trees, and creating volatile backup info objects.

Variables:: NAME – str: The name of the operation, used for identification.

NAME = None#

__init__(config, server, backup_manager)View on GitHub #

Constructor.

Parameters:

config (barman.config.Config) – The Barman configuration
server (barman.server.Server) – The Barman server instance
backup_manager (barman.backup.BackupManager) – The BackupManager instance

_abc_impl = <_abc._abc_data object>#

_create_volatile_backup_info(backup_info, base_directory)View on GitHub #

Create a VolatileBackupInfo instance as a copy of the given backup_info with base_directory as its location.

Parameters:

backup_info (barman.infofile.LocalBackupInfo) – The original backup info
base_directory (str) – The base directory where the new volatile backup info will be created

Return type:

barman.infofile.VolatileBackupInfo

Returns:

A new VolatileBackupInfo instance that is a copy of the original backup_info, but with the specified base directory

abstractmethod _execute(backup_info, destination, tablespaces, remote_command, recovery_info, safe_horizon, is_last_operation)View on GitHub #

Execute the operation for a given backup.

Parameters:

backup_info (barman.infofile.LocalBackupInfo) – An object representing the backup
destination (str) – The destination directory where the output of the operation will be stored
tablespaces (dict[str,str]|None) – A dictionary mapping tablespace names to their target directories. This is the relocation chosen by the user when invoking the restore command. If None, it means no relocation was chosen
remote_command (str|None) – The SSH remote command to use for the recovery, in case of a remote recovery. If None, it means the recovery is local
recovery_info (dict[str,any]) – A dictionary that populated with metadata about the recovery process
safe_horizon (datetime.datetime|None) – The safe horizon of the backup. Any file rsync-copied after this time has to be checked with checksum
is_last_operation (bool) – Whether this is the last operation in the recovery chain

Return barman.infofile.VolatileBackupInfo:

The respective volatile backup info of backup_info which reflects all changes performed by the operation

_execute_on_chain(backup_info, destination, method, *args, **kwargs)View on GitHub #

Executes a given method iteratively on all backups in a chain. In case of a non-incremental backup, it executes the method only on the specified backup, as usual.

This is a shorthand for operations such as decrypting or decompressing incremental backups, where the operation must be applied not only to the target backup but also to all its ascendants that are also encrypted/compressed.

method must return a barman.infofile.VolatileBackupInfo object.

This method also ensures that all resulting volatile backups are properly re-linked in memory so that tree-based operations like walk_to_root() continue to work.

Note

This method executes the operation only in the backups that need it. If the chain contains backups that do not require the operation, it will skip the operation for those backups, and will simply move (or copy) the backup to the destination directory.

Parameters:

backup_info (barman.infofile.LocalBackupInfo) – The backup in recovery. In case of an incremental backup, all its ascendants are also processed
destination (str) – The destination directory where the output of the operation will be stored
method (callable) – The method to execute on the backup. In case of an incremental backup, this method is also executed on all its ascendants
args – Positional arguments to pass to the method
kwargs – Keyword arguments to pass to the method

Return barman.infofile.VolatileBackupInfo:

The respective volatile backup info of backup_info which reflects all changes performed by the operation

_get_command_interface(remote_command)View on GitHub #

Get the command interface for executing operations.

The command interface can be a barman.fs.UnixLocalCommand or a barman.fs.UnixRemoteCommand, depending on where the operation is meant to be executed (if config.staging_location is remote or local).

Parameters:: remote_command (str|None) – The SSH remote command to use for the recovery, in case of a remote recovery. If None, it means the recovery is local
Return barman.fs.UnixLocalCommand:: The command interface for executing operations

_link_tablespaces(backup_info, pgdata_dir, tablespaces, is_last_operation)View on GitHub #

Create the symlinks for the tablespaces in the destination directory.

Each tablespace has a symlink created in the pg_tblspc directory pointing to the respective tablespace location after the recovery.

Note:: “pg_tblspc” directory is created even if there are no tablespaces to be linked, so we comply with the structure created by Postgres.

Parameters:

backup_info (barman.infofile.VolatileBackupInfo) – The volatile backup info representing the backup state
pgdata_dir (str) – The PGDATA directory of the restored backup
tablespaces (dict[str,str]|None) – A dictionary mapping tablespace names to their target directories. This is the relocation chosen by the user when invoking the restore command. If None, it means no relocation was chosen. Only used if it is_last_operation.
is_last_operation (bool) – Whether this is the last operation in the recovery chain

_post_recovery_cleanup(destination)View on GitHub #

Perform cleanup actions after the recovery operation is completed.

This takes care of removing unnecessary files on the restored backup. This method is useful for certain operations that direct its output directly to the final destination, without the means to ignore certain files.

Note

Previously in Barman, rsync was the only way we copied files to the final destination. The RsyncCopyOperation class has an exclude parameter, which is used to ignore unwanted files, hence it was guaranteed such files would never appear in the destination directory. With the new structure provided by the MainRecoveryExecutor, we have operations that might direct its output straight to the destination directory, e.g. CombineOperation or DecryptOperation, without providing any means to exclude specific content. For these cases, we need to ensure that unwanted files are removed after the operation is finished, which is the main purpose of this method.

Parameters:: destination (str) – The destination directory where the recovery was performed

_prepare_directory(dest_dir, delete_if_exists=True)View on GitHub #

Prepare a directory for receiving a backup operation’s output.

This method is responsible for removing a directory if it already exists, then (re)creating it and ensuring the correct permissions.

Parameters:

dest_dir (str) – The destination directory
delete_if_exists (bool) – If dest_dir should be removed before we attempt to create it.

abstractmethod _should_execute(backup_info)View on GitHub #

Check if the operation should be executed on the given backup.

This is checked before the operation is executed against each backup in the chain.

This method must be overridden by subclasses to implement specific checks for whether the operation should be executed on the provided backup_info.

Parameters:: backup_info (barman.infofile.LocalBackupInfo) – The backup info to check
Return bool:: True if the operation should be executed, False otherwise

cleanup_staging_dir()View on GitHub #

Cleans up the staging directory if exists.

Attempts to delete the staging directory specified by self.staging_path using the operation command interface. If the deletion fails, a warning is logged with the error details.

Raises:: CommandFailedException – If the deletion operation fails.

execute(backup_info, destination, tablespaces=None, remote_command=None, recovery_info=None, safe_horizon=None, is_last_operation=False)View on GitHub #

Execute the operation.

Note

This method is the entry point for executing operations. It calls the respective underlying _execute() method of the class, which contains the actual implementation for dealing with the operation.

Parameters:

backup_info (barman.infofile.LocalBackupInfo) – An object representing the backup
destination (str) – The destination directory where the output of the operation will be stored
tablespaces (dict[str,str]|None) – A dictionary mapping tablespace names to their target directories. This is the relocation chosen by the user when invoking the restore command. If None, it means no relocation was chosen
remote_command (str|None) – The SSH remote command to use for the recovery, in case of a remote recovery. If None, it means the recovery is local
recovery_info (dict[str,any]) – A dictionary that populated with metadata about the recovery process
safe_horizon (datetime.datetime|None) – The safe horizon of the backup. Any file rsync-copied after this time has to be checked with checksum
is_last_operation (bool) – Whether this is the last operation in the recovery chain

Return barman.infofile.VolatileBackupInfo:

The respective volatile backup info of backup_info which reflects all changes performed by the operation

property staging_pathView on GitHub #

Returns the staging path for the current process.

The staging path is constructed by joining the base staging path from the configuration with the class name and the current process ID.

Returns:: The full staging path as a string.
Return type:: str

class barman.recovery_executor.RemoteConfigRecoveryExecutor(backup_manager)View on GitHub #

Bases: RecoveryExecutor

Recovery executor which retrieves config files from the recovery directory instead of the backup directory. Useful when the config files are not available in the backup directory (e.g. compressed backups).

_conf_files_exist(conf_files, backup_info, recovery_info)View on GitHub #

Determine whether the conf files in the supplied list exist in the backup represented by backup_info.

Parameters:

conf_files (list[str]) – List of config files to be checked.
backup_info (BackupInfo) – Backup information for the backup being recovered.
recovery_info (dict) – Dictionary of recovery information.

Return type:

dict[str,bool]

Returns:

A dict representing a map of conf_file:exists.

_copy_conf_files_to_tempdir(backup_info, recovery_info, remote_command=None)View on GitHub #

Copy conf files from the backup location to a temporary directory so that they can be checked and mangled.

Parameters:

backup_info (BackupInfo) – Backup information for the backup being recovered.
recovery_info (dict) – Dictionary of recovery information.
remote_command (str) – The ssh command to be used when copying the files.

Return type:

list[str]

Returns:

A list of paths to the destination conf files.

class barman.recovery_executor.RsyncCopyOperation(config, server, backup_manager)View on GitHub #

Bases: RecoveryOperation

Operation responsible for copying the backup data using rsync.

This operation copies PGDATA and respective tablespaces of a backup to a specified destination, making sure to exclude irrelevant files and directories.

Variables:: NAME – str: The name of the operation, used for identification

NAME = 'barman-rsync-copy'#

_abc_impl = <_abc._abc_data object>#

_copy_backup_dir(backup_info, controller, dest_prefix, vol_backup_info)View on GitHub #

Copy the backup directory to the destination.

Copies the entire backup directory (as in the Barman catalog) to the specified destination, ensuring that the directory structure is preserved.

Parameters:

backup_info (barman.infofile.LocalBackupInfo) – The backup info to copy
controller (barman.copy_controller.RsyncCopyController) – The rsync controller object
dest_prefix (str) – The prefix to add to the destination path
vol_backup_info (barman.infofile.VolatileBackupInfo) – The volatile backup info that is the result of the whole operation

Raises:

barman.exceptions.DataTransferFailure – If the copy operation fails

_copy_pgdata_and_tablespaces(backup_info, controller, dest_prefix, destination, tablespaces)View on GitHub #

Copy the PGDATA and tablespaces to the specified destination.

Copies the PGDATA to the root of destination and tablespaces to their final destination, honoring relocation if requested.

Parameters:

backup_info (barman.infofile.LocalBackupInfo) – The backup info to copy
controller (barman.copy_controller.RsyncCopyController) – The rsync controller object
dest_prefix (str) – The prefix to add to the destination path
destination (str) – The destination directory for the backup
tablespaces (dict[str,str]|None) – A dictionary mapping tablespace names to their target directories. This is the relocation chosen by the user when invoking the restore command. If None, it means no relocation was chosen

Raises:

barman.exceptions.DataTransferFailure – If the copy operation fails

_execute(backup_info, destination, tablespaces, remote_command, recovery_info, safe_horizon, is_last_operation)View on GitHub #

Execute the operation for a given backup.

Parameters:

backup_info (barman.infofile.LocalBackupInfo) – An object representing the backup
destination (str) – The destination directory where the output of the operation will be stored
tablespaces (dict[str,str]|None) – A dictionary mapping tablespace names to their target directories. This is the relocation chosen by the user when invoking the restore command. If None, it means no relocation was chosen
remote_command (str|None) – The SSH remote command to use for the recovery, in case of a remote recovery. If None, it means the recovery is local
recovery_info (dict[str,any]) – A dictionary that populated with metadata about the recovery process
safe_horizon (datetime.datetime|None) – The safe horizon of the backup. Any file rsync-copied after this time has to be checked with checksum
is_last_operation (bool) – Whether this is the last operation in the recovery chain

Return barman.infofile.VolatileBackupInfo:

The respective volatile backup info of backup_info which reflects all changes performed by the operation

_get_command_interface(remote_command)View on GitHub #

Get the command interface for executing operations.

The command interface will be a barman.fs.UnixLocalCommand or a barman.fs.UnixRemoteCommand, depending on whether the remote_command is set or not.

Parameters:: remote_command (str|None) – The SSH remote command to use for the recovery, in case of a remote recovery. If None, it means the recovery is local
Return barman.fs.UnixLocalCommand:: The command interface for executing operations

_rsync_backup_copy(backup_info, destination, tablespaces, remote_command, safe_horizon, is_last_operation)View on GitHub #

Perform the rsync copy of the backup data to the specified destination.

When this is the last operation in the recovery chain, it copies the PGDATA to the root of destination and tablespaces to their final destination, honoring relocation, if requested. Otherwise, it copies the whole backup directory (as in the barman catalog) to destination (a staging directory, in this case).

Parameters:

backup_info (barman.infofile.LocalBackupInfo) – The backup info to copy
destination (str) – The destination directory
tablespaces (dict[str,str]|None) – A dictionary mapping tablespace names to their target directories. This is the relocation chosen by the user when invoking the restore command. If None, it means no relocation chosen
remote_command (str|None) – The SSH remote command to use for the recovery, in case of a remote recovery. If None, it means the recovery is local
safe_horizon (datetime.datetime|None) – The safe horizon of the backup. Any file rsync-copied after this time has to be checked with checksum
is_last_operation (bool) – Whether this is the last operation in the recovery chain

Return barman.infofile.VolatileBackupInfo:

The respective volatile backup info of backup_info which reflects all changes performed by the operation

_should_execute(backup_info)View on GitHub #

Check if the rsync copy operation should be executed on the given backup.

Parameters:: backup_info (barman.infofile.LocalBackupInfo) – The backup info to check
Return bool:: True if the operation should be executed, False otherwise

class barman.recovery_executor.SnapshotRecoveryExecutor(backup_manager)View on GitHub #

Bases: RemoteConfigRecoveryExecutor

Recovery executor which performs barman recovery tasks for a backup taken with backup_method snapshot.

It is responsible for:

Checking that disks cloned from the snapshots in the backup are attached to the recovery instance and that they are mounted at the correct location with the expected options.

Copying the backup_label into place.

Applying the requested recovery options to the PostgreSQL configuration.

It does not handle the creation of the recovery instance, the creation of new disks from the snapshots or the attachment of the disks to the recovery instance. These are expected to have been performed before the barman recover runs.

_backup_copy(backup_info, dest, remote_command=None, **kwargs)View on GitHub #

Copy any files from the backup directory which are required by the snapshot recovery (currently only the backup_label).

Parameters:

backup_info (barman.infofile.LocalBackupInfo) – the backup to recover
dest (str) – the destination directory

_backup_copy_failure_message(e)View on GitHub #: Write the backup failure message to the output.

_prepare_tablespaces(backup_info, cmd, dest, tablespaces)View on GitHub #

There is no need to prepare tablespace directories because they will already be present on the recovery instance through the cloning of disks from the backup snapshots.

This function is therefore a no-op.

_start_backup_copy_message()View on GitHub #: Write the start backup copy message to the output.

static check_mount_points(backup_info, attached_volumes, cmd)View on GitHub #

Check that each disk cloned from a snapshot is mounted at the same mount point as the original disk and with the same mount options.

Raises a RecoveryPreconditionException if any of the devices supplied in attached_snapshots are not mounted at the mount point or with the mount options specified in the snapshot metadata.

Parameters:

backup_info (BackupInfo) – Backup information for the backup being recovered.
attached_volumes (dict[str,barman.cloud.VolumeMetadata]) – Metadata for the volumes attached to the recovery instance.
cmd (UnixLocalCommand) – The command wrapper for running commands on the recovery instance.

static check_recovery_dir_exists(recovery_dir, cmd)View on GitHub #

Verify that the recovery directory already exists.

Parameters:

recovery_dir (str) – Path to the recovery directory on the recovery instance
cmd (UnixLocalCommand) – The command wrapper for running commands on the recovery instance.

static get_attached_volumes_for_backup(snapshot_interface, backup_info, instance_name)View on GitHub #

Verifies that disks cloned from the snapshots specified in the supplied backup_info are attached to the named instance and returns them as a dict where the keys are snapshot names and the values are the names of the attached devices.

If any snapshot associated with this backup is not found as the source for any disk attached to the instance then a RecoveryPreconditionException is raised.

Parameters:

snapshot_interface (CloudSnapshotInterface) – Interface for managing snapshots via a cloud provider API.
backup_info (BackupInfo) – Backup information for the backup being recovered.
instance_name (str) – The name of the VM instance to which the disks to be backed up are attached.

Return type:

dict[str,str]

Returns:

A dict where the key is the snapshot name and the value is the device path for the source disk for that snapshot on the specified instance.

Performs a recovery of a snapshot backup.

This method should be called in a closing context.

Parameters:

backup_info (barman.infofile.BackupInfo) – the backup to recover
dest (str) – the destination directory
wal_dest (str|None) – the destination directory for WALs when doing PITR. See _set_pitr_targets() for more details.
tablespaces (dict[str,str]|None) – a tablespace name -> location map (for relocation)
remote_command (str|None) – The remote command to recover the base backup, in case of remote backup.
target_tli (str|None) – the target timeline
target_time (str|None) – the target time
target_xid (str|None) – the target xid
target_lsn (str|None) – the target LSN
target_name (str|None) – the target name created previously with pg_create_restore_point() function call
target_immediate (str|None) – end recovery as soon as consistency is reached
exclusive (bool) – whether the recovery is exclusive or not
target_action (str|None) – The recovery target action
standby_mode (bool|None) – standby mode
recovery_conf_filename (str|None) – filename for storing recovery configurations
recovery_instance (str|None) – The name of the recovery node as it is known by the cloud provider

barman.recovery_executor.recovery_executor_factory(backup_manager, backup_info)View on GitHub #

Helper function to create an appropriate recovery executor based on the backup type.

Parameters:

backup_manager (barman.backup.BackupManager) – The backup manager instance
backup_info (barman.infofile.LocalBackupInfo) – The backup info to restore

Return barman.recovery_executor.RecoveryExecutor:

An instance of the appropriate recovery executor

barman.recovery_executor module#

This Page