MAATKIT(1)

📦
version 7540 · 3 versions
, in fedora 43

🌸 MAATKIT 💅

ok bestie, so this is the page for maatkit — like, the user contributed perl documentation one. That's the manual name, mwah, noted. Now buckle up because this is a whole bundle of command-line tools and we're going through every single one, no skipping, no cap. 🫶

✨ NAME ✨

maatkit — Essential command-line utilities for MySQL. 💖

🌈 DESCRIPTION 🌈

Maatkit is a collection of command-line utilities that provide missing functionality for MySQL. Some of the tools implement lacking server functionality, such as online consistency checks for master/slave replication; others are client-side utilities such as a query profiler.

Here's the full roster of what's in the box, with the exact version numbers because we do not round, we do not vibe-check away the digits:

$Revision: 7540 $
mk-archiver 1.0.27
mk-config-diff 1.0.0
mk-deadlock-logger 1.0.21
mk-duplicate-key-checker 1.2.15
mk-error-log 1.0.3
mk-fifo-split 1.0.7
mk-find 0.9.23
mk-heartbeat 1.0.23
mk-index-usage 0.9.4
mk-kill 0.9.10
mk-loadavg 0.9.7
mk-log-player 1.0.9
mk-parallel-dump 1.0.28
mk-parallel-restore 1.0.24
mk-purge-logs 0.9.0
mk-query-advisor 1.0.4
mk-query-digest 0.9.29
mk-query-profiler 1.1.22
mk-show-grants 1.0.23
mk-slave-delay 1.0.23
mk-slave-find 1.0.16
mk-slave-move 0.9.12
mk-slave-prefetch 1.0.21
mk-slave-restart 1.0.22
mk-table-checksum 1.2.23
mk-table-sync 1.0.31
mk-table-usage 1.0.1
mk-tcp-model 1.0.1
mk-upgrade 0.9.8
mk-variable-advisor 1.0.2
mk-visual-explain 1.0.22

and now the glow-up tour, one tool at a time 👑

  • mk-archiver — Archive rows from a MySQL table into another table or a file. See mk-archiver.
  • mk-checksum-filter — Filter checksums from mk-table-checksum. See mk-checksum-filter.
  • mk-config-diff — Diff MySQL configuration files and server variables. See mk-config-diff.
  • mk-deadlock-logger — Extract and log MySQL deadlock information. See mk-deadlock-logger.
  • mk-duplicate-key-checker — Find duplicate indexes and foreign keys on MySQL tables. See mk-duplicate-key-checker.
  • mk-error-log — Find new and different MySQL error log entries. See mk-error-log.
  • mk-fifo-split — Split files and pipe lines to a fifo without really splitting. See mk-fifo-split.
  • mk-find — Find MySQL tables and execute actions, like GNU find. See mk-find.
  • mk-heartbeat — Monitor MySQL replication delay. See mk-heartbeat.
  • mk-index-usage — Read queries from a log and analyze how they use indexes. See mk-index-usage.
  • mk-kill — Kill MySQL queries that match certain criteria. See mk-kill.
  • mk-loadavg — Watch MySQL load and take action when it gets too high. See mk-loadavg.
  • mk-log-player — Replay MySQL query logs. See mk-log-player.
  • mk-merge-mqd-results — Merge multiple mk-query-digest reports into one. See mk-merge-mqd-results.
  • mk-parallel-dump — (DEPRECATED) Dump MySQL tables in parallel. See mk-parallel-dump.
  • mk-parallel-restore — (DEPRECATED) Load files into MySQL in parallel. See mk-parallel-restore.
  • mk-profile-compact — Compact the output from mk-query-profiler. See mk-profile-compact.
  • mk-purge-logs — Purge binary logs on a master based on purge rules. See mk-purge-logs.
  • mk-query-advisor — Analyze queries and advise on possible problems. See mk-query-advisor.
  • mk-query-digest — Analyze query execution logs and generate a query report, filter, replay, or transform queries for MySQL, PostgreSQL, memcached, and more. See mk-query-digest.
  • mk-query-profiler — Execute SQL statements and print statistics, or measure activity caused by other processes. See mk-query-profiler.
  • mk-show-grants — Canonicalize and print MySQL grants so you can effectively replicate, compare and version-control them. See mk-show-grants.
  • mk-slave-delay — Make a MySQL slave server lag behind its master. See mk-slave-delay.
  • mk-slave-find — Find and print replication hierarchy tree of MySQL slaves. See mk-slave-find.
  • mk-slave-move — Move a MySQL slave around in the replication hierarchy. See mk-slave-move.
  • mk-slave-prefetch — Pipeline relay logs on a MySQL slave to pre-warm caches. See mk-slave-prefetch.
  • mk-slave-restart — Watch and restart MySQL replication after errors. See mk-slave-restart.
  • mk-table-checksum — Perform an online replication consistency check, or checksum MySQL tables efficiently on one or many servers. See mk-table-checksum.
  • mk-table-sync — Synchronize MySQL table data efficiently. See mk-table-sync.
  • mk-table-usage — Read queries from a log and analyze how they use tables. See mk-table-usage.
  • mk-tcp-model — Transform tcpdump into metrics that permit performance and scalability modeling. See mk-tcp-model.
  • mk-upgrade — Execute queries on multiple servers and check for differences. See mk-upgrade.
  • mk-variable-advisor — Analyze MySQL variables and advise on possible problems. See mk-variable-advisor.
  • mk-visual-explain — Format EXPLAIN output as a tree. See mk-visual-explain.

