barman.backup module#

This module represents a backup.

class barman.backup.BackupManager(server)View on GitHub#

Bases: RemoteStatusMixin, KeepManagerMixin

Manager of the backup archive for a server

DEFAULT_STATUS_FILTER = ('WAITING_FOR_WALS', 'DONE')#
DELETE_ANNOTATION = 'delete_this'#
__init__(server)View on GitHub#

Constructor :param server: barman.server.Server

_abc_impl = <_abc._abc_data object>#
_load_backup_cache()View on GitHub#

Populate the cache of the available backups, reading information from disk.

_set_backup_sizes(backup_info, fsync=False)View on GitHub#

Set the actual size on disk of a backup.

Optionally fsync all files in the backup.

Parameters:

  • backup_info (LocalBackupInfo) – the backup to update

  • fsync (bool) – whether to fsync files to disk

_validate_incremental_backup_configs(**kwargs)View on GitHub#

Check required configurations for a Postgres incremental backup

Raises:

BackupException – if a required configuration is missing

archive_wal(verbose=True)View on GitHub#

Executes WAL maintenance operations, such as archiving and compression

If verbose is set to False, outputs something only if there is at least one file

Parameters:

verbose (bool) – report even if no actions

backup(wait=False, wait_timeout=None, name=None, **kwargs)View on GitHub#

Performs a backup for the server

Parameters:

  • wait (bool) – wait for all the required WAL files to be archived

  • wait_timeout (int|None)

  • name (str|None) – the friendly name to be saved with this backup

  • parent_backup_id (str) – id of the parent backup when taking a Postgres incremental backup

Return BackupInfo:

the generated BackupInfo

backup_cache_add(backup_info)View on GitHub#

Register a BackupInfo object to the backup cache.

NOTE: Initialise the cache - in case it has not been done yet

Parameters:

backup_info (barman.infofile.BackupInfo) – the object we want to register in the cache

backup_cache_remove(backup_info)View on GitHub#

Remove a BackupInfo object from the backup cache

This method _must_ be called after removing the object from disk.

Parameters:

backup_info (barman.infofile.BackupInfo) – the object we want to remove from the cache

backup_fsync_and_set_sizes(backup_info)View on GitHub#

Fsync all files in a backup and set the actual size on disk of a backup.

Also evaluate the deduplication ratio and the deduplicated size if applicable.

Parameters:

backup_info (LocalBackupInfo) – the backup to update

check(check_strategy)View on GitHub#

This function does some checks on the server.

Parameters:

check_strategy (CheckStrategy) – the strategy for the management of the results of the various checks

check_backup(backup_info)View on GitHub#

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.

Parameters:

backup_info – the target backup

check_delete_annotation(backup_id)View on GitHub#

Check if a delete annotation exists for the specified backup.

This method checks if the backup identified by backup_id has a delete annotation. It returns True if the annotation exists, otherwise False.

Parameters:

backup_id (str) – The ID of the backup to check.

Return bool:

True if the delete annotation exists, False otherwise.

cron_retention_policy()View on GitHub#

Retention policy management

delete_backup(backup, skip_wal_cleanup_if_standalone=True)View on GitHub#

Delete a backup

Parameters:

  • backup – the backup to delete

  • skip_wal_cleanup_if_standalone (bool) – By default we will skip removing WALs if the oldest backups are standalone archival backups (i.e. they have a keep annotation of “standalone”). If this function is being called in the context of a retention policy however, it is safe to set skip_wal_cleanup_if_standalone to False and clean up WALs associated with those backups.

Return bool:

True if deleted, False if could not delete the backup

delete_backup_data(backup)View on GitHub#

Delete the data contained in a given backup.

Parameters:

backup (barman.infofile.LocalBackupInfo) – the backup to delete

delete_basebackup(backup)View on GitHub#

Delete the basebackup dir of a given backup.

Parameters:

backup (barman.infofile.LocalBackupInfo) – the backup to delete

delete_wal(wal_info)View on GitHub#

Delete a WAL segment, with the given WalFileInfo

Parameters:

wal_info (barman.infofile.WalFileInfo) – the WAL to delete

fetch_remote_status()View on GitHub#

Build additional remote status lines defined by the BackupManager.

This method does not raise any exception in case of errors, but set the missing values to None in the resulting dictionary.

Return type:

dict[str, None|str]

