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_BACKUP_TYPE_FILTER = ('full', 'incremental', 'rsync', 'snapshot')

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>

_add_json_to_tar(tar, filename, json_content)View on GitHub

Add a JSON string as a file to the tarball.

Parameters:

• tar (TarFile) – the tar file object

• filename (str) – name of the file in the tarball

• json_content (str) – JSON string content

_add_metadata_to_tar(tar, identity_data, backup_info, barman_data)View on GitHub

Add metadata files to the tarball root.

Parameters:

• tar (TarFile) – the tar file object

• identity_data (dict) – server identity information

• backup_info (BackupInfo) – backup information object

• barman_data (dict) – system information

_add_wal_data_to_tar(tar, backup_info)View on GitHub

Add WAL files and xlog.db metadata to the tarball.

This method exports all WAL files required for backup consistency from begin_wal to end_wal (inclusive) and creates an xlog.db file containing metadata for the exported WAL files. Uses a single-pass merge-step algorithm, isolated in a helper method.

Uses a temporary file to avoid memory overhead when exporting backups with many WAL files.

Parameters:

• tar (TarFile) – the tar file object

• backup_info (BackupInfo) – the backup information

_collect_wal_files_for_export(tar, backup_info, xlogdb_file)View on GitHub

Merge-step algorithm for collecting WAL files and xlog.db metadata for export.

Writes xlog.db lines directly to the provided file object to avoid memory overhead for backups with many WAL files.

Parameters:

• tar (TarFile) – the tar file object

• backup_info (BackupInfo) – the backup information

• xlogdb_file (file) – file object to write xlog.db metadata lines

Returns:

count of WAL files added to the tarball

Return type:

int

Raises:

ExportBackupException – for WAL/xlogdb mismatches or missing files

_delete_cloud_backup_data(backup)View on GitHub

Delete backup data from its cloud storage path.

Parameters:

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

_encrypt_backup(backup_info)View on GitHub

Perform encryption of the base backup and tablespaces

Parameters:

backup_info (barman.infofile.LocalBackupInfo) – backup information

Raises:

BackupException – If the encryption validation fails

_encrypt_tar_backup(backup_info, encryption)View on GitHub

Perform encryption of base backup and tablespaces in tar format.

All .tar and .tar.* files under the backup data directory are encrypted.

Parameters:

• backup_info (barman.infofile.LocalBackupInfo) – Backup information

• encryption (barman.encryption.Encryption) – The encryption handler class

_extract_tarball(input_tarball, staging_dir)View on GitHub

Extract the exported tarball to a staging directory.

Uses streaming mode (r|*) to keep only one TarInfo object in memory at a time, avoiding excessive memory usage for tarballs with many files.

Parameters:

• input_tarball (str) – path to the tarball

• staging_dir (str) – target directory for extraction

Raises:

ImportBackupException – if extraction fails or an unsafe member is encountered. Symlinks under backup/data/pg_tblspc/ are skipped rather than rejected.

_import_backup_data(staging_dir, backup_info)View on GitHub

Move backup data from the staging directory to the target backup location. Assumes the pre-flight in import_backup() has already verified that backup/ exists in the staging dir.

Parameters:

• staging_dir (str) – path to the staging directory

• backup_info (LocalBackupInfo) – the backup info object whose get_basebackup_directory() provides the target path

Raises:

ImportBackupException – if the data move fails

_import_backup_metadata(staging_dir, backup_info)View on GitHub

Load backup.info from the staging directory into backup_info, persist it to the catalog, and register it in the cache. Assumes the pre-flight in import_backup() has already verified that backup.info exists in the staging dir.

Parameters:

• staging_dir (str) – path to the staging directory

• backup_info (LocalBackupInfo) – the backup info object to populate from the staging file and register in the catalog

Raises:

ImportBackupException – if metadata loading or registration fails

_import_backup_wals(staging_dir)View on GitHub

Import WAL files from the staging directory into the server’s WAL archive and merge xlog.db entries into the server’s WAL catalog.

Uses a streaming merge-step to combine import entries with the existing xlog.db without loading the entire file into memory. Operates under the server’s xlog.db lock to prevent concurrent modifications. Returns a rollback callable that will undo all changes (remove imported WAL files and rebuild xlog.db to a consistent state derived from the on-disk WAL archive) if a later step in the import process fails.

