Merge lp:~daniel-nichter/percona-toolkit/fix-bug-856065 into lp:percona-toolkit/1.0

[Daniel Nichter]

[Daniel Nichter (daniel-nichter)]

review: Approve

=== modified file '.bzrignore'
--- .bzrignore	2011-07-15 23:50:16 +0000
+++ .bzrignore	2011-11-14 16:37:00 +0000
@@ -5,3 +5,4 @@
 docs/test-coverage/html
 release
 .DS_Store
+build

=== added file 'docs/user/Makefile'
--- docs/user/Makefile	1970-01-01 00:00:00 +0000
+++ docs/user/Makefile	2011-11-14 16:37:00 +0000
@@ -0,0 +1,130 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/PerconaXtraBackup.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PerconaXtraBackup.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/PerconaXtraBackup"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PerconaXtraBackup"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	make -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."

=== removed file 'docs/user/authors.rst'
--- docs/user/authors.rst	2011-08-31 15:44:31 +0000
+++ docs/user/authors.rst	1970-01-01 00:00:00 +0000
@@ -1,9 +0,0 @@
-
-*******
-AUTHORS
-*******
-
-Percona Toolkit is primarily developed by Baron Schwartz and Daniel Nichter,
-both of whom are employed by Percona Inc.  See each program's documenation
-for details.
-

=== removed file 'docs/user/bugs.rst'
--- docs/user/bugs.rst	2011-08-31 15:44:31 +0000
+++ docs/user/bugs.rst	1970-01-01 00:00:00 +0000
@@ -1,21 +0,0 @@
-
-****
-BUGS
-****
-
-Please report bugs at `https://bugs.launchpad.net/percona-toolkit <https://bugs.launchpad.net/percona-toolkit>`_.
-Include the following information in your bug report:
-
-\* Complete command-line used to run the tool
-
-\* Tool \ ``--version``\ 
-
-\* MySQL version of all servers involved
-
-\* Output from the tool including STDERR
-
-\* Input files (log/dump/config files, etc.)
-
-If possible, include debugging output by running the tool with \ ``PTDEBUG``\ ;
-see "ENVIRONMENT".
-

=== removed file 'docs/user/configuration_files.rst'
--- docs/user/configuration_files.rst	2011-08-31 15:44:31 +0000
+++ docs/user/configuration_files.rst	1970-01-01 00:00:00 +0000
@@ -1,115 +0,0 @@
-
-*******************
-CONFIGURATION FILES
-*******************
-
-Percona Toolkit 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 tool, so just
-think of the configuration files as a way to write your command lines.
-
-SYNTAX
-======
-
-The syntax of the configuration 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:
- 
- 
- .. code-block:: perl
- 
-    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.
- 
-
-READ ORDER
-==========
-
-The tools read several configuration files in order:
-
-1.
- 
- The global Percona Toolkit configuration file,
- \ */etc/percona-toolkit/percona-toolkit.conf*\ .  All tools read this file,
- so you should only add options to it that you want to apply to all tools.
- 
-
-2.
- 
- The global tool-specific configuration file, \ */etc/percona-toolkit/TOOL.conf*\ ,
- where \ ``TOOL``\  is a tool name like \ ``pt-query-digest``\ .  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 Percona Toolkit configuration file,
- \ *$HOME/.percona-toolkit.conf*\ .  All tools read this file, so you should only
- add options to it that you want to apply to all tools.
- 
-
-4.
- 
- The user's tool-specific configuration file, \ *$HOME/.TOOL.conf*\ ,
- where \ ``TOOL``\  is a tool name like \ ``pt-query-digest``\ .  This file is named
- after the specific tool you're using, so you can add options that apply
- only to that tool.
- 
-
-SPECIFYING
-==========
-
-There is a special \ ``--config``\  option, which lets you specify which
-configuration files Percona Toolkit 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 separated by whitespace
-\ *without an equal sign*\  between them, like:
-
-.. code-block:: perl
-
-   --config /path/to/file
-
-If you don't want any configuration files at all, specify \ ``--config ''``\  to
-provide an empty list of files.
-

=== removed file 'docs/user/copyright_license_and_warranty.rst'
--- docs/user/copyright_license_and_warranty.rst	2011-08-31 15:44:31 +0000
+++ docs/user/copyright_license_and_warranty.rst	1970-01-01 00:00:00 +0000
@@ -1,22 +0,0 @@
-
-********************************
-COPYRIGHT, LICENSE, AND WARRANTY
-********************************
-
-Percona Toolkit is copyright 2011 Percona Inc. and others.
-See each program's documentation for complete copyright notices.
-
-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.
-

=== removed file 'docs/user/environment.rst'
--- docs/user/environment.rst	2011-08-31 15:44:31 +0000
+++ docs/user/environment.rst	1970-01-01 00:00:00 +0000
@@ -1,15 +0,0 @@
-
-***********
-ENVIRONMENT
-***********
-
-The environment variable \ ``PTDEBUG``\  enables verbose debugging output to STDERR.
-To enable debugging and capture all output to a file, run the tool like:
-
-.. code-block:: perl
-
-    PTDEBUG=1 pt-table-checksum ... > FILE 2>&1
-
-Be careful: debugging output is voluminous and can generate several megabytes
-of output.
-

=== removed file 'docs/user/index.rst'
--- docs/user/index.rst	2011-08-31 15:44:31 +0000
+++ docs/user/index.rst	1970-01-01 00:00:00 +0000
@@ -1,31 +0,0 @@
-
-*****************************
-Percona Toolkit Documentation
-*****************************
-
-Percona Toolkit is a collection of advanced command-line tools used by
-Percona (`http://www.percona.com/ <http://www.percona.com/>`_) support staff to perform a variety of
-MySQL and system tasks that are too difficult or complex to perform manually.
-
-These tools are ideal alternatives to private or "one-off" scripts because
-they are professionally developed, formally tested, and fully documented.
-They are also fully self-contained, so installation is quick and easy and
-no libraries are installed.
-
-Percona Toolkit is derived from Maatkit and Aspersa, two of the best-known
-toolkits for MySQL server administration.  It is developed and supported by
-Percona Inc.  For more information and other free, open-source software
-developed by Percona, visit `http://www.percona.com/software/ <http://www.percona.com/software/>`_.
-
-.. toctree::
-   :maxdepth: 2
-
-   tools
-   configuration_files
-   environment
-   system_requirements
-   bugs
-   authors
-   copyright_license_and_warranty
-   version
-   release_notes

=== added file 'docs/user/make.bat'
--- docs/user/make.bat	1970-01-01 00:00:00 +0000
+++ docs/user/make.bat	2011-11-14 16:37:00 +0000
@@ -0,0 +1,170 @@
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source
+if NOT "%PAPER%" == "" (
+	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+	:help
+	echo.Please use `make ^<target^>` where ^<target^> is one of
+	echo.  html       to make standalone HTML files
+	echo.  dirhtml    to make HTML files named index.html in directories
+	echo.  singlehtml to make a single large HTML file
+	echo.  pickle     to make pickle files
+	echo.  json       to make JSON files
+	echo.  htmlhelp   to make HTML files and a HTML help project
+	echo.  qthelp     to make HTML files and a qthelp project
+	echo.  devhelp    to make HTML files and a Devhelp project
+	echo.  epub       to make an epub
+	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+	echo.  text       to make text files
+	echo.  man        to make manual pages
+	echo.  changes    to make an overview over all changed/added/deprecated items
+	echo.  linkcheck  to check all external links for integrity
+	echo.  doctest    to run all doctests embedded in the documentation if enabled
+	goto end
+)
+
+if "%1" == "clean" (
+	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+	del /q /s %BUILDDIR%\*
+	goto end
+)
+
+if "%1" == "html" (
+	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+	goto end
+)
+
+if "%1" == "dirhtml" (
+	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+	goto end
+)
+
+if "%1" == "singlehtml" (
+	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+	goto end
+)
+
+if "%1" == "pickle" (
+	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the pickle files.
+	goto end
+)
+
+if "%1" == "json" (
+	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the JSON files.
+	goto end
+)
+
+if "%1" == "htmlhelp" (
+	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+	goto end
+)
+
+if "%1" == "qthelp" (
+	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\PerconaXtraBackup.qhcp
+	echo.To view the help file:
+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\PerconaXtraBackup.ghc
+	goto end
+)
+
+if "%1" == "devhelp" (
+	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished.
+	goto end
+)
+
+if "%1" == "epub" (
+	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The epub file is in %BUILDDIR%/epub.
+	goto end
+)
+
+if "%1" == "latex" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "text" (
+	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The text files are in %BUILDDIR%/text.
+	goto end
+)
+
+if "%1" == "man" (
+	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The manual pages are in %BUILDDIR%/man.
+	goto end
+)
+
+if "%1" == "changes" (
+	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.The overview file is in %BUILDDIR%/changes.
+	goto end
+)
+
+if "%1" == "linkcheck" (
+	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+	goto end
+)
+
+if "%1" == "doctest" (
+	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+	goto end
+)
+
+:end

