MAATKIT(1)

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.

The following tools are included:

   $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

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

  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. However, its behavior is not 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.

DSN (DATA SOURCE NAME) SPECIFICATIONS
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.

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:

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, however. 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.

    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.

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.

  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.

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

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

COPYRIGHT, LICENSE AND WARRANTY
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.

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.

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