1MAATKIT(1)            User Contributed Perl Documentation           MAATKIT(1)
2
3
4

NAME

6       maatkit - Essential command-line utilities for MySQL.
7

DESCRIPTION

9       Maatkit is a collection of command-line utilities that provide missing
10       functionality for MySQL.  Some of the tools implement lacking server
11       functionality, such as online consistency checks for master/slave
12       replication; others are client-side utilities such as a query profiler.
13
14       The following tools are included:
15
16          $Revision: 7540 $
17       mk-archiver 1.0.27
18       mk-config-diff 1.0.0
19       mk-deadlock-logger 1.0.21
20       mk-duplicate-key-checker 1.2.15
21       mk-error-log 1.0.3
22       mk-fifo-split 1.0.7
23       mk-find 0.9.23
24       mk-heartbeat 1.0.23
25       mk-index-usage 0.9.4
26       mk-kill 0.9.10
27       mk-loadavg 0.9.7
28       mk-log-player 1.0.9
29       mk-parallel-dump 1.0.28
30       mk-parallel-restore 1.0.24
31       mk-purge-logs 0.9.0
32       mk-query-advisor 1.0.4
33       mk-query-digest 0.9.29
34       mk-query-profiler 1.1.22
35       mk-show-grants 1.0.23
36       mk-slave-delay 1.0.23
37       mk-slave-find 1.0.16
38       mk-slave-move 0.9.12
39       mk-slave-prefetch 1.0.21
40       mk-slave-restart 1.0.22
41       mk-table-checksum 1.2.23
42       mk-table-sync 1.0.31
43       mk-table-usage 1.0.1
44       mk-tcp-model 1.0.1
45       mk-upgrade 0.9.8
46       mk-variable-advisor 1.0.2
47       mk-visual-explain 1.0.22
48
49       mk-archiver
50           Archive rows from a MySQL table into another table or a file. See
51           mk-archiver.
52
53       mk-checksum-filter
54           Filter checksums from mk-table-checksum. See mk-checksum-filter.
55
56       mk-config-diff
57           Diff MySQL configuration files and server variables. See mk-config-
58           diff.
59
60       mk-deadlock-logger
61           Extract and log MySQL deadlock information. See mk-deadlock-logger.
62
63       mk-duplicate-key-checker
64           Find duplicate indexes and foreign keys on MySQL tables. See mk-
65           duplicate-key-checker.
66
67       mk-error-log
68           Find new and different MySQL error log entries. See mk-error-log.
69
70       mk-fifo-split
71           Split files and pipe lines to a fifo without really splitting. See
72           mk-fifo-split.
73
74       mk-find
75           Find MySQL tables and execute actions, like GNU find. See mk-find.
76
77       mk-heartbeat
78           Monitor MySQL replication delay. See mk-heartbeat.
79
80       mk-index-usage
81           Read queries from a log and analyze how they use indexes. See mk-
82           index-usage.
83
84       mk-kill
85           Kill MySQL queries that match certain criteria. See mk-kill.
86
87       mk-loadavg
88           Watch MySQL load and take action when it gets too high. See mk-
89           loadavg.
90
91       mk-log-player
92           Replay MySQL query logs. See mk-log-player.
93
94       mk-merge-mqd-results
95           Merge multiple mk-query-digest reports into one. See mk-merge-mqd-
96           results.
97
98       mk-parallel-dump
99           (DEPRECATED) Dump MySQL tables in parallel. See mk-parallel-dump.
100
101       mk-parallel-restore
102           (DEPRECATED) Load files into MySQL in parallel. See mk-parallel-
103           restore.
104
105       mk-profile-compact
106           Compact the output from mk-query-profiler. See mk-profile-compact.
107
108       mk-purge-logs
109           Purge binary logs on a master based on purge rules. See mk-purge-
110           logs.
111
112       mk-query-advisor
113           Analyze queries and advise on possible problems. See mk-query-
114           advisor.
115
116       mk-query-digest
117           Analyze query execution logs and generate a query report, filter,
118           replay, or transform queries for MySQL, PostgreSQL, memcached, and
119           more. See mk-query-digest.
120
121       mk-query-profiler
122           Execute SQL statements and print statistics, or measure activity
123           caused by other processes. See mk-query-profiler.
124
125       mk-show-grants
126           Canonicalize and print MySQL grants so you can effectively
127           replicate, compare and version-control them. See mk-show-grants.
128
129       mk-slave-delay
130           Make a MySQL slave server lag behind its master. See mk-slave-
131           delay.
132
133       mk-slave-find
134           Find and print replication hierarchy tree of MySQL slaves. See mk-
135           slave-find.
136
137       mk-slave-move
138           Move a MySQL slave around in the replication hierarchy. See mk-
139           slave-move.
140
141       mk-slave-prefetch
142           Pipeline relay logs on a MySQL slave to pre-warm caches. See mk-
143           slave-prefetch.
144
145       mk-slave-restart
146           Watch and restart MySQL replication after errors. See mk-slave-
147           restart.
148
149       mk-table-checksum
150           Perform an online replication consistency check, or checksum MySQL
151           tables efficiently on one or many servers. See mk-table-checksum.
152
153       mk-table-sync
154           Synchronize MySQL table data efficiently. See mk-table-sync.
155
156       mk-table-usage
157           Read queries from a log and analyze how they use tables. See mk-
158           table-usage.
159
160       mk-tcp-model
161           Transform tcpdump into metrics that permit performance and
162           scalability modeling. See mk-tcp-model.
163
164       mk-upgrade
165           Execute queries on multiple servers and check for differences. See
166           mk-upgrade.
167
168       mk-variable-advisor
169           Analyze MySQL variables and advise on possible problems. See mk-
170           variable-advisor.
171
172       mk-visual-explain
173           Format EXPLAIN output as a tree. See mk-visual-explain.
174

