.TH "MYSQLRPLADMIN" "1" "May 09, 2012" "1.0.3" "MySQL Utilities"
.SH NAME
mysqlrpladmin \- Administration utility for MySQL replication
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.\" Man page generated from reStructeredText.
.
.SH SYNOPSIS
.sp
.nf
.ft C
mysqlrpladmin [options]
.ft P
.fi
.SH DESCRIPTION
.sp
This utility permits users to perform administrative actions on a replication
topology consisting of a master and its slaves. The utility is designed to make
it easy to recover from planned maintenance of the master or from an event that
takes the master offline unexpectedly.
.sp
The act of taking the master offline intentionally and switching control to
another slave is called switchover. In this case, there is no loss of
transactions as the master is locked and all slaves are allowed to catch up to
the master. Once the slaves have read all events from the master, the master is
shutdown and control switched to a slave (in this case called a candidate
slave).
.sp
Recovering from the loss of a downed master is more traumatic and since there
is no way to know what transactions the master may have failed to send, the new
master (called a candidate slave) must be the slave that is most up\-to\-date.
How this is determined depends on the version of the server (see below).
However, it can result in the loss of some transactions that were executed on
the downed master but not sent. The utility accepts a list of slaves to be
considered the candidate slave. If no slave is found to meet the requirements,
the operation will search the list of known slaves.
.sp
The utility also provides a number of useful commands for managing a
replication topology including the following.
.sp
\fBelect\fP
This command is available to only those servers supporting global transaction
identifiers (GTIDs), perform best slave election and report best slave to use
in the event a switchover or failover is required. Best slave election is
simply the first slave to meet the prerequisites. GTIDs are supported in
version 5.6.5 and higher.
.sp
\fBfailover\fP
This command is available to only those servers supporting GTIDs. Conduct
failover to the best slave. The command will test each candidate slave listed
for the prerequisites. Once a candidate slave is elected, it is made a slave of
each of the other slaves thereby collecting any transactions executed on other
slaves but not the candidate. In this way, the candidate becomes the most
up\-to\-date slave.
.sp
\fBgtid\fP
This command is available to only those servers supporting GTIDs. It displays
the contents of the GTID variables, @@GLOBAL.GTID_DONE, @@GLOBAL.GTID_LOST, and
@@GLOBAL.GTID_OWNED. The command also displays universally unique identifiers
(UUIDs) for all servers.
.sp
\fBhealth\fP
Display the replication health of the topology. By default, this includes the
host name, port, role (MASTER or SLAVE) of the server, state of the server (UP
= is connected, WARN = not connected but can ping, DOWN = not connected and
cannot ping), the GTID_MODE, and health state.
.sp
The master health state is based on the following; if GTID_MODE=ON, the server
must have binary log enabled, and there must exist a user with the REPLICATE
SLAVE privilege.
.sp
The slave health state is based on the following; the IO_THREAD and SQL_THREADS
must be running, it must be connected to the master, there are no errors, the
slave delay for non\-gtid enabled scenarios is not more than the threshold
provided by the \fI\%--max-position\fP and the slave is reading the correct
master log file, and slave delay is not more than the
\fI\%--seconds-behind\fP threshold option.
.sp
\fBreset\fP
Execute the STOP SLAVE and RESET SLAVE commands on all slaves.
.sp
\fBstart\fP
Execute the START SLAVE command on all slaves.
.sp
\fBstop\fP
Execute the STOP SLAVE command on all slaves.
.sp
\fBswitchover\fP
Perform slave promotion to a specified candidate slave as designated by the
\fI\%--new-master\fP option. This command is available for both gtid\-enabled
servers and non\-gtid\-enabled scenarios.
.sp
Detection of a downed master is performed as follows. If the connection to the
master is lost, wait \fI\%--timeout\fP seconds and check again. If the master
connection is lost and the master cannot be pinged or reconnected, the failover
event occurs.
.sp
For all commands that require specifying multiple servers, the options require
a comma\-separated list of connection parameters in the following form where the
password, port, and socket are optional.:
.sp
.nf
.ft C
<*user*>[:<*passwd*>]@<*host*>[:<*port*>][:<*socket*>],
.ft P
.fi
.sp
The utility permits users to discover slaves connected to the master. In
order to use the discover slaves feature, all slaves must use the \-\-report\-host
and \-\-report\-port startup variables to specify the correct hostname and ip
port of the slave. If these are missing or report the incorrect information,
the slaves health may not be reported correctly or the slave may not be listed
at all. The discover slaves feature ignores any slaves it cannot connect to.
.sp
The utility permits the user to demote a master to a slave during the
switchover operation. The \fI\%--demote-master\fP option tells the utility
to, once the new master is established, make the old master a slave of the
new master. This permits rotation of the master role among a set of servers.
.sp
The utility permits the user to specify an external script to execute
before and after the switchover and failover commands. The user can specify
these with the \fI\%--exec-before\fP and \fI\%--exec-after\fP options.
The return code of the script is used to determine success thus each script
must report 0 (success) to be considered successful. If a script returns a
value other than 0, the result code is presented in an error message.
.sp
The utility permits the user to log all actions taken during the commands. The
\fI\%--log\fP option requires a valid path and file name of the file to use
for logging operations. The log is active only when this option is specified.
The option \fI\%--log-age\fP specifies the age in days that log entries are
kept. The default is seven (7) days. Older entries are automatically deleted
from the log file (but only if the \fI\%--log\fP option is specified).
.sp
The format of the log file includes the date and time of the event, the level
of the event (informational \- INFO, warning \- WARN, error \- ERROR, critical
failure \- CRITICAL), and the message reported by the utility.
.sp
The utility has a number of options each explained in more detail below.
Some of the options are specific to certain commands. Warning messages are
issued whenever an option is used that does not apply to the command requested.
A brief overview of each command and its options is presented in the following
paragraphs.
.sp
The elect, failover, start, stop, and reset commands require either the
\fI\%--slaves\fP option to list all of the slaves in the topology or the
\fI\%--discover-slaves-login\fP option to provide the user name and password
to discover any slaves in the topology that are registered to the master but
are not listed in the \fI\%--slaves\fP option.
.sp
The options required for the health and gtid commands include the
\fI\-\-master\fP option to specify the existing master, and either the
\fI\%--slaves\fP option to list all of the slaves in the topology or the
\fI\%--discover-slaves-login\fP option to provide the user name and password
to discover any slaves in the topology that are registered to the master but
are not listed in the \fI\%--slaves\fP option.
.sp
Use the \fI\-\-verbose\fP option to see additional information in the
health report and additional messages during switchover or failover.
.sp
The options required for switchover include the \fI\-\-master\fP option to
specify the existing master, the \fI\%--new-master\fP option to specify the
candidate slave (the slave to become the new master.
.SH OPTIONS
.sp
\fBmysqlrpladmin\fP accepts the following command\-line options:
.INDENT 0.0
.TP
.B \-\-help
Display a help message and exit.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-candidates=<candidate slave connections>
Connection information for candidate slave servers for failover in the form:
<\fIuser\fP>[:<\fIpasswd\fP>]@<\fIhost\fP>[:<\fIport\fP>][:<\fIsocket\fP>]. Valid only with
failover command. List multiple slaves in comma\- separated list.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-demote\-master
Make master a slave after switchover.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-discover\-slaves\-login=<user:password>
At startup, query master for all registered slaves and use the user name and
password specified to connect. Supply the user and password in the form
<\fIuser\fP>[:<\fIpasswd\fP>]. For example, \-\-discover=joe:secret will use \(aqjoe\(aq as
the user and \(aqsecret\(aq as the password for each discovered slave.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-exec\-after=<script>
Name of script to execute after failover or switchover. Script name may
include the path.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-exec\-before=<script>
Name of script to execute before failover or switchover. Script name may
include the path.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-format=<format>, \-f <format>
Display the replication health output in either grid (default), tab, csv, or
vertical format.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-log=<log_file>
Specify a log file to use for logging messages
.UNINDENT
.INDENT 0.0
.TP
.B \-\-log\-age=<days>
Specify maximum age of log entries in days. Entries older than this will be
purged on startup. Default = 7 days.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-master=<connection>
Connection information for the master server in
<\fIuser\fP>[:<\fIpasswd\fP>]@<\fIhost\fP>[:<\fIport\fP>][:<\fIsocket\fP>] format.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-max\-position=<position>
Used to detect slave delay. The maximum difference between the master\(aqs
log position and the slave\(aqs reported read position of the master. A value
greater than this means the slave is too far behind the master. Default = 0.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-new\-master=<connection>
Connection information for the slave to be used to replace the master for
switchover in the form:
<\fIuser\fP>[:<\fIpasswd\fP>]@<\fIhost\fP>[:<\fIport\fP>][:<\fIsocket\fP>]. Valid only with
switchover command.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-health
Turn off health report after switchover or failover.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-ping=<number>
Number of ping attempts for detecting downed server. Note: on some
platforms this is the same as number of seconds to wait for ping to
return.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-quiet, \-q
Turn off all messages for quiet execution.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-seconds\-behind=<seconds>
Used to detect slave delay. The maximum number of seconds behind the master
permitted before slave is considered behind the master. Default = 0.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-slaves=<slave connections>
Connection information for slave servers in the form:
<\fIuser\fP>[:<\fIpasswd\fP>]@<\fIhost\fP>[:<\fIport\fP>][:<\fIsocket\fP>]. List multiple slaves
in comma\-separated list.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-timeout=<seconds>
Maximum timeout in seconds to wait for each replication command to complete.
For example, timeout for slave waiting to catch up to master. Default = 3.
Also used to check down status of master. Failover will wait timeout
seconds to check master response. If no response, failover event occurs.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-verbose, \-v
Specify how much information to display. Use this option
multiple times to increase the amount of information.  For example,
\fI\-v\fP = verbose, \fI\-vv\fP = more verbose, \fI\-vvv\fP =
debug.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-version
Display version information and exit.
.UNINDENT
.SH NOTES
.sp
The login user must have the appropriate permissions to execute \fBSHOW SLAVE
STATUS\fP, \fBSHOW MASTER STATUS\fP, and \fBSHOW VARIABLES\fP on the appropriate
servers as well as grant the REPLICATE SLAVE privilege. The utility checks
permissions for the master, slaves, and candidates at startup.
.sp
The \fI\-\-force\fP option cannot be used with the failover command.
.SH EXAMPLES
.sp
To perform best slave election for a topology with GTID_MODE=ON (server version
5.6.5 or higher) where all slaves are specified with the \fI\-\-slaves1\fP
option, run the following command.:
.sp
.nf
.ft C
$ mysqlrpladmin \-\-master=root@localhost:3331 \e
  \-\-slaves=root@localhost:3332,root@localhost:3333,root@localhost:3334 elect
# Electing candidate slave from known slaves.
# Best slave found is located on localhost:3332.
# ...done.
.ft P
.fi
.sp
To perform best slave election supplying a candidate list, use the following
command.:
.sp
.nf
.ft C
$ mysqlrpladmin \-\-master=root@localhost:3331 \e
  \-\-slaves=root@localhost:3332,root@localhost:3333,root@localhost:3334 \e
  \-\-candidates=root@localhost:3333,root@localhost:3334 elect
# Electing candidate slave from candidate list then slaves list.
# Best slave found is located on localhost:3332.
# ...done.
.ft P
.fi
.sp
To perform failover after a master has failed, use the following command.:
.sp
.nf
.ft C
$ mysqlrpladmin  \e
  \-\-slaves=root@localhost:3332,root@localhost:3333,root@localhost:3334 \e
  \-\-candidates=root@localhost:3333,root@localhost:3334 failover
# Performing failover.
# Candidate slave localhost:3333 will become the new master.
# Preparing candidate for failover.
# Creating replication user if it does not exist.
# Stopping slaves.
# Performing STOP on all slaves.
# Switching slaves to new master.
# Starting slaves.
# Performing START on all slaves.
# Checking slaves for errors.
# Failover complete.
# ...done.
.ft P
.fi
.sp
To see the replication health of a topology with GTID_MODE=ON (server version
5.6.5 or higher) and discover all slaves attached to the master, run the
following command. We use the result of the failover command above.:
.sp
.nf
.ft C
$ mysqlrpladmin \-\-master=root@localhost:3333 \e
  \-\-slaves=root@localhost:3332,root@localhost:3334 health
# Getting health for master: localhost:3333.
#
# Replication Topology Health:
+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+
| host       | port  | role    | state  | gtid_mode  | health  |
+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+
| localhost  | 3333  | MASTER  | UP     | ON         | OK      |
| localhost  | 3332  | SLAVE   | UP     | ON         | OK      |
| localhost  | 3334  | SLAVE   | UP     | ON         | OK      |
+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+
# ...done.
.ft P
.fi
.sp
To view a detailed replication health report but with all of the replication
health checks revealed, use the \fI\-\-verbose\fP option as shown below.
In this example, we use vertical format to make viewing easier.:
.sp
.nf
.ft C
$ mysqlrpladmin \-\-master=root@localhost:3331 \e
  \-\-slaves=root@localhost:3332,root@localhost:3333,root@localhost:3334 \e
  \-\-verbose health
# Getting health for master: localhost:3331.
# Attempting to contact localhost ... Success
# Attempting to contact localhost ... Success
# Attempting to contact localhost ... Success
# Attempting to contact localhost ... Success
#
# Replication Topology Health:
*************************       1. row *************************
            host: localhost
            port: 3331
            role: MASTER
           state: UP
       gtid_mode: ON
          health: OK
         version: 5.6.5\-m8\-debug\-log
 master_log_file: mysql\-bin.000001
  master_log_pos: 571
       IO_Thread:
      SQL_Thread:
     Secs_Behind:
 Remaining_Delay:
    IO_Error_Num:
        IO_Error:
*************************       2. row *************************
            host: localhost
            port: 3332
            role: SLAVE
           state: UP
       gtid_mode: ON
          health: OK
         version: 5.6.5\-m8\-debug\-log
 master_log_file: mysql\-bin.000001
  master_log_pos: 571
       IO_Thread: Yes
      SQL_Thread: Yes
     Secs_Behind: 0
 Remaining_Delay: No
    IO_Error_Num: 0
        IO_Error:
*************************       3. row *************************
            host: localhost
            port: 3333
            role: SLAVE
           state: UP
       gtid_mode: ON
          health: OK
         version: 5.6.5\-m8\-debug\-log
 master_log_file: mysql\-bin.000001
  master_log_pos: 571
       IO_Thread: Yes
      SQL_Thread: Yes
     Secs_Behind: 0
 Remaining_Delay: No
    IO_Error_Num: 0
        IO_Error:
*************************       4. row *************************
            host: localhost
            port: 3334
            role: SLAVE
           state: UP
       gtid_mode: ON
          health: OK
         version: 5.6.5\-m8\-debug\-log
 master_log_file: mysql\-bin.000001
  master_log_pos: 571
       IO_Thread: Yes
      SQL_Thread: Yes
     Secs_Behind: 0
 Remaining_Delay: No
    IO_Error_Num: 0
        IO_Error:
4 rows.
# ...done.
.ft P
.fi
.sp
To run the same failover command above, but specify a log file, use the
following command.:
.sp
.nf
.ft C
$ mysqlrpladmin  \e
  \-\-slaves=root@localhost:3332,root@localhost:3333,root@localhost:3334 \e
  \-\-candidates=root@localhost:3333,root@localhost:3334 \e
  \-\-log=test_log.txt failover
# Performing failover.
# Candidate slave localhost:3333 will become the new master.
# Preparing candidate for failover.
# Creating replication user if it does not exist.
# Stopping slaves.
# Performing STOP on all slaves.
# Switching slaves to new master.
# Starting slaves.
# Performing START on all slaves.
# Checking slaves for errors.
# Failover complete.
# ...done.
.ft P
.fi
.sp
After this command, the log file will contain entries like the following:
.sp
.nf
.ft C
2012\-03\-19 14:44:17 PM INFO Executing failover command...
2012\-03\-19 14:44:17 PM INFO Performing failover.
2012\-03\-19 14:44:17 PM INFO Candidate slave localhost:3333 will become the new master.
2012\-03\-19 14:44:17 PM INFO Preparing candidate for failover.
2012\-03\-19 14:44:19 PM INFO Creating replication user if it does not exist.
2012\-03\-19 14:44:19 PM INFO Stopping slaves.
2012\-03\-19 14:44:19 PM INFO Performing STOP on all slaves.
2012\-03\-19 14:44:19 PM INFO Switching slaves to new master.
2012\-03\-19 14:44:20 PM INFO Starting slaves.
2012\-03\-19 14:44:20 PM INFO Performing START on all slaves.
2012\-03\-19 14:44:20 PM INFO Checking slaves for errors.
2012\-03\-19 14:44:21 PM INFO Failover complete.
2012\-03\-19 14:44:21 PM INFO ...done.
.ft P
.fi
.sp
To perform switchover and demote the current master to a slave, use the
following command.:
.sp
.nf
.ft C
$ mysqlrpladmin \-\-master=root@localhost:3331 \e
  \-\-slaves=root@localhost:3332,root@localhost:3333,root@localhost:3334 \e
  \-\-new\-master=root@localhost:3332 \-\-demote\-master switchover
# Performing switchover from master at localhost:3331 to slave at localhost:3332.
# Checking candidate slave prerequisites.
# Waiting for slaves to catch up to old master.
# Stopping slaves.
# Performing STOP on all slaves.
# Demoting old master to be a slave to the new master.
# Switching slaves to new master.
# Starting all slaves.
# Performing START on all slaves.
# Checking slaves for errors.
# Switchover complete.
# ...done.
.ft P
.fi
.sp
If the replication health report is generated on the topology following the
above command, it will display the old master as a slave as shown below.:
.sp
.nf
.ft C
# Replication Topology Health:
+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+
| host       | port  | role    | state  | gtid_mode  | health  |
+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+
| localhost  | 3332  | MASTER  | UP     | ON         | OK      |
| localhost  | 3331  | SLAVE   | UP     | ON         | OK      |
| localhost  | 3333  | SLAVE   | UP     | ON         | OK      |
| localhost  | 3334  | SLAVE   | UP     | ON         | OK      |
+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+
.ft P
.fi
.sp
To use the discover slaves feature, you can omit the \fI\%--slaves\fP option
if and only if all slaves report their host and port to the master. A sample
command to generate a replication health report with discovery is shown below.
he option:\fI\-\-discover\-slaves\-login\fP option can be used in conjunction with the
\fI\%--slaves\fP option to specify a list of known slaves (or slaves that do
not report their host and ip) and to discover any other slaves connected to the
master.:
.sp
.nf
.ft C
$ mysqlrpladmin \-\-master=root@localhost:3332 \e
  \-\-discover\-slaves\-login=root  health
# Discovering slaves for master at localhost:3332
# Getting health for master: localhost:3332.
#
# Replication Topology Health:
+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+
| host       | port  | role    | state  | gtid_mode  | health  |
+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+
| localhost  | 3332  | MASTER  | UP     | ON         | OK      |
| localhost  | 3331  | SLAVE   | UP     | ON         | OK      |
| localhost  | 3333  | SLAVE   | UP     | ON         | OK      |
| localhost  | 3334  | SLAVE   | UP     | ON         | OK      |
+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+
# ...done.
.ft P
.fi
.SH COPYRIGHT
.sp
Copyright (c) 2011, 2012, Oracle and/or its affiliates. All rights reserved.
.sp
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; version 2 of the License.
.sp
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.
.sp
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110\-1301 USA
.SH AUTHOR
MySQL Utilities Team
.SH COPYRIGHT
2010, Oracle and/or its affiliates. All rights reserved.
.\" Generated by docutils manpage writer.
.\" 
.