barman.infofile module

class barman.infofile.BackupInfo(backup_id, **kwargs)View on GitHub

Bases: FieldListFile

DONE = 'DONE'

EMPTY = 'EMPTY'

Conversion to string

FAILED = 'FAILED'

KEEP_FULL = 'KEEP:FULL'

KEEP_STANDALONE = 'KEEP:STANDALONE'

NONE = '-'

OBSOLETE = 'OBSOLETE'

Status according to retention policies

POTENTIALLY_OBSOLETE = 'OBSOLETE*'

RETENTION_STATUS = ('OBSOLETE', 'VALID', 'OBSOLETE*', 'KEEP:FULL', 'KEEP:STANDALONE', '-')

STARTED = 'STARTED'

STATUS_ALL = ('EMPTY', 'STARTED', 'WAITING_FOR_WALS', 'DONE', 'SYNCING', 'FAILED')

STATUS_ARCHIVING = ('STARTED', 'WAITING_FOR_WALS', 'DONE', 'SYNCING')

STATUS_COPY_DONE = ('WAITING_FOR_WALS', 'DONE')

STATUS_NOT_EMPTY = ('STARTED', 'WAITING_FOR_WALS', 'DONE', 'SYNCING', 'FAILED')

SYNCING = 'SYNCING'

VALID = 'VALID'

WAITING_FOR_WALS = 'WAITING_FOR_WALS'

__init__(backup_id, **kwargs)View on GitHub

Stores meta information about a single backup

Parameters:

backup_id (str,None)

_hide_if_null = ('backup_name', 'snapshots_info')

backup_id

backup_label

backup_name

property backup_typeView on GitHub

Returns a string with the backup type label.

Note

Even though this property is available in this base class, it is not expected to be used in the context of cloud backups.

The backup type can be one of the following: - snapshot: If the backup mode starts with snapshot. - rsync: If the backup mode starts with rsync. - incremental: If the mode is postgres and the backup is incremental. - full: If the mode is postgres and the backup is not incremental.

Return str:

The backup type label.

backup_version

begin_offset

begin_time

begin_wal

begin_xlog

children_backup_ids

cluster_size

compression

config_file

copy_stats

data_checksums

deduplicated_size

property deduplication_ratioView on GitHub

Returns a value between and including 0 and 1 related to the estimate deduplication ratio of the backup.

Note

For rsync backups, the size of the backup, which is the sum of all file sizes in basebackup directory, is used to calculate the ratio. For postgres backups, the cluster_size is used, which contains the estimated size of the Postgres cluster at backup time.

We perform this calculation to make an estimation of how much network and disk I/O has been saved when taking an incremental backup through rsync or through pg_basebackup.

We abuse of the term “deduplication” here. It makes more sense to rsync than to postgres method. However, the idea is the same in both cases: get an estimation of resources saving.

Note

Even though this property is available in this base class, it is not expected to be used in the context of cloud backups.

Return float:

The backup deduplication ratio.

end_offset

end_time

end_wal

end_xlog

error

classmethod from_json(server, json_backup_info)View on GitHub

Factory method that builds a BackupInfo object from a json dictionary

Parameters:

• server (barman.Server) – the server related to the Backup

• json_backup_info (dict) – the data set containing values from json

get_external_config_files()View on GitHub

Identify all the configuration files that reside outside the PGDATA.

Returns a list of TypedFile objects.

Return type:

list[TypedFile]

get_required_wal_segments()View on GitHub

Get the list of required WAL segments for the current backup

property has_childrenView on GitHub

Only checks if the backup_info has children

Note

This property only makes sense in the context of local backups stored in the Barman server. However, this property is used for retention policies processing, code which is shared among local and cloud backups. As this property always returns False for cloud backups, it can safely be reused in their code paths as well, though.

Return bool:

True if this backup has at least one child, False otherwise.

hba_file

ident_file

included_files

property is_incrementalView on GitHub

Only checks if the backup_info is an incremental backup

Note

