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.<\/p>\n\n\n\n
“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.<\/p>\n\n\n\n
\nDon’t hesitate to open the source of your open source.<\/p>\n<\/blockquote>\n\n\n\n
What is pt-upgrade<\/h2>\n\n\n\n
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.<\/p>\n\n\n\n
Query Classes and Differences<\/h3>\n\n\n\n
When pt-upgrade runs, it groups queries into “Query classes” based on their execution characteristics. This classification is crucial for identifying QUERY DIFFERENCES\u2014the discrepancies between the results returned by the queries on different versions.<\/p>\n\n\n\n
What is query class?<\/h3>\n\n\n\n
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.<\/p>\n\n\n\n
When queries are reported?<\/h3>\n\n\n\n
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.<\/p>\n\n\n\n
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.<\/p>\n\n\n\n
Output and Monitoring Progress<\/h2>\n\n\n\n
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:<\/p>\n\n\n\n
pt-upgrade ... 1>report 2>err &\ntail -f err<\/code><\/pre>\n\n\n\nThis setup allows you to track ongoing operations while reviewing the results in real-time.<\/p>\n\n\n\n
Exit status or Return codes<\/h2>\n\n\n\n
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.<\/p>\n\n\n\n
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.<\/p>\n\n\n\n
pt-upgrade return codes<\/h2>\n\n\n\n
For quick reference, here\u2019s the summarized table of return codes:<\/p>\n\n\n\n
Exit Code<\/strong><\/td> Description<\/strong><\/td><\/tr> 0<\/td> No errors; the upgrade is successful.<\/td><\/tr> 1<\/td> Too many internal errors or warnings; check STDERR.<\/td><\/tr> 4<\/td> There were QUERY DIFFERENCES; see the report.<\/td><\/tr> 8<\/td> –run-time expired; the tool did not finish reading the logs.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n