Parameters:

staging_dir (str) – path to the staging directory

Returns:

a callable that rolls back all WAL import side effects

Return type:

callable

Raises:

ImportBackupException – if WAL import fails

_iter_tarball_xlogdb(staging_dir)View on GitHub

Stream the tarball’s xlog.db line by line. Yields (stripped_line, wal_name) for each non-blank entry, in the order the entries appear in the file (which is sorted by WAL name — the export side writes via a merge-step over the server catalog, so this invariant is guaranteed for any tarball produced by barman export-backup).

Parameters:

staging_dir (str) – path to the staging directory

Raises:

ImportBackupException – on I/O errors opening the file or on a malformed line (with a line number)

_load_backup_cache()View on GitHub

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

_load_backups_from_cloud()View on GitHub

Fetch backup.info files from the cloud storage and populate the cache.

_read_identity_from_tarball(input_tarball)View on GitHub

Read identity.json directly from the tarball without extracting.

Uses streaming mode (r|*) to avoid loading all TarInfo objects into memory. Since the export writes metadata first, identity.json is found immediately.

Parameters:

input_tarball (str) – path to the tarball

Returns:

parsed identity data

Return type:

dict

Raises:

ImportBackupException – if identity.json is missing or unreadable

_reconstruct_tablespace_symlinks(staging_dir, backup_info)View on GitHub

Recreate pg_tblspc symlinks in the staging directory after tarball extraction.

pg_basebackup emits tablespace entries as symlinks directly under data/pg_tblspc/<oid>. _extract_tarball() skips these members to avoid the broad symlink-rejection check. This method recreates them pointing to the correct destination-catalog paths (backup_info.get_data_directory(oid)) before the staging backup/ tree is moved to its final location by _import_backup_data().

This is a no-op when backup_info carries no tablespaces.

Parameters:

• staging_dir (str) – path to the staging directory

• backup_info (LocalBackupInfo) – backup info whose tablespaces attribute provides the OID list

Raises:

ImportBackupException – if a symlink cannot be created

_rollback_wal_import(moved_files, created_dirs)View on GitHub

Undo WAL import side effects: remove moved WAL files, remove newly-created empty hash directories, and rebuild xlog.db from the WAL archive on disk.

Parameters:

• moved_files (list) – list of WAL file paths that were moved

• created_dirs (list) – list of hash directories that were created

_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_import_identity(export_identity, local_identity)View on GitHub

Validate that the exported backup belongs to the target server by comparing identity data.

Parameters:

• export_identity (dict) – identity data from the exported tarball

• local_identity (dict) – local server identity data

Raises:

ImportBackupException – if identity validation fails

_validate_incremental_backup_configs(**kwargs)View on GitHub

Check required configurations for a Postgres incremental backup

Raises:

BackupException – if a required configuration is missing

_verify_staged_wals(staging_dir, backup_info)View on GitHub

Single-pass verification of the staged WAL set. Iterates the staging xlog.db once, advancing pointers in lock-step against:

• the required WAL segments from backup_info (sorted by name)

• the target server’s existing xlog.db (sorted by name)

For each entry in the staging xlog.db this verifies:

• it covers the next required WAL (no gap in the required range)

• the physical file exists in staging_dir/wals/<hash>/<name>

• it does not collide with the server’s xlog.db

• the physical file does not collide with the server’s wals_directory (catches the case where xlog.db is stale)

Memory is O(1) on both xlog.db streams; only the truncated list of conflict names is accumulated for error reporting.

Parameters:

• staging_dir (str) – path to the staging directory

• backup_info (LocalBackupInfo) – the backup info with begin/end_wal

Raises:

ImportBackupException – on missing required WALs, missing physical files, malformed xlog.db, or conflicts with the target server’s WAL archive

_verify_staging(staging_dir, backup_info)View on GitHub

Pre-flight: confirm the extracted staging directory is structurally valid and that the staged WAL set will be safe to publish into the catalog. Loads backup.info from staging into backup_info as a side effect so callers don’t have to do it separately (_import_backup_metadata() will re-load idempotently and persist later).

Parameters:

• staging_dir (str) – path to the staging directory