This property only makes sense in the context of local backups stored in the Barman server. However, this property is used for retention policies processing, code which is shared among local and cloud backups. As this property always returns False for cloud backups, it can safely be reused in their code paths as well, though.

Return bool:

True if this backup has a parent, False otherwise.

mode

parent_backup_id

pg_major_version()View on GitHub

Returns the major version of the PostgreSQL instance from which the backup was made taking into account the change in versioning scheme between PostgreSQL < 10.0 and PostgreSQL >= 10.0.

pgdata

server_name

set_attribute(key, value)View on GitHub

Set a value for a given key

size

snapshots_info

status

summarize_wal

systemid

tablespaces

timeline

to_dict()View on GitHub

Return the backup_info content as a simple dictionary

Return dict:

to_json()View on GitHub

Return an equivalent dictionary that uses only json-supported types

version

wal_directory()View on GitHub

Returns “pg_wal” (v10 and above) or “pg_xlog” (v9.6 and below) based on the Postgres version represented by this backup

xlog_segment_size

class barman.infofile.Field(name, dump=None, load=None, default=None, doc=None)View on GitHub

Bases: object

__init__(name, dump=None, load=None, default=None, doc=None)View on GitHub

Field descriptor to be used with a FieldListFile subclass.

The resulting field is like a normal attribute with two optional associated function: to_str and from_str

The Field descriptor can also be used as a decorator

class C(FieldListFile):

x = Field(‘x’) @x.dump def x(val): return ‘0x%x’ % val @x.load def x(val): return int(val, 16)

Parameters:

• name (str) – the name of this attribute

• dump (callable) – function used to dump the content to a disk

• load (callable) – function used to reload the content from disk

• default – default value for the field

• doc (str) – docstring of the filed

dump(to_str)View on GitHub

load(from_str)View on GitHub

class barman.infofile.FieldListFile(**kwargs)View on GitHub

Bases: object

__init__(**kwargs)View on GitHub

Represent a predefined set of keys with the associated value.

The constructor build the object assigning every keyword argument to the corresponding attribute. If a provided keyword argument doesn’t has a corresponding attribute an AttributeError exception is raised.

The values provided to the constructor must be of the appropriate type for the corresponding attribute. The constructor will not attempt any validation or conversion on them.

This class is meant to be an abstract base class.

Raises:

AttributeError

_fields

_hide_if_null = ()

filename

classmethod from_meta_file(filename)View on GitHub

Factory method that read the specified file and build an object with its content.

Parameters:

filename (str) – the file to read

items()View on GitHub

Return a generator returning a list of (key, value) pairs.

If a filed has a dump function defined, it will be used.

load(filename=None, file_object=None)View on GitHub

Replaces the current object content with the one deserialized from the provided file.

This method set the filename attribute.

A ValueError exception is raised if the provided file contains any invalid line.

Parameters:

• filename (str) – path of the file to read

• file_object (file) – a file like object to read from

• filename – the file to read

Raises:

ValueError

save(filename=None, file_object=None)View on GitHub

Serialize the object to the specified file or file object

If a file_object is specified it will be used.

If the filename is not specified it uses the one memorized in the filename attribute. If neither the filename attribute and parameter are set a ValueError exception is raised.

Parameters:

• filename (str) – path of the file to write

• file_object (file) – a file like object to write in

• filename – the file to write

Raises:

ValueError

class barman.infofile.LocalBackupInfo(server, info_file=None, backup_id=None, **kwargs)View on GitHub

Bases: BackupInfo

__init__(server, info_file=None, backup_id=None, **kwargs)View on GitHub

Stores meta information about a single backup

Parameters:

• server (Server)

• info_file (file,str,None)

• backup_id (str,None)

Raises:

BackupInfoBadInitialisation – if the info_file content is invalid or neither backup_info or

backup_manager

config

detect_backup_id()View on GitHub

Detect the backup ID from the name of the parent dir of the info file

get_backup_manifest_path()View on GitHub

Get the full path to the backup manifest file

Return str:

the full path to the backup manifest file.

