1MAATKIT(1) User Contributed Perl Documentation MAATKIT(1)
2
6 maatkit - Essential command-line utilities for MySQL.
7
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 The following tools are included:
15 $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 mk-archiver
50 Archive rows from a MySQL table into another table or a file. See
51 mk-archiver.
52 mk-checksum-filter
54 Filter checksums from mk-table-checksum. See mk-checksum-filter.
55 mk-config-diff
57 Diff MySQL configuration files and server variables. See mk-config-
58 diff.
59 mk-deadlock-logger
61 Extract and log MySQL deadlock information. See mk-deadlock-logger.
62 mk-duplicate-key-checker
64 Find duplicate indexes and foreign keys on MySQL tables. See mk-
65 duplicate-key-checker.
66 mk-error-log
68 Find new and different MySQL error log entries. See mk-error-log.
69 mk-fifo-split
71 Split files and pipe lines to a fifo without really splitting. See
72 mk-fifo-split.
73 mk-find
75 Find MySQL tables and execute actions, like GNU find. See mk-find.
76 mk-heartbeat
78 Monitor MySQL replication delay. See mk-heartbeat.
79 mk-index-usage
81 Read queries from a log and analyze how they use indexes. See mk-
82 index-usage.
83 mk-kill
85 Kill MySQL queries that match certain criteria. See mk-kill.
86 mk-loadavg
88 Watch MySQL load and take action when it gets too high. See mk-
89 loadavg.
90 mk-log-player
92 Replay MySQL query logs. See mk-log-player.
93 mk-merge-mqd-results
95 Merge multiple mk-query-digest reports into one. See mk-merge-mqd-
96 results.
97 mk-parallel-dump
99 (DEPRECATED) Dump MySQL tables in parallel. See mk-parallel-dump.
100 mk-parallel-restore
102 (DEPRECATED) Load files into MySQL in parallel. See mk-parallel-
103 restore.
104 mk-profile-compact
106 Compact the output from mk-query-profiler. See mk-profile-compact.
107 mk-purge-logs
109 Purge binary logs on a master based on purge rules. See mk-purge-
110 logs.
111 mk-query-advisor
113 Analyze queries and advise on possible problems. See mk-query-
114 advisor.
115 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 mk-query-profiler
122 Execute SQL statements and print statistics, or measure activity
123 caused by other processes. See mk-query-profiler.
124 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 mk-slave-delay
130 Make a MySQL slave server lag behind its master. See mk-slave-
131 delay.
132 mk-slave-find
134 Find and print replication hierarchy tree of MySQL slaves. See mk-
135 slave-find.
136 mk-slave-move
138 Move a MySQL slave around in the replication hierarchy. See mk-
139 slave-move.
140 mk-slave-prefetch
142 Pipeline relay logs on a MySQL slave to pre-warm caches. See mk-
143 slave-prefetch.
144 mk-slave-restart
146 Watch and restart MySQL replication after errors. See mk-slave-
147 restart.
148 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 mk-table-sync
154 Synchronize MySQL table data efficiently. See mk-table-sync.
155 mk-table-usage
157 Read queries from a log and analyze how they use tables. See mk-
158 table-usage.
159 mk-tcp-model
161 Transform tcpdump into metrics that permit performance and
162 scalability modeling. See mk-tcp-model.
163 mk-upgrade
165 Execute queries on multiple servers and check for differences. See
166 mk-upgrade.
167 mk-variable-advisor
169 Analyze MySQL variables and advise on possible problems. See mk-
170 variable-advisor.
171 mk-visual-explain
173 Format EXPLAIN output as a tree. See mk-visual-explain.
174
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 cd <package directory>
181 perl Makefile.PL
182 make install
183
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 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 SYNTAX
196 The syntax of the files is as follows:
197 • Whitespace followed by a hash (#) sign signifies that the rest of
199 the line is a comment. This is deleted.
200 • Whitespace is stripped from the beginning and end of all lines.
202 • Empty lines are ignored.
204 • Each line is permitted to be in either of the following formats:
206 option
208 option=value
209 Whitespace around the equals sign is deleted during processing.
211 • Only long options are recognized.
213 • 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 FILES
219 The tools read several configuration files in order:
220 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 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 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 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 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 --config /path/to/file
248 If you don't want any configuration files at all, specify "--config ''"
250 to provide an empty list of files.
251
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 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 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 A Specifies the default character set for the connection.
268 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 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 D Specifies the connection's default database.
284 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 [client]
296 user=your_user_name
297 pass=secret
298 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 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 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 S Socket file to use for the connection (on Unix systems).
316 h Hostname or IP address for the connection.
318 p Password to use when connecting.
320 u User for login if not current user.
322 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 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 h=host1,u=fred,p=wilma host2 host3
337 This is tool-specific.
339
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
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
349 This program is copyright (c) 2007 Baron Schwartz and others. Feedback
350 and improvements are welcome.
351 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 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 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
367 See the individual program's documentation for details.
368
370 This manual page documents Distrib 7540 $Revision: 534 $.
371perl v5.38.0 2023-07-20 MAATKIT(1)