1MK-SLAVE-RESTART(1) User Contributed Perl Documentation MK-SLAVE-RESTART(1)
2
6 mk-slave-restart - Watch and restart MySQL replication after errors.
7
9 Usage: mk-slave-restart [OPTION...] [DSN]
10 mk-slave-restart watches one or more MySQL replication slaves for
12 errors, and tries to restart replication if it stops.
13
15 The following section is included to inform users about the potential
16 risks, whether known or unknown, of using this tool. The two main
17 categories of risks are those created by the nature of the tool (e.g.
18 read-only tools vs. read-write tools) and those created by bugs.
19 mk-slave-restart is a brute-force way to try to keep a slave server
21 running when it is having problems with replication. Don't be too
22 hasty to use it unless you need to. If you use this tool carelessly,
23 you might miss the chance to really solve the slave server's problems.
24 At the time of this release there is a bug that causes an invalid
26 "CHANGE MASTER TO" statement to be executed.
27 The authoritative source for updated information is always the online
29 issue tracking system. Issues that affect this tool will be marked as
30 such. You can see a list of such issues at the following URL:
31 <http://www.maatkit.org/bugs/mk-slave-restart>.
32 See also "BUGS" for more information on filing bugs and getting help.
34
36 mk-slave-restart watches one or more MySQL replication slaves and tries
37 to skip statements that cause errors. It polls slaves intelligently
38 with an exponentially varying sleep time. You can specify errors to
39 skip and run the slaves until a certain binlog position.
40 Note: it has come to my attention that Yahoo! had or has an internal
42 tool called fix_repl, described to me by a past Yahoo! employee and
43 mentioned in the first edition of High Performance MySQL. Apparently
44 this tool does the same thing. Make no mistake, though: this is not a
45 way to "fix replication." In fact I would not even encourage its use
46 on a regular basis; I use it only when I have an error I know I just
47 need to skip past.
48
50 If you specify "--verbose", mk-slave-restart prints a line every time
51 it sees the slave has an error. See "--verbose" for details.
52
54 mk-slave-restart sleeps intelligently between polling the slave. The
55 current sleep time varies.
56 • The initial sleep time is given by "--sleep".
58 • If it checks and finds an error, it halves the previous sleep time.
60 • If it finds no error, it doubles the previous sleep time.
62 • The sleep time is bounded below by "--min-sleep" and above by
64 "--max-sleep".
65 • Immediately after finding an error, mk-slave-restart assumes
67 another error is very likely to happen next, so it sleeps the
68 current sleep time or the initial sleep time, whichever is less.
69
71 An exit status of 0 (sometimes also called a return value or return
72 code) indicates success. Any other value represents the exit status of
73 the Perl process itself, or of the last forked process that exited if
74 there were multiple servers to monitor.
75
77 mk-slave-restart should work on many versions of MySQL. Lettercase of
78 many output columns from SHOW SLAVE STATUS has changed over time, so it
79 treats them all as lowercase.
80
82 This tool accepts additional command-line arguments. Refer to the
83 "SYNOPSIS" and usage information for details.
84 --always
86 Start slaves even when there is no error. With this option
87 enabled, mk-slave-restart will not let you stop the slave manually
88 if you want to!
89 --ask-pass
91 Prompt for a password when connecting to MySQL.
92 --charset
94 short form: -A; type: string
95 Default character set. If the value is utf8, sets Perl's binmode
97 on STDOUT to utf8, passes the mysql_enable_utf8 option to
98 DBD::mysql, and runs SET NAMES UTF8 after connecting to MySQL. Any
99 other value sets binmode on STDOUT without the utf8 layer, and runs
100 SET NAMES after connecting to MySQL.
101 --[no]check-relay-log
103 default: yes
104 Check the last relay log file and position before checking for
106 slave errors.
107 By default mk-slave-restart will not doing anything (it will just
109 sleep) if neither the relay log file nor the relay log position
110 have changed since the last check. This prevents infinite loops
111 (i.e. restarting the same error in the same relay log file at the
112 same relay log position).
113 For certain slave errors, however, this check needs to be disabled
115 by specifying "--no-check-relay-log". Do not do this unless you
116 know what you are doing!
117 --config
119 type: Array
120 Read this comma-separated list of config files; if specified, this
122 must be the first option on the command line.
123 --daemonize
125 Fork to the background and detach from the shell. POSIX operating
126 systems only.
127 --database
129 short form: -D; type: string
130 Database to use.
132 --defaults-file
134 short form: -F; type: string
135 Only read mysql options from the given file. You must give an
137 absolute pathname.
138 --error-length
140 type: int
141 Max length of error message to print. When "--verbose" is set high
143 enough to print the error, this option will truncate the error text
144 to the specified length. This can be useful to prevent wrapping on
145 the terminal.
146 --error-numbers
148 type: hash
149 Only restart this comma-separated list of errors. Makes mk-slave-
151 restart only try to restart if the error number is in this comma-
152 separated list of errors. If it sees an error not in the list, it
153 will exit.
154 The error number is in the "last_errno" column of "SHOW SLAVE
156 STATUS".
157 --error-text
159 type: string
160 Only restart errors that match this pattern. A Perl regular
162 expression against which the error text, if any, is matched. If
163 the error text exists and matches, mk-slave-restart will try to
164 restart the slave. If it exists but doesn't match, mk-slave-
165 restart will exit.
166 The error text is in the "last_error" column of "SHOW SLAVE
168 STATUS".
169 --help
171 Show help and exit.
172 --host
174 short form: -h; type: string
175 Connect to host.
177 --log
179 type: string
180 Print all output to this file when daemonized.
182 --max-sleep
184 type: float; default: 64
185 Maximum sleep seconds.
187 The maximum time mk-slave-restart will sleep before polling the
189 slave again. This is also the time that mk-slave-restart will wait
190 for all other running instances to quit if both "--stop" and
191 "--monitor" are specified.
192 See "SLEEP".
194 --min-sleep
196 type: float; default: 0.015625
197 The minimum time mk-slave-restart will sleep before polling the
199 slave again. See "SLEEP".
200 --monitor
202 Whether to monitor the slave (default). Unless you specify
203 --monitor explicitly, "--stop" will disable it.
204 --password
206 short form: -p; type: string
207 Password to use when connecting.
209 --pid
211 type: string
212 Create the given PID file when daemonized. The file contains the
214 process ID of the daemonized instance. The PID file is removed
215 when the daemonized instance exits. The program checks for the
216 existence of the PID file when starting; if it exists and the
217 process with the matching PID exists, the program exits.
218 --port
220 short form: -P; type: int
221 Port number to use for connection.
223 --quiet
225 short form: -q
226 Suppresses normal output (disables "--verbose").
228 --recurse
230 type: int; default: 0
231 Watch slaves of the specified server, up to the specified number of
233 servers deep in the hierarchy. The default depth of 0 means "just
234 watch the slave specified."
235 mk-slave-restart examines "SHOW PROCESSLIST" and tries to determine
237 which connections are from slaves, then connect to them. See
238 "--recursion-method".
239 Recursion works by finding all slaves when the program starts, then
241 watching them. If there is more than one slave, "mk-slave-restart"
242 uses fork() to monitor them.
243 This also works if you have configured your slaves to show up in
245 "SHOW SLAVE HOSTS". The minimal configuration for this is the
246 "report_host" parameter, but there are other "report" parameters as
247 well for the port, username, and password.
248 --recursion-method
250 type: string
251 Preferred recursion method used to find slaves.
253 Possible methods are:
255 METHOD USES
257 =========== ================
258 processlist SHOW PROCESSLIST
259 hosts SHOW SLAVE HOSTS
260 The processlist method is preferred because SHOW SLAVE HOSTS is not
262 reliable. However, the hosts method is required if the server uses
263 a non-standard port (not 3306). Usually mk-slave-restart does the
264 right thing and finds the slaves, but you may give a preferred
265 method and it will be used first. If it doesn't find any slaves,
266 the other methods will be tried.
267 --run-time
269 type: time
270 Time to run before exiting. Causes mk-slave-restart to stop after
272 the specified time has elapsed. Optional suffix: s=seconds,
273 m=minutes, h=hours, d=days; if no suffix, s is used.
274 --sentinel
276 type: string; default: /tmp/mk-slave-restart-sentinel
277 Exit if this file exists.
279 --set-vars
281 type: string; default: wait_timeout=10000
282 Set these MySQL variables. Immediately after connecting to MySQL,
284 this string will be appended to SET and executed.
285 --skip-count
287 type: int; default: 1
288 Number of statements to skip when restarting the slave.
290 --sleep
292 type: int; default: 1
293 Initial sleep seconds between checking the slave.
295 See "SLEEP".
297 --socket
299 short form: -S; type: string
300 Socket file to use for connection.
302 --stop
304 Stop running instances by creating the sentinel file.
305 Causes "mk-slave-restart" to create the sentinel file specified by
307 "--sentinel". This should have the effect of stopping all running
308 instances which are watching the same sentinel file. If
309 "--monitor" isn't specified, "mk-slave-restart" will exit after
310 creating the file. If it is specified, "mk-slave-restart" will
311 wait the interval given by "--max-sleep", then remove the file and
312 continue working.
313 You might find this handy to stop cron jobs gracefully if
315 necessary, or to replace one running instance with another. For
316 example, if you want to stop and restart "mk-slave-restart" every
317 hour (just to make sure that it is restarted every hour, in case of
318 a server crash or some other problem), you could use a "crontab"
319 line like this:
320 0 * * * * mk-slave-restart --monitor --stop --sentinel /tmp/mk-slave-restartup
322 The non-default "--sentinel" will make sure the hourly "cron" job
324 stops only instances previously started with the same options (that
325 is, from the same "cron" job).
326 See also "--sentinel".
328 --until-master
330 type: string
331 Run until this master log file and position. Start the slave, and
333 retry if it fails, until it reaches the given replication
334 coordinates. The coordinates are the logfile and position on the
335 master, given by relay_master_log_file, exec_master_log_pos. The
336 argument must be in the format "file,pos". Separate the filename
337 and position with a single comma and no space.
338 This will also cause an UNTIL clause to be given to START SLAVE.
340 After reaching this point, the slave should be stopped and mk-
342 slave-restart will exit.
343 --until-relay
345 type: string
346 Run until this relay log file and position. Like "--until-master",
348 but in the slave's relay logs instead. The coordinates are given
349 by relay_log_file, relay_log_pos.
350 --user
352 short form: -u; type: string
353 User for login if not current user.
355 --verbose
357 short form: -v; cumulative: yes; default: 1
358 Be verbose; can specify multiple times. Verbosity 1 outputs
360 connection information, a timestamp, relay_log_file, relay_log_pos,
361 and last_errno. Verbosity 2 adds last_error. See also
362 "--error-length". Verbosity 3 prints the current sleep time each
363 time mk-slave-restart sleeps.
364 --version
366 Show version and exit.
368
370 These DSN options are used to create a DSN. Each option is given like
371 "option=value". The options are case-sensitive, so P and p are not the
372 same option. There cannot be whitespace before or after the "=" and if
373 the value contains whitespace it must be quoted. DSN options are
374 comma-separated. See the maatkit manpage for full details.
375 • A
377 dsn: charset; copy: yes
379 Default character set.
381 • D
383 dsn: database; copy: yes
385 Default database.
387 • F
389 dsn: mysql_read_default_file; copy: yes
391 Only read default options from the given file
393 • h
395 dsn: host; copy: yes
397 Connect to host.
399 • p
401 dsn: password; copy: yes
403 Password to use when connecting.
405 • P
407 dsn: port; copy: yes
409 Port number to use for connection.
411 • S
413 dsn: mysql_socket; copy: yes
415 Socket file to use for connection.
417 • u
419 dsn: user; copy: yes
421 User for login if not current user.
423
425 You can download Maatkit from Google Code at
426 <http://code.google.com/p/maatkit/>, or you can get any of the tools
427 easily with a command like the following:
428 wget http://www.maatkit.org/get/toolname
430 or
431 wget http://www.maatkit.org/trunk/toolname
432 Where "toolname" can be replaced with the name (or fragment of a name)
434 of any of the Maatkit tools. Once downloaded, they're ready to run; no
435 installation is needed. The first URL gets the latest released version
436 of the tool, and the second gets the latest trunk code from Subversion.
437
439 The environment variable "MKDEBUG" enables verbose debugging output in
440 all of the Maatkit tools:
441 MKDEBUG=1 mk-....
443 When "--daemonize" is given and this variable is set, output is
445 directed to a debug file in "/tmp".
446
448 You need Perl, DBI, DBD::mysql, and some core packages that ought to be
449 installed in any reasonably new version of Perl.
450
452 For a list of known bugs see
453 <http://www.maatkit.org/bugs/mk-slave-restart>.
454 Please use Google Code Issues and Groups to report bugs or request
456 support: <http://code.google.com/p/maatkit/>. You can also join
457 #maatkit on Freenode to discuss Maatkit.
458 Please include the complete command-line used to reproduce the problem
460 you are seeing, the version of all MySQL servers involved, the complete
461 output of the tool when run with "--version", and if possible,
462 debugging output produced by running with the "MKDEBUG=1" environment
463 variable.
464
466 This program is copyright 2007-2011 Baron Schwartz. Feedback and
467 improvements are welcome.
468 THIS PROGRAM IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
470 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
471 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
472 This program is free software; you can redistribute it and/or modify it
474 under the terms of the GNU General Public License as published by the
475 Free Software Foundation, version 2; OR the Perl Artistic License. On
476 UNIX and similar systems, you can issue `man perlgpl' or `man
477 perlartistic' to read these licenses.
478 You should have received a copy of the GNU General Public License along
480 with this program; if not, write to the Free Software Foundation, Inc.,
481 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
482
484 See also mk-table-checksum, mk-table-sync, mk-slave-delay.
485
487 Baron Schwartz
488
490 This tool is part of Maatkit, a toolkit for power users of MySQL.
491 Maatkit was created by Baron Schwartz; Baron and Daniel Nichter are the
492 primary code contributors. Both are employed by Percona. Financial
493 support for Maatkit development is primarily provided by Percona and
494 its clients.
495
497 This manual page documents Ver 1.0.22 Distrib 7540 $Revision: 7531 $.
498perl v5.38.0 2023-07-20 MK-SLAVE-RESTART(1)