get_basebackup_directory()View on GitHub

Get the default filename for the backup.info file based on backup ID and server directory for base backups

get_child_backup_info(child_backup_id)View on GitHub

Allow to retrieve a specific child of the current incremental backup, if there are any.

If the child backup exists, the LocalBackupInfo object for it is returned. If does not exist or its status is EMPTY, return None

Parameters:

child_backup_id (str) – the ID of the child backup to retrieve

Return LocalBackupInfo|None:

the child backup info object, or None if it does not exist or is empty.

get_data_directory(tablespace_oid=None)View on GitHub

Get path to the backup data dir according with the backup version

If tablespace_oid is passed, build the path to the tablespace base directory, according with the backup version

Parameters:

tablespace_oid (int) – the oid of a valid tablespace

get_filename()View on GitHub

Get the default filename for the backup.info file based on backup ID and server directory for base backups

get_list_of_files(target)View on GitHub

Get the list of files for the current backup

get_parent_backup_info()View on GitHub

If the backup is incremental, build the LocalBackupInfo object for the parent backup and return it. If the backup is not incremental OR the status of the parent backup is EMPTY, return None.

Return LocalBackupInfo|None:

the parent backup info object, or None if it does not exist or is empty.

is_checksum_consistent()View on GitHub

Check if all backups in the chain are consistent with their checksums configurations.

The backup chain is considered inconsistent if the current backup was taken with data_checksums enabled and any of its ascendants were taken with it disabled. It is considered consistent otherwise.

Note

While this method was created to check inconsistencies in chains of one or more (Postgres 17+ core) incremental backups, it can be safely used with any Postgres version and with any Barman backup method. That is true because it always returns True when called for a Postgres full backup or for a rsync backup.

return bool:

True if it is consistent, False otherwise.

is_full_and_eligible_for_incremental()View on GitHub

Check if this is a full backup taken with postgres method and which is eligible to be a parent for an incremental backup.

Note

Only consider backups which are eligible for Postgres core incremental backups:

• backup_method = postgres

• summarize_wal = on

• is_incremental = False

Return bool:

True if it’s a full backup or False if not.

property is_orphanView on GitHub

Determine if the backup is an orphan.

An orphan backup is defined as a backup directory that contains only a non-empty backup.info file. This may indicate an incomplete delete operation.

Return bool:

True if the backup is an orphan, False otherwise.

save(filename=None, file_object=None)View on GitHub

Serialize the object to the specified file or file object

If a file_object is specified it will be used.

If the filename is not specified it uses the one memorized in the filename attribute. If neither the filename attribute and parameter are set a ValueError exception is raised.

Parameters:

• filename (str) – path of the file to write

• file_object (file) – a file like object to write in

• filename – the file to write

Raises:

ValueError

server

walk_backups_tree(return_self=True)View on GitHub

Walk through all the children backups of the current backup.

Note

The objects are returned with a bottom-up approach, including all children backups plus the caller backup.

Parameters:

return_self (bool) – Whether to return the current backup. Default to True.

Yields:

a generator of LocalBackupInfo objects for each backup, walking from the leaves to self.

walk_to_root(return_self=True)View on GitHub

Walk through all the parent backups of the current backup.

Note

The objects are returned with a bottom-up approach, including all parents backups plus the caller backup if return_self is True.

Parameters:

return_self (bool) – Whether to return the current backup. Default to True.

Yield:

a generator of LocalBackupInfo objects for each parent backup.

class barman.infofile.SyntheticBackupInfo(server, base_directory, backup_id=None, info_file=None, **kwargs)View on GitHub

Bases: LocalBackupInfo

__init__(server, base_directory, backup_id=None, info_file=None, **kwargs)View on GitHub

Stores meta information about a single synthetic backup.

Note

A synthetic backup is a base backup which was artificially created through pg_combinebackup. A synthetic backup is not part of the Barman backup catalog, and only exists so we are able to recover a backup created by pg_combinebackup utility, as almost all functions and methods require a backup info object.