static find_next_backup_in(available_backups, backup_id, status_filter=('WAITING_FOR_WALS', 'DONE'))View on GitHub#

Find the next backup (if any) in the supplied dict of BackupInfo objects.

static find_previous_backup_in(available_backups, backup_id, status_filter=('WAITING_FOR_WALS', 'DONE'))View on GitHub#

Find the next backup (if any) in the supplied dict of BackupInfo objects.

get_available_backups(status_filter=('WAITING_FOR_WALS', 'DONE'))View on GitHub#

Get a list of available backups

Parameters:

status_filter – default DEFAULT_STATUS_FILTER. The status of the backup list returned

get_backup(backup_id)View on GitHub#

Return the backup information for the given backup id.

If the backup_id is None or backup.info file doesn’t exists, it returns None.

Parameters:

backup_id (str|None) – the ID of the backup to return

Return type:

BackupInfo|None

get_backup_id_from_name(backup_name, status_filter=('WAITING_FOR_WALS', 'DONE'))View on GitHub#

Get the id of the named backup, if it exists.

Parameters:

  • backup_name (string) – The name of the backup for which an ID should be returned

  • status_filter (tuple) – The status of the backup to return.

Return string|None:

ID of the backup

get_first_backup_id(status_filter=('WAITING_FOR_WALS', 'DONE'))View on GitHub#

Get the id of the oldest/first backup in the catalog (if exists)

Parameters:

status_filter – The status of the backup to return, default to DEFAULT_STATUS_FILTER.

Return string|None:

ID of the backup

get_last_backup_id(status_filter=('WAITING_FOR_WALS', 'DONE'))View on GitHub#

Get the id of the latest/last backup in the catalog (if exists)

Parameters:

status_filter – The status of the backup to return, default to DEFAULT_STATUS_FILTER.

Return str|None:

ID of the backup

get_last_full_backup_id(status_filter=('WAITING_FOR_WALS', 'DONE'))View on GitHub#

Get the id of the latest/last FULL backup in the catalog (if exists)

Parameters:

status_filter – The status of the backup to return, default to DEFAULT_STATUS_FILTER.

Return str|None:

ID of the backup

get_latest_archived_wals_info()View on GitHub#

Return a dictionary of timelines associated with the WalFileInfo of the last WAL file in the archive, or None if the archive doesn’t contain any WAL file.

Return type:

dict[str, WalFileInfo]|None

get_next_backup(backup_id, status_filter=('WAITING_FOR_WALS', 'DONE'))View on GitHub#

Get the next backup (if any) in the catalog

Parameters:

status_filter – default DEFAULT_STATUS_FILTER. The status of the backup returned

get_previous_backup(backup_id, status_filter=('WAITING_FOR_WALS', 'DONE'))View on GitHub#

Get the previous backup (if any) in the catalog

Parameters:

status_filter – default DEFAULT_STATUS_FILTER. The status of the backup returned

static get_timelines_to_protect(remove_until, deleted_backup, available_backups)View on GitHub#

Returns all timelines in available_backups which are not associated with the backup at remove_until. This is so that we do not delete WALs on any other timelines.

property modeView on GitHub#

Property defining the BackupInfo mode content

put_delete_annotation(backup_id)View on GitHub#

Add a delete annotation to the specified backup.

This method adds an annotation to the backup identified by backup_id to mark it for deletion. The annotation is stored using the annotation manager.

Parameters:

backup_id (str) – The ID of the backup to annotate.

rebuild_xlogdb()View on GitHub#

Rebuild the whole xlog database guessing it from the archive content.

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

Performs a recovery of a backup

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.

  • 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 (bool|None) – end recovery as soon as consistency is reached

  • exclusive (bool) – whether the recovery is exclusive or not

  • target_action (str|None) – default None. The recovery target action

  • standby_mode (bool|None) – the standby mode if needed

  • recovery_conf_filename (str|None) – filename for storing recovery configurations

release_delete_annotation(backup_id)View on GitHub#

Remove the delete annotation from the backup identified by backup_id.

Parameters:

backup_id (str) – The ID of the backup to remove the annotation from.

remove_wal_before_backup(backup_info, timelines_to_protect=None, wal_ranges_to_protect=[])View on GitHub#

Remove WAL files which have been archived before the start of the provided backup.

If no backup_info is provided delete all available WAL files

If timelines_to_protect list is passed, never remove a wal in one of these timelines.

