1
package Percona::Toolkit;
3
our $VERSION = '1.0.0';
11
Percona Toolkit - Advanced command-line tools used by Percona for MySQL support and consulting
15
Percona Toolkit is a collection of advanced command-line tools used by
16
Percona (L<http://www.percona.com/>) support staff to perform a variety of
17
MySQL and system tasks that are too difficult or complex to perform manually.
19
These tools are ideal alternatives to private or "one-off" scripts because
20
they are professionally developed, formally tested, and fully documented.
21
They are also fully self-contained, so installation is quick and easy and
22
no libraries are installed.
24
Percona Toolkit is developed and supported by Percona Inc. For more
25
information and other free, open-source software developed by Percona,
26
visit L<http://www.percona.com/software/>.
30
This release of Percona Toolkit includes the following tools:
40
For more free, open-source software developed Percona, visit
41
L<http://www.percona.com/software/>.
43
=head1 CONFIGURATION FILES
45
Percona Toolkit tools can read options from configuration files. The
46
configuration file syntax is simple and direct, and bears some resemblances
47
to the MySQL command-line client tools. The configuration files all follow
50
Internally, what actually happens is that the lines are read from the file and
51
then added as command-line options and arguments to the tool, so just
52
think of the configuration files as a way to write your command lines.
56
The syntax of the configuration files is as follows:
62
Whitespace followed by a hash (#) sign signifies that the rest of the line is a
63
comment. This is deleted.
67
Whitespace is stripped from the beginning and end of all lines.
71
Empty lines are ignored.
75
Each line is permitted to be in either of the following formats:
80
Whitespace around the equals sign is deleted during processing.
84
Only long options are recognized.
88
A line containing only two hyphens signals the end of option parsing. Any
89
further lines are interpreted as additional arguments (not options) to the
96
The tools read several configuration files in order:
102
The global Percona Toolkit configuration file,
103
F</etc/percona-toolkit/percona-toolkit.conf>. All tools read this file,
104
so you should only add options to it that you want to apply to all tools.
108
The global tool-specific configuration file, F</etc/percona-toolkit/TOOL.conf>,
109
where C<TOOL> is a tool name like C<pt-query-digest>. This file is named
110
after the specific tool you're using, so you can add options that apply
115
The user's own Percona Toolkit configuration file,
116
F<$HOME/.percona-toolkit.conf>. All tools read this file, so you should only
117
add options to it that you want to apply to all tools.
121
The user's tool-specific configuration file, F<$HOME/.TOOL.conf>,
122
where C<TOOL> is a tool name like C<pt-query-digest>. This file is named
123
after the specific tool you're using, so you can add options that apply
130
There is a special C<--config> option, which lets you specify which
131
configuration files Percona Toolkit should read. You specify a
132
comma-separated list of files. However, its behavior is not like other
133
command-line options. It must be given B<first> on the command line,
134
before any other options. If you try to specify it anywhere else, it will
135
cause an error. Also, you cannot specify C<--config=/path/to/file>;
136
you must specify the option and the path to the file separated by whitespace
137
I<without an equal sign> between them, like:
139
--config /path/to/file
141
If you don't want any configuration files at all, specify C<--config ''> to
142
provide an empty list of files.
144
=head1 DSN (DATA SOURCE NAME) SPECIFICATIONS
146
Percona Toolkit tools use DSNs to specify how to create a DBD connection to
147
a MySQL server. A DSN is a comma-separated string of C<key=value> parts, like:
151
The standard key parts are shown below, but some tools add additional key
152
parts. See each tool's documentation for details.
154
Some tools do not use DSNs but still connect to MySQL using options like
155
C<--host>, C<--user>, and C<--password>. Such tools uses these options to
156
create a DSN automatically, behind the scenes.
158
Other tools uses both DSNs and options like the ones above. The options
159
provide defaults for all DSNs that do not specify the option's corresponding
160
key part. For example, if DSN C<h=host1> and option C<--port=12345> are
161
specified, then the tool automatically adds C<P=12345> to DSN.
165
Many of the tools add more parts to DSNs for special purposes, and sometimes
166
override parts to make them do something slightly different. However, all the
167
tools support at least the following:
173
Specifies the default character set for the connection.
175
Enables character set settings in Perl and MySQL. If the value is C<utf8>, sets
176
Perl's binmode on STDOUT to utf8, passes the C<mysql_enable_utf8> option to
177
DBD::mysql, and runs C<SET NAMES UTF8> after connecting to MySQL. Any other
178
value sets binmode on STDOUT without the utf8 layer, and runs C<SET NAMES> after
181
Unfortunately, there is no way from within Perl itself to specify the client
182
library's character set. C<SET NAMES> only affects the server; if the client
183
library's settings don't match, there could be problems. You can use the
184
defaults file to specify the client library's character set, however. See the
185
description of the F part below.
189
Specifies the connection's default database.
193
Specifies a defaults file the mysql client library (the C client library used by
194
DBD::mysql, I<not Percona Toolkit itself>) should read. The tools all read the
195
[client] section within the defaults file. If you omit this, the standard
196
defaults files will be read in the usual order. "Standard" varies from system
197
to system, because the filenames to read are compiled into the client library.
198
On Debian systems, for example, it's usually /etc/mysql/my.cnf then ~/.my.cnf.
199
If you place the following into ~/.my.cnf, tools will Do The Right Thing:
205
Omitting the F part is usually the right thing to do. As long as you have
206
configured your ~/.my.cnf correctly, that will result in tools connecting
207
automatically without needing a username or password.
209
You can also specify a default character set in the defaults file. Unlike the
210
L<"A"> part described above, this will actually instruct the client library
211
(DBD::mysql) to change the character set it uses internally, which cannot be
212
accomplished any other way as far as I know, except for C<utf8>.
216
Port number to use for the connection. Note that the usual special-case
217
behaviors apply: if you specify C<localhost> as your hostname on Unix systems,
218
the connection actually uses a socket file, not a TCP/IP connection, and thus
223
Socket file to use for the connection (on Unix systems).
227
Hostname or IP address for the connection.
231
Password to use when connecting.
235
User for login if not current user.
241
Many of the tools will let you specify a DSN as a single word, without any
242
C<key=value> syntax. This is called a 'bareword'. How this is handled is
243
tool-specific, but it is usually interpreted as the L<"h"> part. The tool's
244
C<--help> output will tell you the behavior for that tool.
248
Many tools will let you propagate values from one DSN to the next, so you don't
249
have to specify all the parts for each DSN. For example, if you want to specify
250
a username and password for each DSN, you can connect to three hosts as follows:
252
h=host1,u=fred,p=wilma host2 host3
254
This is tool-specific.
258
The environment variable C<PTDEBUG> enables verbose debugging output to STDERR.
259
To enable debugging and capture all output to a file, run the tool like:
261
PTDEBUG=1 pt-table-checksum ... > FILE 2>&1
263
Be careful: debugging output is voluminous and can generate several megabytes
266
=head1 SYSTEM REQUIREMENTS
272
=item * Perl v5.8 or newer
274
=item * Bash v3 or newer
276
=item * Core Perl modules like Time::HiRes
280
Tools that connect to MySQL require:
284
=item * Perl modules DBI and DBD::mysql
286
=item * MySQL 5.0 or newer
290
Percona Toolkit is only tested on UNIX systems, primarily Debian and
291
Red Hat derivatives; other operating systems are not supported.
293
Tools that connect to MySQL may work with MySQL v4.1, but this is not
298
Please report bugs at L<https://bugs.launchpad.net/percona-toolkit>.
299
Include the following information in your bug report:
303
=item * Complete command-line used to run the tool
305
=item * Tool C<--version>
307
=item * MySQL version of all servers involved
309
=item * Output from the tool including STDERR
311
=item * Input files (log/dump/config files, etc.)
315
If possible, include debugging output by running the tool with C<PTDEBUG>;
316
see L<"ENVIRONMENT">.
320
Percona Toolkit is primarily developed by Baron Schwartz and Daniel Nichter,
321
both of whom are employed by Percona Inc. See each program's documenation
324
=head1 COPYRIGHT, LICENSE, AND WARRANTY
326
Percona Toolkit is copyright 2011 Percona Inc. and others.
327
See each program's documentation for complete copyright notices.
329
THIS PROGRAM IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
330
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
331
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
333
This program is free software; you can redistribute it and/or modify it under
334
the terms of the GNU General Public License as published by the Free Software
335
Foundation, version 2; OR the Perl Artistic License. On UNIX and similar
336
systems, you can issue `man perlgpl' or `man perlartistic' to read these
339
You should have received a copy of the GNU General Public License along with
340
this program; if not, write to the Free Software Foundation, Inc., 59 Temple
341
Place, Suite 330, Boston, MA 02111-1307 USA.
345
Percona Toolkit v1.0.0 released 2008-08-01
added
removed
docs/percona-toolkit.pod