=== removed file 'docs/user/pt-archiver.rst'
--- docs/user/pt-archiver.rst	2011-09-01 16:00:38 +0000
+++ docs/user/pt-archiver.rst	1970-01-01 00:00:00 +0000
@@ -1,1556 +0,0 @@
-
-###########
-pt-archiver
-###########
-
-.. highlight:: perl
-
-
-****
-NAME
-****
-
-
-pt-archiver - Archive rows from a MySQL table into another table or a file.
-
-
-********
-SYNOPSIS
-********
-
-
-Usage: pt-archiver [OPTION...] --source DSN --where WHERE
-
-pt-archiver nibbles records from a MySQL table.  The --source and --dest
-arguments use DSN syntax; if COPY is yes, --dest defaults to the key's value
-from --source.
-
-Examples:
-
-Archive all rows from oltp_server to olap_server and to a file:
-
-
-.. code-block:: perl
-
-   pt-archiver --source h=oltp_server,D=test,t=tbl --dest h=olap_server \
-     --file '/var/log/archive/%Y-%m-%d-%D.%t'                           \
-     --where "1=1" --limit 1000 --commit-each
-
-
-Purge (delete) orphan rows from child table:
-
-
-.. code-block:: perl
-
-   pt-archiver --source h=host,D=db,t=child --purge \
-     --where 'NOT EXISTS(SELECT * FROM parent WHERE col=child.col)'
-
-
-
-*****
-RISKS
-*****
-
-
-The following section is included to inform users about the potential risks,
-whether known or unknown, of using this tool.  The two main categories of risks
-are those created by the nature of the tool (e.g. read-only tools vs. read-write
-tools) and those created by bugs.
-
-pt-achiver is a read-write tool.  It deletes data from the source by default, so
-you should test your archiving jobs with the "--dry-run" option if you're not
-sure about them.  It is designed to have as little impact on production systems
-as possible, but tuning with "--limit", "--txn-size" and similar options
-might be a good idea too.
-
-If you write or use "--plugin" modules, you should ensure they are good
-quality and well-tested.
-
-At the time of this release there is an unverified bug with
-"--bulk-insert" that may cause data loss.
-
-The authoritative source for updated information is always the online issue
-tracking system.  Issues that affect this tool will be marked as such.  You can
-see a list of such issues at the following URL:
-`http://www.percona.com/bugs/pt-archiver <http://www.percona.com/bugs/pt-archiver>`_.
-
-See also "BUGS" for more information on filing bugs and getting help.
-
-
-***********
-DESCRIPTION
-***********
-
-
-pt-archiver is the tool I use to archive tables as described in
-`http://tinyurl.com/mysql-archiving <http://tinyurl.com/mysql-archiving>`_.  The goal is a low-impact, forward-only
-job to nibble old data out of the table without impacting OLTP queries much.
-You can insert the data into another table, which need not be on the same
-server.  You can also write it to a file in a format suitable for LOAD DATA
-INFILE.  Or you can do neither, in which case it's just an incremental DELETE.
-
-pt-archiver is extensible via a plugin mechanism.  You can inject your own
-code to add advanced archiving logic that could be useful for archiving
-dependent data, applying complex business rules, or building a data warehouse
-during the archiving process.
-
-You need to choose values carefully for some options.  The most important are
-"--limit", "--retries", and "--txn-size".
-
-The strategy is to find the first row(s), then scan some index forward-only to
-find more rows efficiently.  Each subsequent query should not scan the entire
-table; it should seek into the index, then scan until it finds more archivable
-rows.  Specifying the index with the 'i' part of the "--source" argument can
-be crucial for this; use "--dry-run" to examine the generated queries and be
-sure to EXPLAIN them to see if they are efficient (most of the time you probably
-want to scan the PRIMARY key, which is the default).  Even better, profile
-pt-archiver with pt-query-profiler and make sure it is not scanning the whole
-table every query.
-
-You can disable the seek-then-scan optimizations partially or wholly with
-"--no-ascend" and "--ascend-first".  Sometimes this may be more efficient
-for multi-column keys.  Be aware that pt-archiver is built to start at the
-beginning of the index it chooses and scan it forward-only.  This might result
-in long table scans if you're trying to nibble from the end of the table by an
-index other than the one it prefers.  See "--source" and read the
-documentation on the \ ``i``\  part if this applies to you.
-
-
-******
-OUTPUT
-******
-
-
-If you specify "--progress", the output is a header row, plus status output
-at intervals.  Each row in the status output lists the current date and time,
-how many seconds pt-archiver has been running, and how many rows it has
-archived.
-
-If you specify "--statistics", \ ``pt-archiver``\  outputs timing and other
-information to help you identify which part of your archiving process takes the
-most time.
-
-
-**************
-ERROR-HANDLING
-**************
-
-
-pt-archiver tries to catch signals and exit gracefully; for example, if you
-send it SIGTERM (Ctrl-C on UNIX-ish systems), it will catch the signal, print a
-message about the signal, and exit fairly normally.  It will not execute
-"--analyze" or "--optimize", because these may take a long time to finish.
-It will run all other code normally, including calling after_finish() on any
-plugins (see "EXTENDING").
-
-In other words, a signal, if caught, will break out of the main archiving
-loop and skip optimize/analyze.
-
-
-*******
-OPTIONS
-*******
-
-
-Specify at least one of "--dest", "--file", or "--purge".
-
-"--ignore" and "--replace" are mutually exclusive.
-
-"--txn-size" and "--commit-each" are mutually exclusive.
-
-"--low-priority-insert" and "--delayed-insert" are mutually exclusive.
-
-"--share-lock" and "--for-update" are mutually exclusive.
-
-"--analyze" and "--optimize" are mutually exclusive.
-
-"--no-ascend" and "--no-delete" are mutually exclusive.
-
-DSN values in "--dest" default to values from "--source" if COPY is yes.
-
-
---analyze
- 
- type: string
- 
- Run ANALYZE TABLE afterwards on "--source" and/or "--dest".
- 
- Runs ANALYZE TABLE after finishing.  The argument is an arbitrary string.  If it
- contains the letter 's', the source will be analyzed.  If it contains 'd', the
- destination will be analyzed.  You can specify either or both.  For example, the
- following will analyze both:
- 
- 
- .. code-block:: perl
- 
-    --analyze=ds
- 
- 
- See `http://dev.mysql.com/doc/en/analyze-table.html <http://dev.mysql.com/doc/en/analyze-table.html>`_ for details on ANALYZE
- TABLE.
- 
-
-
---ascend-first
- 
- Ascend only first column of index.
- 
- If you do want to use the ascending index optimization (see "--no-ascend"),
- but do not want to incur the overhead of ascending a large multi-column index,
- you can use this option to tell pt-archiver to ascend only the leftmost column
- of the index.  This can provide a significant performance boost over not
- ascending the index at all, while avoiding the cost of ascending the whole
- index.
- 
- See "EXTENDING" for a discussion of how this interacts with plugins.
- 
-
-
---ask-pass
- 
- Prompt for a password when connecting to MySQL.
- 
-
-
---buffer
- 
- Buffer output to "--file" and flush at commit.
- 
- Disables autoflushing to "--file" and flushes "--file" to disk only when a
- transaction commits.  This typically means the file is block-flushed by the
- operating system, so there may be some implicit flushes to disk between
- commits as well.  The default is to flush "--file" to disk after every row.
- 
- The danger is that a crash might cause lost data.
- 
- The performance increase I have seen from using "--buffer" is around 5 to 15
- percent.  Your mileage may vary.
- 
-
-
---bulk-delete
- 
- Delete each chunk with a single statement (implies "--commit-each").
- 
- Delete each chunk of rows in bulk with a single \ ``DELETE``\  statement.  The
- statement deletes every row between the first and last row of the chunk,
- inclusive.  It implies "--commit-each", since it would be a bad idea to
- \ ``INSERT``\  rows one at a time and commit them before the bulk \ ``DELETE``\ .
- 
- The normal method is to delete every row by its primary key.  Bulk deletes might
- be a lot faster.  \ **They also might not be faster**\  if you have a complex
- \ ``WHERE``\  clause.
- 
- This option completely defers all \ ``DELETE``\  processing until the chunk of rows
- is finished.  If you have a plugin on the source, its \ ``before_delete``\  method
- will not be called.  Instead, its \ ``before_bulk_delete``\  method is called later.
- 
- \ **WARNING**\ : if you have a plugin on the source that sometimes doesn't return
- true from \ ``is_archivable()``\ , you should use this option only if you understand
- what it does.  If the plugin instructs \ ``pt-archiver``\  not to archive a row,
- it will still be deleted by the bulk delete!
- 
-
-
---[no]bulk-delete-limit
- 
- default: yes
- 
- Add "--limit" to "--bulk-delete" statement.
- 
- This is an advanced option and you should not disable it unless you know what
- you are doing and why!  By default, "--bulk-delete" appends a "--limit"
- clause to the bulk delete SQL statement.  In certain cases, this clause can be
- omitted by specifying \ ``--no-bulk-delete-limit``\ .  "--limit" must still be
- specified.
- 
-
-
---bulk-insert
- 
- Insert each chunk with LOAD DATA INFILE (implies "--bulk-delete" "--commit-each").
- 
- Insert each chunk of rows with \ ``LOAD DATA LOCAL INFILE``\ .  This may be much
- faster than inserting a row at a time with \ ``INSERT``\  statements.  It is
- implemented by creating a temporary file for each chunk of rows, and writing the
- rows to this file instead of inserting them.  When the chunk is finished, it
- uploads the rows.
- 
- To protect the safety of your data, this option forces bulk deletes to be used.
- It would be unsafe to delete each row as it is found, before inserting the rows
- into the destination first.  Forcing bulk deletes guarantees that the deletion
- waits until the insertion is successful.
- 
- The "--low-priority-insert", "--replace", and "--ignore" options work
- with this option, but "--delayed-insert" does not.
- 
-
-
---charset
- 
- short form: -A; type: string
- 
- Default character set.  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.
- 
- See also "--[no]check-charset".
- 
-
-
---[no]check-charset
- 
- default: yes
- 
- Ensure connection and table character sets are the same.  Disabling this check
- may cause text to be erroneously converted from one character set to another
- (usually from utf8 to latin1) which may cause data loss or mojibake.  Disabling
- this check may be useful or necessary when character set conversions are
- intended.
- 
-
-
---[no]check-columns
- 
- default: yes
- 
- Ensure "--source" and "--dest" have same columns.
- 
- Enabled by default; causes pt-archiver to check that the source and destination
- tables have the same columns.  It does not check column order, data type, etc.
- It just checks that all columns in the source exist in the destination and
- vice versa.  If there are any differences, pt-archiver will exit with an
- error.
- 
- To disable this check, specify --no-check-columns.
- 
-
-
---check-interval
- 
- type: time; default: 1s
- 
- How often to check for slave lag if "--check-slave-lag" is given.
- 
-
-
---check-slave-lag
- 
- type: string
- 
- Pause archiving until the specified DSN's slave lag is less than "--max-lag".
- 
-
-
---columns
- 
- short form: -c; type: array
- 
- Comma-separated list of columns to archive.
- 
- Specify a comma-separated list of columns to fetch, write to the file, and
- insert into the destination table.  If specified, pt-archiver ignores other
- columns unless it needs to add them to the \ ``SELECT``\  statement for ascending an
- index or deleting rows.  It fetches and uses these extra columns internally, but
- does not write them to the file or to the destination table.  It \ *does*\  pass
- them to plugins.
- 
- See also "--primary-key-only".
- 
-
-
---commit-each
- 
- Commit each set of fetched and archived rows (disables "--txn-size").
- 
- Commits transactions and flushes "--file" after each set of rows has been
- archived, before fetching the next set of rows, and before sleeping if
- "--sleep" is specified.  Disables "--txn-size"; use "--limit" to
- control the transaction size with "--commit-each".
- 
- This option is useful as a shortcut to make "--limit" and "--txn-size" the
- same value, but more importantly it avoids transactions being held open while
- searching for more rows.  For example, imagine you are archiving old rows from
- the beginning of a very large table, with "--limit" 1000 and "--txn-size"
- 1000.  After some period of finding and archiving 1000 rows at a time,
- pt-archiver finds the last 999 rows and archives them, then executes the next
- SELECT to find more rows.  This scans the rest of the table, but never finds any
- more rows.  It has held open a transaction for a very long time, only to
- determine it is finished anyway.  You can use "--commit-each" to avoid this.
- 
-
-
---config
- 
- type: Array
- 
- Read this comma-separated list of config files; if specified, this must be the
- first option on the command line.
- 
-
-
---delayed-insert
- 
- Add the DELAYED modifier to INSERT statements.
- 
- Adds the DELAYED modifier to INSERT or REPLACE statements.  See
- `http://dev.mysql.com/doc/en/insert.html <http://dev.mysql.com/doc/en/insert.html>`_ for details.
- 
-
-
---dest
- 
- type: DSN
- 
- DSN specifying the table to archive to.
- 
- This item specifies a table into which pt-archiver will insert rows
- archived from "--source".  It uses the same key=val argument format as
- "--source".  Most missing values default to the same values as
- "--source", so you don't have to repeat options that are the same in
- "--source" and "--dest".  Use the "--help" option to see which values
- are copied from "--source".
- 
- \ **WARNING**\ : Using a default options file (F) DSN option that defines a
- socket for "--source" causes pt-archiver to connect to "--dest" using
- that socket unless another socket for "--dest" is specified.  This
- means that pt-archiver may incorrectly connect to "--source" when it
- connects to "--dest".  For example:
- 
- 
- .. code-block:: perl
- 
-    --source F=host1.cnf,D=db,t=tbl --dest h=host2
- 
- 
- When pt-archiver connects to "--dest", host2, it will connect via the
- "--source", host1, socket defined in host1.cnf.
- 
-
-
---dry-run
- 
- Print queries and exit without doing anything.
- 
- Causes pt-archiver to exit after printing the filename and SQL statements
- it will use.
- 
-
-
---file
- 
- type: string
- 
- File to archive to, with DATE_FORMAT()-like formatting.
- 
- Filename to write archived rows to.  A subset of MySQL's DATE_FORMAT()
- formatting codes are allowed in the filename, as follows:
- 
- 
- .. code-block:: perl
- 
-     %d    Day of the month, numeric (01..31)
-     %H    Hour (00..23)
-     %i    Minutes, numeric (00..59)
-     %m    Month, numeric (01..12)
-     %s    Seconds (00..59)
-     %Y    Year, numeric, four digits
- 
- 
- You can use the following extra format codes too:
- 
- 
- .. code-block:: perl
- 
-     %D    Database name
-     %t    Table name
- 
- 
- Example:
- 
- 
- .. code-block:: perl
- 
-     --file '/var/log/archive/%Y-%m-%d-%D.%t'
- 
- 
- The file's contents are in the same format used by SELECT INTO OUTFILE, as
- documented in the MySQL manual: rows terminated by newlines, columns
- terminated by tabs, NULL characters are represented by \N, and special
- characters are escaped by \.  This lets you reload a file with LOAD DATA
- INFILE's default settings.
- 
- If you want a column header at the top of the file, see "--header".  The file
- is auto-flushed by default; see "--buffer".
- 
-
-
---for-update
- 
- Adds the FOR UPDATE modifier to SELECT statements.
- 
- For details, see `http://dev.mysql.com/doc/en/innodb-locking-reads.html <http://dev.mysql.com/doc/en/innodb-locking-reads.html>`_.
- 
-
-
---header
- 
- Print column header at top of "--file".
- 
- Writes column names as the first line in the file given by "--file".  If the
- file exists, does not write headers; this keeps the file loadable with LOAD
- DATA INFILE in case you append more output to it.
- 
-
-
---help
- 
- Show help and exit.
- 
-
-
---high-priority-select
- 
- Adds the HIGH_PRIORITY modifier to SELECT statements.
- 
- See `http://dev.mysql.com/doc/en/select.html <http://dev.mysql.com/doc/en/select.html>`_ for details.
- 
-
-
---host
- 
- short form: -h; type: string
- 
- Connect to host.
- 
-
-
---ignore
- 
- Use IGNORE for INSERT statements.
- 
- Causes INSERTs into "--dest" to be INSERT IGNORE.
- 
-
-
---limit
- 
- type: int; default: 1
- 
- Number of rows to fetch and archive per statement.
- 
- Limits the number of rows returned by the SELECT statements that retrieve rows
- to archive.  Default is one row.  It may be more efficient to increase the
- limit, but be careful if you are archiving sparsely, skipping over many rows;
- this can potentially cause more contention with other queries, depending on the
- storage engine, transaction isolation level, and options such as
- "--for-update".
- 
-
-
---local
- 
- Do not write OPTIMIZE or ANALYZE queries to binlog.
- 
- Adds the NO_WRITE_TO_BINLOG modifier to ANALYZE and OPTIMIZE queries.  See
- "--analyze" for details.
- 
-
-
---low-priority-delete
- 
- Adds the LOW_PRIORITY modifier to DELETE statements.
- 
- See `http://dev.mysql.com/doc/en/delete.html <http://dev.mysql.com/doc/en/delete.html>`_ for details.
- 
-
-
---low-priority-insert
- 
- Adds the LOW_PRIORITY modifier to INSERT or REPLACE statements.
- 
- See `http://dev.mysql.com/doc/en/insert.html <http://dev.mysql.com/doc/en/insert.html>`_ for details.
- 
-
-
---max-lag
- 
- type: time; default: 1s
- 
- Pause archiving if the slave given by "--check-slave-lag" lags.
- 
- This option causes pt-archiver to look at the slave every time it's about
- to fetch another row.  If the slave's lag is greater than the option's value,
- or if the slave isn't running (so its lag is NULL), pt-table-checksum sleeps
- for "--check-interval" seconds and then looks at the lag again.  It repeats
- until the slave is caught up, then proceeds to fetch and archive the row.
- 
- This option may eliminate the need for "--sleep" or "--sleep-coef".
- 
-
-
---no-ascend
- 
- Do not use ascending index optimization.
- 
- The default ascending-index optimization causes \ ``pt-archiver``\  to optimize
- repeated \ ``SELECT``\  queries so they seek into the index where the previous query
- ended, then scan along it, rather than scanning from the beginning of the table
- every time.  This is enabled by default because it is generally a good strategy
- for repeated accesses.
- 
- Large, multiple-column indexes may cause the WHERE clause to be complex enough
- that this could actually be less efficient.  Consider for example a four-column
- PRIMARY KEY on (a, b, c, d).  The WHERE clause to start where the last query
- ended is as follows:
- 
- 
- .. code-block:: perl
- 
-     WHERE (a > ?)
-        OR (a = ? AND b > ?)
-        OR (a = ? AND b = ? AND c > ?)
-        OR (a = ? AND b = ? AND c = ? AND d >= ?)
- 
- 
- Populating the placeholders with values uses memory and CPU, adds network
- traffic and parsing overhead, and may make the query harder for MySQL to
- optimize.  A four-column key isn't a big deal, but a ten-column key in which
- every column allows \ ``NULL``\  might be.
- 
- Ascending the index might not be necessary if you know you are simply removing
- rows from the beginning of the table in chunks, but not leaving any holes, so
- starting at the beginning of the table is actually the most efficient thing to
- do.
- 
- See also "--ascend-first".  See "EXTENDING" for a discussion of how this
- interacts with plugins.
- 
-
-
---no-delete
- 
- Do not delete archived rows.
- 
- Causes \ ``pt-archiver``\  not to delete rows after processing them.  This disallows
- "--no-ascend", because enabling them both would cause an infinite loop.
- 
- If there is a plugin on the source DSN, its \ ``before_delete``\  method is called
- anyway, even though \ ``pt-archiver``\  will not execute the delete.  See
- "EXTENDING" for more on plugins.
- 
-
-
---optimize
- 
- type: string
- 
- Run OPTIMIZE TABLE afterwards on "--source" and/or "--dest".
- 
- Runs OPTIMIZE TABLE after finishing.  See "--analyze" for the option syntax
- and `http://dev.mysql.com/doc/en/optimize-table.html <http://dev.mysql.com/doc/en/optimize-table.html>`_ for details on OPTIMIZE
- TABLE.
- 
-
-
---password
- 
- short form: -p; type: string
- 
- Password to use when connecting.
- 
-
-
---pid
- 
- type: string
- 
- Create the given PID file when daemonized.  The file contains the process ID of
- the daemonized instance.  The PID file is removed when the daemonized instance
- exits.  The program checks for the existence of the PID file when starting; if
- it exists and the process with the matching PID exists, the program exits.
- 
-
-
---plugin
- 
- type: string
- 
- Perl module name to use as a generic plugin.
- 
- Specify the Perl module name of a general-purpose plugin.  It is currently used
- only for statistics (see "--statistics") and must have \ ``new()``\  and a
- \ ``statistics()``\  method.
- 
- The \ ``new( src =``\  $src, dst => $dst, opts => $o )> method gets the source
- and destination DSNs, and their database connections, just like the
- connection-specific plugins do.  It also gets an OptionParser object (\ ``$o``\ ) for
- accessing command-line options (example: \ ``$o-``\ get('purge');>).
- 
- The \ ``statistics(\%stats, $time)``\  method gets a hashref of the statistics
- collected by the archiving job, and the time the whole job started.
- 
-
-
---port
- 
- short form: -P; type: int
- 
- Port number to use for connection.
- 
-
-
---primary-key-only
- 
- Primary key columns only.
- 
- A shortcut for specifying "--columns" with the primary key columns.  This is
- an efficiency if you just want to purge rows; it avoids fetching the entire row,
- when only the primary key columns are needed for \ ``DELETE``\  statements.  See also
- "--purge".
- 
-
-
---progress
- 
- type: int
- 
- Print progress information every X rows.
- 
- Prints current time, elapsed time, and rows archived every X rows.
- 
-
-
---purge
- 
- Purge instead of archiving; allows omitting "--file" and "--dest".
- 
- Allows archiving without a "--file" or "--dest" argument, which is
- effectively a purge since the rows are just deleted.
- 
- If you just want to purge rows, consider specifying the table's primary key
- columns with "--primary-key-only".  This will prevent fetching all columns
- from the server for no reason.
- 
-
-
---quick-delete
- 
- Adds the QUICK modifier to DELETE statements.
- 
- See `http://dev.mysql.com/doc/en/delete.html <http://dev.mysql.com/doc/en/delete.html>`_ for details.  As stated in the
- documentation, in some cases it may be faster to use DELETE QUICK followed by
- OPTIMIZE TABLE.  You can use "--optimize" for this.
- 
-
-
---quiet
- 
- short form: -q
- 
- Do not print any output, such as for "--statistics".
- 
- Suppresses normal output, including the output of "--statistics", but doesn't
- suppress the output from "--why-quit".
- 
-
-
---replace
- 
- Causes INSERTs into "--dest" to be written as REPLACE.
- 
-
-
---retries
- 
- type: int; default: 1
- 
- Number of retries per timeout or deadlock.
- 
- Specifies the number of times pt-archiver should retry when there is an
- InnoDB lock wait timeout or deadlock.  When retries are exhausted,
- pt-archiver will exit with an error.
- 
- Consider carefully what you want to happen when you are archiving between a
- mixture of transactional and non-transactional storage engines.  The INSERT to
- "--dest" and DELETE from "--source" are on separate connections, so they
- do not actually participate in the same transaction even if they're on the same
- server.  However, pt-archiver implements simple distributed transactions in
- code, so commits and rollbacks should happen as desired across the two
- connections.
- 
- At this time I have not written any code to handle errors with transactional
- storage engines other than InnoDB.  Request that feature if you need it.
- 
-
-
---run-time
- 
- type: time
- 
- Time to run before exiting.
- 
- Optional suffix s=seconds, m=minutes, h=hours, d=days; if no suffix, s is used.
- 
-
-
---[no]safe-auto-increment
- 
- default: yes
- 
- Do not archive row with max AUTO_INCREMENT.
- 
- Adds an extra WHERE clause to prevent pt-archiver from removing the newest
- row when ascending a single-column AUTO_INCREMENT key.  This guards against
- re-using AUTO_INCREMENT values if the server restarts, and is enabled by
- default.
- 
- The extra WHERE clause contains the maximum value of the auto-increment column
- as of the beginning of the archive or purge job.  If new rows are inserted while
- pt-archiver is running, it will not see them.
- 
-
-
---sentinel
- 
- type: string; default: /tmp/pt-archiver-sentinel
- 
- Exit if this file exists.
- 
- The presence of the file specified by "--sentinel" will cause pt-archiver to
- stop archiving and exit.  The default is /tmp/pt-archiver-sentinel.  You
- might find this handy to stop cron jobs gracefully if necessary.  See also
- "--stop".
- 
-
-
---set-vars
- 
- type: string; default: wait_timeout=10000
- 
- Set these MySQL variables.
- 
- Specify any variables you want to be set immediately after connecting to MySQL.
- These will be included in a \ ``SET``\  command.
- 
-
-
---share-lock
- 
- Adds the LOCK IN SHARE MODE modifier to SELECT statements.
- 
- See `http://dev.mysql.com/doc/en/innodb-locking-reads.html <http://dev.mysql.com/doc/en/innodb-locking-reads.html>`_.
- 
-
-
---skip-foreign-key-checks
- 
- Disables foreign key checks with SET FOREIGN_KEY_CHECKS=0.
- 
-
-
---sleep
- 
- type: int
- 
- Sleep time between fetches.
- 
- Specifies how long to sleep between SELECT statements.  Default is not to
- sleep at all.  Transactions are NOT committed, and the "--file" file is NOT
- flushed, before sleeping.  See "--txn-size" to control that.
- 
- If "--commit-each" is specified, committing and flushing happens before
- sleeping.
- 
-
-
---sleep-coef
- 
- type: float
- 
- Calculate "--sleep" as a multiple of the last SELECT time.
- 
- If this option is specified, pt-archiver will sleep for the query time of the
- last SELECT multiplied by the specified coefficient.
- 
- This is a slightly more sophisticated way to throttle the SELECTs: sleep a
- varying amount of time between each SELECT, depending on how long the SELECTs
- are taking.
- 
-
-
---socket
- 
- short form: -S; type: string
- 
- Socket file to use for connection.
- 
-
-
---source
- 
- type: DSN
- 
- DSN specifying the table to archive from (required).  This argument is a DSN.
- See DSN OPTIONS for the syntax.  Most options control how pt-archiver
- connects to MySQL, but there are some extended DSN options in this tool's
- syntax.  The D, t, and i options select a table to archive:
- 
- 
- .. code-block:: perl
- 
-    --source h=my_server,D=my_database,t=my_tbl
- 
- 
- The a option specifies the database to set as the connection's default with USE.
- If the b option is true, it disables binary logging with SQL_LOG_BIN.  The m
- option specifies pluggable actions, which an external Perl module can provide.
- The only required part is the table; other parts may be read from various
- places in the environment (such as options files).
- 
- The 'i' part deserves special mention.  This tells pt-archiver which index
- it should scan to archive.  This appears in a FORCE INDEX or USE INDEX hint in
- the SELECT statements used to fetch archivable rows.  If you don't specify
- anything, pt-archiver will auto-discover a good index, preferring a \ ``PRIMARY
- KEY``\  if one exists.  In my experience this usually works well, so most of the
- time you can probably just omit the 'i' part.
- 
- The index is used to optimize repeated accesses to the table; pt-archiver
- remembers the last row it retrieves from each SELECT statement, and uses it to
- construct a WHERE clause, using the columns in the specified index, that should
- allow MySQL to start the next SELECT where the last one ended, rather than
- potentially scanning from the beginning of the table with each successive
- SELECT.  If you are using external plugins, please see "EXTENDING" for a
- discussion of how they interact with ascending indexes.
- 
- The 'a' and 'b' options allow you to control how statements flow through the
- binary log.  If you specify the 'b' option, binary logging will be disabled on
- the specified connection.  If you specify the 'a' option, the connection will
- \ ``USE``\  the specified database, which you can use to prevent slaves from
- executing the binary log events with \ ``--replicate-ignore-db``\  options.  These
- two options can be used as different methods to achieve the same goal: archive
- data off the master, but leave it on the slave.  For example, you can run a
- purge job on the master and prevent it from happening on the slave using your
- method of choice.
- 
- \ **WARNING**\ : Using a default options file (F) DSN option that defines a
- socket for "--source" causes pt-archiver to connect to "--dest" using
- that socket unless another socket for "--dest" is specified.  This
- means that pt-archiver may incorrectly connect to "--source" when it
- is meant to connect to "--dest".  For example:
- 
- 
- .. code-block:: perl
- 
-    --source F=host1.cnf,D=db,t=tbl --dest h=host2
- 
- 
- When pt-archiver connects to "--dest", host2, it will connect via the
- "--source", host1, socket defined in host1.cnf.
- 
-
-
---statistics
- 
- Collect and print timing statistics.
- 
- Causes pt-archiver to collect timing statistics about what it does.  These
- statistics are available to the plugin specified by "--plugin"
- 
- Unless you specify "--quiet", \ ``pt-archiver``\  prints the statistics when it
- exits.  The statistics look like this:
- 
- 
- .. code-block:: perl
- 
-   Started at 2008-07-18T07:18:53, ended at 2008-07-18T07:18:53
-   Source: D=db,t=table
-   SELECT 4
-   INSERT 4
-   DELETE 4
-   Action         Count       Time        Pct
-   commit            10     0.1079      88.27
-   select             5     0.0047       3.87
-   deleting           4     0.0028       2.29
-   inserting          4     0.0028       2.28
-   other              0     0.0040       3.29
- 
- 
- The first two (or three) lines show times and the source and destination tables.
- The next three lines show how many rows were fetched, inserted, and deleted.
- 
- The remaining lines show counts and timing.  The columns are the action, the
- total number of times that action was timed, the total time it took, and the
- percent of the program's total runtime.  The rows are sorted in order of
- descending total time.  The last row is the rest of the time not explicitly
- attributed to anything.  Actions will vary depending on command-line options.
- 
- If "--why-quit" is given, its behavior is changed slightly.  This option
- causes it to print the reason for exiting even when it's just because there are
- no more rows.
- 
- This option requires the standard Time::HiRes module, which is part of core Perl
- on reasonably new Perl releases.
- 
-
-
---stop
- 
- Stop running instances by creating the sentinel file.
- 
- Causes pt-archiver to create the sentinel file specified by "--sentinel" and
- exit.  This should have the effect of stopping all running instances which are
- watching the same sentinel file.
- 
-
-
---txn-size
- 
- type: int; default: 1
- 
- Number of rows per transaction.
- 
- Specifies the size, in number of rows, of each transaction. Zero disables
- transactions altogether.  After pt-archiver processes this many rows, it
- commits both the "--source" and the "--dest" if given, and flushes the
- file given by "--file".
- 
- This parameter is critical to performance.  If you are archiving from a live
- server, which for example is doing heavy OLTP work, you need to choose a good
- balance between transaction size and commit overhead.  Larger transactions
- create the possibility of more lock contention and deadlocks, but smaller
- transactions cause more frequent commit overhead, which can be significant.  To
- give an idea, on a small test set I worked with while writing pt-archiver, a
- value of 500 caused archiving to take about 2 seconds per 1000 rows on an
- otherwise quiet MySQL instance on my desktop machine, archiving to disk and to
- another table.  Disabling transactions with a value of zero, which turns on
- autocommit, dropped performance to 38 seconds per thousand rows.
- 
- If you are not archiving from or to a transactional storage engine, you may
- want to disable transactions so pt-archiver doesn't try to commit.
- 
-
-
---user
- 
- short form: -u; type: string
- 
- User for login if not current user.
- 
-
-
---version
- 
- Show version and exit.
- 
-
-
---where
- 
- type: string
- 
- WHERE clause to limit which rows to archive (required).
- 
- Specifies a WHERE clause to limit which rows are archived.  Do not include the
- word WHERE.  You may need to quote the argument to prevent your shell from
- interpreting it.  For example:
- 
- 
- .. code-block:: perl
- 
-     --where 'ts < current_date - interval 90 day'
- 
- 
- For safety, "--where" is required.  If you do not require a WHERE clause, use
- "--where" 1=1.
- 
-
-
---why-quit
- 
- Print reason for exiting unless rows exhausted.
- 
- Causes pt-archiver to print a message if it exits for any reason other than
- running out of rows to archive.  This can be useful if you have a cron job with
- "--run-time" specified, for example, and you want to be sure pt-archiver is
- finishing before running out of time.
- 
- If "--statistics" is given, the behavior is changed slightly.  It will print
- the reason for exiting even when it's just because there are no more rows.
- 
- This output prints even if "--quiet" is given.  That's so you can put
- \ ``pt-archiver``\  in a \ ``cron``\  job and get an email if there's an abnormal exit.
- 
-
-
-
-***********
-DSN OPTIONS
-***********
-
-
-These DSN options are used to create a DSN.  Each option is given like
-\ ``option=value``\ .  The options are case-sensitive, so P and p are not the
-same option.  There cannot be whitespace before or after the \ ``=``\  and
-if the value contains whitespace it must be quoted.  DSN options are
-comma-separated.  See the percona-toolkit manpage for full details.
-
-
-\* a
- 
- copy: no
- 
- Database to USE when executing queries.
- 
-
-
-\* A
- 
- dsn: charset; copy: yes
- 
- Default character set.
- 
-
-
-\* b
- 
- copy: no
- 
- If true, disable binlog with SQL_LOG_BIN.
- 
-
-
-\* D
- 
- dsn: database; copy: yes
- 
- Database that contains the table.
- 
-
-
-\* F
- 
- dsn: mysql_read_default_file; copy: yes
- 
- Only read default options from the given file
- 
-
-
-\* h
- 
- dsn: host; copy: yes
- 
- Connect to host.
- 
-
-
-\* i
- 
- copy: yes
- 
- Index to use.
- 
-
-
-\* m
- 
- copy: no
- 
- Plugin module name.
- 
-
-
-\* p
- 
- dsn: password; copy: yes
- 
- Password to use when connecting.
- 
-
-
-\* P
- 
- dsn: port; copy: yes
- 
- Port number to use for connection.
- 
-
-
-\* S
- 
- dsn: mysql_socket; copy: yes
- 
- Socket file to use for connection.
- 
-
-
-\* t
- 
- copy: yes
- 
- Table to archive from/to.
- 
-
-
-\* u
- 
- dsn: user; copy: yes
- 
- User for login if not current user.
- 
-
-
-
-*********
-EXTENDING
-*********
-
-
-pt-archiver is extensible by plugging in external Perl modules to handle some
-logic and/or actions.  You can specify a module for both the "--source" and
-the "--dest", with the 'm' part of the specification.  For example:
-
-
-.. code-block:: perl
-
-    --source D=test,t=test1,m=My::Module1 --dest m=My::Module2,t=test2
-
-
-This will cause pt-archiver to load the My::Module1 and My::Module2 packages,
-create instances of them, and then make calls to them during the archiving
-process.
-
-You can also specify a plugin with "--plugin".
-
-The module must provide this interface:
-
-
-new(dbh => $dbh, db => $db_name, tbl => $tbl_name)
- 
- The plugin's constructor is passed a reference to the database handle, the
- database name, and table name.  The plugin is created just after pt-archiver
- opens the connection, and before it examines the table given in the arguments.
- This gives the plugin a chance to create and populate temporary tables, or do
- other setup work.
- 
-
-
-before_begin(cols => \@cols, allcols => \@allcols)
- 
- This method is called just before pt-archiver begins iterating through rows
- and archiving them, but after it does all other setup work (examining table
- structures, designing SQL queries, and so on).  This is the only time
- pt-archiver tells the plugin column names for the rows it will pass the
- plugin while archiving.
- 
- The \ ``cols``\  argument is the column names the user requested to be archived,
- either by default or by the "--columns" option.  The \ ``allcols``\  argument is
- the list of column names for every row pt-archiver will fetch from the source
- table.  It may fetch more columns than the user requested, because it needs some
- columns for its own use.  When subsequent plugin functions receive a row, it is
- the full row containing all the extra columns, if any, added to the end.
- 
-
-
-is_archivable(row => \@row)
- 
- This method is called for each row to determine whether it is archivable.  This
- applies only to "--source".  The argument is the row itself, as an arrayref.
- If the method returns true, the row will be archived; otherwise it will be
- skipped.
- 
- Skipping a row adds complications for non-unique indexes.  Normally
- pt-archiver uses a WHERE clause designed to target the last processed row as
- the place to start the scan for the next SELECT statement.  If you have skipped
- the row by returning false from is_archivable(), pt-archiver could get into
- an infinite loop because the row still exists.  Therefore, when you specify a
- plugin for the "--source" argument, pt-archiver will change its WHERE clause
- slightly.  Instead of starting at "greater than or equal to" the last processed
- row, it will start "strictly greater than."  This will work fine on unique
- indexes such as primary keys, but it may skip rows (leave holes) on non-unique
- indexes or when ascending only the first column of an index.
- 
- \ ``pt-archiver``\  will change the clause in the same way if you specify
- "--no-delete", because again an infinite loop is possible.
- 
- If you specify the "--bulk-delete" option and return false from this method,
- \ ``pt-archiver``\  may not do what you want.  The row won't be archived, but it will
- be deleted, since bulk deletes operate on ranges of rows and don't know which
- rows the plugin selected to keep.
- 
- If you specify the "--bulk-insert" option, this method's return value will
- influence whether the row is written to the temporary file for the bulk insert,
- so bulk inserts will work as expected.  However, bulk inserts require bulk
- deletes.
- 
-
-
-before_delete(row => \@row)
- 
- This method is called for each row just before it is deleted.  This applies only
- to "--source".  This is a good place for you to handle dependencies, such as
- deleting things that are foreign-keyed to the row you are about to delete.  You
- could also use this to recursively archive all dependent tables.
- 
- This plugin method is called even if "--no-delete" is given, but not if
- "--bulk-delete" is given.
- 
-
-
-before_bulk_delete(first_row => \@row, last_row => \@row)
- 
- This method is called just before a bulk delete is executed.  It is similar to
- the \ ``before_delete``\  method, except its arguments are the first and last row of
- the range to be deleted.  It is called even if "--no-delete" is given.
- 
-
-
-before_insert(row => \@row)
- 
- This method is called for each row just before it is inserted.  This applies
- only to "--dest".  You could use this to insert the row into multiple tables,
- perhaps with an ON DUPLICATE KEY UPDATE clause to build summary tables in a data
- warehouse.
- 
- This method is not called if "--bulk-insert" is given.
- 
-
-
-before_bulk_insert(first_row => \@row, last_row => \@row, filename => bulk_insert_filename)
- 
- This method is called just before a bulk insert is executed.  It is similar to
- the \ ``before_insert``\  method, except its arguments are the first and last row of
- the range to be deleted.
- 
-
-
-custom_sth(row => \@row, sql => $sql)
- 
- This method is called just before inserting the row, but after
- "before_insert()".  It allows the plugin to specify different \ ``INSERT``\ 
- statement if desired.  The return value (if any) should be a DBI statement
- handle.  The \ ``sql``\  parameter is the SQL text used to prepare the default
- \ ``INSERT``\  statement.  This method is not called if you specify
- "--bulk-insert".
- 
- If no value is returned, the default \ ``INSERT``\  statement handle is used.
- 
- This method applies only to the plugin specified for "--dest", so if your
- plugin isn't doing what you expect, check that you've specified it for the
- destination and not the source.
- 
-
-
-custom_sth_bulk(first_row => \@row, last_row => \@row, sql => $sql, filename => $bulk_insert_filename)
- 
- If you've specified "--bulk-insert", this method is called just before the
- bulk insert, but after "before_bulk_insert()", and the arguments are
- different.
- 
- This method's return value etc is similar to the "custom_sth()" method.
- 
-
-
-after_finish()
- 
- This method is called after pt-archiver exits the archiving loop, commits all
- database handles, closes "--file", and prints the final statistics, but
- before pt-archiver runs ANALYZE or OPTIMIZE (see "--analyze" and
- "--optimize").
- 
-
-
-If you specify a plugin for both "--source" and "--dest", pt-archiver
-constructs, calls before_begin(), and calls after_finish() on the two plugins in
-the order "--source", "--dest".
-
-pt-archiver assumes it controls transactions, and that the plugin will NOT
-commit or roll back the database handle.  The database handle passed to the
-plugin's constructor is the same handle pt-archiver uses itself.  Remember
-that "--source" and "--dest" are separate handles.
-
-A sample module might look like this:
-
-
-.. code-block:: perl
-
-    package My::Module;
- 
-    sub new {
-       my ( $class, %args ) = @_;
-       return bless(\%args, $class);
-    }
- 
-    sub before_begin {
-       my ( $self, %args ) = @_;
-       # Save column names for later
-       $self->{cols} = $args{cols};
-    }
- 
-    sub is_archivable {
-       my ( $self, %args ) = @_;
-       # Do some advanced logic with $args{row}
-       return 1;
-    }
- 
-    sub before_delete {} # Take no action
-    sub before_insert {} # Take no action
-    sub custom_sth    {} # Take no action
-    sub after_finish  {} # Take no action
- 
-    1;
-
-
-
-***********
-ENVIRONMENT
-***********
-
-
-The environment variable \ ``PTDEBUG``\  enables verbose debugging output to STDERR.
-To enable debugging and capture all output to a file, run the tool like:
-
-
-.. code-block:: perl
-
-    PTDEBUG=1 pt-archiver ... > FILE 2>&1
-
-
-Be careful: debugging output is voluminous and can generate several megabytes
-of output.
-
-
-*******************
-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
-****
-
-
-For a list of known bugs, see `http://www.percona.com/bugs/pt-archiver <http://www.percona.com/bugs/pt-archiver>`_.
-
-Please report bugs at `https://bugs.launchpad.net/percona-toolkit <https://bugs.launchpad.net/percona-toolkit>`_.
-Include the following information in your bug report:
-
-
-\* Complete command-line used to run the tool
-
-
-
-\* Tool "--version"
-
-
-
-\* MySQL version of all servers involved
-
-
-
-\* Output from the tool including STDERR
-
-
-
-\* Input files (log/dump/config files, etc.)
-
-
-
-If possible, include debugging output by running the tool with \ ``PTDEBUG``\ ;
-see "ENVIRONMENT".
-
-
-***********
-DOWNLOADING
-***********
-
-
-Visit `http://www.percona.com/software/percona-toolkit/ <http://www.percona.com/software/percona-toolkit/>`_ to download the
-latest release of Percona Toolkit.  Or, get the latest release from the
-command line:
-
-
-.. code-block:: perl
-
-    wget percona.com/get/percona-toolkit.tar.gz
- 
-    wget percona.com/get/percona-toolkit.rpm
- 
-    wget percona.com/get/percona-toolkit.deb
-
-
-You can also get individual tools from the latest release:
-
-
-.. code-block:: perl
-
-    wget percona.com/get/TOOL
-
-
-Replace \ ``TOOL``\  with the name of any tool.
-
-
-*******
-AUTHORS
-*******
-
-
-Baron Schwartz
-
-
-***************
-ACKNOWLEDGMENTS
-***************
-
-
-Andrew O'Brien
-
-
-*********************
-ABOUT PERCONA TOOLKIT
-*********************
-
-
-This tool is part of Percona Toolkit, a collection of advanced command-line
-tools developed by Percona for MySQL support and consulting.  Percona Toolkit
-was forked from two projects in June, 2011: Maatkit and Aspersa.  Those
-projects were created by Baron Schwartz and developed primarily by him and
-Daniel Nichter, both of whom are employed by Percona.  Visit
-`http://www.percona.com/software/ <http://www.percona.com/software/>`_ for more software developed by Percona.
-
-
-********************************
-COPYRIGHT, LICENSE, AND WARRANTY
-********************************
-
-
-This program is copyright 2007-2011 Baron Schwartz, 2011 Percona Inc.
-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
-MERCHANTABILITY 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.
-
-
-*******
-VERSION
-*******
-
-
-pt-archiver 1.0.1
-