🎀 INSTALLATION 🎀

Strictly speaking these tools require no installation; you should be able to run them stand-alone. That's the dream, honestly, no setup arc, we just go. ✨

However, on UNIX-ish systems you can use the standard Perl installation sequence:

cd <package directory>
perl Makefile.PL
make install

💜 CONFIGURATION 💜

Maatkit tools can read options from configuration files. The configuration file syntax is simple and direct, and bears some resemblances to the MySQL command-line client tools. The configuration files all follow the same conventions.

Internally, what actually happens is that the lines are read from the file and then added as command-line options and arguments to the Maatkit tool, so just think of the configuration files as a way to write your command lines. no thoughts, just command line 💅

🦋 SYNTAX 🦋

The syntax of the files is as follows:

  • Whitespace followed by a hash (#) sign signifies that the rest of the line is a comment. This is deleted.
  • Whitespace is stripped from the beginning and end of all lines.
  • Empty lines are ignored.
  • Each line is permitted to be in either of the following formats:
option
option=value

Whitespace around the equals sign is deleted during processing.

  • Only long options are recognized.
  • A line containing only two hyphens signals the end of option parsing. Any further lines are interpreted as additional arguments (not options) to the program.

🌸 FILES 🌸

The tools read several configuration files in order:

  1. The global Maatkit configuration file, /etc/maatkit/maatkit.conf. All tools read this file, so you should only add options to it that you want to apply to all Maatkit tools.
  2. The global tool configuration file, /etc/maatkit/[toolname].conf. This file is named after the specific tool you're using, so you can add options that apply only to that tool.
  3. The user's own Maatkit configuration file, $HOME/.maatkit.conf. All tools read this file, so you should only add options to it that you want to apply to all Maatkit tools.
  4. The user's tool configuration file, $HOME/.[toolname].conf. This file is named after the specific tool you're using, so you can add options that apply only to that tool.

⭐ SPECIFYING CONFIGURATION FILES ⭐

There is a special --config option, which lets you specify which configuration files Maatkit should read. You specify a comma-separated list of files.

ok but listen, bestie — this one does not behave like other command-line options. It must be given first on the command line, before any other options. If you try to specify it anywhere else, it will cause an error. 😭

Also, you cannot specify --config=/path/to/file; you must specify the option and the path to the file(s) separated by whitespace, without an equals-sign between them, e.g.

--config /path/to/file

If you don't want any configuration files at all, specify --config '' to provide an empty list of files. periodt. 💖

...and there's more, bestie, don't go anywhere — part 2 is coming 💅

💾 DSN (DATA SOURCE NAME) SPECIFICATIONS 💾

okay bestie so this is like, the most important part of the whole page, don't skip it 💖 Maatkit uses DSNs to specify how to create a DBD connection to a MySQL server. The maatkit tools that have command-line arguments such as -u or -p use them to create a DSN behind the scenes, then use the DSN to connect to MySQL. it's giving puppet-master energy honestly ✨

A DSN is a string of key=value parts separated by commas. The possible keys are shown later in this document. You can also get a quick synopsis from the --help output of many of the maatkit tools. 🫶

🎀 PARTS 🎀

Many of the tools add more parts to DSNs for special purposes, and sometimes override parts to make them do something slightly different. However, all the tools support at least the following — no cap, every single one 👑

  • A — Specifies the default character set for the connection.

Enables character set settings in Perl and MySQL. If the value is "utf8", sets Perl's binmode on STDOUT to utf8, passes the "mysql_enable_utf8" option to DBD::mysql, and runs "SET NAMES UTF8" after connecting to MySQL. Any other value sets binmode on STDOUT without the utf8 layer, and runs "SET NAMES" after connecting to MySQL. 😌

unfortunately, there is no way from within Perl itself to specify the client library's character set. "SET NAMES" only affects the server; if the client library's settings don't match, there could be problems. 😭 You can use the defaults file to specify the client library's character set, though. See the description of the F part below. 👇
  • D — Specifies the connection's default database. 📚
  • F — Specifies a defaults file the mysql client library (the C client library used by DBD::mysql, not maatkit itself) should read. The maatkit tools all read the [client] section within the defaults file. If you omit this, the standard defaults files will be read in the usual order. "Standard" varies from system to system, because the filenames to read are compiled into the client library. On Debian systems, for example, it's usually /etc/mysql/my.cnf then ~/.my.cnf. If you place the following into ~/.my.cnf, maatkit will Do The Right Thing: 💅
[client]
user=your_user_name
pass=secret

Omitting the F part is usually the right thing to do. As long as you have configured your ~/.my.cnf correctly, that will result in maatkit connecting automatically without needing a username or password. iconic behaviour fr fr 🌸

You can also specify a default character set in the defaults file. Unlike the "A" part described above, this will actually instruct the client library (DBD::mysql) to change the character set it uses internally, which cannot be accomplished any other way as far as I know, except for "utf8". 🦋

  • P — Port number to use for the connection. Note that the usual special-case behaviors apply: if you specify "localhost" as your hostname on Unix systems, the connection actually uses a socket file, not a TCP/IP connection, and thus ignores the port. 💀 sneaky
  • S — Socket file to use for the connection (on Unix systems). 🔌
  • h — Hostname or IP address for the connection. 🌐
  • p — Password to use when connecting. 🤫
  • u — User for login if not current user. 🙋

🦄 BAREWORD 🦄

Many of the tools will let you specify a DSN as a single word, without any key=value syntax. This is called a 'bareword'. How this is handled is tool-specific, but it is usually interpreted as the "h" part. The tool's --help output will tell you the behavior for that tool. iykyk ✨

🌈 DEFAULT PROPAGATION 🌈

Many tools will let you propagate values from one DSN to the next, so you don't have to specify all the parts for each DSN. For example, if you want to specify a username and password for each DSN, you can connect to three hosts as follows:

h=host1,u=fred,p=wilma host2 host3

This is tool-specific. one u and p to rule them all, obsessed 😌

⭐ SYSTEM REQUIREMENTS ⭐

You need Perl, DBI, DBD::mysql, and some core packages that ought to be installed in any reasonably new version of Perl. that's it bestie, you got this 🫶

🐛 BUGS 🐛

If you find bugs, need features, etc please use the bug tracker, forums, and mailing lists at http://code.google.com/p/maatkit/ — they want to hear from you, fr fr 💜

This program is copyright (c) 2007 Baron Schwartz and others. Feedback and improvements are welcome. 🎀

THIS PROGRAM IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. 🚨 bestie this means no promises, okay?? none!!

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; OR the Perl Artistic License. On UNIX and similar systems, you can issue `man perlgpl' or `man perlartistic' to read these licenses. 📜

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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.

💌 AUTHOR 💌

See the individual program's documentation for details. (yes really, that's the whole section, go check the tool's own page babes 💖)

🌟 VERSION 🌟

This manual page documents Distrib 7540 $Revision: 534 $.

and that's a wrap on this whole page!! 🎉 it was generated with perl v5.42.0 and dated 2025-07-24, so like… periodt, you're fully caught up bestie, go forth and connect 💅✨

📦 where this page comes from