/ 
PGObject-Util-Replication-Standby-0.02
River stage zero No dependents
/ PGObject::Util::Replication::Standby

NAME

PGObject::Util::Replication::Standby - Manage PG replication standbys

VERSION

Version 0.02

SYNOPSIS

use PGObject::Util::Replication::Standby;

my $replica = PGObject::Util::Replication::Standby->new();
$replica->standby_name('denver', 1); // uses slot denver
$replica->upstream_host('pgmain.chicago.mydomain.foo');

#however you may be better off setting cert auth instead.
$replica->credentials('foo', 'superdupersecret');

# finally get the recovery.conf contents
$replica->recoveryconf_contents();

### manage replication slots
# clearing all slots, for example failing over
$replica->clearslots();

# list all slots
$replica->slots();

# add new slot
$replica->addslot('downstream1');

# delete slot
$replica->deleteslot('downstream2');


#also ways to measure recovery lag
$lsn = $standby->recovery_lsn(); # current recovery log location
$standby->lag_bytes_from($lsn);

# Promote to master
$standby->promote();

# we can also get the master from the connection string, for example to look up the 
# wal segments

my $wal_info = $standby->master->ping_wall();

DESCRIPTION AND USE

This module manages replication-related functions on standbys.

A standby is a physical replica (i.e. data files are brought to the same structure). Logical replication in this case is not supported in terms of failover and the like.

This module was written to make the task of managing replicated systems from Rex much easier. The module thus supports the three basic aspects of replication management:

WAL telemetry on the receiving end, and calculating lag
Promotion of a standby in a failover case.

STANDBY PROPERTIES

All of those of an SMO plus

recoveryconf

The config manager for the PostgreSQL

upstream_host

upstream_port

upstream_user

upstream_password

upstream_database

standby_name

recoveryconf_path

Last path of the recoveryconf loaded, or the recoveryconf to remove for promoting a standby.

METHODS

Recovery Configuration

Recovery configuration here provides a basic interface for working with the parameters in the recovery.conf file. Note that this file cannot be managed via ALTER SYSTEM so a physical file must be generated even once this is supported in PGObject::Util::PGConfig

set_recovery_param($name, $value)

Sets the parameter for the recovery.conf

connection_string

connection_string($cstring)

Generates the connection string from the current attributes for the SMO.

We accept reading aboth formats (key/value and URI). We always write URIs.

This function in either form has the side effect of updating the primary_conninfo field in the recoveryconf property.

from_recoveryconf($path)

Sets all appropriate parameters from a given recovery.conf at a valid path.

This weill normalize the connection string in URL format.

recoveryconf_contents

Returns the contents of the recovery.conf to be used.

credentials($user, $pass)

Sets the username and password.

WAL telemetry

WAL telemetry works differently on standby than on a master. The standby is not in charge of writes and so there is no "current" wal location. Instead we go by the latest received location.

This has a number of important implications. After STONITH, we can quickly poll a set of replicas to see who is most current and redirect traffic there. This is most useful in a server down situation so you can ensure that the most recent replica is failed over to.

This can also be used to check WAL telemetry against that on the master to see if there are slow links regarding non-synchronous standby servers and the like.

lag_bytes_from($lsn)

Returns the number of bytes passed on the recovery connection between the log series number (lsn) and the current recovery position.

Upstream traversal

upstream()

Provides a generic SMO for the immediate upstream server.

master()

Traverses upstream until it finds a server which is not recovering and returns a Master SMO for that server.

Promotion

Promotion can be done in this case if we can touch a trigger file specified in the recovery.conf or if we can remove the recovery.conf and restart PostgreSQL.

promote($method)

Promotes a slave to master. First tries the trigger file if available. Otherwise tries to rename the recovery.conf and restart. Methods tried are:

trigger: write to trigger file
recoveryconf: delete recovery.conf

We can only restart if PGObject::Util::Replication::SMO supports restarting the cluster.

AUTHOR

Chris Travers, <chris.travers at adjust.com>

BUGS

Please report any bugs or feature requests to bug-pgobject-util-replication-standby at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=PGObject-Util-Replication-Standby. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc PGObject::Util::Replication::Standby

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2017 Adjust.com

This program is distributed under the (Revised) BSD License: http://www.opensource.org/licenses/BSD-3-Clause

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

* Neither the name of Adjust.com nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.