=== removed file 'docs/user/pt-collect.rst'
--- docs/user/pt-collect.rst	2011-09-01 16:00:38 +0000
+++ docs/user/pt-collect.rst	1970-01-01 00:00:00 +0000
@@ -1,264 +0,0 @@
-
-##########
-pt-collect
-##########
-
-.. highlight:: perl
-
-
-****
-NAME
-****
-
-
-pt-collect - Collect information from a server for some period of time.
-
-
-********
-SYNOPSIS
-********
-
-
-Usage: pt-collect -d -g -i -o -s [OPTIONS] [-- MYSQL-OPTIONS]
-
-pt-collect tool gathers a variety of information about a system for a period
-of time.  It is typically executed when the stalk tool detects a condition
-and wants to collect information to assist in diagnosis.  Four options
-must be specified on the command line: -dgios.
-
-
-*****
-RISKS
-*****
-
-
-The following section is included to inform users about the potential risks,
-whether known or unknown, of using this tool.  The two main categories of risks
-are those created by the nature of the tool (e.g. read-only tools vs. read-write
-tools) and those created by bugs.
-
-pt-collect is a read-only tool.  It should be very low-risk.
-
-At the time of this release, we know of no bugs that could cause serious harm
-to users.
-
-The authoritative source for updated information is always the online issue
-tracking system.  Issues that affect this tool will be marked as such.  You can
-see a list of such issues at the following URL:
-`http://www.percona.com/bugs/pt-collect <http://www.percona.com/bugs/pt-collect>`_.
-
-See also "BUGS" for more information on filing bugs and getting help.
-
-
-***********
-DESCRIPTION
-***********
-
-
-pt-collect creates a lock to ensure that only one instance runs at a time,
-and then saves a variety of performance and status data into files in the
-configured directory.  Files are named with a timestamp so they can be
-grouped together.  The tool is MySQL-centric by default, and gathers quite
-a bit of diagnostic data that's useful for understanding the behavior of
-a MySQL database server.
-
-Options after \ ``--``\  are passed to \ ``mysql``\  and \ ``mysqladmin``\ .
-
-
-*******
-OPTIONS
-*******
-
-
-
--d (required)
- 
- DESTINATION Where to store the resulting data; must already exist.
- 
-
-
--g <yes/no> (required)
- 
- Collect GDB stack traces.
- 
-
-
--i INTERVAL (required)
- 
- How many seconds to collect data.
- 
-
-
--o <yes/no> (required)
- 
- Collect oprofile data; disables -s.
- 
-
-
--s <yes/no> (required)
- 
- Collect strace data.
- 
-
-
--f PERCENT
- 
- Exit if the disk is more than this percent full (default 100).
- 
-
-
--m MEGABYTES
- 
- Exit if there are less than this many megabytes free disk space (default 0).
- 
-
-
--p PREFIX
- 
- Store the data into files with this prefix (optional).
- 
-
-
--t <yes/no>
- 
- Collect tcpdump data.
- 
-
-
-
-***********
-ENVIRONMENT
-***********
-
-
-This tool does not use any environment variables.
-
-
-*******************
-SYSTEM REQUIREMENTS
-*******************
-
-
-This tool requires Bash v3 or newer and assumes that these programs
-are installed, in the PATH, and executable: sysctl, top, vmstat, iostat,
-mpstat, lsof, mysql, mysqladmin, df, netstat, pidof, flock, and others
-depending on what command-line options are specified.  If some of those
-programs are not available, the tool will still run but may print warnings.
-
-
-****
-BUGS
-****
-
-
-For a list of known bugs, see `http://www.percona.com/bugs/pt-collect <http://www.percona.com/bugs/pt-collect>`_.
-
-Please report bugs at `https://bugs.launchpad.net/percona-toolkit <https://bugs.launchpad.net/percona-toolkit>`_.
-Include the following information in your bug report:
-
-
-\* Complete command-line used to run the tool
-
-
-
-\* Tool "--version"
-
-
-
-\* MySQL version of all servers involved
-
-
-
-\* Output from the tool including STDERR
-
-
-
-\* Input files (log/dump/config files, etc.)
-
-
-
-If possible, include debugging output by running the tool with \ ``PTDEBUG``\ ;
-see "ENVIRONMENT".
-
-
-***********
-DOWNLOADING
-***********
-
-
-Visit `http://www.percona.com/software/percona-toolkit/ <http://www.percona.com/software/percona-toolkit/>`_ to download the
-latest release of Percona Toolkit.  Or, get the latest release from the
-command line:
-
-
-.. code-block:: perl
-
-    wget percona.com/get/percona-toolkit.tar.gz
- 
-    wget percona.com/get/percona-toolkit.rpm
- 
-    wget percona.com/get/percona-toolkit.deb
-
-
-You can also get individual tools from the latest release:
-
-
-.. code-block:: perl
-
-    wget percona.com/get/TOOL
-
-
-Replace \ ``TOOL``\  with the name of any tool.
-
-
-*******
-AUTHORS
-*******
-
-
-Baron Schwartz
-
-
-*********************
-ABOUT PERCONA TOOLKIT
-*********************
-
-
-This tool is part of Percona Toolkit, a collection of advanced command-line
-tools developed by Percona for MySQL support and consulting.  Percona Toolkit
-was forked from two projects in June, 2011: Maatkit and Aspersa.  Those
-projects were created by Baron Schwartz and developed primarily by him and
-Daniel Nichter, both of whom are employed by Percona.  Visit
-`http://www.percona.com/software/ <http://www.percona.com/software/>`_ for more software developed by Percona.
-
-
-********************************
-COPYRIGHT, LICENSE, AND WARRANTY
-********************************
-
-
-This program is copyright 2010-2011 Baron Schwartz, 2011 Percona Inc.
-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
-MERCHANTABILITY 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.
-
-
-*******
-VERSION
-*******
-
-
-pt-collect 1.0.1
-

