barman.postgres module

This module represents the interface towards a PostgreSQL server.

class barman.postgres.PostgreSQL(conninfo)View on GitHub

Bases: RemoteStatusMixin

This abstract class represents a generic interface to a PostgreSQL server.

CHECK_QUERY = 'SELECT 1'

MINIMAL_VERSION = 90600

__init__(conninfo)View on GitHub

Abstract base class constructor for PostgreSQL interface.

Parameters:

conninfo (str) – Connection information (aka DSN)

_abc_impl = <_abc._abc_data object>

_check_connection()View on GitHub

Return false if the connection is broken

Return type:

bool

_cursor(*args, **kwargs)View on GitHub

Return a cursor

close()View on GitHub

Close the connection to PostgreSQL

connect()View on GitHub

Generic function for Postgres connection (using psycopg2)

static encode_dsn(parameters)View on GitHub

Build a connection string from a dictionary of connection parameters

Parameters:

parameters (dict[str,str]) – Connection parameters

Return type:

str

get_connection_string(application_name=None)View on GitHub

Return the connection string, adding the application_name parameter if requested, unless already defined by user in the connection string

Parameters:

application_name (str) – the application_name to add

Return str:

the connection string

static int_version_to_string_version(int_version)View on GitHub

takes an int version :param int_version: ex: 10.22 121200 or 130800 :return: str ex 10.22.00 12.12.00 13.8.00

is_minimal_postgres_version()View on GitHub

Checks if postgres version has at least minimal version

property minimal_txt_versionView on GitHub

Human readable version of PostgreSQL (calculated from server_version)

Return type:

str|None

static parse_dsn(dsn)View on GitHub

Parse connection parameters from ‘conninfo’

Parameters:

dsn (str) – Connection information (aka DSN)

Return type:

dict[str,str]

property server_major_versionView on GitHub

PostgreSQL major version (calculated from server_txt_version)

Return type:

str|None

property server_txt_versionView on GitHub

Human readable version of PostgreSQL (calculated from server_version)

Return type:

str|None

property server_versionView on GitHub

Version of PostgreSQL (returned by psycopg2)

class barman.postgres.PostgreSQLConnection(conninfo, immediate_checkpoint=False, slot_name=None, application_name='barman')View on GitHub

Bases: PostgreSQL

This class represents a standard client connection to a PostgreSQL server.

ANY_STREAMING_CLIENT = (1, 2)

HEARTBEAT_QUERY = 'SELECT 1'

STANDBY = 1

WALSTREAMER = 2

__init__(conninfo, immediate_checkpoint=False, slot_name=None, application_name='barman')View on GitHub

PostgreSQL connection constructor.

Parameters:

• conninfo (str) – Connection information (aka DSN)

• immediate_checkpoint (bool) – Whether to do an immediate checkpoint when start a backup

• slot_name (str|None) – Replication slot name

_abc_impl = <_abc._abc_data object>

property archive_timeoutView on GitHub

Retrieve the archive_timeout setting in PostgreSQL

Returns:

The archive timeout (in seconds)

checkpoint()View on GitHub

Execute a checkpoint

property checkpoint_timeoutView on GitHub

Retrieve the checkpoint_timeout setting in PostgreSQL

Returns:

The checkpoint timeout (in seconds)

connect()View on GitHub

Connect to the PostgreSQL server. It reuses an existing connection.

create_restore_point(target_name)View on GitHub

Create a restore point with the given target name

The method executes the pg_create_restore_point() function through a PostgreSQL connection. Only for Postgres versions >= 9.1 when not in replication.

If requirements are not met, the operation is skipped.

Parameters:

target_name (str) – name of the restore point

Returns:

the restore point LSN

Return type:

str|None

property current_sizeView on GitHub

Returns the total size of the PostgreSQL server (requires superuser or pg_read_all_stats)

property current_xlog_file_nameView on GitHub

Get current WAL file from PostgreSQL

Return str:

current WAL file in PostgreSQL

property current_xlog_infoView on GitHub

Get detailed information about the current WAL position in PostgreSQL.

This method returns a dictionary containing the following data:

• location

• file_name

• file_offset

• timestamp

When executed on a standby server file_name and file_offset are always None

Return type:

psycopg2.extras.DictRow

property current_xlog_locationView on GitHub

Get current WAL location from PostgreSQL

Return str:

current WAL location in PostgreSQL

fetch_remote_status()View on GitHub

Get the status of the PostgreSQL server

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]

get_archiver_stats()View on GitHub

This method gathers statistics from pg_stat_archiver. Only for Postgres 9.4+ or greater. If not available, returns None.

Return dict|None:

a dictionary containing Postgres statistics from pg_stat_archiver or None

get_configuration_files()View on GitHub

Get postgres configuration files or an empty dictionary in case of error

Return type:

dict

get_replication_slot(slot_name)View on GitHub

Retrieve from the PostgreSQL server a physical replication slot with a specific slot_name.

This method returns a dictionary containing the following data:

• slot_name

• active

• restart_lsn

Parameters:

slot_name (str) – the replication slot name

Return type:

psycopg2.extras.DictRow

get_replication_stats(client_type=1)View on GitHub

Returns streaming replication information

get_setting(name)View on GitHub

Get a Postgres setting with a given name

Parameters:

name – a parameter name

get_synchronous_standby_names()View on GitHub

Retrieve the list of named synchronous standby servers from PostgreSQL

This method returns a list of names

Return list:

synchronous standby names

get_systemid()View on GitHub

Get a Postgres instance systemid

get_tablespaces()View on GitHub

Returns a list of tablespaces or None if not present

property has_backup_privilegesView on GitHub

Returns true if current user is superuser or, for PostgreSQL 10 or above, is a standard user that has grants to read server settings and to execute all the functions needed for exclusive/concurrent backup control and WAL control.

property has_checkpoint_privilegesView on GitHub

Returns true if the current user is a superuser or if, for PostgreSQL 14 and above, the user has the “pg_checkpoint” role.

property has_connectionView on GitHub

Checks if the Postgres connection has already been set

property has_monitoring_privilegesView on GitHub

Check whether the current user can access monitoring information.

Returns True if the current user is a superuser or if the user has the necessary privileges to monitor system status.

Return type:

bool

Returns:

True if the current user can access monitoring information.

property is_in_recoveryView on GitHub

Returns true if PostgreSQL server is in recovery mode (hot standby)

property is_superuserView on GitHub

Returns true if current user has superuser privileges

property name_mapView on GitHub

Return a map with function and directory names according to the current PostgreSQL version.

Each entry has the current name as key and the name for the specific version as value.

Return type:

dict[str]

send_heartbeat_query()View on GitHub

Sends a heartbeat query to the server with the already opened connection.

Returns tuple[bool, Exception|None]:

A tuple where the first value is a boolean indicating if the query executed successfully or not and the second is the exception raised by psycopg2 in case it did not succeed.

property server_txt_versionView on GitHub

Human readable version of PostgreSQL (returned by the server).

Note: The return value of this function is used when composing include patterns which are passed to rsync when copying tablespaces. If the value does not exactly match the PostgreSQL version then Barman may fail to copy tablespace files during a backup.

start_concurrent_backup(label)View on GitHub

Calls pg_backup_start on the PostgreSQL server using the API introduced with version 9.6

This method returns a dictionary containing the following data:

• location

• timeline

• timestamp

Parameters:

label (str) – descriptive string to identify the backup

Return type:

psycopg2.extras.DictRow

start_exclusive_backup(label)View on GitHub

Calls pg_backup_start() on the PostgreSQL server

This method returns a dictionary containing the following data:

• location

• file_name

• file_offset

• timestamp

Parameters:

label (str) – descriptive string to identify the backup

Return type:

psycopg2.extras.DictRow

stop_concurrent_backup()View on GitHub

Calls pg_backup_stop on the PostgreSQL server using the API introduced with version 9.6

This method returns a dictionary containing the following data:

• location

• timeline

• backup_label

• timestamp

Return type:

psycopg2.extras.DictRow

stop_exclusive_backup()View on GitHub

Calls pg_backup_stop() on the PostgreSQL server

This method returns a dictionary containing the following data:

• location

• file_name

• file_offset

• timestamp

Return type:

psycopg2.extras.DictRow

switch_wal()View on GitHub

Execute a pg_switch_wal()

To be SURE of the switch of a xlog, we collect the xlogfile name before and after the switch. The method returns the just closed xlog file name if the current xlog file has changed, it returns an empty string otherwise.

The method returns None if something went wrong during the execution of the pg_switch_wal command.

Return type:

str|None

property xlog_segment_sizeView on GitHub

Retrieve the size of one WAL file.

In PostgreSQL 11, users will be able to change the WAL size at runtime. Up to PostgreSQL 10, included, the WAL size can be changed at compile time

Returns:

The wal size (In bytes)

class barman.postgres.PostgresKeepAlive(postgres, interval, raise_exception=False)View on GitHub

Bases: object

Context manager to maintain a Postgres connection alive.

A child thread is spawned to execute heartbeat queries in the background at a specified interval during its living context.

It does not open or close any connections on its own. Instead, it waits for the specified connection to be opened on the main thread before start sending any query.

Variables:

THREAD_NAME – The name identifying the keep-alive thread.

THREAD_NAME = 'barman_keepalive_thread'

__init__(postgres, interval, raise_exception=False)View on GitHub

Constructor.

Parameters:

• postgres (barman.postgres.PostgreSQLConnection) – The Postgres connection to keep alive.

• interval (int) – An interval in seconds at which a heartbeat query will be sent to keep the connection alive. A value <= 0 won’t start the keepalive.

• raise_exception (bool) – A boolean indicating if an exception should be raised in case the connection is lost. If True, a PostgresConnectionLost exception will be raised as soon as it’s noticed a connection failure. If False, it will keep executing normally until the context exits.

