- DESCRIPTION AND USE
- STANDBY PROPERTIES
- LICENSE AND COPYRIGHT
PGObject::Util::Replication::Standby - Manage PG replication standbys
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();
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:
All of those of an SMO plus
The config manager for the PostgreSQL
Last path of the recoveryconf loaded, or the recoveryconf to remove for promoting a standby.
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
Sets the parameter for the recovery.conf
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.
Sets all appropriate parameters from a given recovery.conf at a valid path.
This weill normalize the connection string in URL format.
Returns the contents of the recovery.conf to be used.
Sets the username and password.
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.
Returns the number of bytes passed on the recovery connection between the log series number (lsn) and the current recovery position.
Provides a generic SMO for the immediate upstream server.
Traverses upstream until it finds a server which is not recovering and returns a Master SMO for that server.
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.
Promotes a slave to master. First tries the trigger file if available. Otherwise tries to rename the recovery.conf and restart. Methods tried are:
We can only restart if PGObject::Util::Replication::SMO supports restarting the cluster.
<chris.travers at adjust.com>
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.
You can find documentation for this module with the perldoc command.
You can also look for information at:
RT: CPAN's request tracker (report bugs here)
AnnoCPAN: Annotated CPAN documentation
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.