1MK-SLAVE-RESTART(1)   User Contributed Perl Documentation  MK-SLAVE-RESTART(1)
2
3
4

NAME

6       mk-slave-restart - Watch and restart MySQL replication after errors.
7

SYNOPSIS

9       Usage: mk-slave-restart [OPTION...] [DSN]
10
11       mk-slave-restart watches one or more MySQL replication slaves for
12       errors, and tries to restart replication if it stops.
13

RISKS

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
20       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
25       At the time of this release there is a bug that causes an invalid
26       "CHANGE MASTER TO" statement to be executed.
27
28       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
33       See also "BUGS" for more information on filing bugs and getting help.
34

DESCRIPTION

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
41       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

OUTPUT

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

SLEEP

54       mk-slave-restart sleeps intelligently between polling the slave.  The
55       current sleep time varies.
56
57       •   The initial sleep time is given by "--sleep".
58
59       •   If it checks and finds an error, it halves the previous sleep time.
60
61       •   If it finds no error, it doubles the previous sleep time.
62
63       •   The sleep time is bounded below by "--min-sleep" and above by
64           "--max-sleep".
65
66       •   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

EXIT STATUS

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

COMPATIBILITY

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

OPTIONS

82       This tool accepts additional command-line arguments.  Refer to the
83       "SYNOPSIS" and usage information for details.
84
85       --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
90       --ask-pass
91           Prompt for a password when connecting to MySQL.
92
93       --charset
94           short form: -A; type: string
95
96           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
102       --[no]check-relay-log
103           default: yes
104
105           Check the last relay log file and position before checking for
106           slave errors.
107
108           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
114           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
118       --config
119           type: Array
120
121           Read this comma-separated list of config files; if specified, this
122           must be the first option on the command line.
123
124       --daemonize
125           Fork to the background and detach from the shell.  POSIX operating
126           systems only.
127
128       --database
129           short form: -D; type: string
130
131           Database to use.
132
133       --defaults-file
134           short form: -F; type: string
135
136           Only read mysql options from the given file.  You must give an
137           absolute pathname.
138
139       --error-length
140           type: int
141
142           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
147       --error-numbers
148           type: hash
149
150           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
155           The error number is in the "last_errno" column of "SHOW SLAVE
156           STATUS".
157
158       --error-text
159           type: string
160
161           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
167           The error text is in the "last_error" column of "SHOW SLAVE
168           STATUS".
169
170       --help
171           Show help and exit.
172
173       --host
174           short form: -h; type: string
175
176           Connect to host.
177
178       --log
179           type: string
180
181           Print all output to this file when daemonized.
182
183       --max-sleep
184           type: float; default: 64
185
186           Maximum sleep seconds.
187
188           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
193           See "SLEEP".
194
195       --min-sleep
196           type: float; default: 0.015625
197
198           The minimum time mk-slave-restart will sleep before polling the
199           slave again.  See "SLEEP".
200
201       --monitor
202           Whether to monitor the slave (default).  Unless you specify
203           --monitor explicitly, "--stop" will disable it.
204
205       --password
206           short form: -p; type: string
207
208           Password to use when connecting.
209
210       --pid
211           type: string
212
213           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
219       --port
220           short form: -P; type: int
221
222           Port number to use for connection.
223
224       --quiet
225           short form: -q
226
227           Suppresses normal output (disables "--verbose").
228
229       --recurse
230           type: int; default: 0
231
232           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
236           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
240           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
244           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
249       --recursion-method
250           type: string
251
252           Preferred recursion method used to find slaves.
253
254           Possible methods are:
255
256             METHOD       USES
257             ===========  ================
258             processlist  SHOW PROCESSLIST
259             hosts        SHOW SLAVE HOSTS
260
261           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
268       --run-time
269           type: time
270
271           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
275       --sentinel
276           type: string; default: /tmp/mk-slave-restart-sentinel
277
278           Exit if this file exists.
279
280       --set-vars
281           type: string; default: wait_timeout=10000
282
283           Set these MySQL variables.  Immediately after connecting to MySQL,
284           this string will be appended to SET and executed.
285
286       --skip-count
287           type: int; default: 1
288
289           Number of statements to skip when restarting the slave.
290
291       --sleep
292           type: int; default: 1
293
294           Initial sleep seconds between checking the slave.
295
296           See "SLEEP".
297
298       --socket
299           short form: -S; type: string
300
301           Socket file to use for connection.
302
303       --stop
304           Stop running instances by creating the sentinel file.
305
306           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
314           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
321            0 * * * * mk-slave-restart --monitor --stop --sentinel /tmp/mk-slave-restartup
322
323           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
327           See also "--sentinel".
328
329       --until-master
330           type: string
331
332           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
339           This will also cause an UNTIL clause to be given to START SLAVE.
340
341           After reaching this point, the slave should be stopped and mk-
342           slave-restart will exit.
343
344       --until-relay
345           type: string
346
347           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
351       --user
352           short form: -u; type: string
353
354           User for login if not current user.
355
356       --verbose
357           short form: -v; cumulative: yes; default: 1
358
359           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
365       --version
366
367       Show version and exit.
368

DSN OPTIONS

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
376       •   A
377
378           dsn: charset; copy: yes
379
380           Default character set.
381
382       •   D
383
384           dsn: database; copy: yes
385
386           Default database.
387
388       •   F
389
390           dsn: mysql_read_default_file; copy: yes
391
392           Only read default options from the given file
393
394       •   h
395
396           dsn: host; copy: yes
397
398           Connect to host.
399
400       •   p
401
402           dsn: password; copy: yes
403
404           Password to use when connecting.
405
406       •   P
407
408           dsn: port; copy: yes
409
410           Port number to use for connection.
411
412       •   S
413
414           dsn: mysql_socket; copy: yes
415
416           Socket file to use for connection.
417
418       •   u
419
420           dsn: user; copy: yes
421
422           User for login if not current user.
423

DOWNLOADING

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
429          wget http://www.maatkit.org/get/toolname
430          or
431          wget http://www.maatkit.org/trunk/toolname
432
433       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

ENVIRONMENT

439       The environment variable "MKDEBUG" enables verbose debugging output in
440       all of the Maatkit tools:
441
442          MKDEBUG=1 mk-....
443
444       When "--daemonize" is given and this variable is set, output is
445       directed to a debug file in "/tmp".
446

SYSTEM REQUIREMENTS

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

BUGS

452       For a list of known bugs see
453       <http://www.maatkit.org/bugs/mk-slave-restart>.
454
455       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
459       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

COPYRIGHT, LICENSE AND WARRANTY

466       This program is copyright 2007-2011 Baron Schwartz.  Feedback and
467       improvements are welcome.
468
469       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
473       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
479       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

SEE ALSO

484       See also mk-table-checksum, mk-table-sync, mk-slave-delay.
485

AUTHOR

487       Baron Schwartz
488

ABOUT MAATKIT

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

VERSION

497       This manual page documents Ver 1.0.22 Distrib 7540 $Revision: 7531 $.
498
499
500
501perl v5.38.0                      2023-07-20               MK-SLAVE-RESTART(1)
Impressum