INSTALLATION

176       Strictly speaking these tools require no installation; you should be
177       able to run them stand-alone.  However, on UNIX-ish systems you can use
178       the standard Perl installation sequence:
179
180          cd <package directory>
181          perl Makefile.PL
182          make install
183

CONFIGURATION

185       Maatkit tools can read options from configuration files.  The
186       configuration file syntax is simple and direct, and bears some
187       resemblances to the MySQL command-line client tools.  The configuration
188       files all follow the same conventions.
189
190       Internally, what actually happens is that the lines are read from the
191       file and then added as command-line options and arguments to the
192       Maatkit tool, so just think of the configuration files as a way to
193       write your command lines.
194
195   SYNTAX
196       The syntax of the files is as follows:
197
198       •   Whitespace followed by a hash (#) sign signifies that the rest of
199           the line is a comment.  This is deleted.
200
201       •   Whitespace is stripped from the beginning and end of all lines.
202
203       •   Empty lines are ignored.
204
205       •   Each line is permitted to be in either of the following formats:
206
207             option
208             option=value
209
210           Whitespace around the equals sign is deleted during processing.
211
212       •   Only long options are recognized.
213
214       •   A line containing only two hyphens signals the end of option
215           parsing.  Any further lines are interpreted as additional arguments
216           (not options) to the program.
217
218   FILES
219       The tools read several configuration files in order:
220
221       1.  The global Maatkit configuration file, /etc/maatkit/maatkit.conf.
222           All tools read this file, so you should only add options to it that
223           you want to apply to all Maatkit tools.
224
225       2.  The global tool configuration file, /etc/maatkit/[toolname].conf.
226           This file is named after the specific tool you're using, so you can
227           add options that apply only to that tool.
228
229       3.  The user's own Maatkit configuration file, $HOME/.maatkit.conf.
230           All tools read this file, so you should only add options to it that
231           you want to apply to all Maatkit tools.
232
233       4.  The user's tool configuration file, $HOME/.[toolname].conf.  This
234           file is named after the specific tool you're using, so you can add
235           options that apply only to that tool.
236
237   SPECIFYING CONFIGURATION FILES
238       There is a special --config option, which lets you specify which
239       configuration files Maatkit should read.  You specify a comma-separated
240       list of files.  However, its behavior is not like other command-line
241       options.  It must be given first on the command line, before any other
242       options.  If you try to specify it anywhere else, it will cause an
243       error.  Also, you cannot specify --config=/path/to/file; you must
244       specify the option and the path to the file(s) separated by whitespace,
245       without an equals-sign between them, e.g.
246
247         --config /path/to/file
248
249       If you don't want any configuration files at all, specify "--config ''"
250       to provide an empty list of files.
251

DSN (DATA SOURCE NAME) SPECIFICATIONS

253       Maatkit uses DSNs to specify how to create a DBD connection to a MySQL
254       server.  The maatkit tools that have command-line arguments such as -u
255       or -p use them to create a DSN behind the scenes, then use the DSN to
256       connect to MySQL.
257
258       A DSN is a string of key=value parts separated by commas.  The possible
259       keys are shown later in this document.  You can also get a quick
260       synopsis from the --help output of many of the maatkit tools.
261
262   PARTS
263       Many of the tools add more parts to DSNs for special purposes, and
264       sometimes override parts to make them do something slightly different.
265       However, all the tools support at least the following:
266
267       A   Specifies the default character set for the connection.
268
269           Enables character set settings in Perl and MySQL.  If the value is
270           "utf8", sets Perl's binmode on STDOUT to utf8, passes the
271           "mysql_enable_utf8" option to DBD::mysql, and runs "SET NAMES UTF8"
272           after connecting to MySQL.  Any other value sets binmode on STDOUT
273           without the utf8 layer, and runs "SET NAMES" after connecting to
274           MySQL.
275
276           Unfortunately, there is no way from within Perl itself to specify
277           the client library's character set.  "SET NAMES" only affects the
278           server; if the client library's settings don't match, there could
279           be problems.  You can use the defaults file to specify the client
280           library's character set, however.  See the description of the F
281           part below.
282
283       D   Specifies the connection's default database.
284
285       F   Specifies a defaults file the mysql client library (the C client
286           library used by DBD::mysql, not maatkit itself) should read.  The
287           maatkit tools all read the [client] section within the defaults
288           file.  If you omit this, the standard defaults files will be read
289           in the usual order.  "Standard" varies from system to system,
290           because the filenames to read are compiled into the client library.
291           On Debian systems, for example, it's usually /etc/mysql/my.cnf then
292           ~/.my.cnf.  If you place the following into ~/.my.cnf, maatkit will
293           Do The Right Thing:
294
295            [client]
296            user=your_user_name
297            pass=secret
298
299           Omitting the F part is usually the right thing to do.  As long as
300           you have configured your ~/.my.cnf correctly, that will result in
301           maatkit connecting automatically without needing a username or
302           password.
303
304           You can also specify a default character set in the defaults file.
305           Unlike the "A" part described above, this will actually instruct
306           the client library (DBD::mysql) to change the character set it uses
307           internally, which cannot be accomplished any other way as far as I
308           know, except for "utf8".
309
310       P   Port number to use for the connection.  Note that the usual
311           special-case behaviors apply: if you specify "localhost" as your
312           hostname on Unix systems, the connection actually uses a socket
313           file, not a TCP/IP connection, and thus ignores the port.
314
315       S   Socket file to use for the connection (on Unix systems).
316
317       h   Hostname or IP address for the connection.
318
319       p   Password to use when connecting.
320
321       u   User for login if not current user.
322
323   BAREWORD
324       Many of the tools will let you specify a DSN as a single word, without
325       any key=value syntax.  This is called a 'bareword'.  How this is
326       handled is tool-specific, but it is usually interpreted as the "h"
327       part.  The tool's --help output will tell you the behavior for that
328       tool.
329
330   DEFAULT PROPAGATION
331       Many tools will let you propagate values from one DSN to the next, so
332       you don't have to specify all the parts for each DSN.  For example, if
333       you want to specify a username and password for each DSN, you can
334       connect to three hosts as follows:
335
336        h=host1,u=fred,p=wilma host2 host3
337
338       This is tool-specific.
339

SYSTEM REQUIREMENTS

341       You need Perl, DBI, DBD::mysql, and some core packages that ought to be
342       installed in any reasonably new version of Perl.
343

BUGS

345       If you find bugs, need features, etc please use the bug tracker,
346       forums, and mailing lists at http://code.google.com/p/maatkit/
347

COPYRIGHT, LICENSE AND WARRANTY

349       This program is copyright (c) 2007 Baron Schwartz and others.  Feedback
350       and improvements are welcome.
351
352       THIS PROGRAM IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
353       WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
354       MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
355
356       This program is free software; you can redistribute it and/or modify it
357       under the terms of the GNU General Public License as published by the
358       Free Software Foundation, version 2; OR the Perl Artistic License.  On
359       UNIX and similar systems, you can issue `man perlgpl' or `man
360       perlartistic' to read these licenses.
361
362       You should have received a copy of the GNU General Public License along
363       with this program; if not, write to the Free Software Foundation, Inc.,
364       59 Temple Place, Suite 330, Boston, MA  02111-1307  USA.
365

AUTHOR

367       See the individual program's documentation for details.
368

VERSION

370       This manual page documents Distrib 7540 $Revision: 534 $.
371
372
373
374perl v5.36.0                      2022-07-21                        MAATKIT(1)
Impressum