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: 6652 $
mk-archiver 1.0.23
mk-deadlock-logger 1.0.21
mk-duplicate-key-checker 1.2.13
mk-error-log 1.0.3
mk-fifo-split 1.0.7
mk-find 0.9.23
mk-heartbeat 1.0.22
mk-index-usage 0.9.0
mk-kill 0.9.6
mk-loadavg 0.9.6
mk-log-player 1.0.8
mk-parallel-dump 1.0.26
mk-parallel-restore 1.0.23
mk-purge-logs 0.9.0
mk-query-digest 0.9.19
mk-query-profiler 1.1.22
mk-show-grants 1.0.23
mk-slave-delay 1.0.21
mk-slave-find 1.0.12
mk-slave-move 0.9.12
mk-slave-prefetch 1.0.19
mk-slave-restart 1.0.22
mk-table-checksum 1.2.16
mk-table-sync 1.0.29
mk-upgrade 0.9.8
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-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

Split and play MySQL slow 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

Dump MySQL tables in parallel. See mk-parallel-dump.

mk-parallel-restore

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

Parses logs and more. Analyze, transform, filter, review and report on queries. 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 tables efficiently. See mk-table-sync.

mk-upgrade

Execute queries on multiple servers and check for differences. See mk-upgrade.

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.

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 6652 $Revision: 534 $.