_prepare_signal_handler()View on GitHub

Set up a signal handler to raise an exception on the main thread when the keep-alive thread wishes to interrupt it. This method listens for a SIGUSR1 signal and, when received, raises a PostgresConnectionLost exception.

Note

This code is, and only works if, executed while on the main thread. We are not able to set a signal listener on a child thread, therefore this method must be executed before the keep-alive thread starts.

_raise_exception_on_main()View on GitHub

Trigger an exception on the main thread at whatever frame is being executed at the moment. This is done by sending a SIGUSR1 signal to the process, which will be caught by the signal handler set previously in this class.

Note

This is an alternative way of interrupting the main thread’s work, since there is no direct way of killing or raising exceptions on the main thread from a child thread in Python. A handler for this signal has been set beforehand by the _prepare_signal_handler method in this class.

_run_keep_alive()View on GitHub

Runs the keepalive until a stop-thread event is set

class barman.postgres.StandbyPostgreSQLConnection(conninfo, primary_conninfo, immediate_checkpoint=False, slot_name=None, primary_checkpoint_timeout=0, application_name='barman')View on GitHub

Bases: PostgreSQLConnection

A specialised PostgreSQLConnection for standby servers.

Works almost exactly like a regular PostgreSQLConnection except it requires a primary_conninfo option at creation time which is used to create a connection to the primary for the purposes of forcing a WAL switch during the stop backup process.

This increases the likelihood that backups against standbys with archive_mode = always and low traffic on the primary are able to complete.

__init__(conninfo, primary_conninfo, immediate_checkpoint=False, slot_name=None, primary_checkpoint_timeout=0, application_name='barman')View on GitHub

Standby PostgreSQL connection constructor.

Parameters:

• conninfo (str) – Connection information (aka DSN) for the standby.

• primary_conninfo (str) – Connection information (aka DSN) for the primary.

• immediate_checkpoint (bool) – Whether to do an immediate checkpoint when a backup is started.

• slot_name (str|None) – Replication slot name.

• str – The application_name to use for this connection.

_abc_impl = <_abc._abc_data object>

_start_wal_switch()View on GitHub

Start switching WALs in a child process.

_stop_backup(stop_backup_fun)View on GitHub

Stop a backup while also calling pg_switch_wal().

Starts a child process to call pg_switch_wal() on the primary before attempting to stop the backup on the standby. The WAL switch is intended to allow the pg_backup_stop call to complete when running against a standby with archive_mode = always. Once the call to stop_concurrent_backup completes the child process is stopped as no further WAL switches are required.

Parameters:

stop_backup_fun (function) – The function which should be called to stop the backup. This will be a reference to one of the superclass methods stop_concurrent_backup or stop_exclusive_backup.

Return type:

psycopg2.extras.DictRow

_stop_wal_switch()View on GitHub

Stop the WAL switching process.

close()View on GitHub

Close the connection to PostgreSQL.

stop_concurrent_backup()View on GitHub

Stop a concurrent backup on a standby PostgreSQL instance.

Return type:

psycopg2.extras.DictRow

stop_exclusive_backup()View on GitHub

Stop an exclusive backup on a standby PostgreSQL instance.

Return type:

psycopg2.extras.DictRow

switch_wal()View on GitHub

Perform a WAL switch on the primary PostgreSQL instance.

switch_wal_in_background(done_q, times=10, wait=10)View on GitHub

Perform a pg_switch_wal in a background process.

This function runs in a child process and is intended to keep calling pg_switch_wal() until it is told to stop or until times is exceeded. The parent process will use done_q to tell this process to stop.

Parameters:

• done_q (multiprocessing.Queue) – A Queue used by the parent process to communicate with the WAL switching process. A value of True on this queue indicates that this function should stop.

• times (int) – The maximum number of times a WAL switch should be performed.

• wait (int) – The number of seconds to wait between WAL switches.

class barman.postgres.StreamingConnection(conninfo)View on GitHub

Bases: PostgreSQL

This class represents a streaming connection to a PostgreSQL server.

CHECK_QUERY = 'IDENTIFY_SYSTEM'

__init__(conninfo)View on GitHub

Streaming connection constructor

Parameters:

conninfo (str) – Connection information (aka DSN)

_abc_impl = <_abc._abc_data object>

connect()View on GitHub

Connect to the PostgreSQL server. It reuses an existing connection.

Returns:

the connection to the server

create_physical_repslot(slot_name)View on GitHub

Create a physical replication slot using the streaming connection :param str slot_name: Replication slot name

drop_repslot(slot_name)View on GitHub

Drop a physical replication slot using the streaming connection :param str slot_name: Replication slot name

fetch_remote_status()View on GitHub

Returns the status of the connection to the PostgreSQL server.

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]

barman.postgres._atexit()View on GitHub

Ensure that all the connections are correctly closed at interpreter shutdown

barman.postgres._live_connections = []

List of connections to be closed at the interpreter shutdown