• backup_info (LocalBackupInfo) – backup info object to populate from the staging backup.info and use for WAL verification

Raises:

ImportBackupException – on any structural or WAL-set issue

_verify_staging_layout(staging_dir)View on GitHub

Verify that the staging directory contains the entries an exported tarball is expected to provide: backup/, backup.info, wals/, and xlog.db. Raises ImportBackupException with a clear message naming the missing entry on the first failure.

Parameters:

staging_dir (str) – path to the staging directory

Raises:

ImportBackupException – if any expected entry is missing

_wal_conflicts_with_server(wal_name, tarball_line, tarball_wal_path, server_line, server_wal_path)View on GitHub

Classify a tarball WAL against the server’s current state.

Returns True if the server has this WAL in a form that disagrees with the tarball — i.e., a real conflict that must block the import.

Returns False for both safe cases:

• clean import: the server has neither the xlog.db entry nor the file on disk.

• idempotent re-import: the server has both the xlog.db entry and the file, AND the xlog.db metadata agrees on every field except compression (see note below), AND the WAL file contents are byte-equal. This legitimately happens whenever the tarball contains WALs still alive in the target server’s catalog — for example, importing a tarball whose required WAL range overlaps with WALs the server has continued to archive on its own.

  A WAL’s on-disk form is fixed at archive time (its compression and encryption mode are recorded in xlog.db and not re-applied later), so a byte-equal file comparison is sufficient — no decoding or decompression is required.

Note

compression is intentionally excluded from the metadata comparison. Server.rebuild_xlogdb (which is also our rollback mechanism — see _rollback_wal_import) detects file format by reading magic bytes, and for a WAL that is both compressed AND encrypted, the visible outer magic is the encryption magic. A rebuild therefore clears the compression field that the original xlog.db had recorded. Without this exception, a previously-correct tarball would become non-importable any time the server’s xlog.db gets rebuilt between export and import. The file content itself is the ground truth for “same WAL”, and filecmp.cmp below verifies it.

Parameters:

• wal_name (str) – the WAL name from the tarball

• tarball_line (str) – stripped xlog.db line from the tarball

• tarball_wal_path (str) – path to the WAL file in the staged tarball

• server_line (str|None) – the server’s xlog.db line at or after wal_name (caller is responsible for advancing the pointer)

• server_wal_path (str) – path to where this WAL would live in the server’s wals_directory

Return type:

bool

_xlogdb_metadata_match(line_a, line_b)View on GitHub

Compare two xlog.db lines for equivalence, ignoring the compression field. See the .. note:: in _wal_conflicts_with_server() for why compression is excluded.

Parameters:

• line_a (str) – stripped xlog.db line

• line_b (str) – stripped xlog.db line

Return type:

bool

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.

cloud_wal_archive(wal_path, parallel=0)View on GitHub

Archive a WAL file to cloud storage.

Intended to be used as archive_command in Postgres.

Performs archiving similar to WalArchiver, but with the specific purpose of archiving a WAL file to cloud storage directly from pg_wal, meaning WAL files are not staged in incoming directory and do not go through the usual WAL archiving process. This is done that way because the barman cloud-wal-archive command is intended to replace the script barman-cloud-wal-archive when the Barman server runs in the same host as Postgres. Also, this avoids having to use cp as archive_command, which could send much more WALs to the incoming directory than what Barman is actually able to archive in a timely manner – besides the fact that barman wal-archive is awaken only by barman cron every 1 minute, while archive_command is called by Postgres for every WAL file generated.

Note

This method assumes validation of the WAL file and of the server configuration has already been performed. At this point, we can simply archive the WAL to cloud object storage.

Important

This method cannot be used with LocalWalStorageStrategy because that strategy modifies and/or removes the source WAL file as part of the save() call, which is not acceptable here given we are using the WAL from pg_wal.

Parameters:

• wal_path (str) – the path of the WAL file to archive

• parallel (int) – number of WALs to archive in parallel (0=disabled)

cloud_wal_restore(wal_name, wal_dest, spool_dir)View on GitHub

Restore a WAL file from a cloud object storage.

Parameters:

• wal_name (str) – the name of the WAL file to restore

• wal_dest (str) – the destination path where to restore the WAL file

• spool_dir (str) – the spool directory for extra WALs fetched in parallel

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_backupinfo_file(backup)View on GitHub