Parameters:

  • backup_info (BackupInfo|None) – the backup information structure

  • timelines_to_protect (set) – optional list of timelines to protect

  • wal_ranges_to_protect (list) – optional list of (begin_wal, end_wal) tuples which define inclusive ranges of WALs which must not be deleted.

Return list:

a list of removed WAL files

static should_remove_wals(backup, available_backups, keep_manager, skip_wal_cleanup_if_standalone, status_filter=('WAITING_FOR_WALS', 'DONE'))View on GitHub#

Determine whether we should remove the WALs for the specified backup.

Returns the following tuple:

  • (bool should_remove_wals, list wal_ranges_to_protect)

Where should_remove_wals is a boolean which is True if the WALs associated with this backup should be removed and False otherwise.

wal_ranges_to_protect is a list of (begin_wal, end_wal) tuples which define inclusive ranges where any matching WAL should not be deleted.

The rules for determining whether we should remove WALs are as follows:

  1. If there is no previous backup then we can clean up the WALs.

  2. If there is a previous backup and it has no keep annotation then do not clean up the WALs. We need to allow PITR from that older backup to the current time.

  3. If there is a previous backup and it has a keep target of “full” then do nothing. We need to allow PITR from that keep:full backup to the current time.

  4. If there is a previous backup and it has a keep target of “standalone”:

  1. If that previous backup is the oldest backup then delete WALs up to the begin_wal of the next backup except for WALs which are >= begin_wal and <= end_wal of the keep:standalone backup - we can therefore add (begin_wal, end_wal) to wal_ranges_to_protect and return True.

  2. If that previous backup is not the oldest backup then we add the (begin_wal, end_wal) to wal_ranges_to_protect and go to 2 above. We will either end up returning False, because we hit a backup with keep:full or no keep annotation, or all backups to the oldest backup will be keep:standalone in which case we will delete up to the begin_wal of the next backup, preserving the WALs needed by each keep:standalone backups by adding them to wal_ranges_to_protect.

This is a static method so it can be re-used by barman-cloud which will pass in its own dict of available_backups.

Parameters:

  • backup_info (BackupInfo) – The backup for which we are determining whether we can clean up WALs.

  • available_backups (dict[str,BackupInfo]) – A dict of BackupInfo objects keyed by backup_id which represent all available backups for the current server.

  • keep_manager (KeepManagerMixin) – An object implementing the KeepManagerMixin interface. This will be either a BackupManager (in barman) or a CloudBackupCatalog (in barman-cloud).

  • skip_wal_cleanup_if_standalone (bool) – If set to True then we should skip removing WALs for cases where all previous backups are standalone archival backups (i.e. they have a keep annotation of “standalone”). The default is True. It is only safe to set this to False if the backup is being deleted due to a retention policy rather than a barman delete command.

  • status_filter – The status of the backups to check when determining if we should remove WALs. default to DEFAULT_STATUS_FILTER.

status()View on GitHub#

This function show the server status

validate_backup_args(**kwargs)View on GitHub#

Validate backup arguments and Postgres configurations. Arguments might be syntactically correct but still be invalid if necessary Postgres configurations are not met.

Parameters:

parent_backup_id (str) – id of the parent backup when taking a Postgres incremental backup

Raises:

BackupException – if a command argument is considered invalid

validate_last_backup_maximum_age(last_backup_maximum_age)View on GitHub#

Evaluate the age of the last available backup in a catalogue. If the last backup is older than the specified time interval (age), the function returns False. If within the requested age interval, the function returns True.

Parameters:

last_backup_maximum_age (timedate.timedelta) – time interval representing the maximum allowed age for the last backup in a server catalogue

Return tuple:

a tuple containing the boolean result of the check and auxiliary information about the last backup current age

validate_last_backup_min_size(last_backup_minimum_size)View on GitHub#

Evaluate the size of the last available backup in a catalogue. If the last backup is smaller than the specified size the function returns False. Otherwise, the function returns True.

Parameters:

last_backup_minimum_size – size in bytes representing the maximum allowed age for the last backup in a server catalogue

Return tuple:

a tuple containing the boolean result of the check and auxiliary information about the last backup current age

verify_backup(backup_info)View on GitHub#

This function should check if pg_verifybackup is installed and run it against backup path should test if pg_verifybackup is installed locally

Parameters:

backup_info – barman.infofile.LocalBackupInfo instance

On this page
Edit on GitHub
Show Source