.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "PT-UPGRADE 1p" .TH PT-UPGRADE 1p "2020-08-30" "perl v5.30.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" pt\-upgrade \- Verify that query results are identical on different servers. .SH "SYNOPSIS" .IX Header "SYNOPSIS" Usage: pt-upgrade [\s-1OPTIONS\s0] LOGS|RESULTS \s-1DSN\s0 [\s-1DSN\s0] .PP pt-upgrade executes queries in the given MySQL \f(CW\*(C`LOGS\*(C'\fR on each \f(CW\*(C`DSN\*(C'\fR, compares the results, and reports any significant differences. The tool can also save the results for later analyses. \f(CW\*(C`LOGS\*(C'\fR can be slow, general, binary, tcpdump, and \*(L"raw\*(R". .PP Compare host2 to host1 using queries in \f(CW\*(C`slow.log\*(C'\fR: .PP .Vb 1 \& pt\-upgrade h=host1 h=host2 slow.log .Ve .PP Compare host2 to saved results from host1: .PP .Vb 1 \& pt\-upgrade h=host1 \-\-save\-results host1_results/ slow.log \& \& pt\-upgrade host1_results1/ h=host2 .Ve .SH "RISKS" .IX Header "RISKS" Percona Toolkit is mature, proven in the real world, and well tested, but all database tools can pose a risk to the system and the database server. Before using this tool, please: .IP "\(bu" 4 Read the tool's documentation .IP "\(bu" 4 Review the tool's known \*(L"\s-1BUGS\*(R"\s0 .IP "\(bu" 4 Test the tool on a non-production server .IP "\(bu" 4 Backup your production server and verify the backups .SH "DESCRIPTION" .IX Header "DESCRIPTION" pt-upgrade helps determine if it is safe to upgrade (or downgrade) to a new version of MySQL. A safe and conservative upgrade plan has several steps, one of which is ensuring that queries will produce identical results on the new version of MySQL. .PP pt-upgrade executes queries from slow, general, binary, tcpdump, and \&\*(L"raw\*(R" logs on two servers, compares many aspects of each query's exeuction and results, and reports any significant differences. The two servers are typically development servers, one running the current production version of MySQL and the other running the new version of MySQL. .SH "USE CASES" .IX Header "USE CASES" pt-upgrade has two use cases. The first, canonical case is running \*(L"host to host\*(R". A log file and two \s-1DSN\s0 are given on the command line, one for each MySQL server. See the first example in the \*(L"\s-1SYNOPSIS\*(R"\s0. Queries are executed and compared on each server as the tool runs. Queries with differences are printed as the tool runs, or when it finishes (see \&\*(L"\s-1WHEN QUERIES ARE REPORTED\*(R"\s0). Nothing is saved to disk, so this use case requires less hard disk space, but the queries must be executed on both servers if the tool is ran again, even if one of the servers hasn't changed. If there are a lot of queries or executing them takes a long time, and one server doesn't change, you may want to use the second use case. .PP The second use case is running \*(L"reference results to host\*(R". Reference results are the complete results from a single MySQL server, saved to disk. In this case, you must first generate the reference results with \*(L"\-\-save\-results\*(R", then run the tool a second time to compare another MySQL server to the results. See the second example in the \&\*(L"\s-1SYNOPSIS\*(R"\s0. Results are typically generated for the current version of MySQL which doesn't change. This use case can require \fIa lot\fR of disk space because the results (i.e. rows) for all queries must be saved, plus other data about the queries. If you plan to do many comparisons against a fixed version of MySQL, this use case is more efficient. Or if you don't have access to both servers at the same time, this use case allows you to \*(L"execute now, compare later\*(R". .SH "IMPORTANT CONSIDERATIONS" .IX Header "IMPORTANT CONSIDERATIONS" .SS "\s-1CONSISTENCY\s0" .IX Subsection "CONSISTENCY" Consistent environments and consistent data are crucial for obtaining an accurate report. pt-upgrade should never be ran on a production server or any active server because there is no easy way to ensure a synchronous read for each query. If data is changing on either server while pt-upgrade is running, the report could contain more false-positives than legitimate differences. \fBpt-upgrade assumes that both MySQL servers are static, unchanging (except for any changes made by the tool if ran with \f(CB\*(C`\-\-no\-read\-only\*(C'\fB).\fR A read-only workload shouldn't affect the tool, except maybe query times, so read-only slaves could be used. .SS "\s-1COMPARED TO\s0" .IX Subsection "COMPARED TO" In a host to host comparison, results from the first host establish the norm to which results from the second host are compared. In a reference results to host comparison, the reference results are the norm to which the host is compared. Comparative phrases like \*(L"smaller than\*(R", \*(L"better than\*(R", etc. mean compared to the norm. .PP For example, if the query time for an event is \f(CW0.01\fR on the first host and \f(CW0.5\fR on the second host, that is a significant difference because \&\f(CW0.5\fR is worse than \f(CW0.1\fR, and so the query will be reported. .SS "READ-ONLY" .IX Subsection "READ-ONLY" By default, pt-upgrade only executes \f(CW\*(C`SELECT\*(C'\fR and \f(CW\*(C`SET\*(C'\fR statements. (This does not include '\s-1SELECT...INTO\s0' statements, which do not return rows but dump output to a file or variable.) If you're using recreatable test or development servers and wish to compare write statements too (e.g. \f(CW\*(C`INSERT\*(C'\fR, \f(CW\*(C`UPDATE\*(C'\fR, \f(CW\*(C`DELETE\*(C'\fR), then specify \f(CW\*(C`\-\-no\-read\-only\*(C'\fR. If using a binary log, you must specify \f(CW\*(C`\-\-no\-read\-only\*(C'\fR because binary logs don't contain \f(CW\*(C`SELECT\*(C'\fR statements. See \*(L"\-\-[no]read\-only\*(R". .SS "\s-1TRANSACTIONS\s0" .IX Subsection "TRANSACTIONS" The tool does not create its own transactions, but any transactions in the \f(CW\*(C`LOG\*(C'\fR are executed as-is. Since logs are serial, transactions shouldn't normally be an issue. If, however, you need to compare queries that are somehow transactionally related (in which case you probably also need to disable \*(L"\-\-[no]read\-only\*(R"), then pt-upgrade probably won't do what you need because it's not designed for this purpose. .PP pt-upgrade runs with \f(CW\*(C`autocommit=1\*(C'\fR by default. .SS "\s-1THROTTLING\s0" .IX Subsection "THROTTLING" pt-upgrade has no throttling options because the tool should only be ran on dedicated testing or development servers. \fBDo not run pt-upgrade on production servers!\fR Consequently, the tool is \s-1CPU,\s0 memory, disk, and network intensive. It executes queries as fast as possible. .SH "QUERY DIFFERENCES" .IX Header "QUERY DIFFERENCES" Significant query differences are determined by comparing these aspects of each query from both hosts: .IP "Row count" 4 .IX Item "Row count" The number of rows returned by the query should be the same. This is reported as \*(L"missing rows\*(R" under \*(L"Row diffs\*(R". .IP "Row data" 4 .IX Item "Row data" The row data returned by the query should be the same. All differences are significant: whitespace, float-precision, etc. .IP "Warnings" 4 .IX Item "Warnings" The query should either not produce any errors or warnings, or produce the same errors or warnings. .IP "Query time" 4 .IX Item "Query time" A query rarely executes with a constant time, but its execution time should be within the same order of magnitude or smaller. .IP "Query errors" 4 .IX Item "Query errors" If a query causes a \s-1SQL\s0 error on only one host, this is reported as \&\*(L"Query errors\*(R". Since the query works on one host, its syntax is probably valid, and the error is due to some condition unique to the other host. .IP "\s-1SQL\s0 errors" 4 .IX Item "SQL errors" If a query causes a \s-1SQL\s0 error on both hosts, this is reported as \&\*(L"\s-1SQL\s0 errors\*(R". The \s-1SQL\s0 syntax of the query could be invalid. .SH "REPORT" .IX Header "REPORT" As pt-upgrade runs, it prints queries with differences as soon as it can (see \*(L"\s-1WHEN QUERIES ARE REPORTED\*(R"\s0). To prevent the report from becoming too long, queries are not reported individually but grouped by fingerprint into classes. A query fingerprint is the abstracted form of a query, created by removing literal values, normalizing whitespace, etc. So these queries belong to the same class: .PP .Vb 3 \& SELECT c FROM t WHERE id = 1 \& SELECT c FROM t WHERE id=5 \& select c from t where id = 9 .Ve .PP The fingerprint for those queries is: .PP .Vb 1 \& select c from t where id=? .Ve .PP Each query class can have up to \*(L"\-\-max\-class\-size\*(R" unique queries (1,000 by default). Up to \*(L"\-\-max\-examples\*(R" are reported for each type of difference, per query class. By virtue of being in the same class, an example of one query's difference is usually representative of all queries with the same difference, so it's not necessary to report every example. The total number of queries in a class with a particular difference is indicated in the report. .SS "\s-1EXAMPLE\s0" .IX Subsection "EXAMPLE" .Vb 3 \& #\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \& # Logs \& #\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \& \& File: /opt/mysql/slow.log \& Size: 59700 \& \& #\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \& # Hosts \& #\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \& \& host1: \& \& DSN: h=127.1,P=12345 \& hostname: dev1 \& MySQL: MySQL 5.1.68 \& \& host2: \& \& DSN: h=127.1,P=12348 \& hostname: dev2 \& MySQL: MySQL 5.5.10 \& \& ######################################################################## \& # Query class AAD020567F8398EE \& ######################################################################## \& \& Reporting class because it has diffs, but hasn\*(Aqt been reported yet. \& \& Total queries 1 \& Unique queries 1 \& Discarded queries 0 \& \& insert into t (id, username) values(?+) \& \& ## \& ## Warning diffs: 1 \& ## \& \& \-\- 1. \& \& Code: 1265 \& Level: Warning \& Message: Data truncated for column \*(Aqusername\*(Aq at row 1 \& \& vs. \& \& No warning 1265 \& \& INSERT INTO t (id, username) VALUES (NULL, \*(Aqlong_username\*(Aq) \& \& #\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \& # Stats \& #\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \& \& failed_queries 0 \& not_select 0 \& queries_filtered 0 \& queries_no_diffs 0 \& queries_read 1 \& queries_with_diffs 1 \& queries_with_errors 0 .Ve .PP The \*(L"Query class <\s-1ID\s0>\*(R" sections are the most important because they list \&\*(L"\s-1QUERY DIFFERENCES\*(R"\s0. The first part of the section lists the reason why the query class was report, followed by counts of queries in the class, followed by the fingerprint which defines the class. .PP The rest of the query class section lists the \*(L"\s-1QUERY DIFFERENCES\*(R"\s0 that caused the class to be reported. Each type of difference begins with a double hash mark header that lists the type and total number of queries in the class with the difference. Then up to \*(L"\-\-max\-examples\*(R" are listed, numbered \*(L"\-\- 1.\*(R", \*(L"\-\-\- 2.\*(R", etc. Each example lists the difference for the first and second hosts (respective to the \*(L"Hosts\*(R" section), followed by the first \s-1SQL\s0 statement that revealed the difference. .SH "WHEN QUERIES ARE REPORTED" .IX Header "WHEN QUERIES ARE REPORTED" A query class is reported as soon as any one of the \*(L"\s-1QUERY DIFFERENCES\*(R"\s0 or query errors has \*(L"\-\-max\-examples\*(R". Else, all queries with differences are reported when the tool finishes. .PP For example, if two query time differences are found for a query class, it is not reported yet. Once a third query time diffence is found, the query class is reported, including any other differences that may have been found too. Queries for the class will continue to be executed, but the class will not be reported again. .SH "OUTPUT" .IX Header "OUTPUT" The \*(L"\s-1REPORT\*(R"\s0 is printed to \s-1STDOUT\s0 as the tool runs. Internal warnings, errors, and \*(L"\-\-progress\*(R" are printed to \s-1STDERR.\s0 To keep the two separate, run the tool like: .PP .Vb 1 \& pt\-upgrade ... 1>report 2>err & .Ve .PP Then \f(CW\*(C`tail \-f err\*(C'\fR while the tool is running to track its \*(L"\-\-progress\*(R". .SH "EXIT STATUS" .IX Header "EXIT STATUS" In general, the tool exits zero if it finishes normally and there were no internal warnings or errors, and no \*(L"\s-1QUERY DIFFERENCES\*(R"\s0 were found. Else the tool exits non-zero with one or more of the following codes: .IP "\(bu" 4 1 .Sp There were too many internal errors or warnings; see \s-1STDERR.\s0 See also \*(L"\-\-[no]continue\-on\-error\*(R". .IP "\(bu" 4 4 .Sp There were \*(L"\s-1QUERY DIFFERENCES\*(R"\s0; see the \*(L"\s-1REPORT\*(R"\s0. .IP "\(bu" 4 8 .Sp \&\*(L"\-\-run\-time\*(R" expired; the tool did not finish reading the logs or reference results. .PP Other exit codes indicate that the tool crashed or died unexpectedly. The error that caused this should have printed to \s-1STDERR.\s0 .PP To check for a particular exit code, logical \f(CW\*(C`AND\*(C'\fR (\f(CW\*(C`&\*(C'\fR) the final exit status with the exit code. For example, exit status 5 implies codes 1 and 4 because \f(CW\*(C`5 & 1\*(C'\fR is true, and \f(CW\*(C`5 & 4\*(C'\fR is true. .SH "OPTIONS" .IX Header "OPTIONS" This tool accepts additional command-line arguments. Refer to the \&\*(L"\s-1SYNOPSIS\*(R"\s0 and usage information for details. .IP "\-\-ask\-pass" 4 .IX Item "--ask-pass" Prompt for a password when connecting to MySQL. .IP "\-\-charset" 4 .IX Item "--charset" short form: \-A; type: string .Sp Default character set. If the value is utf8, sets Perl's binmode on \&\s-1STDOUT\s0 to utf8, passes the mysql_enable_utf8 option to DBD::mysql, and runs \s-1SET NAMES UTF8\s0 after connecting to MySQL. Any other value sets binmode on \s-1STDOUT\s0 without the utf8 layer, and runs \s-1SET NAMES\s0 after connecting to MySQL. .IP "\-\-config" 4 .IX Item "--config" type: Array .Sp Read this comma-separated list of config files; if specified, this must be the first option on the command line. .IP "\-\-[no]continue\-on\-error" 4 .IX Item "--[no]continue-on-error" default: yes .Sp Continue parsing even if there is an error. The tool will not continue forever: it stops after 100 errors, in which case there is probably a bug in the tool or the input is invalid. .IP "\-\-[no]create\-upgrade\-table" 4 .IX Item "--[no]create-upgrade-table" default: yes .Sp Create the \*(L"\-\-upgrade\-table\*(R" database and table. .IP "\-\-daemonize" 4 .IX Item "--daemonize" Fork to the background and detach from the shell. \s-1POSIX\s0 operating systems only. .IP "\-\-database" 4 .IX Item "--database" short form: \-D; type: string .Sp Default database when connecting to MySQL. .IP "\-\-defaults\-file" 4 .IX Item "--defaults-file" short form: \-F; type: string .Sp Only read MySQL options from the given file. You must give an absolute pathname. .IP "\-\-[no]disable\-query\-cache" 4 .IX Item "--[no]disable-query-cache" default: yes .Sp \&\f(CW\*(C`SET SESSION query_cache_type = OFF\*(C'\fR to disable the query cache. .IP "\-\-dry\-run" 4 .IX Item "--dry-run" Run but do not execute or compare queries. This is useful for checking command line options, connections to MySQL, and log or reference results parsing. .IP "\-\-filter" 4 .IX Item "--filter" type: string .Sp Allow events for which this Perl code returns true. .Sp See the same option in the documentation for pt-query-digest. .IP "\-\-help" 4 .IX Item "--help" Show help and exit. .IP "\-\-host" 4 .IX Item "--host" short form: \-h; type: string .Sp MySQL hostname or \s-1IP.\s0 .IP "\-\-ignore\-warnings" 4 .IX Item "--ignore-warnings" type: Hash .Sp Ignore these MySQL warning codes when comparing warnings. .IP "\-\-log" 4 .IX Item "--log" type: string .Sp Print \s-1STDOUT\s0 and \s-1STDERR\s0 to this file when daemonized. This option only takes affect when \*(L"\-\-daemonize\*(R" is specified. The file is created if it doesn't exist, else output is appended to it. .IP "\-\-max\-class\-size" 4 .IX Item "--max-class-size" type: int; default: 1000 .Sp Max number of unique queries in each query class. See \*(L"\s-1REPORT\*(R"\s0. .IP "\-\-max\-examples" 4 .IX Item "--max-examples" type: int; default: 3 .Sp Max number of examples to list for each \*(L"\s-1QUERY DIFFERENCES\*(R"\s0. A query class is reported as soon as this many examples for any type of query difference are found. .IP "\-\-password" 4 .IX Item "--password" short form: \-p; type: string .Sp MySQL password for the \*(L"\-\-user\*(R". .IP "\-\-pid" 4 .IX Item "--pid" type: string .Sp Create the given \s-1PID\s0 file. The tool won't start if the \s-1PID\s0 file already exists and the \s-1PID\s0 it contains is different than the current \s-1PID.\s0 However, if the \s-1PID\s0 file exists and the \s-1PID\s0 it contains is no longer running, the tool will overwrite the \s-1PID\s0 file with the current \s-1PID.\s0 The \s-1PID\s0 file is removed automatically when the tool exits. .IP "\-\-port" 4 .IX Item "--port" short form: \-P; type: int .Sp MySQL port number. .IP "\-\-progress" 4 .IX Item "--progress" type: array; default: time,30 .Sp Print progress reports to \s-1STDERR.\s0 The tool prints progress reports while reading logs or reference results, roughly estimating how long until it finishes. .Sp The value is a comma-separated list with two parts. The first part can be percentage, time, or iterations; the second part specifies how often an update should be printed, in percentage, seconds, or number of iterations. .IP "\-\-[no]read\-only" 4 .IX Item "--[no]read-only" default: yes .Sp Execute only \f(CW\*(C`SELECT\*(C'\fR and \f(CW\*(C`SET\*(C'\fR statements. If \f(CW\*(C`\-\-no\-read\-only\*(C'\fR is specified, \fIall\fR queries are exeucted: \f(CW\*(C`DROP\*(C'\fR, \f(CW\*(C`DELETE\*(C'\fR, \f(CW\*(C`UPDATE\*(C'\fR, etc. Even when running in default read-only mode, you should use a MySQL user with only \f(CW\*(C`SELECT\*(C'\fR privileges to insure against bugs in the tool. .IP "\-\-report" 4 .IX Item "--report" type: Hash; default: hosts, logs, queries, stats .Sp Print these sections of the \*(L"\s-1REPORT\*(R"\s0. .IP "\-\-run\-time" 4 .IX Item "--run-time" type: time .Sp How long to run before exiting. By default, the tool runs until it finishes reading the logs or reference results. .IP "\-\-save\-results" 4 .IX Item "--save-results" type: string .Sp Save reference results to this directory. This option works only when one \s-1DSN\s0 is specified, to generate reference results. When comparing a host to reference results, specify its results directory instead of its \s-1DSN.\s0 See the second example in the \*(L"\s-1SYNOPSIS\*(R"\s0. .Sp Reference results can use \fIa lot\fR of disk space. .IP "\-\-set\-vars" 4 .IX Item "--set-vars" type: Array .Sp Set the MySQL variables in this comma-separated list of \f(CW\*(C`variable=value\*(C'\fR pairs. .Sp By default, the tool sets: .Sp .Vb 1 \& wait_timeout=10000 .Ve .Sp Variables specified on the command line override these defaults. For example, specifying \f(CW\*(C`\-\-set\-vars wait_timeout=500\*(C'\fR overrides the defaultvalue of \f(CW10000\fR. .Sp The tool prints a warning and continues if a variable cannot be set. .IP "\-\-socket" 4 .IX Item "--socket" short form: \-S; type: string .Sp Socket file to use for connection. .IP "\-\-type" 4 .IX Item "--type" type: string; default: slowlog .Sp Type of log files. Valid types are: .Sp .Vb 7 \& VALUE LOG TYPE \& ======= =========================================== \& slowlog MySQL slow log \& genlog MySQL general log \& binlog MySQL binary log (converted by mysqlbinlog) \& tcpdump TCP dump file generated by tcpdump command \& rawlog Custom log with one SQL statement per line .Ve .IP "\-\-upgrade\-table" 4 .IX Item "--upgrade-table" type: string; default: percona_schema.pt_upgrade .Sp Use this table to clear warnings. To clear all warnings from previous queries, pt-upgrade executes \f(CW\*(C`SELECT * FROM \-\-upgrade\-table LIMIT 1\*(C'\fR on each host before executing each query. .Sp The table must be database-qualified. The database and table are automatically created unless \f(CW\*(C`\-\-no\-create\-upgrade\-table\*(C'\fR is specified (see \*(L"\-\-[no]create\-upgrade\-table\*(R"). If the table does not already exist, it is created with this definition: .Sp .Vb 3 \& CREATE TABLE pt_upgrade ( \& id INT NOT NULL PRIMARY KEY \& ) .Ve .IP "\-\-user" 4 .IX Item "--user" short form: \-u; type: string .Sp MySQL user if not the current system user. .IP "\-\-version" 4 .IX Item "--version" Show version and exit. .IP "\-\-[no]version\-check" 4 .IX Item "--[no]version-check" default: yes .Sp Check for the latest version of Percona Toolkit, MySQL, and other programs. .Sp This is a standard \*(L"check for updates automatically\*(R" feature, with two additional features. First, the tool checks its own version and also the versions of the following software: operating system, Percona Monitoring and Management (\s-1PMM\s0), MySQL, Perl, MySQL driver for Perl (DBD::mysql), and Percona Toolkit. Second, it checks for and warns about versions with known problems. For example, MySQL 5.5.25 had a critical bug and was re-released as 5.5.25a. .Sp A secure connection to Percona’s Version Check database server is done to perform these checks. Each request is logged by the server, including software version numbers and unique \s-1ID\s0 of the checked system. The \s-1ID\s0 is generated by the Percona Toolkit installation script or when the Version Check database call is done for the first time. .Sp Any updates or known problems are printed to \s-1STDOUT\s0 before the tool's normal output. This feature should never interfere with the normal operation of the tool. .Sp For more information, visit . .IP "\-\-watch\-server" 4 .IX Item "--watch-server" type: string .Sp Parse only events for this IP:port for \*(L"\-\-type\*(R" tcpdump. All other \&\s-1IP\s0 addresses are ignored. If not specified, pt-upgrade watches all servers by looking for any \s-1IP\s0 address using port 3306 or \*(L"mysql\*(R". If you're watching a server with a non-standard port, this won't work, so you must specify the \&\s-1IP\s0 address and port to watch. .Sp If you want to watch a mix of servers, some running on standard port 3306 and some running on non-standard ports, you need to create separate tcpdump outputs for the non-standard port servers and then specify this option for each. At present pt-upgrade cannot auto-detect servers on port 3306 and also be told to watch a server on a non-standard port. .SH "DSN OPTIONS" .IX Header "DSN OPTIONS" These \s-1DSN\s0 options are used to create a \s-1DSN.\s0 Each option is given like \&\f(CW\*(C`option=value\*(C'\fR. The options are case-sensitive, so P and p are not the same option. There cannot be whitespace before or after the \f(CW\*(C`=\*(C'\fR, and if the value contains whitespace it must be quoted. \s-1DSN\s0 options are comma-separated. See the percona-toolkit manpage for full details. .IP "\(bu" 4 A .Sp dsn: charset; copy: yes .Sp Default character set. .IP "\(bu" 4 D .Sp dsn: database; copy: yes .Sp Default database. .IP "\(bu" 4 F .Sp dsn: mysql_read_default_file; copy: yes .Sp Only read default options from the given file .IP "\(bu" 4 h .Sp dsn: host; copy: yes .Sp Connect to host. .IP "\(bu" 4 L .Sp copy: yes .Sp Explicitly enable \s-1LOAD DATA LOCAL INFILE.\s0 .Sp For some reason, some vendors compile libmysql without the \&\-\-enable\-local\-infile option, which disables the statement. This can lead to weird situations, like the server allowing \s-1LOCAL INFILE,\s0 but the client throwing exceptions if it's used. .Sp However, as long as the server allows \s-1LOAD DATA,\s0 clients can easily re-enable it; See and . This option does exactly that. .Sp Although we've not found a case where turning this option leads to errors or differing behavior, to be on the safe side, this option is not on by default. .IP "\(bu" 4 p .Sp dsn: password; copy: yes .Sp Password to use when connecting. If password contains commas they must be escaped with a backslash: \*(L"exam\e,ple\*(R" .IP "\(bu" 4 P .Sp dsn: port; copy: yes .Sp Port number to use for connection. .IP "\(bu" 4 S .Sp dsn: mysql_socket; copy: yes .Sp Socket file to use for connection. .IP "\(bu" 4 u .Sp dsn: user; copy: yes .Sp User for login if not current user. .SH "ENVIRONMENT" .IX Header "ENVIRONMENT" The environment variable \f(CW\*(C`PTDEBUG\*(C'\fR enables verbose debugging output to \s-1STDERR.\s0 To enable debugging and capture all output to a file, run the tool like: .PP .Vb 1 \& PTDEBUG=1 pt\-upgrade ... > FILE 2>&1 .Ve .PP Be careful: debugging output is voluminous and can generate several megabytes of output. .SH "SYSTEM REQUIREMENTS" .IX Header "SYSTEM REQUIREMENTS" You need Perl, \s-1DBI,\s0 DBD::mysql, and some core packages that ought to be installed in any reasonably new version of Perl. .SH "BUGS" .IX Header "BUGS" For a list of known bugs, see . .PP Please report bugs at . Include the following information in your bug report: .IP "\(bu" 4 Complete command-line used to run the tool .IP "\(bu" 4 Tool \*(L"\-\-version\*(R" .IP "\(bu" 4 MySQL version of all servers involved .IP "\(bu" 4 Output from the tool including \s-1STDERR\s0 .IP "\(bu" 4 Input files (log/dump/config files, etc.) .PP If possible, include debugging output by running the tool with \f(CW\*(C`PTDEBUG\*(C'\fR; see \*(L"\s-1ENVIRONMENT\*(R"\s0. .SH "DOWNLOADING" .IX Header "DOWNLOADING" Visit to download the latest release of Percona Toolkit. Or, get the latest release from the command line: .PP .Vb 1 \& wget percona.com/get/percona\-toolkit.tar.gz \& \& wget percona.com/get/percona\-toolkit.rpm \& \& wget percona.com/get/percona\-toolkit.deb .Ve .PP You can also get individual tools from the latest release: .PP .Vb 1 \& wget percona.com/get/TOOL .Ve .PP Replace \f(CW\*(C`TOOL\*(C'\fR with the name of any tool. .SH "AUTHORS" .IX Header "AUTHORS" Daniel Nichter .SH "ABOUT PERCONA TOOLKIT" .IX Header "ABOUT PERCONA TOOLKIT" This tool is part of Percona Toolkit, a collection of advanced command-line tools for MySQL developed by Percona. Percona Toolkit was forked from two projects in June, 2011: Maatkit and Aspersa. Those projects were created by Baron Schwartz and primarily developed by him and Daniel Nichter. Visit to learn about other free, open-source software from Percona. .SH "COPYRIGHT, LICENSE, AND WARRANTY" .IX Header "COPYRIGHT, LICENSE, AND WARRANTY" This program is copyright 2009\-2018 Percona \s-1LLC\s0 and/or its affiliates. Feedback and improvements are welcome. .PP \&\s-1THIS PROGRAM IS PROVIDED \*(L"AS IS\*(R" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.\s0 .PP This program is free software; you can redistribute it and/or modify it under the terms of the \s-1GNU\s0 General Public License as published by the Free Software Foundation, version 2; \s-1OR\s0 the Perl Artistic License. On \s-1UNIX\s0 and similar systems, you can issue `man perlgpl' or `man perlartistic' to read these licenses. .PP You should have received a copy of the \s-1GNU\s0 General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, \s-1MA\s0 02111\-1307 \s-1USA.\s0 .SH "VERSION" .IX Header "VERSION" pt-upgrade 3.2.1 .SH "POD ERRORS" .IX Header "POD ERRORS" Hey! \fBThe above document had some coding errors, which are explained below:\fR .IP "Around line 11245:" 4 .IX Item "Around line 11245:" Non-ASCII character seen before =encoding in 'Percona’s'. Assuming \s-1UTF\-8\s0