=== removed file 'docs/user/pt-config-diff.rst'
--- docs/user/pt-config-diff.rst	2011-09-01 16:00:38 +0000
+++ docs/user/pt-config-diff.rst	1970-01-01 00:00:00 +0000
@@ -1,518 +0,0 @@
-
-##############
-pt-config-diff
-##############
-
-.. highlight:: perl
-
-
-****
-NAME
-****
-
-
-pt-config-diff - Diff MySQL configuration files and server variables.
-
-
-********
-SYNOPSIS
-********
-
-
-Usage: pt-config-diff [OPTION...] CONFIG CONFIG [CONFIG...]
-
-pt-config-diff diffs MySQL configuration files and server variables.
-CONFIG can be a filename or a DSN.  At least two CONFIG sources must be given.
-Like standard Unix diff, there is no output if there are no differences.
-
-Diff host1 config from SHOW VARIABLES against host2:
-
-
-.. code-block:: perl
-
-   pt-config-diff h=host1 h=host2
-
-
-Diff config from [mysqld] section in my.cnf against host1 config:
-
-
-.. code-block:: perl
-
-   pt-config-diff /etc/my.cnf h=host1
-
-
-Diff the [mysqld] section of two option files:
-
-
-.. code-block:: perl
-
-    pt-config-diff /etc/my-small.cnf /etc/my-large.cnf
-
-
-
-*****
-RISKS
-*****
-
-
-The following section is included to inform users about the potential risks,
-whether known or unknown, of using this tool.  The two main categories of risks
-are those created by the nature of the tool (e.g. read-only tools vs. read-write
-tools) and those created by bugs.
-
-pt-config-diff reads MySQL's configuration and examines it and is thus very
-low risk.
-
-At the time of this release there are no known bugs that pose a serious risk.
-
-The authoritative source for updated information is always the online issue
-tracking system.  Issues that affect this tool will be marked as such.  You can
-see a list of such issues at the following URL:
-`http://www.percona.com/bugs/pt-config-diff <http://www.percona.com/bugs/pt-config-diff>`_.
-
-See also "BUGS" for more information on filing bugs and getting help.
-
-
-***********
-DESCRIPTION
-***********
-
-
-pt-config-diff diffs MySQL configurations by examining the values of server
-system variables from two or more CONFIG sources specified on the command
-line.  A CONFIG source can be a DSN or a filename containing the output of
-\ ``mysqld --help --verbose``\ , \ ``my_print_defaults``\ , \ ``SHOW VARIABLES``\ , or
-an option file (e.g. my.cnf).
-
-For each DSN CONFIG, pt-config-diff connects to MySQL and gets variables
-and values by executing \ ``SHOW /\*!40103 GLOBAL\*/ VARIABLES``\ .  This is
-an "active config" because it shows what server values MySQL is
-actively (currently) running with.
-
-Only variables that all CONFIG sources have are compared because if a
-variable is not present then we cannot know or safely guess its value.
-For example, if you compare an option file (e.g. my.cnf) to an active config
-(i.e. SHOW VARIABLES from a DSN CONFIG), the option file will probably
-only have a few variables, whereas the active config has every variable.
-Only values of the variables present in both configs are compared.
-
-Option file and DSN configs provide the best results.
-
-
-******
-OUTPUT
-******
-
-
-There is no output when there are no differences.  When there are differences,
-pt-config-diff prints a report to STDOUT that looks similar to the following:
-
-
-.. code-block:: perl
-
-   2 config differences
-   Variable                  my.master.cnf   my.slave.cnf
-   ========================= =============== ===============
-   datadir                   /tmp/12345/data /tmp/12346/data
-   port                      12345           12346
-
-
-Comparing MySQL variables is difficult because there are many variations and
-subtleties across the many versions and distributions of MySQL.  When a
-comparison fails, the tool prints a warning to STDERR, such as the following:
-
-
-.. code-block:: perl
-
-   Comparing log_error values (mysqld.log, /tmp/12345/data/mysqld.log)
-   caused an error: Argument "/tmp/12345/data/mysqld.log" isn't numeric
-   in numeric eq (==) at ./pt-config-diff line 2311.
-
-
-Please report these warnings so the comparison functions can be improved.
-
-
-***********
-EXIT STATUS
-***********
-
-
-pt-config-diff exits with a zero exit status when there are no differences, and
-1 if there are.
-
-
-*******
-OPTIONS
-*******
-
-
-This tool accepts additional command-line arguments.  Refer to the
-"SYNOPSIS" and usage information for details.
-
-
---ask-pass
- 
- Prompt for a password when connecting to MySQL.
- 
-
-
---charset
- 
- short form: -A; type: string
- 
- Default character set.  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.
- 
-
-
---config
- 
- type: Array
- 
- Read this comma-separated list of config files; if specified, this must be the
- first option on the command line.  (This option does not specify a CONFIG;
- it's equivalent to \ ``--defaults-file``\ .)
- 
-
-
---daemonize
- 
- Fork to the background and detach from the shell.  POSIX
- operating systems only.
- 
-
-
---defaults-file
- 
- short form: -F; type: string
- 
- Only read mysql options from the given file.  You must give an absolute
- pathname.
- 
-
-
---help
- 
- Show help and exit.
- 
-
-
---host
- 
- short form: -h; type: string
- 
- Connect to host.
- 
-
-
---ignore-variables
- 
- type: array
- 
- Ignore, do not compare, these variables.
- 
-
-
---password
- 
- short form: -p; type: string
- 
- Password to use for connection.
- 
-
-
---pid
- 
- type: string
- 
- Create the given PID file when daemonized.  The file contains the process
- ID of the daemonized instance.  The PID file is removed when the
- daemonized instance exits.  The program checks for the existence of the
- PID file when starting; if it exists and the process with the matching PID
- exists, the program exits.
- 
-
-
---port
- 
- short form: -P; type: int
- 
- Port number to use for connection.
- 
-
-
---[no]report
- 
- default: yes
- 
- Print the MySQL config diff report to STDOUT.  If you just want to check
- if the given configs are different or not by examining the tool's exit
- status, then specify \ ``--no-report``\  to suppress the report.
- 
-
-
---report-width
- 
- type: int; default: 78
- 
- Truncate report lines to this many characters.  Since some variable values can
- be long, or when comparing multiple configs, it may help to increase the
- report width so values are not truncated beyond readability.
- 
-
-
---set-vars
- 
- type: string; default: wait_timeout=10000
- 
- Set these MySQL variables.  Immediately after connecting to MySQL, this string
- will be appended to SET and executed.
- 
-
-
---socket
- 
- short form: -S; type: string
- 
- Socket file to use for connection.
- 
-
-
---user
- 
- short form: -u; type: string
- 
- MySQL user if not current user.
- 
-
-
---version
- 
- Show version and exit.
- 
-
-
-
-***********
-DSN OPTIONS
-***********
-
-
-These DSN options are used to create a DSN.  Each option is given like
-\ ``option=value``\ .  The options are case-sensitive, so P and p are not the
-same option.  There cannot be whitespace before or after the \ ``=``\  and
-if the value contains whitespace it must be quoted.  DSN options are
-comma-separated.  See the percona-toolkit manpage for full details.
-
-
-\* A
- 
- dsn: charset; copy: yes
- 
- Default character set.
- 
-
-
-\* D
- 
- dsn: database; copy: yes
- 
- Default database.
- 
-
-
-\* F
- 
- dsn: mysql_read_default_file; copy: yes
- 
- Only read default options from the given file
- 
-
-
-\* h
- 
- dsn: host; copy: yes
- 
- Connect to host.
- 
-
-
-\* p
- 
- dsn: password; copy: yes
- 
- Password to use when connecting.
- 
-
-
-\* P
- 
- dsn: port; copy: yes
- 
- Port number to use for connection.
- 
-
-
-\* S
- 
- dsn: mysql_socket; copy: yes
- 
- Socket file to use for connection.
- 
-
-
-\* u
- 
- dsn: user; copy: yes
- 
- User for login if not current user.
- 
-
-
-
-***********
-ENVIRONMENT
-***********
-
-
-The environment variable \ ``PTDEBUG``\  enables verbose debugging output to STDERR.
-To enable debugging and capture all output to a file, run the tool like:
-
-
-.. code-block:: perl
-
-    PTDEBUG=1 pt-config-diff ... > FILE 2>&1
-
-
-Be careful: debugging output is voluminous and can generate several megabytes
-of output.
-
-
-*******************
-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
-****
-
-
-For a list of known bugs, see `http://www.percona.com/bugs/pt-config-diff <http://www.percona.com/bugs/pt-config-diff>`_.
-
-Please report bugs at `https://bugs.launchpad.net/percona-toolkit <https://bugs.launchpad.net/percona-toolkit>`_.
-Include the following information in your bug report:
-
-
-\* Complete command-line used to run the tool
-
-
-
-\* Tool "--version"
-
-
-
-\* MySQL version of all servers involved
-
-
-
-\* Output from the tool including STDERR
-
-
-
-\* Input files (log/dump/config files, etc.)
-
-
-
-If possible, include debugging output by running the tool with \ ``PTDEBUG``\ ;
-see "ENVIRONMENT".
-
-
-***********
-DOWNLOADING
-***********
-
-
-Visit `http://www.percona.com/software/percona-toolkit/ <http://www.percona.com/software/percona-toolkit/>`_ to download the
-latest release of Percona Toolkit.  Or, get the latest release from the
-command line:
-
-
-.. code-block:: perl
-
-    wget percona.com/get/percona-toolkit.tar.gz
- 
-    wget percona.com/get/percona-toolkit.rpm
- 
-    wget percona.com/get/percona-toolkit.deb
-
-
-You can also get individual tools from the latest release:
-
-
-.. code-block:: perl
-
-    wget percona.com/get/TOOL
-
-
-Replace \ ``TOOL``\  with the name of any tool.
-
-
-*******
-AUTHORS
-*******
-
-
-Baron Schwartz and Daniel Nichter
-
-
-*********************
-ABOUT PERCONA TOOLKIT
-*********************
-
-
-This tool is part of Percona Toolkit, a collection of advanced command-line
-tools developed by Percona for MySQL support and consulting.  Percona Toolkit
-was forked from two projects in June, 2011: Maatkit and Aspersa.  Those
-projects were created by Baron Schwartz and developed primarily by him and
-Daniel Nichter, both of whom are employed by Percona.  Visit
-`http://www.percona.com/software/ <http://www.percona.com/software/>`_ for more software developed by Percona.
-
-
-********************************
-COPYRIGHT, LICENSE, AND WARRANTY
-********************************
-
-
-This program is copyright 2011 Percona Inc.
-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
-MERCHANTABILITY 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.
-
-
-*******
-VERSION
-*******
-
-
-pt-config-diff 1.0.1
-

=== removed file 'docs/user/pt-deadlock-logger.rst'
--- docs/user/pt-deadlock-logger.rst	2011-09-01 16:00:38 +0000
+++ docs/user/pt-deadlock-logger.rst	1970-01-01 00:00:00 +0000
@@ -1,760 +0,0 @@
-
-##################
-pt-deadlock-logger
-##################
-
-.. highlight:: perl
-
-
-****
-NAME
-****
-
-
-pt-deadlock-logger - Extract and log MySQL deadlock information.
-
-
-********
-SYNOPSIS
-********
-
-
-Usage: pt-deadlock-logger [OPTION...] SOURCE_DSN
-
-pt-deadlock-logger extracts and saves information about the most recent deadlock
-in a MySQL server.
-
-Print deadlocks on SOURCE_DSN:
-
-
-.. code-block:: perl
-
-    pt-deadlock-logger SOURCE_DSN
-
-
-Store deadlock information from SOURCE_DSN in test.deadlocks table on SOURCE_DSN
-(source and destination are the same host):
-
-
-.. code-block:: perl
-
-    pt-deadlock-logger SOURCE_DSN --dest D=test,t=deadlocks
-
-
-Store deadlock information from SOURCE_DSN in test.deadlocks table on DEST_DSN
-(source and destination are different hosts):
-
-
-.. code-block:: perl
-
-    pt-deadlock-logger SOURCE_DSN --dest DEST_DSN,D=test,t=deadlocks
-
-
-Daemonize and check for deadlocks on SOURCE_DSN every 30 seconds for 4 hours:
-
-
-.. code-block:: perl
-
-    pt-deadlock-logger SOURCE_DSN --dest D=test,t=deadlocks --daemonize --run-time 4h --interval 30s
-
-
-
-*****
-RISKS
-*****
-
-
-The following section is included to inform users about the potential risks,
-whether known or unknown, of using this tool.  The two main categories of risks
-are those created by the nature of the tool (e.g. read-only tools vs. read-write
-tools) and those created by bugs.
-
-pt-deadlock-logger is a read-only tool unless you specify a "--dest" table.
-In some cases polling SHOW INNODB STATUS too rapidly can cause extra load on the
-server.  If you're using it on a production server under very heavy load, you
-might want to set "--interval" to 30 seconds or more.
-
-At the time of this release, we know of no bugs that could cause serious harm to
-users.
-
-The authoritative source for updated information is always the online issue
-tracking system.  Issues that affect this tool will be marked as such.  You can
-see a list of such issues at the following URL:
-`http://www.percona.com/bugs/pt-deadlock-logger <http://www.percona.com/bugs/pt-deadlock-logger>`_.
-
-See also "BUGS" for more information on filing bugs and getting help.
-
-
-***********
-DESCRIPTION
-***********
-
-
-pt-deadlock-logger extracts deadlock data from a MySQL server.  Currently only
-InnoDB deadlock information is available.  You can print the information to
-standard output, store it in a database table, or both.  If neither
-"--print" nor "--dest" are given, then the deadlock information is
-printed by default.  If only "--dest" is given, then the deadlock
-information is only stored.  If both options are given, then the deadlock
-information is printed and stored.
-
-The source host can be specified using one of two methods.  The first method is
-to use at least one of the standard connection-related command line options:
-"--defaults-file", "--password", "--host", "--port", "--socket"
-or "--user".  These options only apply to the source host; they cannot be
-used to specify the destination host.
-
-The second method to specify the source host, or the optional destination host
-using "--dest", is a DSN.  A DSN is a special syntax that can be either just
-a hostname (like \ ``server.domain.com``\  or \ ``1.2.3.4``\ ), or a
-\ ``key=value,key=value``\  string. Keys are a single letter:
-
-
-.. code-block:: perl
-
-   KEY MEANING
-   === =======
-   h   Connect to host
-   P   Port number to use for connection
-   S   Socket file to use for connection
-   u   User for login if not current user
-   p   Password to use when connecting
-   F   Only read default options from the given file
-
-
-If you omit any values from the destination host DSN, they are filled in with
-values from the source host, so you don't need to specify them in both places.
-\ ``pt-deadlock-logger``\  reads all normal MySQL option files, such as ~/.my.cnf, so
-you may not need to specify username, password and other common options at all.
-
-
-******
-OUTPUT
-******
-
-
-You can choose which columns are output and/or saved to "--dest" with the
-"--columns" argument.  The default columns are as follows:
-
-
-server
- 
- The (source) server on which the deadlock occurred.  This might be useful if
- you're tracking deadlocks on many servers.
- 
-
-
-ts
- 
- The date and time of the last detected deadlock.
- 
-
-
-thread
- 
- The MySQL thread number, which is the same as the connection ID in SHOW FULL
- PROCESSLIST.
- 
-
-
-txn_id
- 
- The InnoDB transaction ID, which InnoDB expresses as two unsigned integers.  I
- have multiplied them out to be one number.
- 
-
-
-txn_time
- 
- How long the transaction was active when the deadlock happened.
- 
-
-
-user
- 
- The connection's database username.
- 
-
-
-hostname
- 
- The connection's host.
- 
-
-
-ip
- 
- The connection's IP address.  If you specify "--numeric-ip", this is
- converted to an unsigned integer.
- 
-
-
-db
- 
- The database in which the deadlock occurred.
- 
-
-
-tbl
- 
- The table on which the deadlock occurred.
- 
-
-
-idx
- 
- The index on which the deadlock occurred.
- 
-
-
-lock_type
- 
- The lock type the transaction held on the lock that caused the deadlock.
- 
-
-
-lock_mode
- 
- The lock mode of the lock that caused the deadlock.
- 
-
-
-wait_hold
- 
- Whether the transaction was waiting for the lock or holding the lock.  Usually
- you will see the two waited-for locks.
- 
-
-
-victim
- 
- Whether the transaction was selected as the deadlock victim and rolled back.
- 
-
-
-query
- 
- The query that caused the deadlock.
- 
-
-
-
-**************************
-INNODB CAVEATS AND DETAILS
-**************************
-
-
-InnoDB's output is hard to parse and sometimes there's no way to do it right.
-
-Sometimes not all information (for example, username or IP address) is included
-in the deadlock information.  In this case there's nothing for the script to put
-in those columns.  It may also be the case that the deadlock output is so long
-(because there were a lot of locks) that the whole thing is truncated.
-
-Though there are usually two transactions involved in a deadlock, there are more
-locks than that; at a minimum, one more lock than transactions is necessary to
-create a cycle in the waits-for graph.  pt-deadlock-logger prints the
-transactions (always two in the InnoDB output, even when there are more
-transactions in the waits-for graph than that) and fills in locks.  It prefers
-waited-for over held when choosing lock information to output, but you can
-figure out the rest with a moment's thought.  If you see one wait-for and one
-held lock, you're looking at the same lock, so of course you'd prefer to see
-both wait-for locks and get more information.  If the two waited-for locks are
-not on the same table, more than two transactions were involved in the deadlock.
-
-
-*******
-OPTIONS
-*******
-
-
-This tool accepts additional command-line arguments.  Refer to the
-"SYNOPSIS" and usage information for details.
-
-
---ask-pass
- 
- Prompt for a password when connecting to MySQL.
- 
-
-
---charset
- 
- short form: -A; type: string
- 
- Default character set.  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.
- 
-
-
---clear-deadlocks
- 
- type: string
- 
- Use this table to create a small deadlock.  This usually has the effect of
- clearing out a huge deadlock, which otherwise consumes the entire output of
- \ ``SHOW INNODB STATUS``\ .  The table must not exist.  pt-deadlock-logger will
- create it with the following MAGIC_clear_deadlocks structure:
- 
- 
- .. code-block:: perl
- 
-    CREATE TABLE test.deadlock_maker(a INT PRIMARY KEY) ENGINE=InnoDB;
- 
- 
- After creating the table and causing a small deadlock, the tool will drop the
- table again.
- 
-
-
---[no]collapse
- 
- Collapse whitespace in queries to a single space.  This might make it easier to
- inspect on the command line or in a query.  By default, whitespace is collapsed
- when printing with "--print", but not modified when storing to "--dest".
- (That is, the default is different for each action).
- 
-
-
---columns
- 
- type: hash
- 
- Output only this comma-separated list of columns.  See "OUTPUT" for more
- details on columns.
- 
-
-
---config
- 
- type: Array
- 
- Read this comma-separated list of config files; if specified, this must be the
- first option on the command line.
- 
-
-
---create-dest-table
- 
- Create the table specified by "--dest".
- 
- Normally the "--dest" table is expected to exist already.  This option
- causes pt-deadlock-logger to create the table automatically using the suggested
- table structure.
- 
-
-
---daemonize
- 
- Fork to the background and detach from the shell.  POSIX operating systems only.
- 
-
-
---defaults-file
- 
- short form: -F; type: string
- 
- Only read mysql options from the given file.  You must give an absolute
- pathname.
- 
-
-
---dest
- 
- type: DSN
- 
- DSN for where to store deadlocks; specify at least a database (D) and table (t).
- 
- Missing values are filled in with the same values from the source host, so you
- can usually omit most parts of this argument if you're storing deadlocks on the
- same server on which they happen.
- 
- By default, whitespace in the query column is left intact;
- use "--[no]collapse" if you want whitespace collapsed.
- 
- The following MAGIC_dest_table is suggested if you want to store all the
- information pt-deadlock-logger can extract about deadlocks:
- 
- 
- .. code-block:: perl
- 
-   CREATE TABLE deadlocks (
-     server char(20) NOT NULL,
-     ts datetime NOT NULL,
-     thread int unsigned NOT NULL,
-     txn_id bigint unsigned NOT NULL,
-     txn_time smallint unsigned NOT NULL,
-     user char(16) NOT NULL,
-     hostname char(20) NOT NULL,
-     ip char(15) NOT NULL, -- alternatively, ip int unsigned NOT NULL
-     db char(64) NOT NULL,
-     tbl char(64) NOT NULL,
-     idx char(64) NOT NULL,
-     lock_type char(16) NOT NULL,
-     lock_mode char(1) NOT NULL,
-     wait_hold char(1) NOT NULL,
-     victim tinyint unsigned NOT NULL,
-     query text NOT NULL,
-     PRIMARY KEY  (server,ts,thread)
-   ) ENGINE=InnoDB
- 
- 
- If you use "--columns", you can omit whichever columns you don't want to
- store.
- 
-
-
---help
- 
- Show help and exit.
- 
-
-
---host
- 
- short form: -h; type: string
- 
- Connect to host.
- 
-
-
---interval
- 
- type: time
- 
- How often to check for deadlocks.  If no "--run-time" is specified,
- pt-deadlock-logger runs forever, checking for deadlocks at every interval.
- See also "--run-time".
- 
-
-
---log
- 
- type: string
- 
- Print all output to this file when daemonized.
- 
-
-
---numeric-ip
- 
- Express IP addresses as integers.
- 
-
-
---password
- 
- short form: -p; type: string
- 
- Password to use when connecting.
- 
-
-
---pid
- 
- type: string
- 
- Create the given PID file when daemonized.  The file contains the process ID of
- the daemonized instance.  The PID file is removed when the daemonized instance
- exits.  The program checks for the existence of the PID file when starting; if
- it exists and the process with the matching PID exists, the program exits.
- 
-
-
---port
- 
- short form: -P; type: int
- 
- Port number to use for connection.
- 
-
-
---print
- 
- Print results on standard output.  See "OUTPUT" for more.  By default,
- enables "--[no]collapse" unless you explicitly disable it.
- 
- If "--interval" or "--run-time" is specified, only new deadlocks are
- printed at each interval.  A fingerprint for each deadlock is created using
- "--columns" server, ts and thread (even if those columns were not specified
- by "--columns") and if the current deadlock's fingerprint is different from
- the last deadlock's fingerprint, then it is printed.
- 
-
-
---run-time
- 
- type: time
- 
- How long to run before exiting.  By default pt-deadlock-logger runs once,
- checks for deadlocks, and exits.  If "--run-time" is specified but
- no "--interval" is specified, a default 1 second interval will be used.
- 
-
-
---set-vars
- 
- type: string; default: wait_timeout=10000
- 
- Set these MySQL variables.  Immediately after connecting to MySQL, this string
- will be appended to SET and executed.
- 
-
-
---socket
- 
- short form: -S; type: string
- 
- Socket file to use for connection.
- 
-
-
---tab
- 
- Print tab-separated columns, instead of aligned.
- 
-
-
---user
- 
- short form: -u; type: string
- 
- User for login if not current user.
- 
-
-
---version
- 
- Show version and exit.
- 
-
-
-
-***********
-DSN OPTIONS
-***********
-
-
-These DSN options are used to create a DSN.  Each option is given like
-\ ``option=value``\ .  The options are case-sensitive, so P and p are not the
-same option.  There cannot be whitespace before or after the \ ``=``\  and
-if the value contains whitespace it must be quoted.  DSN options are
-comma-separated.  See the percona-toolkit manpage for full details.
-
-
-\* A
- 
- dsn: charset; copy: yes
- 
- Default character set.
- 
-
-
-\* D
- 
- dsn: database; copy: yes
- 
- Default database.
- 
-
-
-\* F
- 
- dsn: mysql_read_default_file; copy: yes
- 
- Only read default options from the given file
- 
-
-
-\* h
- 
- dsn: host; copy: yes
- 
- Connect to host.
- 
-
-
-\* p
- 
- dsn: password; copy: yes
- 
- Password to use when connecting.
- 
-
-
-\* P
- 
- dsn: port; copy: yes
- 
- Port number to use for connection.
- 
-
-
-\* S
- 
- dsn: mysql_socket; copy: yes
- 
- Socket file to use for connection.
- 
-
-
-\* t
- 
- Table in which to store deadlock information.
- 
-
-
-\* u
- 
- dsn: user; copy: yes
- 
- User for login if not current user.
- 
-
-
-
-***********
-ENVIRONMENT
-***********
-
-
-The environment variable \ ``PTDEBUG``\  enables verbose debugging output to STDERR.
-To enable debugging and capture all output to a file, run the tool like:
-
-
-.. code-block:: perl
-
-    PTDEBUG=1 pt-deadlock-logger ... > FILE 2>&1
-
-
-Be careful: debugging output is voluminous and can generate several megabytes
-of output.
-
-
-*******************
-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
-****
-
-
-For a list of known bugs, see `http://www.percona.com/bugs/pt-deadlock-logger <http://www.percona.com/bugs/pt-deadlock-logger>`_.
-
-Please report bugs at `https://bugs.launchpad.net/percona-toolkit <https://bugs.launchpad.net/percona-toolkit>`_.
-Include the following information in your bug report:
-
-
-\* Complete command-line used to run the tool
-
-
-
-\* Tool "--version"
-
-
-
-\* MySQL version of all servers involved
-
-
-
-\* Output from the tool including STDERR
-
-
-
-\* Input files (log/dump/config files, etc.)
-
-
-
-If possible, include debugging output by running the tool with \ ``PTDEBUG``\ ;
-see "ENVIRONMENT".
-
-
-***********
-DOWNLOADING
-***********
-
-
-Visit `http://www.percona.com/software/percona-toolkit/ <http://www.percona.com/software/percona-toolkit/>`_ to download the
-latest release of Percona Toolkit.  Or, get the latest release from the
-command line:
-
-
-.. code-block:: perl
-
-    wget percona.com/get/percona-toolkit.tar.gz
- 
-    wget percona.com/get/percona-toolkit.rpm
- 
-    wget percona.com/get/percona-toolkit.deb
-
-
-You can also get individual tools from the latest release:
-
-
-.. code-block:: perl
-
-    wget percona.com/get/TOOL
-
-
-Replace \ ``TOOL``\  with the name of any tool.
-
-
-*******
-AUTHORS
-*******
-
-
-Baron Schwartz
-
-
-*********************
-ABOUT PERCONA TOOLKIT
-*********************
-
-
-This tool is part of Percona Toolkit, a collection of advanced command-line
-tools developed by Percona for MySQL support and consulting.  Percona Toolkit
-was forked from two projects in June, 2011: Maatkit and Aspersa.  Those
-projects were created by Baron Schwartz and developed primarily by him and
-Daniel Nichter, both of whom are employed by Percona.  Visit
-`http://www.percona.com/software/ <http://www.percona.com/software/>`_ for more software developed by Percona.
-
-
-********************************
-COPYRIGHT, LICENSE, AND WARRANTY
-********************************
-
-
-This program is copyright 2007-2011 Baron Schwartz, 2011 Percona Inc.
-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
-MERCHANTABILITY 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.
-
-
-*******
-VERSION
-*******
-
-
-pt-deadlock-logger 1.0.1
-

=== removed file 'docs/user/pt-diskstats.rst'
--- docs/user/pt-diskstats.rst	2011-09-01 16:00:38 +0000
+++ docs/user/pt-diskstats.rst	1970-01-01 00:00:00 +0000
@@ -1,390 +0,0 @@
-
-############
-pt-diskstats
-############
-
-.. highlight:: perl
-
-
-****
-NAME
-****
-
-
-pt-diskstats - Aggregate and summarize \ */proc/diskstats*\ .
-
-
-********
-SYNOPSIS
-********
-
-
-Usage: pt-diskstats [OPTIONS] [FILES]
-
-pt-diskstats reads \ */proc/diskstats*\  periodically, or files with the
-contents of \ */proc/diskstats*\ , aggregates the data, and prints it nicely.
-
-
-*****
-RISKS
-*****
-
-
-The following section is included to inform users about the potential risks,
-whether known or unknown, of using this tool.  The two main categories of risks
-are those created by the nature of the tool (e.g. read-only tools vs. read-write
-tools) and those created by bugs.
-
-pt-diskstats is a read-only tool.  It should be very low-risk.
-
-At the time of this release, we know of no bugs that could cause serious harm
-to users.
-
-The authoritative source for updated information is always the online issue
-tracking system.  Issues that affect this tool will be marked as such.  You can
-see a list of such issues at the following URL:
-`http://www.percona.com/bugs/pt-diskstats <http://www.percona.com/bugs/pt-diskstats>`_.
-
-See also "BUGS" for more information on filing bugs and getting help.
-
-
-***********
-DESCRIPTION
-***********
-
-
-pt-diskstats tool is similar to iostat, but has some advantages. It separates
-reads and writes, for example, and computes some things that iostat does in
-either incorrect or confusing ways.  It is also menu-driven and interactive
-with several different ways to aggregate the data, and integrates well with
-the pt-collect tool. These properties make it very convenient for quickly
-drilling down into I/O performance at the desired level of granularity.
-
-This program works in two main modes. One way is to process a file with saved
-disk statistics, which you specify on the command line.  The other way is to
-start a background process gathering samples at intervals and saving them into
-a file, and process this file in the foreground.  In both cases, the tool is
-interactively controlled by keystrokes, so you can redisplay and slice the
-data flexibly and easily.  If the tool is not attached to a terminal, it
-doesn't run interactively; it just processes and prints its output, then exits.
-Otherwise it loops until you exit with the 'q' key.
-
-If you press the '?' key, you will bring up the interactive help menu that
-shows which keys control the program.
-
-Files should have this format:
-
-
-.. code-block:: perl
-
-    <contents of /proc/diskstats>
-    TS <timestamp>
-    <contents of /proc/diskstats>
-    ... et cetera
-    TS <timestamp>  <-- must end with a TS line.
-
-
-See `http://aspersa.googlecode.com/svn/html/diskstats.html <http://aspersa.googlecode.com/svn/html/diskstats.html>`_ for a detailed
-example of using the tool.
-
-
-******
-OUTPUT
-******
-
-
-The columns are as follows:
-
-
-#ts
- 
- The number of seconds of samples in the line.  If there is only one, then
- the timestamp itself is shown, without the {curly braces}.
- 
-
-
-device
- 
- The device name.  If there is more than one device, then instead the number
- of devices aggregated into the line is shown, in {curly braces}.
- 
-
-
-rd_mb_s
- 
- The number of megabytes read per second, average, during the sampled interval.
- 
-
-
-rd_cnc
- 
- The average concurrency of the read operations, as computed by Little's Law
- (a.k.a. queueing theory).
- 
-
-
-rd_rt
- 
- The average response time of the read operations, in milliseconds.
- 
-
-
-wr_mb_s
- 
- Megabytes written per second, average.
- 
-
-
-wr_cnc
- 
- Write concurrency, similar to read concurrency.
- 
-
-
-wr_rt
- 
- Write response time, similar to read response time.
- 
-
-
-busy
- 
- The fraction of time that the device had at least one request in progress;
- this is what iostat calls %util (which is a misleading name).
- 
-
-
-in_prg
- 
- The number of requests that were in progress.  Unlike the read and write
- concurrencies, which are averages that are generated from reliable numbers,
- this number is an instantaneous sample, and you can see that it might
- represent a spike of requests, rather than the true long-term average.
- 
-
-
-In addition to the above columns, there are a few columns that are hidden by
-default. If you press the 'c' key, and then press Enter, you will blank out
-the regular expression pattern that selects columns to display, and you will
-then see the extra columns:
-
-
-rd_s
- 
- The number of reads per second.
- 
-
-
-rd_avkb
- 
- The average size of the reads, in kilobytes.
- 
-
-
-rd_mrg
- 
- The percentage of read requests that were merged together in the disk
- scheduler before reaching the device.
- 
-
-
-wr_s, wr_avgkb, and wr_mrg
- 
- These are analogous to their \ ``rd_\*``\  cousins.
- 
-
-
-
-*******
-OPTIONS
-*******
-
-
-Options must precede files on the command line.
-
-
--c COLS
- 
- Awk regex of which columns to include (default cnc|rt|mb|busy|prg).
- 
-
-
--d DEVICES
- 
- Awk regex of which devices to include.
- 
-
-
--g GROUPBY
- 
- Group-by mode (default disk); specify one of the following:
- 
- 
- .. code-block:: perl
- 
-     disk   - Each line of output shows one disk device.
-     sample - Each line of output shows one sample of statistics.
-     all    - Each line of output shows one sample and one disk device.
- 
- 
-
-
--i INTERVAL
- 
- In -g sample mode, include INTERVAL seconds per sample.
- 
-
-
--k KEEPFILE
- 
- File to save diskstats samples in (default /tmp/diskstats-samples).
- If a non-default filename is used, it will be saved for later analysis.
- 
-
-
--n SAMPLES
- 
- When in interactive mode, stop after N samples.
- 
-
-
--s INTERVAL
- 
- Sample /proc/diskstats every N seconds (default 1).
- 
-
-
-
-***********
-ENVIRONMENT
-***********
-
-
-This tool does not use any environment variables.
-
-
-*******************
-SYSTEM REQUIREMENTS
-*******************
-
-
-This tool requires Bash v3 or newer and the \ */proc*\  filesystem unless
-reading from files.
-
-
-****
-BUGS
-****
-
-
-For a list of known bugs, see `http://www.percona.com/bugs/pt-diskstats <http://www.percona.com/bugs/pt-diskstats>`_.
-
-Please report bugs at `https://bugs.launchpad.net/percona-toolkit <https://bugs.launchpad.net/percona-toolkit>`_.
-Include the following information in your bug report:
-
-
-\* Complete command-line used to run the tool
-
-
-
-\* Tool "--version"
-
-
-
-\* MySQL version of all servers involved
-
-
-
-\* Output from the tool including STDERR
-
-
-
-\* Input files (log/dump/config files, etc.)
-
-
-
-If possible, include debugging output by running the tool with \ ``PTDEBUG``\ ;
-see "ENVIRONMENT".
-
-
-***********
-DOWNLOADING
-***********
-
-
-Visit `http://www.percona.com/software/percona-toolkit/ <http://www.percona.com/software/percona-toolkit/>`_ to download the
-latest release of Percona Toolkit.  Or, get the latest release from the
-command line:
-
-
-.. code-block:: perl
-
-    wget percona.com/get/percona-toolkit.tar.gz
- 
-    wget percona.com/get/percona-toolkit.rpm
- 
-    wget percona.com/get/percona-toolkit.deb
-
-
-You can also get individual tools from the latest release:
-
-
-.. code-block:: perl
-
-    wget percona.com/get/TOOL
-
-
-Replace \ ``TOOL``\  with the name of any tool.
-
-
-*******
-AUTHORS
-*******
-
-
-Baron Schwartz
-
-
-*********************
-ABOUT PERCONA TOOLKIT
-*********************
-
-
-This tool is part of Percona Toolkit, a collection of advanced command-line
-tools developed by Percona for MySQL support and consulting.  Percona Toolkit
-was forked from two projects in June, 2011: Maatkit and Aspersa.  Those
-projects were created by Baron Schwartz and developed primarily by him and
-Daniel Nichter, both of whom are employed by Percona.  Visit
-`http://www.percona.com/software/ <http://www.percona.com/software/>`_ for more software developed by Percona.
-
-
-********************************
-COPYRIGHT, LICENSE, AND WARRANTY
-********************************
-
-
-This program is copyright 2010-2011 Baron Schwartz, 2011 Percona Inc.
-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
-MERCHANTABILITY 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.
-
-
-*******
-VERSION
-*******
-
-
-pt-diskstats 1.0.1
-

=== removed file 'docs/user/pt-duplicate-key-checker.rst'
--- docs/user/pt-duplicate-key-checker.rst	2011-09-01 16:00:38 +0000
+++ docs/user/pt-duplicate-key-checker.rst	1970-01-01 00:00:00 +0000
@@ -1,563 +0,0 @@
-
-########################
-pt-duplicate-key-checker
-########################
-
-.. highlight:: perl
-
-
-****
-NAME
-****
-
-
-pt-duplicate-key-checker - Find duplicate indexes and foreign keys on MySQL tables.
-
-
-********
-SYNOPSIS
-********
-
-
-Usage: pt-duplicate-key-checker [OPTION...] [DSN]
-
-pt-duplicate-key-checker examines MySQL tables for duplicate or redundant
-indexes and foreign keys.  Connection options are read from MySQL option files.
-
-
-.. code-block:: perl
-
-    pt-duplicate-key-checker --host host1
-
-
-
-*****
-RISKS
-*****
-
-
-The following section is included to inform users about the potential risks,
-whether known or unknown, of using this tool.  The two main categories of risks
-are those created by the nature of the tool (e.g. read-only tools vs. read-write
-tools) and those created by bugs.
-
-pt-duplicate-key-checker is a read-only tool that executes SHOW CREATE TABLE and
-related queries to inspect table structures, and thus is very low-risk.
-
-At the time of this release, there is an unconfirmed bug that causes the tool
-to crash.
-
-The authoritative source for updated information is always the online issue
-tracking system.  Issues that affect this tool will be marked as such.  You can
-see a list of such issues at the following URL:
-`http://www.percona.com/bugs/pt-duplicate-key-checker <http://www.percona.com/bugs/pt-duplicate-key-checker>`_.
-
-See also "BUGS" for more information on filing bugs and getting help.
-
-
-***********
-DESCRIPTION
-***********
-
-
-This program examines the output of SHOW CREATE TABLE on MySQL tables, and if
-it finds indexes that cover the same columns as another index in the same
-order, or cover an exact leftmost prefix of another index, it prints out
-the suspicious indexes.  By default, indexes must be of the same type, so a
-BTREE index is not a duplicate of a FULLTEXT index, even if they have the same
-columns.  You can override this.
-
-It also looks for duplicate foreign keys.  A duplicate foreign key covers the
-same columns as another in the same table, and references the same parent
-table.
-
-
-*******
-OPTIONS
-*******
-
-
-This tool accepts additional command-line arguments.  Refer to the
-"SYNOPSIS" and usage information for details.
-
-
---all-structs
- 
- Compare indexes with different structs (BTREE, HASH, etc).
- 
- By default this is disabled, because a BTREE index that covers the same columns
- as a FULLTEXT index is not really a duplicate, for example.
- 
-
-
---ask-pass
- 
- Prompt for a password when connecting to MySQL.
- 
-
-
---charset
- 
- short form: -A; type: string
- 
- Default character set.  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.
- 
-
-
---[no]clustered
- 
- default: yes
- 
- PK columns appended to secondary key is duplicate.
- 
- Detects when a suffix of a secondary key is a leftmost prefix of the primary
- key, and treats it as a duplicate key.  Only detects this condition on storage
- engines whose primary keys are clustered (currently InnoDB and solidDB).
- 
- Clustered storage engines append the primary key columns to the leaf nodes of
- all secondary keys anyway, so you might consider it redundant to have them
- appear in the internal nodes as well.  Of course, you may also want them in the
- internal nodes, because just having them at the leaf nodes won't help for some
- queries.  It does help for covering index queries, however.
- 
- Here's an example of a key that is considered redundant with this option:
- 
- 
- .. code-block:: perl
- 
-    PRIMARY KEY  (`a`)
-    KEY `b` (`b`,`a`)
- 
- 
- The use of such indexes is rather subtle.  For example, suppose you have the
- following query:
- 
- 
- .. code-block:: perl
- 
-    SELECT ... WHERE b=1 ORDER BY a;
- 
- 
- This query will do a filesort if we remove the index on \ ``b,a``\ .  But if we
- shorten the index on \ ``b,a``\  to just \ ``b``\  and also remove the ORDER BY, the query
- should return the same results.
- 
- The tool suggests shortening duplicate clustered keys by dropping the key
- and re-adding it without the primary key prefix.  The shortened clustered
- key may still duplicate another key, but the tool cannot currently detect
- when this happens without being ran a second time to re-check the newly
- shortened clustered keys.  Therefore, if you shorten any duplicate clustered
- keys, you should run the tool again.
- 
-
-
---config
- 
- type: Array
- 
- Read this comma-separated list of config files; if specified, this must be the
- first option on the command line.
- 
-
-
---databases
- 
- short form: -d; type: hash
- 
- Check only this comma-separated list of databases.
- 
-
-
---defaults-file
- 
- short form: -F; type: string
- 
- Only read mysql options from the given file.  You must give an absolute pathname.
- 
-
-
---engines
- 
- short form: -e; type: hash
- 
- Check only tables whose storage engine is in this comma-separated list.
- 
-
-
---help
- 
- Show help and exit.
- 
-
-
---host
- 
- short form: -h; type: string
- 
- Connect to host.
- 
-
-
---ignore-databases
- 
- type: Hash
- 
- Ignore this comma-separated list of databases.
- 
-
-
---ignore-engines
- 
- type: Hash
- 
- Ignore this comma-separated list of storage engines.
- 
-
-
---ignore-order
- 
- Ignore index order so KEY(a,b) duplicates KEY(b,a).
- 
-
-
---ignore-tables
- 
- type: Hash
- 
- Ignore this comma-separated list of tables.  Table names may be qualified with
- the database name.
- 
-
-
---key-types
- 
- type: string; default: fk
- 
- Check for duplicate f=foreign keys, k=keys or fk=both.
- 
-
-
---password
- 
- short form: -p; type: string
- 
- Password to use when connecting.
- 
-
-
---pid
- 
- type: string
- 
- Create the given PID file.  The file contains the process ID of the script.
- The PID file is removed when the script exits.  Before starting, the script
- checks if the PID file already exists.  If it does not, then the script creates
- and writes its own PID to it.  If it does, then the script checks the following:
- if the file contains a PID and a process is running with that PID, then
- the script dies; or, if there is no process running with that PID, then the
- script overwrites the file with its own PID and starts; else, if the file
- contains no PID, then the script dies.
- 
-
-
---port
- 
- short form: -P; type: int
- 
- Port number to use for connection.
- 
-
-
---set-vars
- 
- type: string; default: wait_timeout=10000
- 
- Set these MySQL variables.  Immediately after connecting to MySQL, this string
- will be appended to SET and executed.
- 
-
-
---socket
- 
- short form: -S; type: string
- 
- Socket file to use for connection.
- 
-
-
---[no]sql
- 
- default: yes
- 
- Print DROP KEY statement for each duplicate key.  By default an ALTER TABLE
- DROP KEY statement is printed below each duplicate key so that, if you want to
- remove the duplicate key, you can copy-paste the statement into MySQL.
- 
- To disable printing these statements, specify --nosql.
- 
-
-
---[no]summary
- 
- default: yes
- 
- Print summary of indexes at end of output.
- 
-
-
---tables
- 
- short form: -t; type: hash
- 
- Check only this comma-separated list of tables.
- 
- Table names may be qualified with the database name.
- 
-
-
---user
- 
- short form: -u; type: string
- 
- User for login if not current user.
- 
-
-
---verbose
- 
- short form: -v
- 
- Output all keys and/or foreign keys found, not just redundant ones.
- 
-
-
---version
- 
- Show version and exit.
- 
-
-
-
-***********
-DSN OPTIONS
-***********
-
-
-These DSN options are used to create a DSN.  Each option is given like
-\ ``option=value``\ .  The options are case-sensitive, so P and p are not the
-same option.  There cannot be whitespace before or after the \ ``=``\  and
-if the value contains whitespace it must be quoted.  DSN options are
-comma-separated.  See the percona-toolkit manpage for full details.
-
-
-\* A
- 
- dsn: charset; copy: yes
- 
- Default character set.
- 
-
-
-\* D
- 
- dsn: database; copy: yes
- 
- Default database.
- 
-
-
-\* F
- 
- dsn: mysql_read_default_file; copy: yes
- 
- Only read default options from the given file
- 
-
-
-\* h
- 
- dsn: host; copy: yes
- 
- Connect to host.
- 
-
-
-\* p
- 
- dsn: password; copy: yes
- 
- Password to use when connecting.
- 
-
-
-\* P
- 
- dsn: port; copy: yes
- 
- Port number to use for connection.
- 
-
-
-\* S
- 
- dsn: mysql_socket; copy: yes
- 
- Socket file to use for connection.
- 
-
-
-\* u
- 
- dsn: user; copy: yes
- 
- User for login if not current user.
- 
-
-
-
-***********
-ENVIRONMENT
-***********
-
-
-The environment variable \ ``PTDEBUG``\  enables verbose debugging output to STDERR.
-To enable debugging and capture all output to a file, run the tool like:
-
-
-.. code-block:: perl
-
-    PTDEBUG=1 pt-duplicate-key-checker ... > FILE 2>&1
-
-
-Be careful: debugging output is voluminous and can generate several megabytes
-of output.
-
-
-*******************
-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
-****
-
-
-For a list of known bugs, see `http://www.percona.com/bugs/pt-duplicate-key-checker <http://www.percona.com/bugs/pt-duplicate-key-checker>`_.
-
-Please report bugs at `https://bugs.launchpad.net/percona-toolkit <https://bugs.launchpad.net/percona-toolkit>`_.
-Include the following information in your bug report:
-
-
-\* Complete command-line used to run the tool
-
-
-
-\* Tool "--version"
-
-
-
-\* MySQL version of all servers involved
-
-
-
-\* Output from the tool including STDERR
-
-
-
-\* Input files (log/dump/config files, etc.)
-
-
-
-If possible, include debugging output by running the tool with \ ``PTDEBUG``\ ;
-see "ENVIRONMENT".
-
-
-***********
-DOWNLOADING
-***********
-
-
-Visit `http://www.percona.com/software/percona-toolkit/ <http://www.percona.com/software/percona-toolkit/>`_ to download the
-latest release of Percona Toolkit.  Or, get the latest release from the
-command line:
-
-
-.. code-block:: perl
-
-    wget percona.com/get/percona-toolkit.tar.gz
- 
-    wget percona.com/get/percona-toolkit.rpm
- 
-    wget percona.com/get/percona-toolkit.deb
-
-
-You can also get individual tools from the latest release:
-
-
-.. code-block:: perl
-
-    wget percona.com/get/TOOL
-
-
-Replace \ ``TOOL``\  with the name of any tool.
-
-
-*******
-AUTHORS
-*******
-
-
-Baron Schwartz and Daniel Nichter
-
-
-*********************
-ABOUT PERCONA TOOLKIT
-*********************
-
-
-This tool is part of Percona Toolkit, a collection of advanced command-line
-tools developed by Percona for MySQL support and consulting.  Percona Toolkit
-was forked from two projects in June, 2011: Maatkit and Aspersa.  Those
-projects were created by Baron Schwartz and developed primarily by him and
-Daniel Nichter, both of whom are employed by Percona.  Visit
-`http://www.percona.com/software/ <http://www.percona.com/software/>`_ for more software developed by Percona.
-
-
-********************************
-COPYRIGHT, LICENSE, AND WARRANTY
-********************************
-
-
-This program is copyright 2007-2011 Baron Schwartz, 2011 Percona Inc.
-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
-MERCHANTABILITY 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.
-
-
-*******
-VERSION
-*******
-
-
-pt-duplicate-key-checker 1.0.1
-

=== removed file 'docs/user/pt-fifo-split.rst'
--- docs/user/pt-fifo-split.rst	2011-09-01 16:00:38 +0000
+++ docs/user/pt-fifo-split.rst	1970-01-01 00:00:00 +0000
@@ -1,305 +0,0 @@
-
-#############
-pt-fifo-split
-#############
-
-.. highlight:: perl
-
-
-****
-NAME
-****
-
-
-pt-fifo-split - Split files and pipe lines to a fifo without really splitting.
-
-
-********
-SYNOPSIS
-********
-
-
-Usage: pt-fifo-split [options] [FILE ...]
-
-pt-fifo-split splits FILE and pipes lines to a fifo.  With no FILE, or when FILE
-is -, read standard input.
-
-Read hugefile.txt in chunks of a million lines without physically splitting it:
-
-
-.. code-block:: perl
-
-  pt-fifo-split --lines 1000000 hugefile.txt
-  while [ -e /tmp/pt-fifo-split ]; do cat /tmp/pt-fifo-split; done
-
-
-
-*****
-RISKS
-*****
-
-
-The following section is included to inform users about the potential risks,
-whether known or unknown, of using this tool.  The two main categories of risks
-are those created by the nature of the tool (e.g. read-only tools vs. read-write
-tools) and those created by bugs.
-
-pt-fifo-split creates and/or deletes the "--fifo" file.  Otherwise, no other
-files are modified, and it merely reads lines from the file given on the
-command-line.  It should be very low-risk.
-
-At the time of this release, we know of no bugs that could cause serious harm to
-users.
-
-The authoritative source for updated information is always the online issue
-tracking system.  Issues that affect this tool will be marked as such.  You can
-see a list of such issues at the following URL:
-`http://www.percona.com/bugs/pt-fifo-split <http://www.percona.com/bugs/pt-fifo-split>`_.
-
-See also "BUGS" for more information on filing bugs and getting help.
-
-
-***********
-DESCRIPTION
-***********
-
-
-pt-fifo-split lets you read from a file as though it contains only some of the
-lines in the file.  When you read from it again, it contains the next set of
-lines; when you have gone all the way through it, the file disappears.  This
-works only on Unix-like operating systems.
-
-You can specify multiple files on the command line.  If you don't specify any,
-or if you use the special filename \ ``-``\ , lines are read from standard input.
-
-
-*******
-OPTIONS
-*******
-
-
-This tool accepts additional command-line arguments.  Refer to the
-"SYNOPSIS" and usage information for details.
-
-
---config
- 
- type: Array
- 
- Read this comma-separated list of config files; if specified, this must be the
- first option on the command line.
- 
-
-
---fifo
- 
- type: string; default: /tmp/pt-fifo-split
- 
- The name of the fifo from which the lines can be read.
- 
-
-
---force
- 
- Remove the fifo if it exists already, then create it again.
- 
-
-
---help
- 
- Show help and exit.
- 
-
-
---lines
- 
- type: int; default: 1000
- 
- The number of lines to read in each chunk.
- 
-
-
---offset
- 
- type: int; default: 0
- 
- Begin at the Nth line.  If the argument is 0, all lines are printed to the fifo.
- If 1, then beginning at the first line, lines are printed (exactly the same as
- 0).  If 2, the first line is skipped, and the 2nd and subsequent lines are
- printed to the fifo.
- 
-
-
---pid
- 
- type: string
- 
- Create the given PID file.  The file contains the process ID of the script.
- The PID file is removed when the script exits.  Before starting, the script
- checks if the PID file already exists.  If it does not, then the script creates
- and writes its own PID to it.  If it does, then the script checks the following:
- if the file contains a PID and a process is running with that PID, then
- the script dies; or, if there is no process running with that PID, then the
- script overwrites the file with its own PID and starts; else, if the file
- contains no PID, then the script dies.
- 
-
-
---statistics
- 
- Print out statistics between chunks.  The statistics are the number of chunks,
- the number of lines, elapsed time, and lines per second overall and during the
- last chunk.
- 
-
-
---version
- 
- Show version and exit.
- 
-
-
-
-***********
-ENVIRONMENT
-***********
-
-
-The environment variable \ ``PTDEBUG``\  enables verbose debugging output to STDERR.
-To enable debugging and capture all output to a file, run the tool like:
-
-
-.. code-block:: perl
-
-    PTDEBUG=1 pt-fifo-split ... > FILE 2>&1
-
-
-Be careful: debugging output is voluminous and can generate several megabytes
-of output.
-
-
-*******************
-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
-****
-
-
-For a list of known bugs, see `http://www.percona.com/bugs/pt-fifo-split <http://www.percona.com/bugs/pt-fifo-split>`_.
-
-Please report bugs at `https://bugs.launchpad.net/percona-toolkit <https://bugs.launchpad.net/percona-toolkit>`_.
-Include the following information in your bug report:
-
-
-\* Complete command-line used to run the tool
-
-
-
-\* Tool "--version"
-
-
-
-\* MySQL version of all servers involved
-
-
-
-\* Output from the tool including STDERR
-
-
-
-\* Input files (log/dump/config files, etc.)
-
-
-
-If possible, include debugging output by running the tool with \ ``PTDEBUG``\ ;
-see "ENVIRONMENT".
-
-
-***********
-DOWNLOADING
-***********
-
-
-Visit `http://www.percona.com/software/percona-toolkit/ <http://www.percona.com/software/percona-toolkit/>`_ to download the
-latest release of Percona Toolkit.  Or, get the latest release from the
-command line:
-
-
-.. code-block:: perl
-
-    wget percona.com/get/percona-toolkit.tar.gz
- 
-    wget percona.com/get/percona-toolkit.rpm
- 
-    wget percona.com/get/percona-toolkit.deb
-
-
-You can also get individual tools from the latest release:
-
-
-.. code-block:: perl
-
-    wget percona.com/get/TOOL
-
-
-Replace \ ``TOOL``\  with the name of any tool.
-
-
-*******
-AUTHORS
-*******
-
-
-Baron Schwartz
-
-
-*********************
-ABOUT PERCONA TOOLKIT
-*********************
-
-
-This tool is part of Percona Toolkit, a collection of advanced command-line
-tools developed by Percona for MySQL support and consulting.  Percona Toolkit
-was forked from two projects in June, 2011: Maatkit and Aspersa.  Those
-projects were created by Baron Schwartz and developed primarily by him and
-Daniel Nichter, both of whom are employed by Percona.  Visit
-`http://www.percona.com/software/ <http://www.percona.com/software/>`_ for more software developed by Percona.
-
-
-********************************
-COPYRIGHT, LICENSE, AND WARRANTY
-********************************
-
-
-This program is copyright 2007-2011 Baron Schwartz, 2011 Percona Inc.
-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
-MERCHANTABILITY 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.
-
-
-*******
-VERSION
-*******
-
-
-pt-fifo-split 1.0.1
-

=== removed file 'docs/user/pt-find.rst'
--- docs/user/pt-find.rst	2011-09-01 16:00:38 +0000
+++ docs/user/pt-find.rst	1970-01-01 00:00:00 +0000
@@ -1,977 +0,0 @@
-
-#######
-pt-find
-#######
-
-.. highlight:: perl
-
-
-****
-NAME
-****
-
-
-pt-find - Find MySQL tables and execute actions, like GNU find.
-
-
-********
-SYNOPSIS
-********
-
-
-Usage: pt-find [OPTION...] [DATABASE...]
-
-pt-find searches for MySQL tables and executes actions, like GNU find.  The
-default action is to print the database and table name.
-
-Find all tables created more than a day ago, which use the MyISAM engine, and
-print their names:
-
-
-.. code-block:: perl
-
-   pt-find --ctime +1 --engine MyISAM
-
-
-Find InnoDB tables that haven't been updated in a month, and convert them to
-MyISAM storage engine (data warehousing, anyone?):
-
-
-.. code-block:: perl
-
-   pt-find --mtime +30 --engine InnoDB --exec "ALTER TABLE %D.%N ENGINE=MyISAM"
-