Delete the backup.info file of 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

export_backup(backup_info, output_filepath, identity_data, barman_data, compression=None, compression_level=None)View on GitHub

Export a completed backup to a portable tarball format.

This method creates a tarball containing: - identity.json from server - backup.info metadata - barman.json with system information - backup/ directory with complete backup data - wals/ directory with all required WAL files preserving hash structure - xlog.db metadata file for exported WAL files

Metadata files are written first so that the importer can validate server identity in streaming mode (r|*) before reading bulk data.

The caller (server.py) is responsible for: - Generating the export filename - Collecting server-level metadata - Handling checksum calculation and file renaming - Cleanup on failure

Parameters:

• backup_info (BackupInfo) – the backup to export

• output_filepath (str) – full path to the output tarball file

• identity_data (dict) – server identity information

• barman_data (dict) – system information for barman.json

• compression (str|None) – compression algorithm (gzip, bzip2, xz) or None for no compression

• compression_level (int|None) – compression level to pass to the compressor, or None for the default level

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'), backup_type_filter=('full', 'incremental', 'rsync', 'snapshot'))View on GitHub

Get a list of available backups

Parameters:

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

• backup_type_filter – default DEFAULT_BACKUP_TYPE_FILTER. The type 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_closest_backup_id_from_target_lsn(target_lsn, target_tli, status_filter=('WAITING_FOR_WALS', 'DONE'))View on GitHub

Get the id of a backup according to the lsn passed as the recovery target target_lsn, and in the given target_tli, if specified.

Parameters:

• target_lsn (str) – The target value with lsn format, e.g., 3/64000000.

• target_tli (int|None) – The target timeline, if a specific one is required.

• status_filter (tuple[str, ...]) – The status of the backup to return.

Return str|None:

ID of the backup.

get_closest_backup_id_from_target_time(target_time, target_tli, status_filter=('WAITING_FOR_WALS', 'DONE'))View on GitHub

Get the id of a backup according to the time passed as the recovery target target_time, and in the given target_tli, if specified.

Parameters:

• target_time (str) – The target value with timestamp format %Y-%m-%d %H:%M:%S with or without timezone.

• target_tli (int|None) – The target timeline, if a specific one is required.

• status_filter (tuple[str, ...]) – The status of the backup to return.

Return str|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_backup_id_from_target_tli(target_tli, status_filter=('WAITING_FOR_WALS', 'DONE'))View on GitHub

Get the id of a backup according to the timeline passed as the recovery target target_tli.

Parameters:

• target_tli (int) – The target timeline.

• status_filter (tuple[str, ...]) – The status of the backup to return.

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.

get_wal_file_info(filename)View on GitHub

Populate a WalFileInfo object taking into account the server configuration.

Set compression to ‘custom’ if no compression is identified and Barman is configured to use custom compression.

Parameters:

filename (str) – the path of the file to identify

Return type:

barman.infofile.WalFileInfo

import_backup(input_tarball, local_identity, backup_id)View on GitHub

Import a backup from an exported tarball into the Barman catalog.

Extracts the tarball to a temporary staging directory, validates server identity, registers backup metadata, moves backup data to the target location, imports WAL files and merges xlog.db entries. Uses a staging directory to make the write to the catalog atomic — a failed import leaves no partial state.

Parameters:

• input_tarball (str) – path to the exported backup tarball

• local_identity (dict) – local server identity data for validation

• backup_id (str) – the backup ID extracted from the tarball filename

Raises:

ImportBackupException – on identity mismatch or invalid tarball

keep_backup(backup_id, target)View on GitHub

Add a keep annotation for backup with ID backup_id with the specified recovery target.

Parameters:

• backup_id (str) – The ID of the backup to keep

• target (str) – The desired target as defined in barman.annotations.KeepManager

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.

recover(backup_info, dest, wal_dest=None, 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

• 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) – 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

• recovery_option_port (str|None) – port to set in restore command when invoking barman-wal-restore

• custom_restore_command (str|None) – Custom restore command to override Barman’s default (only used with get-wal mode)

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.

release_keep(backup_id)View on GitHub

Remove the keep annotation for backup with ID backup_id.

Parameters:

backup_id (str) – The ID of the backup to release

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