Interpreting the results and exit codes of your upgrade tests is essential for assessing the process’s outcome. In this blog, we’ll explore the significance of pt-upgrade return codes and how to evaluate your upgrade tests effectively.
Unnecessary Background
“A friend of mine” recently told me that the pt-upgrade isn’t working and it is failing. The friend suggested that the tool is exiting with the return code of 4 for every execution.
I quickly opened the pt-upgrade git page, found information on return codes (exit status) and enlightened him from the information in source with a tip.
Don’t hesitate to open the source of your open source.
What is pt-upgrade
pt-upgrade is part of the Percona Toolkit, which is specifically designed to help database administrators (DBAs) compare query performance between different versions of MySQL or MariaDB. It executes queries on both the current and upgraded versions of the database, allowing DBAs to identify any discrepancies in results, performance, or query execution behavior.
Query Classes and Differences
When pt-upgrade runs, it groups queries into “Query classes” based on their execution characteristics. This classification is crucial for identifying QUERY DIFFERENCES—the discrepancies between the results returned by the queries on different versions.
What is query class?
That’s a query fingerprint. A query fingerprint is a unique identifier generated from a SQL query that captures its structure and semantics, but ignoring specific variable values or session-specific details. Later this structure is passed to hashing algorithm like SHA-1 or MD5. Specific to pt-upgrade you can see md5_hex.
When queries are reported?
A query class is reported as soon as a predefined number of QUERY DIFFERENCES is reached. By default the –max-examples is defined as 3 to list a query as difference found.
For example, if two differences in query execution time are identified, the class remains unreported until a third difference is found. This helps in reducing noise in the report, focusing only on significant discrepancies.
Output and Monitoring Progress
pt-upgrade generates output to STDOUT and STDERR. The report detailing the results is printed to STDOUT while warnings and errors are sent to STDERR. To keep the outputs separate and monitor progress efficiently, it is recommended to run the tool like so:
pt-upgrade ... 1>report 2>err &
tail -f errThis setup allows you to track ongoing operations while reviewing the results in real-time.
Exit status or Return codes
It is typical for a consultant to evaluate the return code and look for 0 to feel confident. A non-zero return code typically means an error. That said, it is important to understand that every non-zero return code has their specific meanings and “assuming” failure of a tool is not right. The exit status codes from pt-upgrade provide insights into the execution outcome and potential issues.
In general, the tool exits zero if it finishes normally and there were no internal warnings or errors, and no “QUERY DIFFERENCES” were found. Thus, it is very common to get a non-zero return code though that doesn’t mean that the tool did not do its stuff.
pt-upgrade return codes
For quick reference, here’s the summarized table of return codes:
| Exit Code | Description |
| 0 | No errors; the upgrade is successful. |
| 1 | Too many internal errors or warnings; check STDERR. |
| 4 | There were QUERY DIFFERENCES; see the report. |
| 8 | –run-time expired; the tool did not finish reading the logs. |
Reference: https://github.com/percona/percona-toolkit/blob/3.x/bin/pt-upgrade#L11047
To check for specific exit codes, you can perform a logical AND operation with the final exit status. For example, if you receive an exit status of 5, it implies that codes 1 and 4 were also present, as both conditions are met (5 & 1 and 5 & 4 are true).
Conclusion
Understanding the return codes for determining your next steps are important. It’s wise to refer to the documentation or code for a better understanding the meaning of these return codes. Let me know if you’re using pt-upgrade for your upgrades and if you encounter any challenges. Here’s wishing you smooth upgrades and plenty of 0 return codes!