The only difference from this class to its parent LocalBackupInfo is that it accepts a custom base directory for the backup as synthetic backups are expected to live on directories other than the default <server_name>/base path.

Parameters:

• server (barman.server.Server) – the server that owns the synthetic backup

• base_directory (str) – the root directory where this synthetic backup resides, essentially an override to the server.config.basebackups_directory configuration.

• backup_id (str|None) – the backup id of this backup

• info_file (None|str|TextIO) – path or file descriptor of an existing synthetic backup.info file

backup_manager

config

get_basebackup_directory()View on GitHub

Get the backup directory based on its base directory

server

class barman.infofile.Tablespace(name, oid, location)

Bases: tuple

_asdict()

Return a new dict which maps field names to their values.

_field_defaults = {}

_fields = ('name', 'oid', 'location')

classmethod _make(iterable)

Make a new Tablespace object from a sequence or iterable

_replace(**kwds)

Return a new Tablespace object replacing specified fields with new values

location

Alias for field number 2

name

Alias for field number 0

oid

Alias for field number 1

barman.infofile.TypedFile

alias of ConfFile

class barman.infofile.WalFileInfo(**kwargs)View on GitHub

Bases: FieldListFile

Metadata of a WAL file.

compression

compression type

classmethod from_file(filename, compression_manager=None, unidentified_compression=None, **kwargs)View on GitHub

Factory method to generate a WalFileInfo from a WAL file.

Every keyword argument will override any attribute from the provided file. If a keyword argument doesn’t has a corresponding attribute an AttributeError exception is raised.

Parameters:

• filename (str) – the file to inspect

• compression_manager (Compressionmanager) – a compression manager which will be used to identify the compression

• unidentified_compression (str) – the compression to set if the current schema is not identifiable

classmethod from_xlogdb_line(line)View on GitHub

Parse a line from xlog catalogue

Parameters:

line (str) – a line in the wal database to parse

Return type:

WalFileInfo

fullpath(server)View on GitHub

Returns the WAL file full path

Parameters:

server (barman.server.Server) – the server that owns the wal file

name

base name of WAL file

orig_filename

relpath()View on GitHub

Returns the WAL file path relative to the server’s wals_directory

size

WAL file size after compression

time

WAL file modification time (seconds since epoch)

to_json()View on GitHub

Return an equivalent dictionary that can be encoded in json

to_xlogdb_line()View on GitHub

Format the content of this object as a xlogdb line.

barman.infofile.dump_backup_ids(ids)View on GitHub

Dump a list of backup IDs to disk as a string.

Parameters:

ids (list[str]|None) – list of backup IDs, if any

Return str|None:

the dumped string.

barman.infofile.load_backup_ids(string)View on GitHub

Load a list of backup IDs from disk as a list.

Parameters:

string – the string to be loaded as a list.

Return list[str]|None:

the list of backup IDs, if any.

barman.infofile.load_datetime_tz(time_str)View on GitHub

Load datetime and ensure the result is timezone-aware.

If the parsed timestamp is naive, transform it into a timezone-aware one using the local timezone.

Parameters:

time_str (str) – string representing a timestamp

Return datetime:

the parsed timezone-aware datetime

barman.infofile.load_snapshots_info(string)View on GitHub

barman.infofile.load_tablespace_list(string)View on GitHub

Load the tablespaces as a Python list of namedtuple Uses ast to evaluate information about tablespaces. The returned list is used to create a list of namedtuple

Parameters:

string (str)

Return list:

list of namedtuple representing all the tablespaces

barman.infofile.null_repr(obj)View on GitHub

Return the literal representation of an object

Parameters:

obj (object) – object to represent

Return str|None:

Literal representation of an object or None

barman.infofile.output_snapshots_info(snapshots_info)View on GitHub

barman.infofile.output_tablespace_list(tablespaces)View on GitHub

Return the literal representation of tablespaces as a Python string

Parameters:

tablespaces (tablespaces) – list of Tablespaces objects

Return str:

Literal representation of tablespaces